lockf

Syntax

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

Description

The lockf function is a simplified interface to the locking facilities of fcntl (see fcntl, for more detailed information).

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:

#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 locks */

All other values of function are reserved for future extensions and will result in an error return if not implemented, with errno set to EINVAL.

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 section from the current offset through the largest file offset is locked (i.e. from the current offset through the end of file).

The functions defined for lockf are as follows:

F_TEST

This function is used to detect if the specified section is already locked.

F_LOCK

F_TLOCK

F_LOCK and F_TLOCK both lock a section of a file, if the section is available. These two function requests differ only by the action taken if the resource is not available. F_LOCK will cause the calling program to wait until the resource is available. F_TLOCK will cause the function to return a -1 and set errno to EACCES if the section is already locked.

F_ULOCK

F_ULOCK removes locks from a section of the file. This function will release locked sections controlled by the program.

The lockf function will fail, returning -1 and setting errno to the following error values if the associated condition is true:

EBADF

Parameter fildes is not a valid open file.

EACCES

Parameter function is F_TLOCK or F_TEST and the section is already locked.

EINVAL

Parameter function is not one of the implemented functions. Or: An attempt was made to lock a directory, which is not supported.

All lock requests in this implementation are coded as exclusive locks (i.e. all locks use the fcntl request F_WRLCK).

It is therefore wise to code lockf by using function F_TLOCK with all lock requests, and to test the return value to determine if the lock was obtained or not. Using F_TLOCK will cause the implementation to use F_SETLK instead of F_SETLKW, which will return an error if the lock cannot be obtained.

Return Value

On success, zero is returned. On error, -1 is returned, and errno is set appropriately, as described above.

Portability

ANSI/ISO C	No
POSIX	No

Example

/* Request a lock on file handle fd from the current position to the end of the file */ errno = 0; retval = lockf(fd, F_LOCK, 0); /* Request a non-blocking lock on file handle fd */ errno = 0; retval = lockf(fd, F_TLOCK, 0); /* Test a lock on file handle fd */ errno = 0; retval = lockf(fd, F_TEST, 0); /* Release a lock on file handle fd */ errno = 0; retval = lockf(fd, F_ULOCK, 0);