open.2: Document the O_NAMEDATTR flag added recently

[rmacklem]

Summary

Commit 2ec2ba7e232d added support for the O_NAMEDATTR flag to
the opne(2) and openat(2) syscalls for main.

This patch updates the man page for this flag.

Another man page that explains named attributes will
be introduced in a future commit.

[rmacklem]

Add a missing '.' at the end of a statement.

[rmacklem]

Tried to clarify when O_NAMEDATTR is used.

Took mention of ENOATTR out of the description
section. It is in the errors section.

Note that there is no alphabetical ordering in this
man page, so I added new entries at the end of the
lists.

I think I am done tinkering with it now, so please review it.

[kib]

lib/libsys/open.2

533

I suspect this explanation is more confusing than explaining.

Might be, instead of describing the effects of the O_NAMEDATTR flag, it would be more clear to describe how to open the na directory or na object.

[rmacklem]

lib/libsys/open.2

533

Ok, I'll try and rework it.

Btw, named_attribute.7 is in D49851 and it
includes an example (poorly formatted at
this point, but I'm not sure what needs to
cleaned up). If you take a look at it, it might be
less confusing?

[rmacklem]

Rework the description for O_NAMEDATTR to try
and explain how it is used to open named attributes,
as suggested by kib@.

Does this version seem less confusing?

[rmacklem]

Added a sentence trying to explain the use
of O_NAMEDATTR for the openat() of a named
attribute. For this case, it performs a sanity check
to ensure the successful open is that of a named
attribute.

One quirk w.r.t. named attributes (blame Sun for this)
is that ".." in the named attribute directory refers to
the file object (not a parent directory), so an
openat(nameddir_fd, "..", O_RDONLY, 0) opens the
file in the file system namespace and not a named
attribute.

openat(nameddir_fd, "..", O_RDONLY | O_NAMEDATTR, 0)
will fail because ".." is not a named attribute.

I need to explain this quirk in named_attribute.7, because
I have not yet done so.

[rmacklem]

Attempt #2 at explaining the use of O_NAMEDATTR
when opening a named attribute.

[kib]

lib/libsys/open.2

530

Is 'imbedded' a proper English or a typo?

[emaste]

Two very small comments

lib/libsys/open.2

214

If it's equivalent "a named attribute or named attribute directory" sounds better to my ear (although I'm not quite sure why)

530

[rmacklem]

lib/libsys/open.2

214

I agree that the reordered version sounds better.

However, the main use of the flag is for opening
a named attribute directory, so I ordered it that
way.

Do you think I should reorder it?

530

According to google's AI (which must be correct;-)
they are synonyms, although "embedded" is more
common in US and technical writing.

I'll change it.

[rmacklem]

Oops, this is a bit embarrassing. I took another look
at the Solaris doc (which is confusing, too) and realized
I hadn't implemented what they did for their O_XATTR.

For Solaris, an openat(..O_XATTR..) opens a named attribute
for the file or opens the named attribute directory if the
path is ".".

Since I do not see any reason to be non-Solaris compatible,
I have a made a minor change to main, so that the above
semantics is supported. (It will be here for review soon.)

However, this means that this man page needed to be rewritten.

Here is the attempt for the Solaris semantics, which I think are
simpler to describe. (I did try and follow the reviewers previous advice.)