Shell Programming and Scripting

flock FILEHANDLE,OPERATION
               Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns
               true for success, false on failure.  Produces 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 locks only entire files, not records.

               Two potentially non-obvious but traditional "flock" semantics
               are that it waits indefinitely until the lock is granted, and
               that its locks merely advisory.  Such discretionary locks are
               more flexible, but offer fewer guarantees.  This means that
               files locked with "flock" may be modified by programs that do
               not also use "flock".  See perlport, your port's specific docu-
               mentation, or your system-specific local manpages for details.
               It's best to assume traditional behavior if you're writing por-
               table programs.  (But if you're not, you should as always feel
               perfectly free to write for your own system's idiosyncrasies
               (sometimes called "features").  Slavish adherence to portabil-
               ity concerns shouldn't get in the way of your getting your job
               done.)

               OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly com-
               bined with LOCK_NB.  These constants are traditionally valued
               1, 2, 8 and 4, but you can use the symbolic names if you import
               them from the Fcntl module, either individually, or as a group
               using the ':flock' tag.  LOCK_SH requests a shared lock,
               LOCK_EX requests an exclusive lock, and LOCK_UN releases a pre-
               viously requested lock.  If LOCK_NB is bitwise-or'ed with
               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).

               To avoid the possibility of miscoordination, Perl now flushes
               FILEHANDLE before locking or unlocking 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) imple-
               ments.  Most if not all systems implement lockf(3) in terms of
               fcntl(2) locking, though, so the differing semantics shouldn't
               bite too many people.

               Note that the fcntl(2) emulation of flock(3) requires that
               FILEHANDLE be open with read intent to use LOCK_SH and requires
               that it be open with write intent to use LOCK_EX.

               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 "-Ud_flock" to
               the Configure program when you configure perl.

               Here's a mailbox appender for BSD systems.

                   use Fcntl ':flock'; # import LOCK_* constants

                   sub lock {
                       flock(MBOX,LOCK_EX);
                       # and, in case someone appended
                       # while we were waiting...
                       seek(MBOX, 0, 2);
                   }

                   sub unlock {
                       flock(MBOX,LOCK_UN);
                   }

                   open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
                           or die "Can't open mailbox: $!";

                   lock();
                   print MBOX $msg,"\n\n";
                   unlock();

               On systems that support a real flock(), locks are inherited
               across fork() calls, whereas those that must resort to the more
               capricious fcntl() function lose the locks, making it harder to
               write servers.

               See also DB_File for other flock() examples.