On 08/23/2017 04:41 PM, Michael Kerrisk (man-pages) wrote: > Hello Jens, > > On 07/31/2017 05:24 PM, Jens Axboe wrote: >> Hi Michael, >> >> Not sure what the best way to submit this is, but I wrote an >> update for the fcntl man page to cover the new set/get write >> hints commands that are added in 4.13. Attaching the patch, but >> you can also find it below, in a fork of your github repo: >> >> https://github.com/axboe/man-pages/commits/fcntl-write-hints > > Thanks for the patch. Some questions below. > >> From 3eee36f14a650e50f14b42ae1d4fec33e78e6254 Mon Sep 17 00:00:00 2001 >> From: Jens Axboe <axboe@xxxxxxxxx> >> Date: Mon, 26 Jun 2017 16:58:29 -0600 >> Subject: [PATCH] man2/fcntl.2: add description of new read/write hint commands >> >> This adds a description of the new read/write hint commands: >> >> F_GET_RW_HINT Get inode read/write hint >> F_SET_RW_HINT Set inode read/write hint >> F_GET_FILE_RW_HINT Get file read/write hint >> F_SET_FILE_RW_HINT Set file read/write hint >> >> and the currently available values, as of Linux 4.13. >> >> Signed-off-by: Jens Axboe <axboe@xxxxxxxxx> >> --- >> man2/fcntl.2 | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 58 insertions(+) >> >> diff --git a/man2/fcntl.2 b/man2/fcntl.2 >> index 70758d2fcd99..07eacc9564fa 100644 >> --- a/man2/fcntl.2 >> +++ b/man2/fcntl.2 >> @@ -5,6 +5,7 @@ >> .\" and Copyright (C) 2002-2010, 2014 Michael Kerrisk; >> .\" and Copyright (C) 2014 Jeff Layton >> .\" and Copyright (C) 2014 David Herrmann >> +.\" and Copyright (C) 2017 Jens Axboe >> .\" >> .\" %%%LICENSE_START(VERBATIM) >> .\" Permission is granted to make and distribute verbatim copies of this >> @@ -61,6 +62,8 @@ >> .\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. >> .\" 2014-07-08, David Herrmann <dh.herrmann@xxxxxxxxx> >> .\" Document F_ADD_SEALS and F_GET_SEALS >> +.\" 2017-06-26, Jens Axboe <axboe@xxxxxxxxx> >> +.\" Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT >> .\" >> .TH FCNTL 2 2017-05-03 "Linux" "Linux Programmer's Manual" >> .SH NAME >> @@ -1490,6 +1493,61 @@ Furthermore, if there are any asynchronous I/O operations >> .RB ( io_submit (2)) >> pending on the file, >> all outstanding writes will be discarded. >> +.SS File read/write hints >> +Write life time hints can be used to inform the kernel about the relative >> +expected life time of writes on a given inode or file. An application may >> +use this interface for separating writes into different write classes, >> +so that multiple users or applications running on a single storage back-end >> +can aggregate their IO patterns in a consistent manner. However, there are >> +no functional semantics implied by these flags, and different IO classes >> +can use the write life time hints in arbitrary ways so long as they are used >> +consistently. > > I read the above, and it is still not clear to me what a "write lifetime" > is. Can you add some text to explain? (I'm guessing that it means the > amount of time before the data is overwritten by another write, but I'm > not sure of that, and it needs to be more explicit in the text.) You are right, it's exactly what it refers to. It's essentially data lifetime hints for a write command. I'd be happy to take suggestions to improve the description of it. >> +.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. >> +.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. >> +.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. > > Do you mean here "file descriptor" or "file description (i.e., the > open file handle)? Maybe you mean the former, but I want to confirm. I do mean file descriptor. >> +.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. > > Same as above comment. Ditto. -- Jens Axboe -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
