lockf(3C) lockf(3C)NAME lockf - record locking on files SYNOPSIS #include <unistd.h> int lockf(fildes, function, size) long size; int fildes, function; DESCRIPTION The lockf call will allow sections of a file to be locked (advisory write locks). (Mandatory locking is available via locking(2)). Locking calls from other processes which at- tempt to lock the locked file section will either return an error value or be put to sleep until the resource becomes unlocked. All the locks for a process are removed when the process terminates. (See fcntl(2) for more information about record locking.) fildes is an open file descriptor. The file descriptor must have O_WRONLY or O_RDWR permission in order to establish lock with this function call. function is a control value which specifies the action to be taken. The permissible values for function are defined in <unistd.h> as follows: #define F_ULOCK 0 /* Unlock a previously locked section */ #define F_LOCK 1 /* Lock a section for exclusive use */ #define F_TLOCK 2 /* Test and lock a section for exclusive use */ #define F_TEST 3 /* Test section for other processes locks */ All other values of function are reserved for future exten- sions 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 section. F_LOCK and F_TLOCK both lock a section of a file if the section is available. F_ULOCK removes locks from a section of the file. size is the number of contiguous bytes to be locked or un- locked. 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. If size is zero, the sec- tion from the current offset through the largest file offset is locked (i.e., from the current offset through the present or any future end-of-file). An area need not be allocated April, 1990 1
lockf(3C) lockf(3C)to the file in order to be locked, as such locks may exist past the end-of-file. The sections locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be contained by a previously locked sec- tion for the same process. When this occurs, or if adjacent sections occur, the sections are combined into a single sec- tion. 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 section 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 cal- ling process to sleep until the resource is available. F_TLOCK will cause the function to return a -1 and set errno to [EACCES] error if the section is already locked by anoth- er process. F_ULOCK requests may, in whole or in part, release one or more locked sections controlled by the process. When sec- tions are not fully released, the remaining sections are still locked by the process. Releasing the center section of a locked section requires an additional element in the table of active locks. If this table is full, an [EDEADLK] error is returned and the requested section 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 lock or fcntl 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. Sleeping on a resource is interrupted with any signal. The alarm(2) command 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. Oth- erwise, a value of -1 is returned and errno is set to indi- cate the error. ERRORS The lockf utility will fail if one or more of the following are true: [EBADF] fildes is not a valid open descriptor. [EACCES] function is F_TLOCK or F_TEST and the section is already locked by another process. [EDEADLK] function is F_LOCK or F_TLOCK and a deadlock 2 April, 1990
lockf(3C) lockf(3C)would occur. Also the function is either of the above or F_ULOCK and the number of entries in the lock table would exceed the number allocated on the system. [EREMOTE] fildes is a file descriptor referring to a file on a remotely mounted file system. CAVEATS 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 is the most common source of unexpected buffering. SEE ALSO close(2), creat(2), fcntl(2), intro(2), locking(2), open(2), read(2), write(2). April, 1990 3