From: Roderick Schertler Date: Sat, 4 Jan 1997 00:31:11 +0000 (-0500) Subject: expanded flock() docs X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1fd81fbbe87d964ad1f7dbdce41e36f3781dcf82;p=p5sagit%2Fp5-mst-13.2.git expanded flock() docs p5p-msgid: <4481.852337871@eeyore.ibcinc.com> --- diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index c39dd29..e6a34df 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -1029,14 +1029,35 @@ value is taken as the name of the filehandle. =item flock FILEHANDLE,OPERATION -Calls flock(2) on FILEHANDLE. See L for definition of -OPERATION. Returns TRUE for success, FALSE on failure. Will produce a -fatal error if used on a machine that doesn't implement either flock(2) or -fcntl(2). The fcntl(2) system call will be automatically used if flock(2) -is missing from your system. This makes flock() the portable file locking -strategy, although it will lock only entire files, not records. Note also -that some versions of flock() cannot lock things over the network; you -would need to use the more system-specific fcntl() for that. +Calls flock(2), or an emulation of it, on FILEHANDLE. Returns TRUE for +success, FALSE on failure. Will produce a fatal error if used on a +machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). +flock() is Perl's portable file locking interface, although it will lock +only entire files, not records. + +OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with +LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but +you can use the symbolic names if you pull them in with an explicit +request to the Fcntl module. The names can be requested as a group with +the :flock tag (or they can be requested individually, of course). +LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and +LOCK_UN releases a previously requested lock. If LOCK_NB is added to +LOCK_SH or LOCK_EX then flock() will return immediately rather than +blocking waiting for the lock (check the return status to see if you got +it). + +Note that the emulation built with lockf(3) doesn't provide shared +locks, and it requires that FILEHANDLE be open with write intent. These +are the semantics that lockf(3) implements. Most (all?) systems +implement lockf(3) in terms of fcntl(2) locking, though, so the +differing semantics shouldn't bite too many people. + +Note also that some versions of flock() cannot lock things over the +network; you would need to use the more system-specific fcntl() for +that. If you like you can force Perl to ignore your system's flock(2) +function, and so provide its own fcntl(2)-based emulation, by passing +the switch C<-Ud_flock> to the F program when you configure +perl. Here's a mailbox appender for BSD systems.