lockf(3)                            CLIX                            lockf(3)



  NAME

    lockf - Provides record locking on files

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <unistd.h>

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

  PARAMETERS

    fildes     An integer representing a file descriptor

    function   An integer representing a control value

    size       The number of contiguous bytes to be locked

  DESCRIPTION

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

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

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

    F_ULOCK   0    /* Unlock a previously locked section */

    F_LOCK    1    /* Lock a section for exclusive use */

    F_TLOCK   2    /* Test and lock a section for exclusive use */

    F_TEST    3    /* Test section for other processes locks */




  2/94 - Intergraph Corporation                                              1

  lockf(3)                            CLIX                            lockf(3)



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

    The F_TEXT control value is used to detect if a lock by another process is
    present on the specified section.  Both O_LOCK and O_TLOCK lock a section
    of a file if the section is available.  The F_ULOCK removes locks from a
    section of the file.

    The size parameter is the number of contiguous bytes to be locked or
    unlocked.  The resource 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 preceding bytes up to but not including the current offset).  If
    size is 0, 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, F_LOCK or F_TLOCK may, in whole or in
    part,contain or be contained by a previously locked section for the same
    process.  When this occurs, or if adjacent sections occur, the sections
    are combined 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.

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

    The F_ULOCK 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 [EDLOCK] 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()
    function may be used to provide a timeout facility in applications which
    require this facility.

  CAUTIONS

    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.



  2                                              Intergraph Corporation - 2/94

  lockf(3)                            CLIX                            lockf(3)



    The standard I/O package is the most common source of unexpected
    buffering.  Because in the future the variable errno will be set to EAGAN
    rather than EACCES, when a section of a file is already locked by another
    process, portable application programs should expect and test for either
    value.

  RETURN VALUES

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

  ERRORS

    The lockf() function fails if one or more of the following are true:

    [EBADF]     The fildes is not a valid open descriptor.

    [EACCES]    The cmd is F_TLOCK or F_TEST and the section is already locked
                by another process.

    [EDEADLK]   The value of cmd is F_LOCK and a deadlock would occur.  Also
                the cmd is either F_LOCK, F_TLOCK, or F_ULOCK and the number
                of entries in the lock table would exceed the number allocated
                on the system.

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

  RELATED INFORMATION

    Functions:  chmod(2), close(2), creat(2), fcntl(2), open(2), read(2),
    write(2)






















  2/94 - Intergraph Corporation                                              3