LOCKF(3-BSD)        RISC/os Reference Manual         LOCKF(3-BSD)



NAME
     lockf - advisory record locking on files

SYNOPSIS
     #include <unistd.h>

     #define   FULOCK   0    /* Unlock a previously locked section */
     #define   FLOCK    1    /* Lock a section for exclusive use */
     #define   FTLOCK   2    /* Test and lock a section (non-blocking) */
     #define   FTEST    3    /* Test section for other process' locks */

     lockf(fd, cmd, size)
     int fd, cmd;
     long 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)



                         Printed 1/15/91                   Page 1

LOCKF(3-BSD)        RISC/os Reference Manual         LOCKF(3-BSD)



     system call.

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.

     EAGAIN    cmd is F_TLOCK or F_TEST and the section is
               already locked by another process.

     EINTR     cmd is F_LOCK and a signal interrupted the process
               while it was waiting for the lock to be granted.

     ENOLCK    cmd is F_LOCK, F_TLOCK, or F_ULOCK and there are
               no more file lock entries available.

SEE ALSO
     fcntl(2).
     lockd(1M) in the System Administrator's Reference Manual.

ERRORS
     File locks obtained through the lockf mechanism do not
     interact in any way with those acquired via flock(2).  They
     do, however, work correctly with the locks claimed by
     fcntl(2).























 Page 2                  Printed 1/15/91