Adding upstream version 4.23.0.upstream/4.23.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 102 insertions, 100 deletions

diff --git a/upstream/debian-unstable/man2/fcntl.2 b/upstream/debian-unstable/man2/fcntl.2
index 93620444..76a8bae0 100644
--- a/upstream/debian-unstable/man2/fcntl.2
+++ b/upstream/debian-unstable/man2/fcntl.2
@@ -44,7 +44,7 @@
 .\" 2017-06-26, Jens Axboe <axboe@kernel.dk>
 .\"     Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT
 .\"
-.TH fcntl 2 2023-03-30 "Linux man-pages 6.05.01"
+.TH fcntl 2 2024-05-02 "Linux man-pages 6.8"
 .SH NAME
 fcntl \- manipulate file descriptor
 .SH LIBRARY
@@ -53,22 +53,22 @@ Standard C library
 .SH SYNOPSIS
 .nf
 .B #include <fcntl.h>
-.PP
-.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
+.P
+.BI "int fcntl(int " fd ", int " op ", ... /* " arg " */ );"
 .fi
 .SH DESCRIPTION
 .BR fcntl ()
 performs one of the operations described below on the open file descriptor
 .IR fd .
 The operation is determined by
-.IR cmd .
-.PP
+.IR op .
+.P
 .BR fcntl ()
 can take an optional third argument.
 Whether or not this argument is required is determined by
-.IR cmd .
+.IR op .
 The required argument type is indicated in parentheses after each
-.I cmd
+.I op
 name (in most cases, the required type is
 .IR int ,
 and we identify the argument using the name
@@ -76,14 +76,14 @@ and we identify the argument using the name
 or
 .I void
 is specified if the argument is not required.
-.PP
+.P
 Certain of the operations below are supported only since a particular
 Linux kernel version.
 The preferred method of checking whether the host kernel supports
 a particular operation is to invoke
 .BR fcntl ()
 with the desired
-.I cmd
+.I op
 value and then test whether the call failed with
 .BR EINVAL ,
 indicating that the kernel does not recognize this value.
@@ -121,7 +121,7 @@ see the description of
 in
 .BR open (2).
 .SS File descriptor flags
-The following commands manipulate the flags associated with
+The following operations manipulate the flags associated with
 a file descriptor.
 Currently, only one such flag is defined:
 .BR FD_CLOEXEC ,
@@ -147,7 +147,7 @@ is ignored.
 .BR F_SETFD " (\fIint\fP)"
 Set the file descriptor flags to the value specified by
 .IR arg .
-.PP
+.P
 In multithreaded programs, using
 .BR fcntl ()
 .B F_SETFD
@@ -177,7 +177,7 @@ Duplicated file descriptors
 .BR fork (2),
 etc.) refer to the same open file description, and thus
 share the same file status flags.
-.PP
+.P
 The file status flags and their semantics are described in
 .BR open (2).
 .TP
@@ -198,7 +198,7 @@ and file creation flags
 in
 .I arg
 are ignored.
-On Linux, this command can change only the
+On Linux, this operation can change only the
 .BR O_APPEND ,
 .BR O_ASYNC ,
 .BR O_DIRECT ,
@@ -216,7 +216,7 @@ 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.
-.PP
+.P
 .BR F_SETLK ,
 .BR F_SETLKW ,
 and
@@ -227,7 +227,7 @@ The third argument,
 .IR lock ,
 is a pointer to a structure that has at least the following fields
 (in unspecified order).
