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

ID: 50218 User updated by: shelby at coolpage dot com Reported By: shelby at coolpage dot com Status: Open Bug Type: Documentation problem Operating System: All PHP Version: 5.3.0 New Comment: In the meantime, you have many errors in those user comments which did get approved on that page. Talk about future housekeeping! Dan you have no point and no logic. But you are good at destroying effort and chasing away the people who do apply inspired effort. Previous Comments: ------------------------------------------------------------------------ [2009-11-18 16:25:49] shelby at coolpage dot com Dan Brown I had already read the submission guidelines for manual annotations, and in fact my notation repeats some of the other notations already on the manual page (e.g. that LOCK_NB is a binary flag option that can be combined with options). Removing my note from the manual page, means that others will spend a whole day of frustration trying to figure out what I figured out, for as long as the manual is not fixed, which who knows might be months or even years. So you preference is to deny the users the information, because they surely won't find this bug report in meantime? I put a link here in the bug report, so who ever fixes the bug, can send an email to the note editor to remove my note later. Your premature deletion of my note did not save any housekeeping effort on your part, it merely destroys my work and hides the information from the millions of PHP users. Shame on you Dan Brown. At least you had the dignity to post here what you had done, so I can reply to you. Waste my time once, but never again. I will withhold my contributions from PHP from here out. Congratulations. ------------------------------------------------------------------------ [2009-11-18 13:55:15] danbrown@php.net 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. ------------------------------------------------------------------------ [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