lockf(3)						     Library Functions Manual							  lockf(3)

NAME

       lockf -	Locks and unlocks regions of open file descriptors

SYNOPSIS

       #include <unistd.h>

       int lockf(      int filedes,	 int request,	   off_t size );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       lockf():  XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Specifies  the file to which the lock is to be applied or removed.  The file descriptor is returned by a successful open() or fcntl() func-
       tion.  Specifies one of the following constants for the lockf() function: Unlocks a previously locked region in the file.  Locks the region
       for  exclusive  use.  This  request  causes  the  calling process to sleep if the region overlaps a locked region, and to resume when it is
       granted the lock.  Same as F_LOCK, except that the request returns an error if the region overlaps  a  locked  region.	Tests  to  see	if
       another process has already locked a region. The lockf() function returns 0 (zero) if the region is unlocked. If the region is locked, then
       -1 is returned and errno is set to [EACCES].  The number of bytes to be locked or unlocked for the lockf() function. The region	starts	at
       the  current location in the open file and extends forward if size is positive and backward if size is negative. If the size parameter is 0
       (zero),	the region starts at the current location and extends forward to the maximum possible file size, including the	unallocated  space
       after the end of the file.

DESCRIPTION

       The lockf() function locks and unlocks sections of an open file.  Unlike the fcntl() function, however, its interface is limited to setting
       only write (exclusive) locks.

       Although the lockf() and fcntl() functions are different, the implementations are fully integrated.  Therefore,	locks  obtained  from  one
       function are honored and enforced by the other lock function.

       Each lock is either an enforced lock or an advisory lock, and must also be either a read lock or a write lock.

       Locks  on  a file are advisory or enforced depending on the mode of the file (see the chmod() function.)  A given file can have advisory or
       enforced locks, but not both.  See the sys/mode.h header file for a description of file attributes.

       When a process holds an enforced exclusive lock on a section of a file, no other process can access that  section  of  the  file  with  the
       read() or write() functions. In addition, the open(), truncate(), and ftruncate() functions cannot truncate the locked section of the file.
       If another process attempts to read or modify the locked section of the file, it sleeps until the section is unlocked or  returns  with	an
       error indication.

       The file descriptor on which an exclusive lock is being placed must have been opened with write access.

       Some  general rules about file locking include the following: Changing or unlocking part of a file in the middle of a locked section leaves
       two smaller sections locked at each end of the originally locked section.  All locks associated with a file for a given process are removed
       when the process closes any file descriptor for that file.  Locks are not inherited by a child process after running a fork() function.

       Locks  can  start  and extend beyond the current end of a file, but cannot be negative relative to the beginning of the file. A lock can be
       set to extend to the end of the file by setting the l_len field to 0 (zero). If a lock is specified with the l_start field set to 0 and the
       l_whence field set to SEEK_SET, the whole file is locked.

       Advisory  file region locking is supported over NFS, provided the locking daemon (rpc.lockd) and status monitor daemon (rpc.statd) are run-
       ning.

NOTES

       Buffered I/O does not work properly when used with file locking. Do not use the standard I/O package routines on files that will be locked.

       Deadlocks due to file locks in a distributed system are not always detected. When such deadlocks are possible, the programs requesting  the
       locks should set time-out timers.

RETURN VALUES

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

ERRORS

       If  the lockf() function fails, errno may be set to one of the following values: The file region is locked and F_TEST was specified; or the
       file region is locked and F_TLOCK was specified.  The filedes parameter is not a valid open file descriptor; or the  request  parameter	is
       F_LOCK  or  F_TLOCK  and  filedes  is not a valid file descriptor open for writing.  The lock is blocked by some lock from another process.
       Putting the calling process to sleep while waiting for that lock to become free would cause a deadlock.	The request parameter  is  F_TLOCK
       and  the  lockf()  function was interrupted by a signal which was caught.  The request parameter is not valid or size plus the current file
       offset is less than 0 (zero).  The request parameter is F_LOCK, F_TLOCK, or F_UNLOCK and satisfying the lock or unlock request would exceed
       the configurable system limit of NLOCK_RECORD.

	      [Tru64 UNIX]  If using NFS, the server is out of resources or the file handle is stale.

RELATED INFORMATION

       Functions: chmod(2), close(2), exec(2), fcntl(2), flock(2), fork(2), open(2), read(2), write(2)

       Commands: rpc.lockd(8), rpc.statd(8)

       Standards: standards(5) delim off

																	  lockf(3)