Document the named attribute interface

[rmacklem]

Summary

The named attribute interface is an alternate way
to manipulate extended attributes, based on the
interface provided by Solaris.

This man page documents this interface.

I put it in section 7, since that seemed the best fit?

[rmacklem]

Re-written to conform to the more Solaris-like
semantics of O_NAMEDATTR that is now implemented
in main.

[rmacklem]

Replaced the copyright notice with the new recommended
short one, as suggested by ziaee@.

[rmacklem]

Clarified when named attributes and named attribute
directories are created.

I also added a paragraph related to use of pathconf(2)
names.

[emaste]

share/man/man7/named_attribute.7

14–15

@ziaee this seems more verbose than typical; you've been looking at all kinds of man pages so would like your advice/commentary on guidelines

[ziaee]

share/man/man7/named_attribute.7

14–15

I'm sorry for the delay, I have seen this but I am chewing on it because I agree. Simplifying language to make it easier to read, especially on topics you're not so familiar with, is hard. We probably shouldn't hold this up though.

[rmacklem]

Deleted a few sentences that seemed redundant.
I think what now remains in the man page is useful
information.

If no one comments/reviews it within a week, I am
going to commit it and it can be improved after that.

[kib]

share/man/man7/named_attribute.7

25

27

30

32

42

44

45

associated == file for which we query the named attr, I suppose.
This formulation make me stop until I realized this.

Is there a better word than 'associated'?

50

BTW, does it work to pass "" and O_EMPTY_PATH | P_NAMEDATTR ?

54

Please use .Xr ... 2, I stopped flagging all such places.

57

I suppose renameat only works confined to the same named attr directory? Could this be clarified somewhere?

116

Section 9 is not about system calls, it is about internal kernel interfaces.

BTW, I thought that our extattrs and Solaris named attributes are incompatible by design, but this sentence basically states the reverse. I think this is confusing esp. because UFS only supports extattrs, and I suspect that ZFS only supports named attrs due to the Solaris heritage.

Might be add a dedicated section of comparision between extattrs and named attrs.

129

Is there chown?

132

145

[markj]

Perhaps modify extattr.2 and extattr.3 to reference this page?

share/man/man7/named_attribute.7

38

I'd say explicitly that the value of each attribute is contained in the corresponding file.

I'm not sure what "analogous to regular files" really means. Maybe we could say that the attribute files behave like regular files for most or all purposes?

139

143

145

147

Does the FreeBSD NFSv4 server support them?

[rmacklem]

Answered the inline questions. I will update the diff soon.

share/man/man7/named_attribute.7

45

I've changed this to "on a file to query the named attributes for the file".
Hopefully this is clearer?

50

For the case where the "fd" argument is for the file,
it fails with ENOATTR.

For the case where the "fd" argument is for the named
attribute directory or a named attribute, then it does work.

Btw, Solaris doesn't have O_EMPTY_PATH, so I don't know what
would be considered correct semantics. I will note that for the
case where the "fd" is for a file, the VOP_LOOKUP() call is needed
to implement it and that could be messy.

Do you think this semantic is ok?

57

I've added a sentence here.

116

I've changed it to .Xr extattr 2 and added a couple
of sentences to try and clarify that both mechanisms
can be used interchangeably. For ZFS and the NFSv4
client, most extended attributes can be accessed either
way. For example, you can:

1. lsextattr user foo
2. and see the list of names or
3. runat foo ls
4. and see the list of names

I've added a small paragraph covering the cases where
you cannot use both mechanisms. (Very large attribute
values and system namespace attributes.)

129

I've added "via fchown 2.".

145

Done, although I have no idea how to remount
ZFS volumes, so I just reboot;-)

147

I've added a sentence that explains "only if ZFS
file systems with "xattr=dir" are exported.

[rmacklem]

Made changes that kib@ and markj@ suggested.

[ziaee]

git-arc -c D49851 errors on the *.xattr files

[rmacklem]

In D49851#1169304, @ziaee wrote:

git-arc -c D49851 errors on the *.xattr files

No idea what you are talking about. Why would
git have anything to do with a man page?

[ziaee]

In D49851#1169305, @rmacklem wrote:

In D49851#1169304, @ziaee wrote:

git-arc -c D49851 errors on the *.xattr files

No idea what you are talking about. Why would
git have anything to do with a man page?

Oops, I meant git-arc patch -c D49851, which applies the patch to the tree.

[ziaee]

{F122857752}

[pauamma_gundo.com]

A couple typos, fixable on commit if everything else looks good to others.

share/man/man7/named_attribute.7

27

141

[kib]

share/man/man7/named_attribute.7

19

It is not section 9.

124

[kib]

Updated man page is much more concise IMO. Also it answers questions that I asked myself when I read the previous version.

share/man/man7/named_attribute.7

50

Yes I think it is fine for now.

[rmacklem]

Marked inline comments as done.

[rmacklem]

In D49851#1169308, @ziaee wrote:

In D49851#1169305, @rmacklem wrote:

In D49851#1169304, @ziaee wrote:

git-arc -c D49851 errors on the *.xattr files

No idea what you are talking about. Why would
git have anything to do with a man page?

Oops, I meant git-arc patch -c D49851, which applies the patch to the tree.

Ok. I don't use git arc or anything like that to apply the
patch to the tree. I set it up manually in a working branch.

[rmacklem]

Thanks everyone for your comments. I plan on
committing this later to-day, so if you have any
more suggestions, please make them soon.

Thanks, rick

[ziaee]

--and pauamma's typos.

share/man/man7/named_attribute.7

122

line over 80 char creates a mandoc warning.

175