From 5d93c92d365a2a54ea3c4fbf37f2692f3f9cdf7f Mon Sep 17 00:00:00 2001 From: Alejandro Colomar Date: Sun, 13 Jul 2025 01:59:09 +0200 Subject: [PATCH] man/man2/fcntl.2, man/man2const/F_GET_RW_HINT.2const: Split F_{G,S}ET{,_FILE}_RW_HINT from fcntl(2) Signed-off-by: Alejandro Colomar --- man/man2/fcntl.2 | 86 ++------------------- man/man2const/F_GET_RW_HINT.2const | 120 +++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 79 deletions(-) create mode 100644 man/man2const/F_GET_RW_HINT.2const diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 index d42712fe9..947db1e0a 100644 --- 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 index 000000000..01bbcca5a --- /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 +.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) -- 2.47.2