Technical Reference: Base Operating System and Extensions, Volume 1

lockfx, lockf, flock, or lockf64 Subroutine

Purpose

Locks and unlocks sections of open files.

Libraries

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

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;

Note: The lockf64 subroutine applies to AIX 4.2 and later releases.

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

Note: The lockf64 subroutine applies to AIX 4.2 and later releases.

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.

Parameters

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:

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:

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:

EWOULDBLOCK

The file is locked and the LOCK_NB option was specified.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

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.

Related Information

The close (close Subroutine) subroutine, exec: execl, execv, execle, execlp, execvp, or exect (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, fcntl (fcntl, dup, or dup2 Subroutine) subroutine, fork (fork, f_fork, or vfork Subroutine) subroutine, open, openx, or creat (open, openx, open64, creat, or creat64 Subroutine) subroutine.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.