From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Michael Kerrisk (man-pages)" Subject: Re: man page update (fcntl(2) new set/get write hints) Date: Fri, 25 Aug 2017 00:10:49 +0200 Message-ID: References: <25b8e025-d49b-e033-5ba3-f6967a6a970f@kernel.dk> <39f20b08-9a35-652e-4ae9-96f3cb8e5679@kernel.dk> Reply-To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Return-path: In-Reply-To: <39f20b08-9a35-652e-4ae9-96f3cb8e5679-tSWWG44O7X1aa/9Udqfwiw@public.gmane.org> Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: Jens Axboe Cc: linux-man List-Id: linux-man@vger.kernel.org Hello Jens, On 24 August 2017 at 16:39, Jens Axboe 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 >>> 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 >>> --- >>> 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 >>> .\" Document F_ADD_SEALS and F_GET_SEALS >>> +.\" 2017-06-26, Jens Axboe >>> +.\" 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