lloocckkff() -- General Function (libc)

Lock a file or a section of a file
#iinncclluuddee <uunniissttdd.hh>
iinntt
lloocckkff(_f_d, _c_m_d, _s_i_z_e)
iinntt _f_d, _c_m_d; lloonngg _s_i_z_e;

The COHERENT library function lloocckkff() allows  a process to lock part or all
of a file.  If another process  calls lloocckkff() on the same file to request a
lock that conflicts with a previous lock, the later lloocckkff() call returns an
error or sleeps until the file is unlocked by the first process.

_f_d gives a file descriptor of  an open file; the file must have been opened
with OO_WWRROONNLLYY or OO_RRDDWWRR permission if lloocckkff() is to succeed.

_s_i_z_e  specifies how  many bytes  should  be locked  or unlocked.   The lock
begins  at  the  current file  position  and  extend  forward  (if _s_i_z_e  is
positive)  or backwards  (if it  is  negative).  A  _s_i_z_e of  zero locks  or
unlocks the entire file starting from the current position.

_c_m_d  specifies  the action  lloocckkff()  is to  take.   lloocckkff() recognizes  the
following four commands, as specified in the header file <uunniissttdd.hh>:

FF_TTEESSTT  Test whether a lock has already been set upon the specified section
        of the file.

FF_LLOOCCKK  Lock a section of the file,  if possible.  If the section cannot be
        locked, sleep until it becomes available for locking.

FF_TTLLOOCCKK Lock a  section of the  file, if possible.   Unlike FF_LLOOCCKK, FF_TTLLOOCCKK
        does not sleep if the  section cannot be locked; rather, it returns
        -1 and sets eerrrrnnoo to EEAAGGAAIINN if the lock is not available.

FF_UULLOOCCKK Unlock a currently existing lock.

Use lloocckkff()  with the unbuffered I/O routines (ooppeenn(),  wwrriittee(), and so on)
rather  than  with  standard  I/O  library  routines  (ffooppeenn(),  ffpprriinnttff(),
ffwwrriittee(), and so  on).  The buffering used by the  standard I/O library may
cause unexpected behavior with file locking.

_S_e_e _A_l_s_o
ccrreeaatt(), ffccnnttll(), lliibbcc, ooppeenn()

_D_i_a_g_n_o_s_t_i_c_s
lloocckkff() returns zero  on success, -1 on failure.  On  failure, it also sets
eerrrrnnoo to an appropriate value.  Possible errors include the following:

EEIINNVVAALL  Invalid file descriptor.

EEAAGGAAIINN  Requested section is already locked.

EEDDEEAADDLLKK A deadlock  would occur  if the command  slept, or the  system lock
        table is full.

_N_o_t_e_s
See the Lexicon entry for ffccnnttll()  for a fuller description of the COHERENT
system's method of file locking.
