# fcntl_locking

## NAME



           F_GETLK, F_SETLK, F_SETLKW, F_OFD_GETLK, F_OFD_SETLK, F_OFD_SETLKW
           - locking
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <fcntl.h>**
    
           **int fcntl(int** _fd_**, F_GETLK, struct flock ***_lock_**);**
           **int fcntl(int** _fd_**, F_SETLK, const struct flock ***_lock_**);**
           **int fcntl(int** _fd_**, F_SETLKW, const struct flock ***_lock_**);**
    
           **int fcntl(int** _fd_**, F_OFD_GETLK, struct flock ***_lock_**);**
           **int fcntl(int** _fd_**, F_OFD_SETLK, const struct flock ***_lock_**);**
           **int fcntl(int** _fd_**, F_OFD_SETLKW, const struct flock ***_lock_**);**
    


## DESCRIPTION



       **Advisory record locking**
           Linux implements traditional ("process-associated") UNIX record
           locks, as standardized by POSIX.  For a Linux-specific alternative
           with better semantics, see the discussion of open file description
           locks below.
    
           **F_SETLK** , **F_SETLKW** , and **F_GETLK** are used to acquire, release, and
           test for the existence of record locks (also known as byte-range,
           file-segment, or file-region locks).  The third argument, _lock_ , is
           a pointer to a structure that has at least the following fields
           (in unspecified order).
    
               struct flock {
                   ...
                   short l_type;    /* Type of lock: F_RDLCK,
                                       F_WRLCK, F_UNLCK */
                   short l_whence;  /* How to interpret l_start:
                                       SEEK_SET, SEEK_CUR, SEEK_END */
                   off_t l_start;   /* Starting offset for lock */
                   off_t l_len;     /* Number of bytes to lock */
                   pid_t l_pid;     /* PID of process blocking our lock
                                       (set by F_GETLK and F_OFD_GETLK) */
                   ...
               };
    
           The _l_whence_ , _l_start_ , and _l_len_ fields of this structure specify
           the range of bytes we wish to lock.  Bytes past the end of the
           file may be locked, but not bytes before the start of the file.
    
           _l_start_ is the starting offset for the lock, and is interpreted
           relative to either: the start of the file (if _l_whence_ is
           **SEEK_SET**); the current file offset (if _l_whence_ is **SEEK_CUR**); or
           the end of the file (if _l_whence_ is **SEEK_END**).  In the final two
           cases, _l_start_ can be a negative number provided the offset does
           not lie before the start of the file.
    
           _l_len_ specifies the number of bytes to be locked.  If _l_len_ is
           positive, then the range to be locked covers bytes _l_start_ up to
           and including _l_start_ +_l_len_ -1.  Specifying 0 for _l_len_ has the
           special meaning: lock all bytes starting at the location specified
           by _l_whence_ and _l_start_ through to the end of file, no matter how
           large the file grows.
    
           POSIX.1-2001 allows (but does not require) an implementation to
           support a negative _l_len_ value; if _l_len_ is negative, the interval
           described by _lock_ covers bytes _l_start_ +_l_len_ up to and including
           _l_start_ -1.  This is supported since Linux 2.4.21 and Linux 2.5.49.
    
           The _l_type_ field can be used to place a read (**F_RDLCK**) or a write
           (**F_WRLCK**) lock on a file.  Any number of processes may hold a read
           lock (shared lock) on a file region, but only one process may hold
           a write lock (exclusive lock).  An exclusive lock excludes all
           other locks, both shared and exclusive.  A single process can hold
           only one type of lock on a file region; if a new lock is applied
           to an already-locked region, then the existing lock is converted
           to the new lock type.  (Such conversions may involve splitting,
           shrinking, or coalescing with an existing lock if the byte range
           specified by the new lock does not precisely coincide with the
           range of the existing lock.)
    
           **F_SETLK**
                  Acquire a lock (when _l_type_ is **F_RDLCK** or **F_WRLCK**) or
                  release a lock (when _l_type_ is **F_UNLCK**) on the bytes
                  specified by the _l_whence_ , _l_start_ , and _l_len_ fields of
                  _lock_.  If a conflicting lock is held by another process,
                  this call returns -1 and sets _errno_ to **EACCES** or **EAGAIN**.
                  (The error returned in this case differs across
                  implementations, so POSIX requires a portable application
                  to check for both errors.)
    
           **F_SETLKW**
                  As for **F_SETLK** , but if a conflicting lock is held on the
                  file, then wait for that lock to be released.  If a signal
                  is caught while waiting, then the call is interrupted and
                  (after the signal handler has returned) returns immediately
                  (with return value -1 and _errno_ set to **EINTR** ; see
                  signal(7)).
    
           **F_GETLK**
                  On input to this call, _lock_ describes a lock we would like
                  to place on the file.  If the lock could be placed, **fcntl**()
                  does not actually place it, but returns **F_UNLCK** in the
                  _l_type_ field of _lock_ and leaves the other fields of the
                  structure unchanged.
    
                  If one or more incompatible locks would prevent this lock
                  being placed, then **fcntl**() returns details about one of
                  those locks in the _l_type_ , _l_whence_ , _l_start_ , and _l_len_
                  fields of _lock_.  If the conflicting lock is a traditional
                  (process-associated) record lock, then the _l_pid_ field is
                  set to the PID of the process holding that lock.  If the
                  conflicting lock is an open file description lock, then
                  _l_pid_ is set to -1.  Note that the returned information may
                  already be out of date by the time the caller inspects it.
    
           In order to place a read lock, _fd_ must be open for reading.  In
           order to place a write lock, _fd_ must be open for writing.  To
           place both types of lock, open a file read-write.
    
           When placing locks with **F_SETLKW** , the kernel detects _deadlocks_ ,
           whereby two or more processes have their lock requests mutually
           blocked by locks held by the other processes.  For example,
           suppose process A holds a write lock on byte 100 of a file, and
           process B holds a write lock on byte 200.  If each process then
           attempts to lock the byte already locked by the other process
           using **F_SETLKW** , then, without deadlock detection, both processes
           would remain blocked indefinitely.  When the kernel detects such
           deadlocks, it causes one of the blocking lock requests to
           immediately fail with the error **EDEADLK** ; an application that
           encounters such an error should release some of its locks to allow
           other applications to proceed before attempting regain the locks
           that it requires.  Circular deadlocks involving more than two
           processes are also detected.  Note, however, that there are
           limitations to the kernel's deadlock-detection algorithm; see
           BUGS.
    
           As well as being removed by an explicit **F_UNLCK** , record locks are
           automatically released when the process terminates.
    
           Record locks are not inherited by a child created via fork(2), but
           are preserved across an execve(2).
    
           Because of the buffering performed by the stdio(3) library, the
           use of record locking with routines in that package should be
           avoided; use read(2) and write(2) instead.
    
           The record locks described above are associated with the process
           (unlike the open file description locks described below).  This
           has some unfortunate consequences:
    
           •  If a process closes _any_ file descriptor referring to a file,
              then all of the process's locks on that file are released,
              regardless of the file descriptor(s) on which the locks were
              obtained.  This is bad: it means that a process can lose its
              locks on a file such as _/etc/passwd_ or _/etc/mtab_ when for some
              reason a library function decides to open, read, and close the
              same file.
    
           •  The threads in a process share locks.  In other words, a
              multithreaded program can't use record locking to ensure that
              threads don't simultaneously access the same region of a file.
    
           Open file description locks solve both of these problems.
    
       **Open file description locks (non-POSIX)**
           Open file description locks are advisory byte-range locks whose
           operation is in most respects identical to the traditional record
           locks described above.  This lock type is Linux-specific, and
           available since Linux 3.15.  (There is a proposal with the Austin
           Group to include this lock type in the next revision of POSIX.1.)
           For an explanation of open file descriptions, see open(2).
    
           The principal difference between the two lock types is that
           whereas traditional record locks are associated with a process,
           open file description locks are associated with the open file
           description on which they are acquired, much like locks acquired
           with flock(2).  Consequently (and unlike traditional advisory
           record locks), open file description locks are inherited across
           fork(2) (and clone(2) with **CLONE_FILES**), and are only
           automatically released on the last close of the open file
           description, instead of being released on any close of the file.
    
           Conflicting lock combinations (i.e., a read lock and a write lock
           or two write locks) where one lock is an open file description
           lock and the other is a traditional record lock conflict even when
           they are acquired by the same process on the same file descriptor.
    
           Open file description locks placed via the same open file
           description (i.e., via the same file descriptor, or via a
           duplicate of the file descriptor created by fork(2), dup(2),
           F_DUPFD(2const), and so on) are always compatible: if a new lock
           is placed on an already locked region, then the existing lock is
           converted to the new lock type.  (Such conversions may result in
           splitting, shrinking, or coalescing with an existing lock as
           discussed above.)
    
           On the other hand, open file description locks may conflict with
           each other when they are acquired via different open file
           descriptions.  Thus, the threads in a multithreaded program can
           use open file description locks to synchronize access to a file
           region by having each thread perform its own open(2) on the file
           and applying locks via the resulting file descriptor.
    
           As with traditional advisory locks, the third argument to **fcntl**(),
           _lock_ , is a pointer to an _flock_ structure.  By contrast with
           traditional record locks, the _l_pid_ field of that structure must
           be set to zero when using the operations described below.
    
           The operations for working with open file description locks are
           analogous to those used with traditional locks:
    
           **F_OFD_SETLK**
                  Acquire an open file description lock (when _l_type_ is
                  **F_RDLCK** or **F_WRLCK**) or release an open file description
                  lock (when _l_type_ is **F_UNLCK**) on the bytes specified by the
                  _l_whence_ , _l_start_ , and _l_len_ fields of _lock_.  If a
                  conflicting lock is held by another process, this call
                  returns -1 and sets _errno_ to **EAGAIN**.
    
           **F_OFD_SETLKW**
                  As for **F_OFD_SETLK** , but if a conflicting lock is held on
                  the file, then wait for that lock to be released.  If a
                  signal is caught while waiting, then the call is
                  interrupted and (after the signal handler has returned)
                  returns immediately (with return value -1 and _errno_ set to
                  **EINTR** ; see signal(7)).
    
           **F_OFD_GETLK**
                  On input to this call, _lock_ describes an open file
                  description lock we would like to place on the file.  If
                  the lock could be placed, **fcntl**() does not actually place
                  it, but returns **F_UNLCK** in the _l_type_ field of _lock_ and
                  leaves the other fields of the structure unchanged.  If one
                  or more incompatible locks would prevent this lock being
                  placed, then details about one of these locks are returned
                  via _lock_ , as described above for **F_GETLK**.
    
           In the current implementation, no deadlock detection is performed
           for open file description locks.  (This contrasts with process-
           associated record locks, for which the kernel does perform
           deadlock detection.)
    
       **Mandatory locking**
           _Warning_ : the Linux implementation of mandatory locking is
           unreliable.  See BUGS below.  Because of these bugs, and the fact
           that the feature is believed to be little used, since Linux 4.5,
           mandatory locking has been made an optional feature, governed by a
           configuration option (**CONFIG_MANDATORY_FILE_LOCKING**).  This
           feature is no longer supported at all in Linux 5.15 and above.
    
           By default, both traditional (process-associated) and open file
           description record locks are advisory.  Advisory locks are not
           enforced and are useful only between cooperating processes.
    
           Both lock types can also be mandatory.  Mandatory locks are
           enforced for all processes.  If a process tries to perform an
           incompatible access (e.g., read(2) or write(2)) on a file region
           that has an incompatible mandatory lock, then the result depends
           upon whether the **O_NONBLOCK** flag is enabled for its open file
           description.  If the **O_NONBLOCK** flag is not enabled, then the
           system call is blocked until the lock is removed or converted to a
           mode that is compatible with the access.  If the **O_NONBLOCK** flag
           is enabled, then the system call fails with the error **EAGAIN**.
    
           To make use of mandatory locks, mandatory locking must be enabled
           both on the filesystem that contains the file to be locked, and on
           the file itself.  Mandatory locking is enabled on a filesystem
           using the "-o mand" option to mount(8), or the **MS_MANDLOCK** flag
           for mount(2).  Mandatory locking is enabled on a file by disabling
           group execute permission on the file and enabling the set-group-ID
           permission bit (see chmod(1) and chmod(2)).
    
           Mandatory locking is not specified by POSIX.  Some other systems
           also support mandatory locking, although the details of how to
           enable it vary across systems.
    
       **Lost locks**
           When an advisory lock is obtained on a networked filesystem such
           as NFS it is possible that the lock might get lost.  This may
           happen due to administrative action on the server, or due to a
           network partition (i.e., loss of network connectivity with the
           server) which lasts long enough for the server to assume that the
           client is no longer functioning.
    
           When the filesystem determines that a lock has been lost, future
           read(2) or write(2) requests may fail with the error **EIO**.  This
           error will persist until the lock is removed or the file
           descriptor is closed.  Since Linux 3.12, this happens at least for
           NFSv4 (including all minor versions).
    
           Some versions of UNIX send a signal (**SIGLOST**) in this
           circumstance.  Linux does not define this signal, and does not
           provide any asynchronous notification of lost locks.
    


