Re: man page update (fcntl(2) new set/get write hints)

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hello Jens,

On 24 August 2017 at 16:39, Jens Axboe <axboe-tSWWG44O7X1aa/9Udqfwiw@public.gmane.org> 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-tSWWG44O7X1aa/9Udqfwiw@public.gmane.org>
>>> 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-tSWWG44O7X1aa/9Udqfwiw@public.gmane.org>
>>> ---
>>>  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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>>>  .\"     Document F_ADD_SEALS and F_GET_SEALS
>>> +.\" 2017-06-26, Jens Axboe <axboe-tSWWG44O7X1aa/9Udqfwiw@public.gmane.org>
>>> +.\"     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.

>>> +.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.

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?

Cheers,

Michael

>>> +.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
>



-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html