lockf(S)                       6 January 1993                       lockf(S)


 Name

    lockf - record locking on files

 Syntax


    cc  . . .  -lc


    #include <unistd.h>

    int lockf (fildes, function, size)
    int fildes, function;
    long size;


 Description

    The lockf command allows sections of a file to be locked; advisory or
    mandatory write locks are used depending on the mode bits of the file
    [see chmod(S)].  Locking calls from other processes which attempt to lock
    the locked file section either return an error value or are put to sleep
    until the resource becomes unlocked.  All the locks initiated by a pro-
    cess are removed when the process terminates or when the process closes
    the file.  See fcntl(S) for more information about record locking.

    fildes is an open file descriptor.  The file descriptor must have
    OWRONLY or ORDWR permission in order to establish a lock with this
    function call.

    function is a control value which specifies the action to be taken.  The
    permissible values for function are defined in <unistd.h> as follows:


       #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 for exclusive use */
       #define F_TEST   3    /* Test section for other processes locks */


    All other values of function are reserved for future extensions and will
    result in an error return if not implemented.

    FTEST is used to detect if a lock by another process is present on the
    specified section.  FLOCK and FTLOCK both lock a section of a file if
    the section is available.  FULOCK removes locks from a section of the
    file.

    size is the number of contiguous bytes to be locked or unlocked.  The
    section to be locked starts at the current offset in the file and extends
    forward for a positive size and backward for a negative size (the preced-
    ing bytes up to but not including the current offset).  If size is zero,
    the section from the current offset through the largest file offset is
    locked (that is, from the current offset through the present or any
    future end-of-file).  An area need not be allocated to the file in order
    to be locked as such locks may exist past the end-of-file.

    The sections locked with FLOCK or FTLOCK may, in whole or in part, con-
    tain or be contained by a previously locked section for the same process.
    When this occurs, or if adjacent sections occur, the sections are com-
    bined into a single section.  If the request requires that a new element
    be added to the table of active locks and this table is already full, an
    error is returned, and the new section is not locked.

    FLOCK and FTLOCK requests differ only by the action taken if the
    resource is not available.  FLOCK causes the calling process to sleep
    until the resource is available.  FTLOCK causes the function to return a
    -1 and set errno to [EACCES] if the section is already locked by another
    process.

    FULOCK requests may, in whole or in part, release one or more locked
    sections controlled by the process.  When sections are not fully
    released, the remaining sections are still locked by the process.
    Releasing the center section of a locked section requires an additional
    element in the table of active locks.  If this table is full, an
    [EDEADLK] error is returned, and the requested section is not released.

    A potential for deadlock occurs if a process controlling a locked
    resource is put to sleep by accessing another process's locked resource.
    Thus calls to lockf or fcntl scan for a deadlock prior to sleeping on a
    locked resource.  An error return is made if sleeping on the locked
    resource would cause a deadlock.

    Sleeping on a resource is interrupted with any signal.  The alarm(S)
    function may be used to provide a timeout facility in applications which
    require this facility.

    The lockf utility fails if one or more of the following is true:

    [EBADF]        fildes is not a valid open descriptor.

    [EACCES]       cmd is FTLOCK or FTEST and the section is already locked
                   by another process.

    [EDEADLK]      cmd is FLOCK and a deadlock would occur.  Also the cmd is
                   either FLOCK, FTLOCK, or FULOCK and the number of
                   entries in the lock table would exceed the number allo-
                   cated on the system.

    [ECOMM]        fildes is on a remote machine and the link to that machine
                   is no longer active.

 Diagnostics

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

 Warnings

    Unexpected results may occur in processes that do buffering in the user
    address space.  The process may later read/write data which is/was
    locked.  The standard I/O package is the most common source of unexpected
    buffering.

    Because in the future the variable errno will be set to EAGAIN rather
    than EACCES when a section of a file is already locked by another pro-
    cess, portable application programs should expect and test for either
    value.

 See also

    chmod(S), close(S), creat(S), fcntl(S), Intro(S), open(S), read(S),
    write(S)

 Standards conformance

    lockf is conformant with:
    AT&T SVID Issue 2