Locks and unlocks sections of open files.
lockfx, lockf: Standard C Library (libc.a)
Item | Description |
---|---|
flock: | Berkeley Compatibility Library (libbsd.a) |
#include <fcntl.h>
int lockfx (FileDescriptor,
Command, Argument)
int FileDescriptor;
int Command;
struct flock * Argument;
#include <sys/lockf.h>
#include <unistd.h>
int lockf
(FileDescriptor, Request, Size)
int FileDescriptor;
int Request;
off_t Size;
int lockf64 (FileDescriptor,
Request, Size)
int FileDescriptor;
int Request;
off64_t Size;
#include <sys/file.h>
int flock (FileDescriptor, Operation)
int FileDescriptor;
int Operation;
The lockfx subroutine locks and unlocks sections of an open file. The lockfx subroutine provides a subset of the locking function provided by the fcntl (fcntl, dup, or dup2 Subroutine) subroutine.
The lockf subroutine also locks and unlocks sections of an open file. However, its interface is limited to setting only write (exclusive) locks.
Although the lockfx, lockf, flock, and fcntl interfaces are all different, their implementations are fully integrated. Therefore, locks obtained from one subroutine are honored and enforced by any of the lock subroutines.
The Operation parameter to the lockfx subroutine, which creates the lock, determines whether it is a read lock or a write lock.
The file descriptor on which a write lock is being placed must have been opened with write access.
lockf64 is equivalent to lockf except that a 64-bit lock request size can be given. For lockf, the largest value which can be used is OFF_MAX, for lockf64, the largest value is LONGLONG_MAX.
In the large file enabled programming environment, lockf is redefined to be lock64.
The flock subroutine locks and unlocks entire files. This is a limited interface maintained for BSD compatibility, although its behavior differs from BSD in a few subtle ways. To apply a shared lock, the file must be opened for reading. To apply an exclusive lock, the file must be opened for writing.
Locks are not inherited. Therefore, a child process cannot unlock a file locked by the parent process.
Item | Description |
---|---|
Argument | A pointer to a structure of type flock, defined in the flock.h file. |
Command | Specifies one of the following constants for the lockfx subroutine:
|
FileDescriptor | A file descriptor returned by a successful open or fcntl subroutine, identifying the file to which the lock is to be applied or removed. |
Operation | Specifies one of the following constants for the flock subroutine:
|
Request | Specifies one of the following constants for the lockf subroutine:
|
Size | The number of bytes to be locked or unlocked for the lockf subroutine. The region starts at the current location in the open file, and extends forward if the Size value is positive and backward if the Size value is negative. If the Size value is 0, the region starts at the current location and extends forward to the maximum possible file size, including the unallocated space after the end of the file. |
Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.
The lockfx, lockf, and flock subroutines fail if one of the following is true:
Item | Description |
---|---|
EBADF | The FileDescriptor parameter is not a valid open file descriptor. |
EINVAL | The function argument is not one of F_LOCK, F_TLOCK, F_TEST or F_ULOCK; or size plus the current file offset is less than 0. |
EINVAL | An attempt was made to lock a fifo or pipe. |
EDEADLK | The lock is blocked by a lock from another process. Putting the calling process to sleep while waiting for the other lock to become free would cause a deadlock. |
ENOLCK | The lock table is full. Too many regions are already locked. |
EINTR | The command parameter was F_SETLKW and the process received a signal while waiting to acquire the lock. |
EOVERFLOW | The offset of the first, or if size is not 0 then the last, byte in the requested section cannot be represented correctly in an object of type off_t. |
The lockfx and lockf subroutines fail if one of the following is true:
Item | Description |
---|---|
EACCES | The Command parameter is F_SETLK, the l_type field is F_RDLCK, and the segment of the file to be locked is already write-locked by another process. |
EACCES | The Command parameter is F_SETLK, the l_type field is F_WRLCK, and the segment of a file to be locked is already read-locked or write-locked by another process. |
The flock subroutine fails if the following is true:
Item | Description |
---|---|
EWOULDBLOCK | The file is locked and the LOCK_NB option was specified. |