lkml.org 
[lkml]   [2014]   [Mar]   [18]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: For review: open_by_name_at(2) man page
    On 03/17/2014 11:00 PM, NeilBrown wrote:
    > On Mon, 17 Mar 2014 16:57:29 +0100 "Michael Kerrisk (man-pages)"
    > <mtk.manpages@gmail.com> wrote:
    >
    >> Hi Aneesh, (and others)
    >>
    >> Below is a man page I've written for name_to_handle_at(2) and
    >> open_by_name_at(2). Would you be willing to review it please,
    >> and let me know of any corrections/improvements?
    >>
    >> Thanks,
    >>
    >> Michael
    >
    > Thanks for writing this Michael. The fact that I can only find very small
    > points to comment on reflects the high quality...

    Thanks, Neil. But there was at least one good clanger below :-}.

    >
    >> Otherwise,
    >> .IR dirfd
    >> must be a file descriptor that refers to a directory, and
    > ^^^^^^^
    >> .I pathname
    >> is interpreted relative to that directory.
    >
    > As you clarify later, "must be" is not correct. Maybe this is just an issue
    > of style, in which case you should obviously keep a consistent style across
    > man pages, but to me it sounds wrong. I would use "is generally" or similar.

    Yep, good point. In fact, what I did was rewrite that section completely, to
    more clearly describe the distinct cases based on dirfd/pathname/AT_EMPTY_PATH.


    >> The
    >> .IR mountdirfd
    >> argument is a file descriptor for a directory under
    >> the mount point with respect to which
    >> .IR handle
    >> should be interpreted.
    >
    > mountdirfd does not have to be for a directory. It can be for any object in
    > the filesystem. And I would say "in", not "under".
    > If /foo and /foo/bar are both mountpoints, and I want to look up a
    > filehandle for the filesystem mounted at /foo, then opening "/foo/bar"
    > wouldn't work even though /foo/bar is "under" /foo. And opening "/foo" would
    > work even though "/foo" is not under "/foo/" (is it?).

    Good catch. I got deceived by the name of the argument, which in the kernel
    source is indeed 'mountdirfd', implying it must be a descriptor for a directory.
    I'll rename the argument in the man page to 'mount_fd' and fix the description
    as you suggest here:

    > The
    > .IR mountfd
    > argument is a file descriptor for any object (file, directory, etc.) in the
    > filesystem with respect to which

    I did s/filesystem/mounted filesystem/

    > .IR handle
    > should be interpreted.
    >
    > ??
    >> .B ESTALE
    >> The specified
    >> .I handle
    >> is no longer valid.
    >
    > ESTALE is also returned if the filesystem does not support file-handle ->
    > file mappings.
    > On filesystems which don't provide export_operations (/sys /proc ubifs
    > romfs cramfs nfs coda ... several others) name_to_handle_at will produce a
    > generic handle using the 32 bit inode and 32 bit i_generation.

    Are you sure about this? When I try name_to_handle_at() on /proc and
    /sys, it gives an error (EOPNOTSUPP). I haven't tested the other
    FSes though, so maybe some of them do what you say.

    > open_by_name_at given this (or any) filehandle will fail with ESTALE.
    > I don't know how best to include this in the documentation. Maybe a note
    > earlier noting that some filesystems do not support open_by_name_at(), and
    > you cannot programatically determine which do except by trying.
    > At the same time note that a file handle can become in valid if a file is
    > deleted or for any other reason as determined by the filesystem, and that the
    > error is the same as for when the filesystem doesn't support open_by_name_at.

    I've added text about invalid file handles into NOTES, and noted that not all
    FSes support the production of file handles, but haven't noted ESTALE for the
    latter, since I don't yet know if your statement above is true for some
    filesystems.


    >> For example, one can use the device name in the fifth field of the
    >> .I mountinfo
    >> record to search for the corresponding device UUID via the symbolic links in
    >> .IR /dev/disks/by-uuid .
    >> (A more comfortable way of obtaining the UUID is to use the
    >> .\" e.g., http://stackoverflow.com/questions/6748429/using-libblkid-to-find-uuid-of-a-partition
    >> .BR libblkid (3)
    >> library, which uses the
    >> .I /sys
    >> filesystem to obtain the same information.)
    >
    > Does it? My understanding from "man libblkid" (it is a while since I've read
    > the code) is that it either uses info in /dev/disks/by-* or reads directly
    > from the block devices (maybe using /sys to find them?) and interprets the
    > superblock to extract a UUID.

    Thanks (and to Christoph) -- I'll just remove the words "which uses the /sys
    filesystem to obtain the same information"

    >> Now delete and re-create the file with the same inode number;
    >> .BR open_by_handle_at ()
    >> recognizes that the file referred to by the file handle no longer exists.
    >>
    >> .in +4n
    >> .nf
    >> $ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Display inode number
    >> 4072121
    >> $ \fBecho 'Warum?' > cecilia.txt\fP
    >> $ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Check inode number
    >> 4072121
    >> $ \fBsudo ./t_open_by_handle_at < fh\fP
    >> open_by_handle_at: Stale NFS file handle
    >
    > Something is very wrong here.
    > echo foo > somefile
    > does not "delete and re-create" the file. It opens and truncates.
    > That operation should not invalidate the filehandle on any sane filesystem.

    Indeed! I don't know quite what I was smoking as I reviewed that piece.
    In fact, I started writing this page a long time ago, but then other
    events intervened, and it was a long time before I came back to it recently.
    Certainly, when I produced that shell session log, things proceeded
    (almost) as shown. I'm guessing that what happened is that I by
    accident edited out a line

    rm cecilia.txt

    just before

    echo 'Warum?' > cecilia.txt

    Fixed now. (In that case of course, it is of course a matter of chance
    whether the pathname is re-created with the same i-node number, but if
    you are quick, it often is. I'll add some explanation to the page.)

    >> if (argc > 1)
    >> mount_fd = open(argv[1], O_RDONLY | O_DIRECTORY);
    >
    > O_DIRECTORY is not appropriate, as mentioned earlier.

    Fixed (in two places).

    Thanks for the review, Neil. That helped fix a lot of problems in the page.

    Cheers,

    Michael

    --
    Michael Kerrisk
    Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
    Linux/UNIX System Programming Training: http://man7.org/training/


    \
     
     \ /
      Last update: 2014-03-18 15:21    [W:4.901 / U:0.132 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site