FLOCK(2)                COMMAND REFERENCE                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
     The flock program applies or removes an advisory lock on the
     file associated with the file descriptor fd.  A lock is
     applied by specifying an operation; operation is constructed
     by or'ing together some combination of the following,
     defined in <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 */

     A lock is applied by specifying either LOCK_SH or LOCK_EX,
     possibly or'd with LOCK_NB. LOCK_NB specified alone as the
     entire operation is an invalid request. LOCK_UN unlocks an
     existing lock.

     Advisory locks allow cooperating processes to perform
     consistent operations on files, but do not guarantee
     consistency (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 locks, 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 which is already locked
     normally causes the caller to be blocked until the lock is
     acquired.  If LOCK_NB is included in operation this will not
     happen. Instead the call fails and the error EWOULDBLOCK is
     returned.

     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



Printed 4/6/89                                                  1

FLOCK(2)                COMMAND REFERENCE                FLOCK(2)



     references to a single lock.  If a process holding a lock on
     a file forks and the child explicitly unlocks the file, the
     parent loses its lock.

     Processes blocked awaiting a lock may be awakened by
     signals.

DIAGNOSTICS
     The flock call fails if:

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

     [EBADF]      The argument fd is an invalid descriptor.

     [EOPNOTSUPP] The argument fd refers to a socket, not to a
                  file.

     [EINVAL]     The argument operation is an invalid request.

RETURN VALUE
     Upon successful completion, a value of 0 is returned.
     Otherwise, a value of -1 is returned and errno is set to
     indicate the error.

CAVEATS
     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
     instead; these make use of the services of the network lock
     manager (see lockd(8c)).

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


















Printed 4/6/89                                                  2

%%index%%
na:264,108;
sy:372,718;
de:1090,2409;3835,233;
di:4068,527;
rv:4595,280;
ca:4875,578;
se:5453,253;
%%index%%000000000132