-.PP
+.P
 .in +4n
 .EX
 struct flock {
@@ -244,13 +244,13 @@ struct flock {
 };
 .EE
 .in
-.PP
+.P
 The
 .IR 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.
-.PP
+.P
 .I l_start
 is the starting offset for the lock, and is interpreted
 relative to either:
@@ -270,7 +270,7 @@ In the final two cases,
 .I l_start
 can be a negative number provided the
 offset does not lie before the start of the file.
-.PP
+.P
 .I l_len
 specifies the number of bytes to be locked.
 If
@@ -285,7 +285,7 @@ has the special meaning: lock all bytes starting at the
 location specified by
 .IR l_whence " and " l_start
 through to the end of file, no matter how large the file grows.
-.PP
+.P
 POSIX.1-2001 allows (but does not require)
 an implementation to support a negative
 .I l_len
@@ -298,7 +298,7 @@ covers bytes
 up to and including
 .IR l_start \-1.
 This is supported since Linux 2.4.21 and Linux 2.5.49.
-.PP
+.P
 The
 .I l_type
 field can be used to place a read
@@ -387,7 +387,7 @@ If the conflicting lock is an open file description lock, then
 is set to \-1.
 Note that the returned information
 may already be out of date by the time the caller inspects it.
-.PP
+.P
 In order to place a read lock,
 .I fd
 must be open for reading.
@@ -395,7 +395,7 @@ In order to place a write lock,
 .I fd
 must be open for writing.
 To place both types of lock, open a file read-write.
-.PP
+.P
 When placing locks with
 .BR F_SETLKW ,
 the kernel detects
@@ -418,16 +418,16 @@ 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.
-.PP
+.P
 As well as being removed by an explicit
 .BR F_UNLCK ,
 record locks are automatically released when the process terminates.
-.PP
+.P
 Record locks are not inherited by a child created via
 .BR fork (2),
 but are preserved across an
 .BR execve (2).
-.PP
+.P
 Because of the buffering performed by the
 .BR stdio (3)
 library, the use of record locking with routines in that package
@@ -436,7 +436,7 @@ should be avoided; use
 and
 .BR write (2)
 instead.
-.PP
+.P
 The record locks described above are associated with the process
 (unlike the open file description locks described below).
 This has some unfortunate consequences:
@@ -461,7 +461,7 @@ 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.
-.PP
+.P
 Open file description locks solve both of these problems.
 .SS Open file description locks (non-POSIX)
 Open file description locks are advisory byte-range locks whose operation is
@@ -474,7 +474,7 @@ and available since Linux 3.15.
 to include this lock type in the next revision of POSIX.1.)
 For an explanation of open file descriptions, see
 .BR open (2).
-.PP
+.P
 The principal difference between the two lock types
 is that whereas traditional record locks
 are associated with a process,
@@ -492,13 +492,13 @@ with
 and are only automatically released on the last close
 of the open file description,
 instead of being released on any close of the file.
-.PP
+.P
 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.
-.PP
+.P
 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
@@ -511,7 +511,7 @@ 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.)
-.PP
+.P
 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
@@ -519,7 +519,7 @@ open file description locks to synchronize access to a file region
 by having each thread perform its own
 .BR open (2)
 on the file and applying locks via the resulting file descriptor.
-.PP
+.P
 As with traditional advisory locks, the third argument to
 .BR fcntl (),
 .IR lock ,
@@ -529,9 +529,9 @@ structure.
 By contrast with traditional record locks, the
 .I l_pid
 field of that structure must be set to zero
-when using the commands described below.
-.PP
-The commands for working with open file description locks are analogous
+when using the operations described below.
+.P
+The operations for working with open file description locks are analogous
 to those used with traditional locks:
 .TP
 .BR F_OFD_SETLK " (\fIstruct flock *\fP)"
@@ -587,7 +587,7 @@ then details about one of these locks are returned via
 .IR lock ,
 as described above for
 .BR F_GETLK .
-.PP
+.P
 In the current implementation,
 .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7
 no deadlock detection is performed for open file description locks.
@@ -604,12 +604,12 @@ since Linux 4.5, mandatory locking has been made an optional feature,
 governed by a configuration option
 .RB ( CONFIG_MANDATORY_FILE_LOCKING ).
 This feature is no longer supported at all in Linux 5.15 and above.
-.PP
+.P
 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.
-.PP
+.P
 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.,
@@ -629,7 +629,7 @@ If the
 .B O_NONBLOCK
 flag is enabled, then the system call fails with the error
 .BR EAGAIN .
-.PP
+.P
 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.
@@ -646,7 +646,7 @@ permission bit (see
 .BR chmod (1)
 and
 .BR chmod (2)).
-.PP
+.P
 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.
@@ -658,7 +658,7 @@ 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.
-.PP
+.P
 When the filesystem determines that a lock has been lost, future
 .BR read (2)
 or
@@ -670,7 +670,7 @@ descriptor is closed.
 Since Linux 3.12,
 .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
 this happens at least for NFSv4 (including all minor versions).
-.PP
+.P
 Some versions of UNIX send a signal
 .RB ( SIGLOST )
 in this circumstance.
@@ -722,7 +722,7 @@ one must also enable generation of signals on the file descriptor.
 This is done by using the
 .BR fcntl ()
 .B F_SETFL