## RETURN VALUE



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


## ERRORS



           See fcntl(2).
    
           **EBADF** _op_ is **F_SETLK** or **F_SETLKW** and the file descriptor open mode
                  doesn't match with the type of lock requested.
    
           **EDEADLK**
                  It was detected that the specified **F_SETLKW** operation would
                  cause a deadlock.
    
           **EFAULT** _lock_ is outside your accessible address space.
    
           **EINTR** _op_ is **F_SETLKW** or **F_OFD_SETLKW** and the operation was
                  interrupted by a signal; see signal(7).
    
           **EINTR** _op_ is **F_GETLK** , **F_SETLK** , **F_OFD_GETLK** , or **F_OFD_SETLK** , and
                  the operation was interrupted by a signal before the lock
                  was checked or acquired.  Most likely when locking a remote
                  file (e.g., locking over NFS), but can sometimes happen
                  locally.
    
           **EINVAL** _op_ is **F_OFD_SETLK** , **F_OFD_SETLKW** , or **F_OFD_GETLK** , and _l_pid_
                  was not specified as zero.
    
           **ENOLCK** Too many segment locks open, lock table is full, or a
                  remote locking protocol failed (e.g., locking over NFS).
    


## STANDARDS



           POSIX.1-2008.
    
           **F_OFD_SETLK** , **F_OFD_SETLKW** , and **F_OFD_GETLK** are Linux-specific (and
           one must define **_GNU_SOURCE** to obtain their definitions), but work
           is being done to have them included in the next version of
           POSIX.1.
    


