NAME

lockf − provide semaphores and record locking on files

SYNOPSIS

#define F_UNLOCK0
#defineF_LOCK1
#define F_TSTLCK2
 lockf(fd, mode, size)
int fd, mode, size;

DESCRIPTION

This call is part of the /usr/group standard and not currently in 4.1c.

Lockf will allow a specified number of bytes to be accessed only by the locking process.  Other processes which attempt to flock, read, or write the locked area will sleep until the area becomes unlocked. 

Fildes is a file descriptor. 

Mode is F_UNLOCK to release the resource.  Mode is F_LOCK or F_TSTLCK for requesting the resource to be locked.  If the mode is F_LOCK, and the resource has some other lock on it, then the process will sleep until the entire all resources are available.  If the mode is F_TSTLCK, and the resource is locked, an error will be returned. 

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.  If size is zero, then the area to the end of the file is locked. 

The potential for deadlock occurs when a process controlling a locked resource is put to sleep by accessing another process’s locked resource.  Thus calls to lockf, read or write 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. 

F_LOCK and F_TSTLCK requests may, in whole or part, contain or be contained by a previously locked resource for the same process.  When this or adjacent areas occur, the areas are combined into a single area.  If the request requires a new lockf element with the lockf table full, and error is returned, and the area is not locked. 

F_UNLOCK requests may, in whole or part, release one or more locked regions controlled by the process.  When regions are not fully released, the remaining areas are still locked by the process.   Release of the center section for a locked area requires an additional lockf element to hold the cut off section.  If the lockf table is full, an error is returned, and the requested area is not released. 

While locks may be applied to special file or pipes, read/write operations will not be blocked.  Locks may not be applied to a directory.  A open call which specifies file truncation will error return when another process has locked the file. 

RETURN VALUE

If lockf succeeds it returns 0.  If it fails, it returns −1 and the global variable errno will be set to a more specific error code. 

ERRORS

The errors returned by lockf are:

[EBADF] If the descriptor is not a valid open file descriptor. 

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

[EDEADLOCK] Will be returned by lockf, read or write if a deadlock would occur, or if the maximum number of entries in the lock table would exceed {LOCK_MAX}. 

CAVEATS

Buffered i/o doesn’t work well with lockf unless care is exercised, particularly when using the standard i/o library. 

Unlocking an area in the middle of a locked region creates two locked regions.  Thus an EDEADLOCK error can occur on an unlock system call. 

SEE ALSO

open(2), creat(2), read(2), write(2), close(2)

Sun System Release 0.3  —  13 February 1983