lockf(3)

NAME
     lockf - advisory record locking on files

SYNOPSIS
     #include <sys/types.h>
     #include <unistd.h>

     #define F_ULOCK   0   /* Unlock a previously locked section */
     #define F_LOCK    1   /* Lock a section for exclusive use */
     #define F_TLOCK   2   /* Test and lock a section (non-blocking) */
     #define F_TEST    3   /* Test section for other process' locks */

     int lockf(int fd, int cmd, off_t size)

DESCRIPTION
     Lockf may be used to test, apply, or remove an advisory  record  lock  on
     the  file associated with the open descriptor fd.  (See fcntl(2) for more
     information about advisory record locking.)

     A lock is obtained by specifying a cmd parameter of  F_LOCK  or  F_TLOCK.
     To  unlock  an existing lock, the F_ULOCK cmd is used.  F_TEST is used to
     detect if a lock by another process is present on the specified segment.

     F_LOCK and F_TLOCK requests differ only by the action taken if  the  lock
     may  not  be  immediately  granted.   F_TLOCK  will cause the function to
     return a -1 and set errno to EAGAIN if the section is already  locked  by
     another  process.   F_LOCK will cause the process to sleep until the lock
     may be granted or a signal is caught.

     Size is the number of contiguous bytes to be  locked  or  unlocked.   The
     lock  starts  at  the current file offset in the file and extends forward
     for a positive size or backward for a negative size (preceeding  but  not
     including  the  current  offset).  A segment need not be allocated to the
     file in order to be locked;  however, a  segment  may  not  extend  to  a
     negative  offset relative to the beginning of the file.  If size is zero,
     the lock will extend from the current offset through the end-of-file.  If
     such  a  lock  starts  at  offset  0, then the entire file will be locked
     (regardless of future file extensions).

NOTES
     The  descriptor  fd  must  have  been  opened  with  O_WRONLY  or  O_RDWR
     permission in order to establish locks with this function call.

     All locks associated with a file for a given process are removed when the
     file is closed or the process terminates.  Locks are not inherited by the
     child process in a fork(2) system call.

     No deadlock detection is performed by this library or  by  fcntl(2).   If
     two  processes  have  locked areas that the other process is waiting for,
     the processes will wait forever for their lock.

RETURN VALUE
     Zero is returned on success, -1 on error, with an error  code  stored  in
     errno.

ERRORS
     Lockf will fail if one or more of the following are true:

     [EBADF]        Fd is not a valid open descriptor.

     [EBADF]        Cmd is F_LOCK or F_TLOCK and the  process  does  not  have
                    write permission on the file.

     [EINVAL]       Either the current file offset and/or size  have  a  value
                    out  of  range  for  the  given file, or cmd is not one of
                    those specified above.

     [EAGAIN]       Cmd is F_TLOCK or F_TEST and the section is already locked
                    by another process.

     [EINTR]        Cmd is F_LOCK or  F_TEST  and  a  signal  interrupted  the
                    process  while  it  was  waiting for a reply from the lock
                    manager.

     [ENOLCK]       There are no more file lock entries available.

SEE ALSO
     fcntl(2).