./_Man_SunOS_4.1.3_html/html3/lockf.3.html

Manual page for LOCKF(3)

lockf - record locking on files

SYNOPSIS

#include <unistd.h>

int lockf(fd, cmd, size) int fd, cmd; long size;

DESCRIPTION

lockf() places, removes, and tests for exclusive locks on sections of files. These locks are either advisory or mandatory depending on the mode bits of the file. The lock is mandatory if the set-GID bit (S_ISGID) is set and the group execute bit (S_IXGRP) is clear (see stat.2v for information about mode bits). Otherwise, the lock is advisory.

If a process holds a mandatory exclusive lock on a segment of a file, both read and write operations block until the lock is removed (see WARNINGS).

An advisory lock does not affect read and write access to the locked segment. Advisory locks may be used by cooperating processes checking for locks using F_GETLCK and voluntarily observing the indicated read and write restrictions.

A locking call on an already locked file section fails, returning an error value or putting the call to sleep until that file section is unlocked. All the locks on a process are removed when that process terminates. See fcntl.2v for more information about record locking.

fd is an open file descriptor. It must have O_WRONLY or O_RDWR permission for a successful locking call.

cmd is a control value which specifies the action to be taken. The accepted values for cmd 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 (non-blocking) */
#define	F_TEST		3	/* Test section for other process' locks */

F_TEST returns -1 and sets errno to EACCES if a lock by another process already exists on the specified section. Otherwise, it returns 0. F_LOCK and F_TLOCK lock available file sections. F_ULOCK removes locks from file sections.

All other values of cmd are reserved for future applications and, until implemented, return an error.

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 size bytes if size is positive, and extends backward size bytes (the preceding bytes up to but not including the current offset) if size is negative. If size is zero, the section from the current offset through the largest file offset is locked (that is, from the current offset through the present or any future EOF). An area need not be allocated to the file to be locked, such a lock may exist after the EOF.

Sections locked with F_LOCK or F_TLOCK may contain all or part of an already locked section. They may also be partially or completely contained by an already locked section. Where these overlapping or adjacent locked sections occur, they are combined into a single section. If the table of active locks is full, a lock request requiring an additional table entry fails and an error value is returned.

F_LOCK and F_TLOCK differ only in their response to requests for unavailable resources. If a section is already locked, F_LOCK directs the calling process to sleep until the resource is available, F_TLOCK directs the function to return -1 and set errno to EACCES (see ERRORS).

When a F_ULOCK request releases part of a section with overlapping locks, the remaining section or sections retain the lock. If F_ULOCK removes the center of a locked section, the two separate locked sections remain, but an additional element is required in the table of active locks. If this table is full, errno is set to ENOLCK and the requested section is not released.

The danger of a deadlock exists when a process controlling a locked resource is put to sleep by requesting an unavailable resource. To avoid this danger, lockf() and fcntl() scan for this conflict before putting a locked resource to sleep. If a deadlock would result, an error value is returned.

The sleep process can be interrupted with any signal. alarm.3v may be used to provide a timeout facility where needed.

RETURN VALUES

lockf() returns:

0: on success.
-1: on failure and sets errno to indicate the error.

ERRORS

EACCES: cmd is F_TLOCK or F_TEST and the section is already locked by another process.
: Note: In future, lockf() may generate EAGAIN under these conditions, so applications testing for EACCES should also test for EAGAIN.
EBADF: fd is not a valid open descriptor.
: cmd is F_LOCK or F_TLOCK and the process does not have write permission on the file.
EDEADLK: cmd is F_LOCK and a deadlock would occur.
EINTR: cmd is F_LOCK and a signal interrupted the process while it was waiting to complete the lock.
ENOLCK: cmd is F_LOCK, F_TLOCK, or F_ULOCK and there are no more file lock entries available.

WARNINGS

Mandatory record locks are dangerous. If a runaway or otherwise out-of-control process should hold a mandatory lock on a file critical to the system and fail to release that lock, the entire system could hang or crash. For this reason, mandatory record locks may be removed in a future SunOS release.n Use advisory record locking whenever possible.

NOTES

A child process does not inherit locks from its parent on fork.2v

BUGS

lockf() locks do not interact in any way with locks granted by flock(), but are compatible with locks granted by fcntl().