lockf(3C)                                               lockf(3C)



     NAME
          lockf - record locking on files

     SYNOPSIS
          # include <unistd.h>

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

     DESCRIPTION
          The lockf call will allow sections of a file to be locked
          (advisory write locks).  (Mandatory or enforcement mode
          record locks are not currently available.) Locking calls
          from other processes which 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(2) 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
          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 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.  If size is zero, the
          section from the current offset through the largest file
          offset is locked (i.e., 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.



     Page 1                                        (last mod. 1/14/87)

     lockf(3C)                                               lockf(3C)



          The sections locked with FLOCK or FTLOCK 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.

          FLOCK and FTLOCK requests differ only by the action taken
          if the resource is not available. FLOCK will cause the
          calling process to sleep until the resource is available.
          FTLOCK will cause the function to return a -1 and set errno
          to [EACCES] error 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 lock 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(2) command may be used to provide a timeout facility
          in applications which require this facility.

     ERRORS
          The lockf utility will fail if one or more of the following
          are true:

          [EBADF]     fildes is not a valid open descriptor.

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

          [EDEADLK]   function is FLOCK or FTLOCK and a deadlock
                      would occur.  Also the function is either of the
                      above or FULOCK and the number of entries in
                      the lock table would exceed the number allocated
                      on the system.

          [EREMOTE]   fildes is a file descriptor referring to a file
                      on a remotely mounted file system.



     Page 2                                        (last mod. 1/14/87)

     lockf(3C)                                               lockf(3C)



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

     CAVEATS
          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.

     SEE ALSO
          close(2), creat(2), fcntl(2), intro(2), open(2), read(2),
          write(2).









































     Page 3                                        (last mod. 1/14/87)