F_GETLEASE(2const)

NAME
F_GETLEASE, F_SETLEASE - leases

LIBRARY
Standard C library (libc, -lc)

SYNOPSIS
#define _GNU_SOURCE
#include <fcntl.h>

int fcntl(int fd, F_SETLEASE, int arg);
int fcntl(int fd, F_GETLEASE);

DESCRIPTION
F_SETLEASE and F_GETLEASE are used to establish a new lease, and retrieve the current lease, on the open file description referred to by the file descriptor fd. A file lease provides a mechanism whereby the process holding the lease (the "lease holder") is notified (via delivery of a signal) when a process (the "lease breaker") tries to open(2) or truncate(2) the file referred to by that file descriptor.

F_SETLEASE
    Set or remove a file lease according to which of the following values is specified in the integer arg:

    F_RDLCK
        Establish a read lease. This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

    F_WRLCK
        Establish a write lease. This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

    F_UNLCK
        Remove our lease from the file.

Leases are associated with an open file description (see open(2)). This means that duplicate file descriptors (created by, for example, fork(2) or dup(2)) refer to the same lease, and this lease may be modified or released using any of these descriptors. Furthermore, the lease is released by either an explicit F_UNLCK operation on any of these duplicate file descriptors, or when all such file descriptors have been closed.

Leases may be taken out only on regular files. An unprivileged process may take out a lease only on a file whose UID (owner) matches the filesystem UID of the process. A process with the CAP_LEASE capability may take out leases on arbitrary files.

F_GETLEASE
    Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.

When a process (the "lease breaker") performs an open(2) or truncate(2) that conflicts with a lease established via F_SETLEASE, the system call is blocked by the kernel and the kernel notifies the lease holder by sending it a signal (SIGIO by default). The lease holder should respond to receipt of this signal by doing whatever cleanup is required in preparation for the file to be accessed by another process (e.g., flushing cached buffers) and then either remove or downgrade its lease. A lease is removed by performing an F_SETLEASE operation specifying arg as F_UNLCK. If the lease holder currently holds a write lease on the file, and the lease breaker is opening the file for reading, then it is sufficient for the lease holder to downgrade the lease to a read lease. This is done by performing an F_SETLEASE operation specifying arg as F_RDLCK.

If the lease holder fails to downgrade or remove the lease within the number of seconds specified in /proc/sys/fs/lease-break-time, then the kernel forcibly removes or downgrades the lease holder's lease.

Once a lease break has been initiated, F_GETLEASE returns the target lease type (either F_RDLCK or F_UNLCK, depending on what would be compatible with the lease breaker) until the lease holder voluntarily downgrades or removes the lease or the kernel forcibly does so after the lease break timer expires.

Once the lease has been voluntarily or forcibly removed or downgraded, and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed.

If the lease breaker's blocked open(2) or truncate(2) is interrupted by a signal handler, then the system call fails with the error EINTR, but the other steps still occur as described above. If the lease breaker is killed by a signal while blocked in open(2) or truncate(2), then the other steps still occur as described above. If the lease breaker specifies the O_NONBLOCK flag when calling open(2), then the call immediately fails with the error EWOULDBLOCK, but the other steps still occur as described above.

The default signal used to notify the lease holder is SIGIO, but this can be changed using the F_SETSIG operation to fcntl(). If a F_SETSIG operation is performed (even one specifying SIGIO), and the signal handler is established using SA_SIGINFO, then the handler will receive a siginfo_t structure as its second argument, and the si_fd field of this argument will hold the file descriptor of the leased file that has been accessed by another process. (This is useful if the caller holds leases against multiple files.)

RETURN VALUE

F_GETLEASE
    Type of lease held on file descriptor.

F_SETLEASE
    Zero.

On error, -1 is returned, and errno is set to indicate the error.

ERRORS
See fcntl(2).

These operations can also fail with the following error codes:

EAGAIN
    The operation is prohibited because the file is open in a way that conflicts with the requested lease.

EINVAL
    The operation is prohibited because the underlying filesystem doesn't support leases, or because fd does not represent a regular file.

STANDARDS
Linux.

HISTORY
Linux 2.4.

SEE ALSO
fcntl(2)