=over

=item flock FILEHANDLE,OPERATION
X<flock> X<lock> X<locking>

Calls L<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 L<flock(2)>, L<fcntl(2)> locking, or
L<lockf(3)>.  L<C<flock>|/flock FILEHANDLE,OPERATION> is Perl's portable
file-locking interface, although it locks entire files only, not
records.

Two potentially non-obvious but traditional L<C<flock>|/flock
FILEHANDLE,OPERATION> semantics are
that it waits indefinitely until the lock is granted, and that its locks
are B<merely advisory>.  Such discretionary locks are more flexible, but
offer fewer guarantees.  This means that programs that do not also use
L<C<flock>|/flock FILEHANDLE,OPERATION> may modify files locked with
L<C<flock>|/flock FILEHANDLE,OPERATION>.  See L<perlport>,
your port's specific documentation, and your system-specific local manpages
for details.  It's best to assume traditional behavior if you're writing
portable 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 portability 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 combined 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 L<Fcntl> module,
either individually, or as a group using the C<:flock> tag.  LOCK_SH
requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
releases a previously requested lock.  If LOCK_NB is bitwise-or'ed with
LOCK_SH or LOCK_EX, then L<C<flock>|/flock FILEHANDLE,OPERATION> returns
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 L<lockf(3)> doesn't provide shared
locks, and it requires that FILEHANDLE be open with write intent.  These
are the semantics that L<lockf(3)> implements.  Most if not all systems
implement L<lockf(3)> in terms of L<fcntl(2)> locking, though, so the
differing semantics shouldn't bite too many people.

Note that the L<fcntl(2)> emulation of L<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 L<C<flock>|/flock FILEHANDLE,OPERATION>
cannot lock things over the network; you would need to use the more
system-specific L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR> for
that.  If you like you can force Perl to ignore your system's L<flock(2)>
function, and so provide its own L<fcntl(2)>-based emulation, by passing
the switch C<-Ud_flock> to the F<Configure> program when you configure
and build a new Perl.

Here's a mailbox appender for BSD systems.

    # import LOCK_* and SEEK_END constants
    use Fcntl qw(:flock SEEK_END);

    sub lock {
        my ($fh) = @_;
        flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
        # and, in case we're running on a very old UNIX
        # variant without the modern O_APPEND semantics...
        seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
    }

    sub unlock {
        my ($fh) = @_;
        flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
    }

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

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

On systems that support a real L<flock(2)>, locks are inherited across
L<C<fork>|/fork> calls, whereas those that must resort to the more
capricious L<fcntl(2)> function lose their locks, making it seriously
harder to write servers.

See also L<DB_File> for other L<C<flock>|/flock FILEHANDLE,OPERATION>
examples.

Portability issues: L<perlport/flock>.

=back