-command to set the
+operation to set the
 .B O_ASYNC
 file status flag on the file descriptor.
 Subsequently, a
@@ -732,7 +732,7 @@ on the file descriptor.
 The
 .BR fcntl ()
 .B F_SETSIG
-command can be used to obtain delivery of a signal other than
+operation can be used to obtain delivery of a signal other than
 .BR SIGIO .
 .IP
 Sending a signal to the owner process (group) specified by
@@ -1002,14 +1002,14 @@ delivering
 and this signal is delivered to the entire
 process rather than to a specific thread.
 .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05
-.PP
+.P
 Using these mechanisms, a program can implement fully asynchronous I/O
 without using
 .BR select (2)
 or
 .BR poll (2)
 most of the time.
-.PP
+.P
 The use of
 .B O_ASYNC
 is specific to BSD and Linux.
@@ -1074,7 +1074,7 @@ other open file descriptors for the file.
 .B F_UNLCK
 Remove our lease from the file.
 .RE
-.PP
+.P
 Leases are associated with an open file description (see
 .BR open (2)).
 This means that duplicate file descriptors (created by, for example,
@@ -1087,7 +1087,7 @@ Furthermore, the lease is released by either an explicit
 .B F_UNLCK
 operation on any of these duplicate file descriptors, or when all
 such file descriptors have been closed.
-.PP
+.P
 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.
@@ -1103,7 +1103,7 @@ by returning either
 indicating, respectively, a read lease , a write lease, or no lease.
 .I arg
 is ignored.
-.PP
+.P
 When a process (the "lease breaker") performs an
 .BR open (2)
 or
@@ -1120,7 +1120,7 @@ accessed by another process (e.g., flushing cached buffers) and
 then either remove or downgrade its lease.
 A lease is removed by performing an
 .B F_SETLEASE
-command specifying
+operation specifying
 .I arg
 as
 .BR F_UNLCK .
@@ -1130,16 +1130,16 @@ then it is sufficient for the lease holder to downgrade
 the lease to a read lease.
 This is done by performing an
 .B F_SETLEASE
-command specifying
+operation specifying
 .I arg
 as
 .BR F_RDLCK .
-.PP
+.P
 If the lease holder fails to downgrade or remove the lease within
 the number of seconds specified in
 .IR /proc/sys/fs/lease\-break\-time ,
 then the kernel forcibly removes or downgrades the lease holder's lease.
-.PP
+.P
 Once a lease break has been initiated,
 .B F_GETLEASE
 returns the target lease type (either
@@ -1149,11 +1149,11 @@ or
 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.
-.PP
+.P
 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.
-.PP
+.P
 If the lease breaker's blocked
 .BR open (2)
 or
@@ -1174,16 +1174,16 @@ flag when calling
 then the call immediately fails with the error
 .BR EWOULDBLOCK ,
 but the other steps still occur as described above.
-.PP
+.P
 The default signal used to notify the lease holder is
 .BR SIGIO ,
 but this can be changed using the
 .B F_SETSIG
-command to
+operation to
 .BR fcntl ().
 If a
 .B F_SETSIG
-command is performed (even one specifying
+operation is performed (even one specifying
 .BR SIGIO ),
 and the signal
 handler is established using
@@ -1206,7 +1206,7 @@ The events to be notified are specified in
 .IR arg ,
 which is a bit mask specified by ORing together zero or more of
 the following bits:
-.PP
+.P
 .RS
 .PD 0
 .TP
@@ -1289,7 +1289,7 @@ The default signal is
 .BR SIGIO ,
 but this can be changed using the
 .B F_SETSIG
-command to
+operation to
 .BR fcntl ().
 (Note that
 .B SIGIO
@@ -1377,7 +1377,7 @@ file and filesystem.
 For an overview of file sealing, a discussion of its purpose,
 and some code examples, see
 .BR memfd_create (2).
-.PP
+.P
 Currently,
 file seals can be applied only to a file descriptor returned by
 .BR memfd_create (2)
@@ -1388,7 +1388,7 @@ On other filesystems, all
 .BR fcntl ()
 operations that operate on seals will return
 .BR EINVAL .
-.PP
+.P
 Seals are a property of an inode.
 Thus, all open file descriptors referring to the same inode share
 the same set of seals.
@@ -1421,7 +1421,7 @@ If the file does not support sealing, \-1 is returned and
 .I errno
 is set to
 .BR EINVAL .
-.PP
+.P
 The following seals are available:
 .TP
 .B F_SEAL_SEAL
@@ -1534,7 +1534,7 @@ for an explanation of open file descriptions.)
 In this context, the term "write lifetime" means
 the expected time the data will live on media, before
 being overwritten or erased.
-.PP
+.P
 An application may use the different hint values specified below to
 separate writes into different write classes,
 so that multiple users or applications running on a single storage back-end
@@ -1542,7 +1542,7 @@ can aggregate their I/O patterns in a consistent manner.
 However, there are no functional semantics implied by these flags,
 and different I/O classes can use the write lifetime hints
 in arbitrary ways, so long as the hints are used consistently.
-.PP
+.P
 The following operations can be applied to the file descriptor,
 .IR fd :
 .TP
@@ -1567,10 +1567,10 @@ the open file description referred to by
 Sets the read/write hint value associated with the open file description
 referred to by
 .IR fd .
-.PP
+.P
 If an open file description has not been assigned a read/write hint,
 then it shall use the value assigned to the inode, if any.
-.PP
+.P
 The following read/write
 hints are valid since Linux 4.13:
 .TP
@@ -1602,7 +1602,7 @@ Data written to this inode or via this open file description
 is expected to have a lifetime longer than
 data written with
 .BR RWH_WRITE_LIFE_LONG .
-.PP
+.P
 All the write-specific hints are relative to each other,
 and no individual absolute meaning should be attributed to them.
 .SH RETURN VALUE
@@ -1629,7 +1629,9 @@ for traditional
 .B SIGIO
 behavior.
 .TP
-.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ
+.B F_GETPIPE_SZ
+.TQ
+.B F_SETPIPE_SZ
 The pipe capacity.
 .TP
 .B F_GET_SEALS
@@ -1637,9 +1639,9 @@ A bit mask identifying the seals that have been set
 for the inode referred to by
 .IR fd .
 .TP
-All other commands
+All other operations
 Zero.
-.PP
+.P
 On error, \-1 is returned, and
 .I errno
 is set to indicate the error.
@@ -1657,7 +1659,7 @@ another process.
 is not an open file descriptor
 .TP
 .B EBADF
-.I cmd
+.I op
 is
 .B F_SETLK
 or
@@ -1666,7 +1668,7 @@ and the file descriptor open mode doesn't match with the
 type of lock requested.
 .TP
 .B EBUSY
-.I cmd
+.I op
 is
 .B F_SETPIPE_SZ
 and the new pipe capacity specified in
@@ -1675,7 +1677,7 @@ is smaller than the amount of buffer space currently
 used to store data in the pipe.
 .TP
 .B EBUSY
-.I cmd
+.I op
 is
 .BR F_ADD_SEALS ,
 .I arg
@@ -1687,14 +1689,14 @@ and there exists a writable, shared mapping on the file referred to by
 .B EDEADLK
 It was detected that the specified
 .B F_SETLKW
-command would cause a deadlock.
+operation would cause a deadlock.
 .TP
 .B EFAULT
 .I lock
 is outside your accessible address space.
 .TP
 .B EINTR
-.I cmd
+.I op
 is
 .B F_SETLKW
 or
@@ -1703,7 +1705,7 @@ and the operation was interrupted by a signal; see
 .BR signal (7).
 .TP
 .B EINTR
-.I cmd
+.I op
 is
 .BR F_GETLK ,
 .BR F_SETLK ,
@@ -1717,11 +1719,11 @@ NFS), but can sometimes happen locally.
 .TP
 .B EINVAL
 The value specified in
-.I cmd
+.I op
 is not recognized by this kernel.
 .TP
 .B EINVAL
-.I cmd
+.I op
 is
 .B F_ADD_SEALS
 and
@@ -1729,7 +1731,7 @@ and
 includes an unrecognized sealing bit.
 .TP
 .B EINVAL
-.I cmd
+.I op
 is
 .B F_ADD_SEALS
 or
@@ -1739,7 +1741,7 @@ and the filesystem containing the inode referred to by
 does not support sealing.
 .TP
 .B EINVAL
-.I cmd
+.I op
 is
 .B F_DUPFD
 and
@@ -1751,7 +1753,7 @@ in
 .BR getrlimit (2)).
 .TP
 .B EINVAL
-.I cmd
+.I op
 is
 .B F_SETSIG
 and
@@ -1759,7 +1761,7 @@ and
 is not an allowable signal number.
 .TP
 .B EINVAL
-.I cmd
+.I op
 is
 .BR F_OFD_SETLK ,
 .BR F_OFD_SETLKW ,
@@ -1770,7 +1772,7 @@ and
 was not specified as zero.
 .TP
 .B EMFILE
-.I cmd
+.I op
 is
 .B F_DUPFD
 and the per-process limit on the number of open file descriptors
@@ -1783,13 +1785,13 @@ protocol failed (e.g., locking over NFS).
 .B ENOTDIR
 .B F_NOTIFY
 was specified in
-.IR cmd ,
+.IR op ,
 but
 .I fd
 does not refer to a directory.
 .TP
 .B EPERM
-.I cmd
+.I op
 is
 .B F_SETPIPE_SZ
 and the soft or hard user pipe limit has been reached; see
@@ -1801,7 +1803,7 @@ Attempted to clear the
 flag on a file that has the append-only attribute set.
 .TP
 .B EPERM
-.I cmd
+.I op
 was
 .BR F_ADD_SEALS ,
 but
@@ -1811,7 +1813,7 @@ or the current set of seals on the file already includes
 .BR F_SEAL_SEAL .
 .SH STANDARDS
 POSIX.1-2008.
-.PP
+.P
 .BR F_GETOWN_EX ,
 .BR F_SETOWN_EX ,
 .BR F_SETPIPE_SZ ,
@@ -1826,9 +1828,9 @@ are Linux-specific.
 (Define the
 .B _GNU_SOURCE
 macro to obtain these definitions.)
-.\" .PP
+.\" .P
 .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
-.PP
+.P
 .BR F_OFD_SETLK ,
 .BR F_OFD_SETLKW ,
 and
@@ -1837,7 +1839,7 @@ are Linux-specific (and one must define
 .B _GNU_SOURCE
 to obtain their definitions),
 but work is being done to have them included in the next version of POSIX.1.
-.PP
+.P
 .B F_ADD_SEALS
 and
 .B F_GET_SEALS
@@ -1845,7 +1847,7 @@ are Linux-specific.
 .\" FIXME . Once glibc adds support, add a note about FTM requirements
 .SH HISTORY
 SVr4, 4.3BSD, POSIX.1-2001.
-.PP
+.P
 Only the operations
 .BR F_DUPFD ,
 .BR F_GETFD ,
@@ -1857,7 +1859,7 @@ Only the operations
 and
 .B F_SETLKW
 are specified in POSIX.1-2001.
-.PP
+.P
 .B F_GETOWN
 and
 .B F_SETOWN
@@ -1869,7 +1871,7 @@ are specified in POSIX.1-2001.
 with the value 500 or greater, or
 .B _POSIX_C_SOURCE
 with the value 200809L or greater.)
