Re: For review: open_by_name_at(2) man page

From: NeilBrown
Date: Mon Mar 17 2014 - 18:00:37 EST

On Mon, 17 Mar 2014 16:57:29 +0100 "Michael Kerrisk (man-pages)"
<mtk.manpages@xxxxxxxxx> 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...

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

> 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?).

.IR mountfd
argument is a file descriptor for any object (file, directory, etc.) in the
filesystem with respect to which
.IR handle
should be interpreted.


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

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

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

> if (argc > 1)
> mount_fd = open(argv[1], O_RDONLY | O_DIRECTORY);

O_DIRECTORY is not appropriate, as mentioned earlier.


Attachment: signature.asc
Description: PGP signature