lockfx, lockf, flock, or lockf64 Subroutine

Purpose

Locks and unlocks sections of open files.

Libraries

lockfx, lockf: Standard C Library (libc.a)

Item Description
flock: Berkeley Compatibility Library (libbsd.a)

Syntax

#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;

Description

Attention: Buffered I/O does not work properly when used with file locking. Do not use the standard I/O package routines on files that are going to be locked.

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.

Parameters

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:
F_SETLK
Sets or clears a file lock. The l_type field of the flock structure indicates whether to establish or remove a read or write lock. If a read or write lock cannot be set, the lockfx subroutine returns immediately with an error value of -1.
F_SETLKW
Performs the same function as F_SETLK unless a read or write lock is blocked by existing locks. In that case, the process sleeps until the section of the file is free to be locked.
F_GETLK
Gets the first lock that blocks the lock described in the flock structure. If a lock is found, the retrieved information overwrites the information in the flock structure. If no lock is found that would prevent this lock from being created, the structure is passed back unchanged except that the l_type field is set to F_UNLCK.
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:
LOCK_SH
Apply a shared (read) lock.
LOCK_EX
Apply an exclusive (write) lock.
LOCK_NB
Do not block when locking. This value can be logically ORed with either LOCK_SH or LOCK_EX.
LOCK_UN
Remove a lock.
Request Specifies one of the following constants for the lockf subroutine:
F_ULOCK
Unlocks a previously locked region in the file.
F_LOCK
Locks the region for exclusive (write) use. This request causes the calling process to sleep if the requested region overlaps a locked region, and to resume when granted the lock.
F_TEST
Tests to see if another process has already locked a region. The lockf subroutine returns 0 if the region is unlocked. If the region is locked, then -1 is returned and the errno global variable is set to EACCES.
F_TLOCK
Locks the region for exclusive use if another process has not already locked the region. If the region has already been locked by another process, the lockf subroutine returns a -1 and the errno global variable is set to EACCES.
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.

Return Values

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.

Error Codes

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.