proc.5: Document /proc/locks

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man5/proc.5 b/man5/proc.5
index 68ca0e16a5352acc4fd2c5be7f72a449669846eb..1da453e9a05d1009511b55c903728af5926b6ebc 100644 (file)
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -1,5 +1,5 @@
 .\" Copyright (C) 1994, 1995 by Daniel Quinlan (quinlan@yggdrasil.com)
-.\" and Copyright (C) 2002-2008 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2002-2008,2017 Michael Kerrisk <mtk.manpages@gmail.com>
 .\" with networking additions from Alan Cox (A.Cox@swansea.ac.uk)
 .\" and scsi additions from Michael Neuffer (neuffer@mail.uni-mainz.de)
 .\" and sysctl additions from Andries Brouwer (aeb@cwi.nl)
@@ -3058,6 +3058,90 @@ This file shows current file locks
 .RB ( flock "(2) and " fcntl (2))
 and leases
 .RB ( fcntl (2)).
+.IP
+An example of the content shown in this file is the following:
+.IP
+.in +4n
+.EX
+1: POSIX  ADVISORY  READ  5433 08:01:7864448 128 128
+2: FLOCK  ADVISORY  WRITE 2001 08:01:7864554 0 EOF
+3: FLOCK  ADVISORY  WRITE 1568 00:2f:32388 0 EOF
+4: POSIX  ADVISORY  WRITE 699 00:16:28457 0 EOF
+5: POSIX  ADVISORY  WRITE 764 00:16:21448 0 0
+6: POSIX  ADVISORY  READ  3548 08:01:7867240 1 1
+7: POSIX  ADVISORY  READ  3548 08:01:7865567 1826 2335
+8: OFDLCK ADVISORY  WRITE -1 08:01:8713209 128 191
+.EE
+.in
+.IP
+The fields shown in each line are as follows:
+.RS
+.IP (1) 4
+The ordinal position of the lock in the list.
+.IP (2)
+The lock type.
+Values that may appear here include:
+.RS
+.TP
+.B FLOCK
+This is a BSD file lock created using
+.BR flock (2).
+.TP
+.B OFDLCK
+This is an open file description (OFD) lock created using
+.BR fcntl (2).
+.TP
+.B POSIX
+This is a POSIX byte-range lock created using
+.BR fcntl (2).
+.RE
+.IP (3)
+Among the strings that can appear here are the following:
+.RS
+.TP
+.B ADVISORY
+This is an advisory lock.
+.TP
+.B MANDATORY
+This is a mandatory lock.
+.RE
+.IP (4)
+The type of lock.
+Values that can appear here are:
+.RS
+.TP
+.B READ
+This is a POSIX or OFD read lock, or a BSD shared lock.
+.TP
+.B WRITE
+This is a POSIX or OFD write lock, or a BSD exclusive lock.
+.RE
+.IP (5)
+The PID of the process that owns the lock.
+.IP
+Because OFD locks are not owned by a single process
+(since multiple processes may have file descriptors that
+refer to the same open file description),
+the value \-1 is displayed in this field for OFD locks.
+(Before kernel 4.14,
+.\" commit d67fd44f697dff293d7cdc29af929241b669affe
+a bug meant that the PID of the process that
+initially acquired the lock was displayed instead of the value \-1.)
+.IP (6)
+Three colon-separated subfields that identify the major and minor device
+ID of the device containing the filesystem where the locked file resides,
+followed by the inode number of the locked file.
+.IP (7)
+The byte offset of the first byte of the lock.
+For BSD locks, this value is always 0.
+.IP (8)
+The byte offset of the last byte of the lock.
+.B EOF
+in this field means that the lock extends to the end of the file.
+For BSD locks, the value shown is always
+.IR EOF .
+.RE
+.IP
 The
 .BR lslocks (8)
 command provides a bit more information about each lock.