4.4BSD/usr/share/man/cat2/flock.0

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

NNAAMMEE
     fflloocckk - apply or remove an advisory lock on an open file

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ffiillee..hh>>
     ##ddeeffiinnee   LLOOCCKK__SSHH   11    //** sshhaarreedd lloocckk **//
     ##ddeeffiinnee   LLOOCCKK__EEXX   22    //** eexxcclluussiivvee lloocckk **//
     ##ddeeffiinnee   LLOOCCKK__NNBB   44    //** ddoonn''tt bblloocckk wwhheenn lloocckkiinngg **//
     ##ddeeffiinnee   LLOOCCKK__UUNN   88    //** uunnlloocckk **//

     _i_n_t
     fflloocckk(_i_n_t _f_d, _i_n_t _o_p_e_r_a_t_i_o_n);

DDEESSCCRRIIPPTTIIOONN
     FFlloocckk() applies or removes an _a_d_v_i_s_o_r_y lock on the file associated with
     the file descriptor _f_d. A lock is applied by specifying an _o_p_e_r_a_t_i_o_n pa-
     rameter 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 consistent opera-
     tions on files, but do not guarantee consistency (i.e., processes may
     still access files without using advisory locks possibly resulting in in-
     consistencies).

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

     A shared lock may be _u_p_g_r_a_d_e_d to an exclusive lock, and vice versa, sim-
     ply by specifying the appropriate lock type; this results in the previous
     lock being released and the new lock applied (possibly after other pro-
     cesses have gained and released the lock).

     Requesting a lock on an object that is already locked normally causes the
     caller to be blocked until the lock may be acquired.  If LOCK_NB is in-
     cluded in _o_p_e_r_a_t_i_o_n, then this will not happen; instead the call will
     fail and the error EWOULDBLOCK will be returned.

NNOOTTEESS
     Locks are on files, not file descriptors.  That is, file descriptors du-
     plicated 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.

     Processes blocked awaiting a lock may be awakened by signals.

RREETTUURRNN VVAALLUUEESS
     Zero is returned if the operation was successful; on an error a -1 is re-
     turned and an error code is left in the global location _e_r_r_n_o.

EERRRROORRSS
     The fflloocckk() call fails if:

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

     [EBADF]        The argument _f_d is an invalid descriptor.

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

SSEEEE AALLSSOO
     open(2),  close(2),  dup(2),  execve(2),  fork(2)

HHIISSTTOORRYY
     The fflloocckk function call appeared in 4.2BSD.

4.2 Berkeley Distribution        June 4, 1993                                2