flock(2)                                                 flock(2)



     NAME
          flock - apply or remove an advisory lock on an open file

     SYNOPSIS
          #include <sys/file.h>

          flock(fd, operation)
          int fd, operation;

     DESCRIPTION
          flock applies or removes an advisory lock on the file asso-
          ciated with the file descriptor fd.  A lock is applied by
          specifying an operation parameter that is the inclusive OR
          of LOCK_SH or LOCK_EX and, possibly, LOCK_NB.  To unlock an
          existing lock, the operation should be LOCK_UN.  The values
          for these operations are defined as follows:

          #define LOCK_SH 1 /* shared lock */
          #define LOCK_EX 2 /* exclusive lock */
          #define LOCK_NB 4 /* nonblocking lock */
          #define LOCK_UN 8 /* unlock */


          Advisory locks allow cooperating processes to perform con-
          sistent operations on files, but do not guarantee exclusive
          access (that is, processes may still access files without
          using advisory locks, possibly resulting in inconsisten-
          cies).

          The locking mechanism allows two types of locks:  shared
          locks and exclusive locks.  More than one process may hold a
          shared lock for a file at any given time, but multiple ex-
          clusive, or both shared and exclusive, locks may not exist
          simultaneously on a file.

          A shared lock may be upgraded to an exclusive lock, and vice
          versa, simply by specifying the appropriate lock type; the
          previous lock will be released and the new lock applied
          (possibly after other processes have gained and released the
          lock).

          Requesting a lock on an object that is already locked nor-
          mally causes the caller to block until the lock may be ac-
          quired.  If LOCK_NB is included in operation, then this will
          not happen; instead the call will fail and the error EWOULD-
          BLOCK will be returned.

     NOTES
          Locks are on files, not file descriptors.  That is, file
          descriptors duplicated through dup(2) or fork(2) do not
          result in multiple instances of a lock, but rather multiple
          references to a single lock.  If a process holding a lock on



     April, 1990                                                     1

     flock(2)                                                 flock(2)



          a file forks and the child explicitly unlocks the file, the
          parent will lose its lock.

          Processes blocked awaiting a lock may be awakened by sig-
          nals.

     RETURN VALUE
          Zero is returned on success, -1 on error, with an error code
          stored in errno.

     ERRORS
          The flock call fails if:

          [EWOULDBLOCK]       The file is locked and the LOCK_NB op-
                              tion was specified.

          [EBADF]             The argument fd is an invalid descrip-
                              tor.

          [EOPNOTSUPP]        The argument fd refers to an object oth-
                              er than a file.

     SEE ALSO
          close(2), dup(2), execve(2), fcntl(2), fork(2), open(2),
          lockf(3).

     BUGS
          Locks obtained through the flock mechanism are known only
          within the system on which they were placed.  Thus, multiple
          clients may successfully acquire exclusive locks on the same
          remote file.  If this behavior is not explicitly desired,
          the fcntl(2) or lockf(3) system calls should be used in-
          stead.






















     2                                                     April, 1990