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

ID: 50218 Updated by: danbrown@php.net Reported By: shelby at coolpage dot com Status: Open Bug Type: Documentation problem Operating System: All PHP Version: 5.3.0 New Comment: For the record, I rejected your note from the manual page. It's enough to have this bug report in place, and is unnecessary to append a note to the page as well. It just leaves more housekeeping for later. Previous Comments: ------------------------------------------------------------------------ [2009-11-18 13:34:33] shelby at coolpage dot com Note the link in the above bug Description, to my annotation at the flock() manual page, was incorrect and should be: http://www.php.net/manual/en/function.flock.php#94682 I have summarized the issues there: * LOCK_NB does work on Windows, only the wouldblock argument is not supported. * LOCK_NB option may be combined with the other LOCK_* options, which may not be combined with each other. * May be used with NFS because implementation uses fcntl. * Locking is mandatory in some cases in addition to Windows. * OS with Posix.1 compliant fcntl will release all a scripts' flock()s on a file, if that same script fclose() any file handle on that file. * Do not confuse the LOCK_* values (1,2,3,4) input to this function, with the LOCK_* OS values (1,2,4,8), even though their semantics are similar. ------------------------------------------------------------------------ [2009-11-18 12:29:32] shelby at coolpage dot com 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 this bug report at http://bugs.php.net/?id=50218&edit=1