NAME

lockf − provide semaphores and record locking on files

SYNOPSIS

#include <unistd.h> lockf(fildes, function, size)
long size;
int fildes, function;

DESCRIPTION

Lockf will allow regions of a file to be used as semaphores (advisory locks) or accessible only by the locking process (enforcement mode record 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 for function are defined in <unistd.h> as follows:

All other values of functions are reserved for future extensions and will result in an error return if not implemented. 

F_TEST is used to detect if a lock by another process is present on the specified region.  F_TEST returns zero if the region is accessable and minus one (−1) if it is not; in this case errno will be set to EACCES.  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 forward for a positive size, and backward for a negative size (the preceding bytes up to but not including the current offset).  If size is zero the region from the current offset through the end of the largest possible file 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 the file. 

The regions locked with F_LOCK or F_TLOCK may, in whole or 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 requests differ only by the action taken if the resource is not available: F_LOCK will cause the calling process to sleep until the resource is available, and the F_TLOCK will return an [EACCES] error if the region is already locked by another process. 

F_ULOCK requests may, in whole or 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 section 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. 

Regular files with the file mode of S_ENFMT not having the group execute bit set will have an enforcement policy enabled.  With enforcement enabled, reads and writes that would access a locked region will sleep until the entire region is available if O_NDELAY is cleared, but will return −1 with errno set if O_NDELAY is set.  File access by other system functions, such as exec, are not subject to the enforcement policy.  Locks on directories, pipes, and special files are advisory only; no enforcement policy will be used. 

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 fcntl, lockf, read, or write scan for a deadlock prior to sleeping on a locked resource.  Deadlock is not checked for the wait and pause system calls, so potential for deadlock is not eliminated.  A creat call or an open call with the O_CREATE and O_TRUNC flags set on a regular file will return [EAGAIN] error if another process has locked part of the file and the file is currently in enforcement mode. 

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:

­[EBADF] If fildes is not a valid, open file descriptor. 

­[EACCES] If the region is already locked by another process. 

­[EDEADLK] If a deadlock would occur; or if the number of entries in the lock table would exceed a system-dependent maximum.  HP−UX guarantees this value to be at least 50. 

­[EINVAL] If function is not one of the functions specified above. 

­[EINVAL] If size plus current offset produces a negative offset into the file. 

WARNINGS

Deadlock conditions may arise when either the wait or pause system calls are used in conjunction with enforced locking, see wait(2) and pause(2) for details.

File and record locking using file descriptors obtained through dup(2) or link(2) may not work as expected, e.g., unlocking regions which were locked using either file descriptor may also unlock regions which were locked using the other file descriptor.

BUGS

Unexpected results may occur in process 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(3S), is the most common source of unexpected buffering.

In a hostile environment locking may be misused by holding key public resources locked.  This is particularly true with public read files that have enforcement mode enabled. 

APPLICATION USAGE

Because in the future the variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value, for example:

     if (lockf(fd, F_TLOCK, siz) == -1)
          if ((errno == EAGAIN) || (errno == EACCES))
               /*
                * section locked by another process
                * check for either EAGAIN or EACCES
                * due to different implementations
                */
          else if ...
               /*
                * check for other errors
                */

HARDWARE DEPENDENCIES

Series 200, 300, 800
For an EINVAL error, the resulting upper bound of the region to be locked would be greater than 2^30.  The current offset is greater than 2^30.

SEE ALSO

chmod(2), close(2), creat(2), fcntl(2), open(2), pause(2), read(2), stat(2), wait(2), write(2). 

FUTURE DIRECTIONS

The error condition which currently sets errno to EACCES will instead set errno to EAGAIN [see also APPLICATION USAGE above]. 

Hewlett-Packard Company  —  Version B.1,  May 11, 2021