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?). The .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. ?? > .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. 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., 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. > 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. Thanks, NeilBrown
Attachment:
signature.asc
Description: PGP signature
