summaryrefslogtreecommitdiffstats
path: root/man3/lockf.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/lockf.3')
-rw-r--r--man3/lockf.3179
1 files changed, 179 insertions, 0 deletions
diff --git a/man3/lockf.3 b/man3/lockf.3
new file mode 100644
index 0000000..a4043ba
--- /dev/null
+++ b/man3/lockf.3
@@ -0,0 +1,179 @@
+'\" t
+.\" Copyright 1997 Nicolás Lichtmaier <nick@debian.org>
+.\" Created Thu Aug 7 00:44:00 ART 1997
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" Added section stuff, aeb, 2002-04-22.
+.\" Corrected include file, drepper, 2003-06-15.
+.\"
+.TH lockf 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+lockf \- apply, test or remove a POSIX lock on an open file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.BI "int lockf(int " fd ", int " cmd ", off_t " len );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR lockf ():
+.nf
+ _XOPEN_SOURCE >= 500
+.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+ || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+ || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+Apply, test, or remove a POSIX lock on a section of an open file.
+The file is specified by
+.IR fd ,
+a file descriptor open for writing, the action by
+.IR cmd ,
+and the section consists of byte positions
+.IR pos .. pos + len \-1
+if
+.I len
+is positive, and
+.IR pos \- len .. pos \-1
+if
+.I len
+is negative, where
+.I pos
+is the current file position, and if
+.I len
+is zero, the section extends from the current file position to
+infinity, encompassing the present and future end-of-file positions.
+In all cases, the section may extend past current end-of-file.
+.PP
+On Linux,
+.BR lockf ()
+is just an interface on top of
+.BR fcntl (2)
+locking.
+Many other systems implement
+.BR lockf ()
+in this way, but note that POSIX.1 leaves the relationship between
+.BR lockf ()
+and
+.BR fcntl (2)
+locks unspecified.
+A portable application should probably avoid mixing calls
+to these interfaces.
+.PP
+Valid operations are given below:
+.TP
+.B F_LOCK
+Set an exclusive lock on the specified section of the file.
+If (part of) this section is already locked, the call
+blocks until the previous lock is released.
+If this section overlaps an earlier locked section,
+both are merged.
+File locks are released as soon as the process holding the locks
+closes some file descriptor for the file.
+A child process does not inherit these locks.
+.TP
+.B F_TLOCK
+Same as
+.B F_LOCK
+but the call never blocks and returns an error instead if the file is
+already locked.
+.TP
+.B F_ULOCK
+Unlock the indicated section of the file.
+This may cause a locked section to be split into two locked sections.
+.TP
+.B F_TEST
+Test the lock: return 0 if the specified section
+is unlocked or locked by this process; return \-1, set
+.I errno
+to
+.B EAGAIN
+.RB ( EACCES
+on some other systems),
+if another process holds a lock.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.BR EACCES " or " EAGAIN
+The file is locked and
+.B F_TLOCK
+or
+.B F_TEST
+was specified, or the operation is prohibited because the file has
+been memory-mapped by another process.
+.TP
+.B EBADF
+.I fd
+is not an open file descriptor; or
+.I cmd
+is
+.B F_LOCK
+or
+.B F_TLOCK
+and
+.I fd
+is not a writable file descriptor.
+.TP
+.B EDEADLK
+The command was
+.B F_LOCK
+and this lock operation would cause a deadlock.
+.TP
+.B EINTR
+While waiting to acquire a lock, the call was interrupted by
+delivery of a signal caught by a handler; see
+.BR signal (7).
+.TP
+.B EINVAL
+An invalid operation was specified in
+.IR cmd .
+.TP
+.B ENOLCK
+Too many segment locks open, lock table is full.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR lockf ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.SH SEE ALSO
+.BR fcntl (2),
+.BR flock (2)
+.PP
+.I locks.txt
+and
+.I mandatory\-locking.txt
+in the Linux kernel source directory
+.I Documentation/filesystems
+(on older kernels, these files are directly under the
+.I Documentation
+directory, and
+.I mandatory\-locking.txt
+is called
+.IR mandatory.txt )