# F_GETLEASE

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



       **Leases**
           **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**
                         Take out 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**
                         Take out 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).
    


## STANDARDS



           Linux.
    


* * *