HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |NOTES |BUGS |SEE ALSO |COLOPHON | |
fcntl_locking(2) System Calls Manualfcntl_locking(2)F_GETLK, F_SETLK, F_SETLKW, F_OFD_GETLK, F_OFD_SETLK, F_OFD_SETLKW - locking
Standard C library (libc,-lc)
#include <fcntl.h>int fcntl(intfd, F_GETLK, struct flock *lock);int fcntl(intfd, F_SETLK, const struct flock *lock);int fcntl(intfd, F_SETLKW, const struct flock *lock);int fcntl(intfd, F_OFD_GETLK, struct flock *lock);int fcntl(intfd, F_OFD_SETLK, const struct flock *lock);int fcntl(intfd, F_OFD_SETLKW, const struct flock *lock);
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, andF_GETLKare 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) */ ... }; Thel_whence,l_start, andl_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 (ifl_whence isSEEK_SET); the current file offset (ifl_whence isSEEK_CUR); or the end of the file (ifl_whence isSEEK_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. Ifl_len is positive, then the range to be locked covers bytesl_start up to and includingl_start+l_len-1. Specifying 0 forl_len has the special meaning: lock all bytes starting at the location specified byl_whence andl_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 negativel_len value; ifl_len is negative, the interval described bylock covers bytesl_start+l_len up to and includingl_start-1. This is supported since Linux 2.4.21 and Linux 2.5.49. Thel_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 (whenl_type isF_RDLCKorF_WRLCK) or release a lock (whenl_type isF_UNLCK) on the bytes specified by thel_whence,l_start, andl_len fields oflock. If a conflicting lock is held by another process, this call returns -1 and setserrno toEACCESorEAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW As forF_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 anderrno set toEINTR; seesignal(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 returnsF_UNLCKin thel_type field oflock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, thenfcntl() returns details about one of those locks in thel_type,l_whence,l_start, andl_len fields oflock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 withF_SETLKW, the kernel detectsdeadlocks, 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 usingF_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 errorEDEADLK; 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 explicitF_UNLCK, record locks are automatically released when the process terminates. Record locks are not inherited by a child created viafork(2), but are preserved across anexecve(2). Because of the buffering performed by thestdio(3) library, the use of record locking with routines in that package should be avoided; useread(2) andwrite(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 closesany 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, seeopen(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 withflock(2). Consequently (and unlike traditional advisory record locks), open file description locks are inherited acrossfork(2) (andclone(2) withCLONE_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 byfork(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 ownopen(2) on the file and applying locks via the resulting file descriptor. As with traditional advisory locks, the third argument tofcntl(),lock, is a pointer to anflock structure. By contrast with traditional record locks, thel_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 (whenl_type isF_RDLCKorF_WRLCK) or release an open file description lock (whenl_type isF_UNLCK) on the bytes specified by thel_whence,l_start, andl_len fields oflock. If a conflicting lock is held by another process, this call returns -1 and setserrno toEAGAIN.F_OFD_SETLKW As forF_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 anderrno set toEINTR; seesignal(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 returnsF_UNLCKin thel_type field oflock 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 vialock, as described above forF_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 lockingWarning: 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) orwrite(2)) on a file region that has an incompatible mandatory lock, then the result depends upon whether theO_NONBLOCKflag is enabled for its open file description. If theO_NONBLOCKflag 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 theO_NONBLOCKflag is enabled, then the system call fails with the errorEAGAIN. 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 tomount(8), or theMS_MANDLOCKflag formount(2). Mandatory locking is enabled on a file by disabling group execute permission on the file and enabling the set-group-ID permission bit (seechmod(1) andchmod(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, futureread(2) orwrite(2) requests may fail with the errorEIO. 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.Zero. On error, -1 is returned, anderrno is set to indicate the error.
Seefcntl(2).EBADFop isF_SETLKorF_SETLKWand the file descriptor open mode doesn't match with the type of lock requested.EDEADLK It was detected that the specifiedF_SETLKWoperation would cause a deadlock.EFAULTlock is outside your accessible address space.EINTRop isF_SETLKWorF_OFD_SETLKWand the operation was interrupted by a signal; seesignal(7).EINTRop isF_GETLK,F_SETLK,F_OFD_GETLK, orF_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.EINVALop isF_OFD_SETLK,F_OFD_SETLKW, orF_OFD_GETLK, andl_pid was not specified as zero.ENOLCKToo many segment locks open, lock table is full, or a remote locking protocol failed (e.g., locking over NFS).
POSIX.1-2008.F_OFD_SETLK,F_OFD_SETLKW, andF_OFD_GETLKare Linux-specific (and one must define_GNU_SOURCEto obtain their definitions), but work is being done to have them included in the next version of POSIX.1.
SVr4, 4.3BSD, POSIX.1-2001. Only the operationsF_GETLK,F_SETLK, andF_SETLKWare specified in POSIX.1-2001.
File locking The original Linuxfcntl() system call was not designed to handle large file offsets (in theflock structure). Consequently, anfcntl64() 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, andF_SETLKW64. However, these details can be ignored by applications using glibc, whosefcntl() 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 byflock(2) andfcntl(). Several systems have more fields instruct 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 Linuxfcntl() system call was not designed to handle large file offsets (in theflock structure). Consequently, anfcntl64() 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, andF_SETLKW64. However, these details can be ignored by applications using glibc, whosefcntl() 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).
Deadlock detection The deadlock-detection algorithm employed by the kernel when dealing withF_SETLKWrequests 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 theclone(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: awrite(2) call that overlaps with a lock may modify data after the mandatory lock is acquired; aread(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 andmmap(2). It is therefore inadvisable to rely on mandatory locking.
fcntl(2),flock(2),lockf(3),lslocks(8)locks.txt,mandatory-locking.txt, anddnotify.txt in the Linux kernel source directoryDocumentation/filesystems/ (on older kernels, these files are directly under theDocumentation/ directory, andmandatory-locking.txt is calledmandatory.txt)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-07-20fcntl_locking(2)Pages that refer to this page:fcntl(2)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |