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

ID: 50218 Updated by: kalle@php.net Reported By: shelby at coolpage dot com -Status: Open +Status: Closed Bug Type: Documentation problem Operating System: All PHP Version: 5.3.0 -Assigned To: +Assigned To: kalle New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2010-01-13 02:50:20] svn@php.net Automatic comment from SVN on behalf of kalle Revision: http://svn.php.net/viewvc/?view=revision&revision=293481 Log: Fixed bug #50218 (flock() has numerous documentation errors) ------------------------------------------------------------------------ [2009-11-19 12:49:19] shelby at coolpage dot com Yes exactly people become jaded by the open source process when it gets bogged down in politics. I do not have time to go locate that manual annotation submission policy page again, but perhaps I can suggest something: "Manual annotations should _ONLY_ be used to supplement the understanding of, and experiences with, the official manual text. When the official manual text is in error, _INSTEAD_ please submit a documentation error bug report at bugs.php.net. When submitting a documentation error bug report, please do not also submit a manual annotation, because this creates duplication of effort and confusion for us and the PHP community. Although perfection is not promised, we make best efforts to process documentation error bug reports within 72 working hours, and to apply any accepted change to the mirrors of the official manual text within days." Also let me suggest you add a feature where people can mark bug reports as applicable to certain manual pages, then have a scrollable list of cross-references on both the manual pages and the bug reports. Formalize the cross-reference at the DB level, may improve utility and understanding. ------------------------------------------------------------------------ [2009-11-19 12:18:26] shelby at coolpage dot com One reason the documentation of PHP's flock() is critical, is for example in my PHP-GTK2 application (a internet cafe timer that is run on customer logon), I need some way to let only one instance of the application run at a time (if customer attempts to run more instances), but I don't want the other application instances blocking-- rather I want them to exit immediately when they detect the lock on the shared file. So the fact that LOCK_NB is supported on Windows is critical to my application (since I am targetting Windows now, but want *nix OS an option in future). Also since many people do run on FreeBSD (e.g. my pair.com server account), it is important to know that the underlying OS fcntl implementation, is going to behave incorrectly if the same process does fclose() while also holding a lock on the same file with another file handle. In fact, that might not be considered a documentation bug, but a real bug where flock(2) instead needs to be used on FreeBSD (and any system implementing the "stupid" Posix.1 standard for fcntl). Thanks for the invitation to become more involved with PHP, actually I have been contributing infrequent suggestions and bug reports (and a few manual annotations) since as far back as PHP3 and I think I've interacted with rasmus and sniper roughly 6 or 7 years. I think I was pointing out the need for destructors and other OO features back then. I remember making a report about the impossibility of reporting error state through JSON due to the way the older PHP had lost its state by the time the error handler got called. In any case, I've got my fingers in many pies right now, e.g. I recently delved into functional programming and tried to simplify it: http://www.coolpage.com/commentary/economic/shelby/Functional_Programming_Essence.html (especially see how I reduced Category Theory and Monads from 10+ pages of goobly-gook mind bending to something easy to grasp by any programmer) And within 2 weeks of starting to learn it, made a crucial suggestion that was accepted by one of the co-creators of Haskell: http://hackage.haskell.org/trac/ghc/ticket/3630 Right now, my focus is on trying to move more free lance (less corporate control) programming into developing world, and so I am in extreme rush because I do not feel we have much time, so my passion is driven also by survival of mankind and freedom and general, so that might explain why I am bit touchy and why I take any opportunity I can get to tell people and recruit more to the awareness (I need to calm down for the long-haul, but reading the links about H1N1 may shed some light on my sentiments): http://goldwetrust.up-with.com/precious-metals-f6/silver-as-an-investment-t33-210.htm#2342 http://www.financialsense.com/fsu/editorials/2009/1109.html Apologies to everyone for this over-personalized diatribe, and again my apologies for misunderstanding the intent and timing of your policy. Thanks for being receptive to making your manual annotation policy more clear. And I do hope this bug report was accurate and helpful. You guys (any gals?) can determine that. All the best. We will cross paths more. ------------------------------------------------------------------------ [2009-11-18 17:10:03] danbrown@php.net That's a fair assessment, and one that should be addressed. We constantly update the site based on suggestions from users in situations that, in all honesty, we may not foresee as part of the big picture. This is an open source project that evolves minute-by- minute, most often with suggestions and submissions by folks such as yourself being implemented over time. Our documentation team is pretty snappy at getting things accomplished quickly, and we're lucky (at least so far) that we don't face bureaucratic roadblocks like a lot of other projects can't seem to overcome. It's by no means a guarantee that the bug will be fixed within 72 hours, but there's a better chance that it will than it won't. That aside, you seriously may want to consider joining the project. You're obviously passionate about it.... why not apply that directly without having to go through a middle-man to achieve results? With no word in jest or sarcasm, the PHP project could benefit from your help. ------------------------------------------------------------------------ [2009-11-18 17:00:26] shelby at coolpage dot com If it is true that documentation errors are resolved within 72 hours, then I eat my words and humbly apologize to you. If you simply added that statement-of-fact to the policy page and to the rejection email, then I wouldn't have even bothered adding the note to the manual page. I do not understand why you wouldn't make that clear on the policy, so that people will not feel like they have fallen in a blackhole, as can be the case in other social politics. Again if that is the case, my apologies. I was offended, because I have had my effort wasted too many times in past and it is unusual to see bug reports resolved all the way to release within 72 hours. I think it wasn't abnormal for me to assume otherwise. Please consider clarifying your policy page, so that bad feelings can not forment from misunderstandings. I can not read your mind. You have to state it. ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at http://bugs.php.net/50218 -- Edit this bug report at http://bugs.php.net/?id=50218&edit=1