Doc #64139 [Opn->Nab]: Misleading warning in documentation of readdir

Edit report at https://bugs.php.net/bug.php?id=64139&edit=1 ID: 64139 Updated by: salathe@php.net Reported by: jens at bremmekamp dot com Summary: Misleading warning in documentation of readdir -Status: Open +Status: Not a bug Type: Documentation Problem Package: Documentation problem Operating System: Debian Squeeze, Ubuntu 12.10 PHP Version: Irrelevant Block user comment: N Private report: N New Comment: The readdir() function is expecting a resource to be passed as its argument. Your example passes FALSE, and as with almost all functions it will return NULL when called with incorrect arguments. This is already noted under "Internal (built-in) functions" [1]. The documentation team has decided against adding such a warning/note to every single function in the manual (that follows the return-NULL-on-invalid-argument convention). [1] http://www.php.net/manual/en/functions.internal.php Previous Comments: ------------------------------------------------------------------------ [2013-02-04 11:09:28] jens at bremmekamp dot com Description: ------------ --- From manual page: http://www.php.net/function.readdir --- The documentation on readdir's return values is wrong for PHP >= 5.3. The warning correctly states that on failure readdir() may return boolean false or other values equivalent to boolean false. It then suggests to use type safe operators to check readdir's return values. The examples given follow this advice. In PHP >= 5.3 this makes no sense. If the return value of a function is not always boolean false, but just falsy, a type safe comparison will not give you any clue if the function failed or not. Witnessed in both 5.3.3-7+squeeze14 and 5.4.6-1ubuntu1.1. PLEASE NOTE: This is not a request to change readdir's return value behaviour. This is a DOCUMENTATION BUG for this specific function's documentation. Test script: --------------- <?php $handle = opendir('/non_existent_dir'); $filename = readdir($handle); // readdir() returns NULL instead of false if(false !== $filename) { unlink($filename); // fails, because $filename is null instead of false } ?> Expected result: ---------------- No warning for the unlink call. Actual result: -------------- PHP Warning: unlink(): No such file or directory in php shell code on line 2 ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=64139&edit=1