NonblockingWaitZeroTreatedAsReaped

warning native on by default PHP ≥ 5.3

Group: Probable bugs

Require a positive PID from nonblocking wait.

Example

<?php
$r=pcntl_waitpid($pid,$status,WNOHANG); if ($r!==-1) { echo pcntl_wexitstatus($status); }

Reported:

• line 2: Require a positive PID from nonblocking wait.

Detection

• Report direct or unchanged-local pcntl_waitpid result compared !=/!== -1, or >= 0, with an explicit resolved WNOHANG option. Zero indicates no available status. Other three-way handling and compound flags remain outside this literal-flag subset.
• Resolve builtin functions, extension classes, method receivers, constants and named arguments. Follow unchanged locals and aliases only within the same bounded lexical scope. Require a reachable path; merge branch facts only when all incoming paths establish them.
• Emit one finding at the violating operation, not one per evidence statement. Rebinding, writes, by-reference escape, unresolved calls that can mutate relevant state, and exhausted analysis budgets remove proof.

Exceptions (no report)

The literal comparison subset is exactly != or !== minus one, and >= zero. Comparisons != or !== zero already exclude a pending result and are not findings.

• Exclude shadowed builtins, unresolved receivers, incomplete syntax and unknown prerequisite facts. An extension function name alone does not prove an application function is that builtin.
• A dominating valid guard or repair described in Detection prevents the finding. Both legacy noinspection and custos-ignore forms suppress this ID.
• No report when the same unchanged wait result is told apart from zero elsewhere, because the code then already handles the pending case. The separating test must start before the end of the statement that contains the comparison: an earlier statement (for example an early return on === 0), another operand of the same condition, an enclosing condition, or a test inside the branch the comparison governs. A test placed after that statement cannot protect the guarded code and does not count.
• Separating tests are: a comparison with zero using ===, !==, ==, !=, > 0 or <= 0; >= 1 or < 1; the mirrored forms with the literal on the left; and truthiness of the variable as an if/elseif/ternary condition, a ! operand, an &&/|| operand, or a switch/match subject. >= 0, < 0, comparisons with other values and tests of a different wait result do not separate zero from a reaped PID.

Fix

No automatic fix. The required repair depends on error handling, data selection, lifecycle ordering or application policy.

All edits use exact byte ranges and preserve comments and evaluation order. Offer no fix when its stated prerequisites cannot be proven or the replacement is unsupported by the configured PHP version.

PHP versions

Requires PHP 5.3 or later and the referenced extension API. Respect method-specific introduction versions within PHP 5.3–8.5; unsupported optional APIs cannot establish facts. Named arguments require PHP 8.0 or later.

Configure

In custos.json:

{
  "rules": {
    "NonblockingWaitZeroTreatedAsReaped": {
      "enabled": false
    }
  }
}

Suppress

Before the statement or declaration (or the first statement of the file):

// @custos-ignore NonblockingWaitZeroTreatedAsReaped