#50218 [NEW]: flock() has numerous documentation errors

From: shelby at coolpage dot com Operating system: All PHP version: 5.3.0 PHP Bug Type: Documentation problem Bug description: flock() has numerous documentation errors Description: ------------ 1) I feel this needs to be added to the documentation until it fixed and thus I have filed an annotation note to the documentation: http://www.php.net/manual/en/function.flock.php#93400 2) The documentation incorrectly states that LOCK_NB does not work on Windows, when in fact only the wouldblock argument is not supported. See lines 78 thru 141 in the flock_compat.c source code: http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/flock_compat.c?revision=272370&view=markup The wouldblock can not be supported on Windows, because the Win32 LockFileEx() function does not support it, nor afaik is there any Win32 function to only query whether a file is currently locked. See the Win32 LockFileEx() documentation at MSDN: http://msdn.microsoft.com/en-us/library/aa365203%28VS.85%29.aspx 3) The documentation does not mention that for the values (1,2,3,4) input to this documented flock() function, the LOCK_NB option is a binary flag that can be combined with the other LOCK_* options, and the other LOCK_* options may not be combined with each other. See line 353 in the file.c source code: http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/file.c?revision=290190&view=markup 4) The documentation is incorrect to warn against use of NFS, because the underlying implementation is using fcntl (except on Windows). See the flock_compat.* source code: http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/flock_compat.h?revision=272370&view=markup http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/flock_compat.c?revision=272370&view=markup 5) The documentation incorrectly states that blocking is advisory (i.e. not mandatory) on all operating systems other than Windows. There are exceptions. See "Mandatory locking" sub-section of the Description section for the Linux fcntl man page: http://manpages.ubuntu.com/manpages/jaunty/en/man2/fcntl.2.html#toptoc2 6) The documentation does not mention the caveat that due to the underlying implementation using fcntl, thus on systems that adhere to the Posix.1 standard, that all locks associated with a file for a given process (script) are removed when any file descriptor (handle) for that file is closed by that process (script). See the Description section of the FreeBSD man page: http://www.freebsd.org/cgi/man.cgi?query=fcntl&apropos=0&sektion=0&manpath=FreeBSD+7.2-RELEASE&format=html#DESCRIPTION 7) Note when viewing the PHP source code links above, do not confuse the operating system #define LOCK_* values (1,2,4,8) with the flock_values[] array LOCK_* 1-based indices (1,2,3,4) documented as input to this documented function flock(). See line 324 in file.c source: http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/ext/standard/file.c?revision=290190&view=markup -- Edit bug report at http://bugs.php.net/?id=50218&edit=1 -- Try a snapshot (PHP 5.2): http://bugs.php.net/fix.php?id=50218&r=trysnapshot52 Try a snapshot (PHP 5.3): http://bugs.php.net/fix.php?id=50218&r=trysnapshot53 Try a snapshot (PHP 6.0): http://bugs.php.net/fix.php?id=50218&r=trysnapshot60 Fixed in SVN: http://bugs.php.net/fix.php?id=50218&r=fixed Fixed in SVN and need be documented: http://bugs.php.net/fix.php?id=50218&r=needdocs Fixed in release: http://bugs.php.net/fix.php?id=50218&r=alreadyfixed Need backtrace: http://bugs.php.net/fix.php?id=50218&r=needtrace Need Reproduce Script: http://bugs.php.net/fix.php?id=50218&r=needscript Try newer version: http://bugs.php.net/fix.php?id=50218&r=oldversion Not developer issue: http://bugs.php.net/fix.php?id=50218&r=support Expected behavior: http://bugs.php.net/fix.php?id=50218&r=notwrong Not enough info: http://bugs.php.net/fix.php?id=50218&r=notenoughinfo Submitted twice: http://bugs.php.net/fix.php?id=50218&r=submittedtwice register_globals: http://bugs.php.net/fix.php?id=50218&r=globals PHP 4 support discontinued: http://bugs.php.net/fix.php?id=50218&r=php4 Daylight Savings: http://bugs.php.net/fix.php?id=50218&r=dst IIS Stability: http://bugs.php.net/fix.php?id=50218&r=isapi Install GNU Sed: http://bugs.php.net/fix.php?id=50218&r=gnused Floating point limitations: http://bugs.php.net/fix.php?id=50218&r=float No Zend Extensions: http://bugs.php.net/fix.php?id=50218&r=nozend MySQL Configuration Error: http://bugs.php.net/fix.php?id=50218&r=mysqlcfg