From b9ef6087314b9ddee5a4a3aa58a8ef2c3c73dcb9 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 26 Aug 2017 03:23:40 +0200 Subject: [PATCH] fcntl.2: Various improvements to Jens Axboe's patch Signed-off-by: Michael Kerrisk --- man2/fcntl.2 | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 01d91b898..7451f55a8 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -1496,30 +1496,41 @@ all outstanding writes will be discarded. .\" .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 file, that is, +expected lifetime of writes on a given inode or +via a particular open file description. +In this context, the term "write lifetime" means the expected time the data will live on media, before being overwritten or erased. -An application may -use this interface for separating writes into different write classes, +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 they are used consistently. +.\" FIXME What are "I/O classes"? +in arbitrary ways, so long as the hints are used consistently. +.PP +The following operations can be applied to the file descriptor, +.IR fd : .TP .BR F_GET_RW_HINT " (\fIuint64_t\fP; since Linux 4.13)" Returns the value of the read/write hint associated with the underlying inode -for the file descriptor. +referred to by +.IR fd . .TP .BR F_SET_RW_HINT " (\fIuint64_t\fP; since Linux 4.13)" -Sets the read/write hint value associated with the underlying inode for the -file descriptor. +Sets the read/write hint value associated with the +underlying inode referred to by +.IR fd . .TP .BR F_GET_FILE_RW_HINT " (\fIuint64_t\fP; since Linux 4.13)" -Returns the value of the read/write hint associated with the file descriptor. +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 " (\fIuint64_t\fP; since Linux 4.13)" -Sets the read/write hint value associated with the file descriptor. +Sets the read/write hint value associated with the open file description +referred to by the file descriptor. .PP If a given file descriptor has not been assigned a read/write hint, then it shall use the value assigned to the inode, if any. @@ -1534,20 +1545,24 @@ This is the default value. No specific write lifetime is associated with this file or inode. .TP .BR RWH_WRITE_LIFE_SHORT -Data written to this file or inode is expected to have a short lifetime. +Data written to this inode or via this open file description +is expected to have a short lifetime. .TP .BR RWH_WRITE_LIFE_MEDIUM -Data written to this file or inode is expected to have a lifetime longer than +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 .BR RWH_WRITE_LIFE_LONG -Data written to this file or inode is expected to have a lifetime longer than +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 .BR RWH_WRITE_LIFE_EXTREME -Data written to this file or inode is expected to have a lifetime longer than +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