## NOTES



       **File locking**
           The original Linux **fcntl**() system call was not designed to handle
           large file offsets (in the _flock_ structure).  Consequently, an
           **fcntl64**() system call was added in Linux 2.4.  The newer system
           call employs a different structure for file locking, _flock64_ , and
           corresponding operations, **F_GETLK64** , **F_SETLK64** , and **F_SETLKW64**.
           However, these details can be ignored by applications using glibc,
           whose **fcntl**() wrapper function transparently employs the more
           recent system call where it is available.
    
       **Record locks**
           Since Linux 2.0, there is no interaction between the types of lock
           placed by flock(2) and **fcntl**().
    
           Several systems have more fields in _struct flock_ such as, for
           example, _l_sysid_ (to identify the machine where the lock is held).
           Clearly, _l_pid_ alone is not going to be very useful if the process
           holding the lock may live on a different machine; on Linux, while
           present on some architectures (such as MIPS32), this field is not
           used.
    
           The original Linux **fcntl**() system call was not designed to handle
           large file offsets (in the _flock_ structure).  Consequently, an
           **fcntl64**() system call was added in Linux 2.4.  The newer system
           call employs a different structure for file locking, _flock64_ , and
           corresponding operations, **F_GETLK64** , **F_SETLK64** , and **F_SETLKW64**.
           However, these details can be ignored by applications using glibc,
           whose **fcntl**() wrapper function transparently employs the more
           recent system call where it is available.
    
       **Record locking and NFS**
           Before Linux 3.12, if an NFSv4 client loses contact with the
           server for a period of time (defined as more than 90 seconds with
           no communication), it might lose and regain a lock without ever
           being aware of the fact.  (The period of time after which contact
           is assumed lost is known as the NFSv4 leasetime.  On a Linux NFS
           server, this can be determined by looking at
           _/proc/fs/nfsd/nfsv4leasetime_ , which expresses the period in
           seconds.  The default value for this file is 90.)  This scenario
           potentially risks data corruption, since another process might
           acquire a lock in the intervening period and perform file I/O.
    
           Since Linux 3.12, if an NFSv4 client loses contact with the
           server, any I/O to the file by a process which "thinks" it holds a
           lock will fail until that process closes and reopens the file.  A
           kernel parameter, _nfs.recover_lost_locks_ , can be set to 1 to
           obtain the pre-3.12 behavior, whereby the client will attempt to
           recover lost locks when contact is reestablished with the server.
           Because of the attendant risk of data corruption, this parameter
           defaults to 0 (disabled).
    


## BUGS



       **Deadlock detection**
           The deadlock-detection algorithm employed by the kernel when
           dealing with **F_SETLKW** requests can yield both false negatives
           (failures to detect deadlocks, leaving a set of deadlocked
           processes blocked indefinitely) and false positives (**EDEADLK**
           errors when there is no deadlock).  For example, the kernel limits
           the lock depth of its dependency search to 10 steps, meaning that
           circular deadlock chains that exceed that size will not be
           detected.  In addition, the kernel may falsely indicate a deadlock
           when two or more processes created using the clone(2) **CLONE_FILES**
           flag place locks that appear (to the kernel) to conflict.
    
       **Mandatory locking**
           The Linux implementation of mandatory locking is subject to race
           conditions which render it unreliable: a write(2) call that
           overlaps with a lock may modify data after the mandatory lock is
           acquired; a read(2) call that overlaps with a lock may detect
           changes to data that were made only after a write lock was
           acquired.  Similar races exist between mandatory locks and
           mmap(2).  It is therefore inadvisable to rely on mandatory
           locking.
    


* * *