Hi Jens, On 25 August 2017 at 22:43, Jens Axboe <axboe@xxxxxxxxx> wrote: > On 08/24/2017 04:10 PM, Michael Kerrisk (man-pages) wrote: >> Hello Jens, >> >> On 24 August 2017 at 16:39, Jens Axboe <axboe@xxxxxxxxx> wrote: >>> 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. >> >> Well, a sentence something like my above is probably a start, but I'd >> prefer you worded something, since it might contain more insight than >> anything that I propose. > > Could perhaps insert a sentence (after the first one) like the following: > > "Life time refers to the expected time the data will live on media, before > being overwritten or erased." Sounds good. >>>>> +.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. >> >> So, what are the semantics if a file descriptor is duplicated using >> dup(2) or similar? If I understand correctly, then the write lifetime >> hint has no effect for the new file descriptor, right? > > If it's dup(2)'ed, then the new file descriptor will refer to the same > hints as the previous. See attached test file. But then isn't this exactly the point I asked about: are the hints private to a file descriptor or are they associated with the open file description (open file table entry, "struct file")? You said "I do mean file descriptor", but actually I understand what you just said now as "hints are associated with the open file description, which may be referred to by multiple duplicated file descriptors". Can you clarify? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- 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
