lockf()

Lock or unlock a section of a file

Synopsis:

#include <unistd.h>

int lockf( int filedes,
           int function,
           off_t size );

Arguments:

fildes

The file descriptor for the file that you want to lock. Open the file with write-only permission (O_WRONLY) or with read/write permission (O_RDWR).

function

A control value that specifies the action to be taken. The permissible values (defined in <unistd.h>) are as follows:

F_LOCK

Lock a section for exclusive use if the section is available. A read-only lock is one of O_RDONLY, O_WRONLY, or O_RDWR. An exclusive lock is one of O_WRONLY, or O_RDWR. (For descriptions of the locks, see open()).

F_TEST

Test a specified section for locks obtained by other processes.

F_TLOCK

Test and lock a section for exclusive use if the section is available.

F_ULOCK

Remove locks from a specified section of the file.

size

The number of contiguous bytes that you want to lock or unlock. The section to be locked or unlocked starts at the current offset in the file and extends forward for a positive size or backward for a negative size (the preceding bytes up to but not including the current offset). If size is 0, the section from the current offset through the largest possible file offset is locked (that is, from the current offset through to the present or any future end-of-file). An area need not be allocated to the file to be locked because locks may exist past the end-of-file.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

You can use the lockf() function to lock a section of a file, using advisory-mode locks. If other threads call lockf() to try to lock the locked file section, those calls either return an error value or block until the section becomes unlocked.

All the locks for a process are removed when the process terminates. Record locking with lockf() is supported for regular files and may be supported for other files.

The sections locked with F_LOCK or F_TLOCK may in whole or in part, contain or be contained by a previously locked section for the same process. When this occurs, or if adjacent locked sections occur, the sections are combined into a single locked section.

File locks are released on the first close by the locking process of any file descriptor for the file.

F_ULOCK requests may release (wholly or in part) one or more locked sections controlled by the process. Locked sections are unlocked starting at the current file offset through size bytes or to the end of file if size is (off_t)0. When all of a locked section isn't released (that is, when the beginning or end of the area to be unlocked falls within a locked section), the remaining portions of that section are still locked by the process. Releasing the center portion of a locked section causes the remaining locked beginning and end portions to become two separate locked sections.

A potential for deadlock occurs if the threads of a process controlling a locked section are blocked by accessing another process's locked section. If the system detects that deadlock could occur, lockf() fails with EDEADLK.

The interaction between fcntl() and lockf() locks is unspecified. Blocking on a section is interrupted by any signal.

If size is the maximum value of type off_t and the process has an existing lock of size 0 in this range (indicating a lock on the entire file), then an F_ULOCK request is treated the same as an F_ULOCK request of size 0. Otherwise an F_ULOCK request attempts to unlock only the requested section. Attempting to lock a section of a file that's associated with a buffered stream produces unspecified results.

Returns:

0

Success.

-1

An error occurred (errno is set). Existing locks aren't changed.

Errors:

EACCES or EAGAIN

The function argument is F_TLOCK or F_TEST and the section is already locked by another process.

EAGAIN

The function argument is F_LOCK or F_TLOCK and the file is mapped with mmap().

EBADF

The fildes argument isn't a valid open file descriptor; or function is F_LOCK or F_TLOCK and fildes isn't a valid file descriptor open for writing.

EDEADLK

The function argument is F_LOCK and a deadlock is detected.

EINTR

A signal was caught during execution of the function.

EINVAL

The function argument isn't one of F_LOCK, F_TLOCK, F_TEST or F_ULOCK; or size plus the current file offset is less than 0.

ENOMEM

The system can't allocate sufficient memory to store lock resources.

EOPNOTSUPP or EINVAL

The implementation doesn't support the locking of files of the type indicated by fildes.

EOVERFLOW

The offset of the first, or if size isn't 0 then the last, byte in the requested section can't be represented correctly in an object of type off_t.

Classification:

POSIX 1003.1 XSI

See also:

fcntl(), flock(), open()