-.PP
+.P
 .B F_DUPFD_CLOEXEC
 is specified in POSIX.1-2008.
 (To get this definition, define
@@ -1895,7 +1897,7 @@ Consequently, an
 system call was added in Linux 2.4.
 The newer system call employs a different structure for file locking,
 .IR flock64 ,
-and corresponding commands,
+and corresponding operations,
 .BR F_GETLK64 ,
 .BR F_SETLK64 ,
 and
@@ -1911,7 +1913,7 @@ placed by
 .BR flock (2)
 and
 .BR fcntl ().
-.PP
+.P
 Several systems have more fields in
 .I "struct flock"
 such as, for example,
@@ -1926,7 +1928,7 @@ 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.
-.PP
+.P
 The original Linux
 .BR fcntl ()
 system call was not designed to handle large file offsets
@@ -1938,7 +1940,7 @@ Consequently, an
 system call was added in Linux 2.4.
 The newer system call employs a different structure for file locking,
 .IR flock64 ,
-and corresponding commands,
+and corresponding operations,
 .BR F_GETLK64 ,
 .BR F_SETLK64 ,
 and
@@ -1975,7 +1977,7 @@ 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.
-.PP
+.P
 Since Linux 3.12,
 .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
 if an NFSv4 client loses contact with the server,
@@ -2096,7 +2098,7 @@ It is therefore inadvisable to rely on mandatory locking.
 .BR capabilities (7),
 .BR feature_test_macros (7),
 .BR lslocks (8)
-.PP
+.P
 .IR locks.txt ,
 .IR mandatory\-locking.txt ,
 and