man/man2/fcntl.2, man/man2const/F_GET_RW_HINT.2const: Split F_{G,S}ET{,_FILE}_RW_HINT...

Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2
index d42712fe9c013ff33f0cf630a8be36021da7ed38..947db1e0a2a4fd6d2267d82dda743ee05d9202a2 100644 (file)
--- a/man/man2/fcntl.2
+++ b/man/man2/fcntl.2
@@ -1178,86 +1178,14 @@ See
 .TQ
 .BR F_GET_SEALS (2const)
 .SS File read/write hints
-Write lifetime hints can be used to inform the kernel about the relative
-expected lifetime of writes on a given inode or
-via a particular open file description.
-(See
-.BR open (2)
-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.
-.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
-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.
-.P
-The following operations can be applied to the file descriptor,
-.IR fd :
-.TP
-.BR F_GET_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
-Returns the value of the read/write hint associated with the underlying inode
-referred to by
-.IR fd .
-.TP
-.BR F_SET_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
-Sets the read/write hint value associated with the
-underlying inode referred to by
-.IR fd .
-This hint persists until either it is explicitly modified or
-the underlying filesystem is unmounted.
-.TP
-.BR F_GET_FILE_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
-Returns the value of the read/write hint associated with
-the open file description referred to by
-.IR fd .
-.TP
-.BR F_SET_FILE_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
-Sets the read/write hint value associated with the open file description
-referred to by
-.IR fd .
-.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.
-.P
-The following read/write
-hints are valid since Linux 4.13:
-.TP
-.B RWH_WRITE_LIFE_NOT_SET
-No specific hint has been set.
-This is the default value.
-.TP
-.B RWH_WRITE_LIFE_NONE
-No specific write lifetime is associated with this file or inode.
-.TP
-.B RWH_WRITE_LIFE_SHORT
-Data written to this inode or via this open file description
-is expected to have a short lifetime.
-.TP
-.B RWH_WRITE_LIFE_MEDIUM
-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_SHORT .
 .TP
-.B RWH_WRITE_LIFE_LONG
-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_MEDIUM .
-.TP
-.B RWH_WRITE_LIFE_EXTREME
-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 .
-.P
-All the write-specific hints are relative to each other,
-and no individual absolute meaning should be attributed to them.
+.BR F_GET_RW_HINT (2const)
+.TQ
+.BR F_SET_RW_HINT (2const)
+.TQ
+.BR F_GET_FILE_RW_HINT (2const)
+.TQ
+.BR F_SET_FILE_RW_HINT (2const)
 .SH RETURN VALUE
 For a successful call, the return value depends on the operation:
 .TP

diff --git a/man/man2const/F_GET_RW_HINT.2const b/man/man2const/F_GET_RW_HINT.2const
new file mode 100644 (file)
index 0000000..01bbcca
--- /dev/null
+++ b/man/man2const/F_GET_RW_HINT.2const
@@ -0,0 +1,120 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH F_GET_RW_HINT 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+F_GET_RW_HINT,
+F_SET_RW_HINT,
+F_GET_FILE_RW_HINT,
+F_SET_FILE_RW_HINT
+\-
+get/set file read/write hints
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <fcntl.h>
+.P
+.BI "int fcntl(int " fd ", F_GET_RW_HINT, uint64_t *" arg );
+.BI "int fcntl(int " fd ", F_SET_RW_HINT, uint64_t *" arg );
+.BI "int fcntl(int " fd ", F_GET_FILE_RW_HINT, uint64_t *" arg );
+.BI "int fcntl(int " fd ", F_GET_FILE_RW_HINT, uint64_t *" arg );
+.fi
+.SH DESCRIPTION
+Write lifetime hints can be used to inform the kernel about the relative
+expected lifetime of writes on a given inode or
+via a particular open file description.
+(See
+.BR open (2)
+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.
+.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
+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.
+.P
+The following operations can be applied to the file descriptor,
+.IR fd :
+.TP
+.BR F_GET_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
+Returns the value of the read/write hint associated with the underlying inode
+referred to by
+.IR fd .
+.TP
+.BR F_SET_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
+Sets the read/write hint value associated with the
+underlying inode referred to by
+.IR fd .
+This hint persists until either it is explicitly modified or
+the underlying filesystem is unmounted.
+.TP
+.BR F_GET_FILE_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
+Returns the value of the read/write hint associated with
+the open file description referred to by
+.IR fd .
+.TP
+.BR F_SET_FILE_RW_HINT "\~(\f[I]uint64_t\~*\f[]; since Linux 4.13)"
+Sets the read/write hint value associated with the open file description
+referred to by
+.IR fd .
+.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.
+.P
+The following read/write
+hints are valid since Linux 4.13:
+.TP
+.B RWH_WRITE_LIFE_NOT_SET
+No specific hint has been set.
+This is the default value.
+.TP
+.B RWH_WRITE_LIFE_NONE
+No specific write lifetime is associated with this file or inode.
+.TP
+.B RWH_WRITE_LIFE_SHORT
+Data written to this inode or via this open file description
+is expected to have a short lifetime.
+.TP
+.B RWH_WRITE_LIFE_MEDIUM
+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_SHORT .
+.TP
+.B RWH_WRITE_LIFE_LONG
+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_MEDIUM .
+.TP
+.B RWH_WRITE_LIFE_EXTREME
+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 .
+.P
+All the write-specific hints are relative to each other,
+and no individual absolute meaning should be attributed to them.
+.SH RETURN VALUE
+Zero.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+See
+.BR fcntl (2).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux.
+.SH SEE ALSO
+.BR fcntl (2)