2.11BSD#431 - /usr/man/cat2/flock.0

FLOCK(2)	    UNIX Programmer's Manual		 FLOCK(2)


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

SYNOPSIS
     #include <sys/file.h>

     #define   LOCK_SH	 1    /* shared lock */
     #define   LOCK_EX	 2    /* exclusive lock */
     #define   LOCK_NB	 4    /* don't block when locking */
     #define   LOCK_UN	 8    /* unlock */

     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 operation should be LOCK_UN.

     Advisory locks allow cooperating processes to perform con-
     sistent operations on files, but do not guarantee con-
     sistency (i.e., processes may still access files without
     using advisory locks possibly resulting in inconsistencies).

     The locking mechanism allows two types of locks: shared
     locks and exclusive locks.  At any time multiple shared
     locks may be applied to a file, but at no time are multiple
     exclusive, or both shared and exclusive, locks allowed
     simultaneously on a file.

     A shared lock may be upgraded to an exclusive lock, and vice
     versa, simply by specifying the appropriate lock type; this
     results in the previous lock being 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 be blocked until the lock may be
     acquired.	If LOCK_NB is included in operation, then this
     will not happen; instead the call will fail and the error
     EWOULDBLOCK 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
     a file forks and the child explicitly unlocks the file, the
     parent will lose its lock.


Printed 11/26/99	  May 22, 1986				1


FLOCK(2)	    UNIX Programmer's Manual		 FLOCK(2)


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

RETURN VALUE
     Zero is returned if the operation was successful; on an
     error a -1 is returned and an error code is left in the glo-
     bal location errno.

ERRORS
     The flock call fails if:

     [EWOULDBLOCK]	 The file is locked and the LOCK_NB
			 option was specified.

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

     [EINVAL]		 The argument fd refers to an object
			 other than a file.

SEE ALSO
     open(2), close(2), dup(2), execve(2), fork(2)


Printed 11/26/99	  May 22, 1986				2