Re: For review: open_by_name_at(2) man page [v2]

On Tue, 18 Mar 2014 13:55:15 +0100 "Michael Kerrisk (man-pages)"
[off-list ref] wrote:

Hi Aneesh, (and others)

After integrating review comments from NeilBown and Christoph Hellwig,
here is draft 2 of a man page I've written for name_to_handle_at(2) and
open_by_name_at(2). Especially thanks to Neil's comments, several parts
of the page underwent a substantial rewrite. Would you be willing to 
review it please, and let me know of any corrections/improvements?

I didn't notice before but above and in $SUBJ I see "open_by_name_at", which
is fictitious :-)

Together, the
.I pathname
and
.I dirfd
arguments identify the file for which a handle is to obtained.

                                                      ^be

The
.I flags
argument is a bit mask constructed by ORing together
zero or more of the following value:

                                     ^s

.TP
.B AT_EMPTY_PATH
Allow
.I pathname
to be an empty string.
See above.
(which may have been obtained using the
.BR open (2)
.B O_PATH
flag).

What "may have been obtained" ??

The
.I flags
argument
is as for
.BR open (2).
.\" FIXME: Confirm that the following is intended behavior.
.\"        (It certainly seems to be the behavior, from experimenting.)
If
.I handle
refers to a symbolic link, the caller must specify the
.B O_PATH
flag, and the symbolic link is not dereferenced (the
.B O_NOFOLLOW
flag, if specified, is ignored).

It certainly sounds like reasonable behaviour.  I cannot comment on intention
though.
Are you bothered that O_PATH is needed for symlinks?  An fd on a symlink is a
sufficiently unusual thing that it seems reasonable for a programmer to
explicitly say they are expecting one.

In the event of an error, both system calls return \-1 and set
.I errno
to indicate the cause of the error.
.SH ERRORS
.BR name_to_handle_at ()
and
.BR open_by_handle_at ()
can fail for the same errors as
.BR openat (2).
In addition, they can fail with the errors noted below.

Should you mention EFAULT if mount_id or handle are not valid pointers?

Not all filesystem types support the translation of pathnames to
file handles.
.\" FIXME NeilBrown noted:
.\"    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.
.\" However, on /proc and /sys, at least, name_to_handle_at() fails with
.\" EOPNOTSUPP. Are there really filesystems that can deliver ESTALE (the
.\" same error as for an invalid file handle) in the above circumstances?

This is all wrong - discard it :-)

NeilBrown