NAME

lockf − provide advisory record locking on files

SYNOPSIS

#include <unistd.h>

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

DESCRIPTION

Lockf allows regions of a file to be used as semaphores (advisory locks).  Other processes which attempt to access the locked resource will either return an error or sleep until the resource becomes unlocked.  All the locks for a process are removed when the process closes the file or terminates.  Fildes is an open file descriptor.  Function is a control value which specifies the action to be taken.  The permissible values are defined in <unistd.h> as follows:

#define F_ULOCK0/∗ Unlock a previously locked region ∗/
#define F_LOCK1/∗ Lock a region for exclusive use ∗/
#define F_TLOCK2/∗ Test and lock a region for exclusive use ∗/
#define F_TEST3/∗ Test region for other processes’ locks ∗/

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

F_TEST is used to detect if a lock by another process is present on the specified region.  F_LOCK and F_TLOCK both lock a region of a file if the region is available.  F_ULOCK removes locks from a region 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 either forward, for a positive size, or backward for a negative size (the preceding byte, up to but not including the current offset).  If size is zero the region from the current offset thru the largest file offset is locked (i.e. from the current offset thru 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 the file. 

The regions locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be contained by a previously locked region for the same process.  When this occurs, or if adjacent regions occur, the regions are combined into a single region.  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 region is not locked. 

F_LOCK and F_TLOCK differ only in the actions taken if the resource is not available:  F_LOCK will cause the calling process to sleep until the resource is available, and F_TLOCK will return an [EACCES] error if the region is already locked by another process. 

F_ULOCK requests may, in whole or in part, release one or more locked regions controlled by the process.  When regions are not fully released, the remaining regions are still locked by the process.  Releasing the center sesction of a locked region requires an additional element in the table of active locks.  If this table is full, an [EDEADLK] error is returned, and the requested region 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 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. 

Since sleeping on a resource is interrupted with any signal, alarm(2) may be used to provide a timeout facility in applications which require this facility. 

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. 

ERRORS

Lockf will fail if any of the following occur:

[EACCES] will be returned for lockf requests in which the region is already locked by another process. 

[EBADF] if fildes is not a valid file descriptor. 

[EDEADLK] will be returned by lockf if a deadlock would occur; or if there are not enough entries in the lock table. 

BUGS

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, stdio(3) is the most common source of unexpected buffering. 
 

4th Berkeley Distribution  —  15 November 1985