FLOCK(2-BSD)        RISC/os Reference Manual         FLOCK(2-BSD)



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

SYNOPSIS
     #include <sys/file.h>

     #define   LOCKSH   1    /* shared lock */
     #define   LOCKEX   2    /* exclusive lock */
     #define   LOCKNB   4    /* don't block when locking */
     #define   LOCKUN   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/19/92                   Page 1

FLOCK(2-BSD)        RISC/os Reference Manual         FLOCK(2-BSD)



     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.

     [EDEADLK]           The file is locked and the LOCK_NB
                         option was not specified, and putting
                         the calling-process to sleep, waiting
                         for that lock to become free, would
                         cause a deadlock.

CAVEAT
     flock is implemented separately from the fcntl(2) mechanism
     so any file locks obtained through the fcntl(2) and lockf(3)
     mechanisms do not interact with those acquired via flock.

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






















 Page 2                 Printed 11/19/92