linux-api.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Silvan Jegen <s.jegen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
To: "Michael Kerrisk (man-pages)"
	<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Cc: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>,
	Jeff Layton <jlayton-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>,
	lkml <linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org>,
	Linux API <linux-api-u79uwXL29TY76Z2rM5mHXA@public.gmane.org>,
	linux-man <linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org>
Subject: Re: Revised statx(2) man page for review
Date: Tue, 25 Apr 2017 20:50:33 +0200	[thread overview]
Message-ID: <20170425185032.nohoaxbke7r5w5jt@myarchbang.ff3l> (raw)
In-Reply-To: <f3ef2be8-dfa5-e1dd-2315-d787a2a2acc3-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>

Hi Michael

On Tue, Apr 25, 2017 at 01:14:26PM +0200, Michael Kerrisk (man-pages) wrote:
>
> [...]
>
> Could you please carefully review the text below, in case 
> I added any errors.

Just a few comments below.

 
> [...] 
>
>    Invoking statx():
>        To  access  a file's status, no permissions are required on the
>        file itself, but in the case of statx() with a  pathname,  exe‐
>        cute  (search) permission is required on all of the directories
>        in pathname that lead to the file.
> 
>        statx() uses pathname, dirfd, and  flags  identify  the  target

This should be:

"statx() uses pathname, dirfd, and  flags  *to* identify  the  target"


> [...] 
>
>        AT_STATX_SYNC_AS_STAT
>               Do  whatever  stat(2)  does.  This is the default and is
>               very much filesystem specific.

Since we write "Linux-specific" further above we should probably use

"very much filesystem-specific."

here for consistency.


>        AT_STATX_FORCE_SYNC
>               Force the attributes to be synchronized with the server.
>               This  may  require  that  a network filesystem perform a
>               data writeback to get the timestamps correct.
> 
>        AT_STATX_DONT_SYNC
>               Don't synchronize anything, but rather just  take  what‐
>               ever  the  system has cached if possible.  This may mean
>               that the information returned is approximate, but, on  a
>               network  filesystem,  it may not involve a round trip to
>               the server - even if no lease is held.
> 
>        The mask argument to statx() is used to tell the  kernel  which
>        fields  the  caller is interested in.  mask is an ORed combina‐
>        tion of the following constants:
> 
>            STATX_TYPE          Want stx_mode & S_IFMT
>            STATX_MODE          Want stx_mode & ~S_IFMT
>            STATX_NLINK         Want stx_nlink
>            STATX_UID           Want stx_uid
>            STATX_GID           Want stx_gid
>            STATX_ATIME         Want stx_atime
>            STATX_MTIME         Want stx_mtime
>            STATX_CTIME         Want stx_ctime
>            STATX_INO           Want stx_ino
>            STATX_SIZE          Want stx_size
>            STATX_BLOCKS        Want stx_blocks
>            STATX_BASIC_STATS   [All of the above]
>            STATX_BTIME         Want stx_btime
>            STATX_ALL           [All currently available fields]
> 
>        Note the kernel does not reject values in mask other  than  the

We should probably either insert a colon here

"Note: the kernel does not reject values in mask other  than  the..."

or reformulate the sentence like this.

"Note that the kernel does not reject values in mask other  than  the..."


> [...] 
>
>        stx_gid
>               The ID of the group that may access the file.

This group ID is the gid of the file owner's primary group, no? At least
that's what the field comment in the DESCRIPTION implies.

I think it would be more accurate to write:

"The ID of the file owner's primary group"


> [...] 
> 
>        STATX_ATTR_COMPRESSED
>               The  file  is  compressed  by  the fs and may take extra

We write out 'filesystem' everywhere else so I think we should replace 'fs'
with it here as well.


> CONFORMING TO
>        statx() is Linux specific.

For consistency we should write:

"statx() is Linux-specific".


I wrote the changes in-line but if you prefer I can 'git send-email'
a patch as well.


Cheers and thanks for all the hard work!

Silvan

  parent reply	other threads:[~2017-04-25 18:50 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-04-25 11:14 Revised statx(2) man page for review Michael Kerrisk (man-pages)
     [not found] ` <f3ef2be8-dfa5-e1dd-2315-d787a2a2acc3-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2017-04-25 18:50   ` Silvan Jegen [this message]
     [not found]     ` <20170425185032.nohoaxbke7r5w5jt-Ug7NTYnKI+9o9fKphESQjg@public.gmane.org>
2017-04-25 19:40       ` Michael Kerrisk (man-pages)
2017-04-25 20:06   ` Dmitry V. Levin
     [not found]     ` <20170425200656.GA30045-u2l5PoMzF/Vg9hUCZPvPmw@public.gmane.org>
2017-04-26  5:42       ` Michael Kerrisk (man-pages)
     [not found]         ` <864d7dbb-9fa7-deb2-e379-8d99a6e8c2aa-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2017-04-26 10:43           ` G. Branden Robinson
2017-04-26 11:35   ` Revised statx(2) man page for review [and AT_EMPTY_PATH question] David Howells
     [not found]     ` <14390.1493206508-S6HVgzuS8uM4Awkfq6JHfwNdhmdF6hFW@public.gmane.org>
2017-04-26 12:13       ` Michael Kerrisk (man-pages)
2017-04-26 15:53       ` Al Viro
2017-04-26 15:10     ` David Howells
     [not found]       ` <20166.1493219435-S6HVgzuS8uM4Awkfq6JHfwNdhmdF6hFW@public.gmane.org>
2017-04-26 19:08         ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170425185032.nohoaxbke7r5w5jt@myarchbang.ff3l \
    --to=s.jegen-re5jqeeqqe8avxtiumwx3w@public.gmane.org \
    --cc=dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org \
    --cc=jlayton-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org \
    --cc=linux-api-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
    --cc=linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
    --cc=linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
    --cc=mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).