Moving attr(5) man page to man-pages
Hi Andreas,
As we discussed offlist, it makes sense to have the attr(5) man page in man-pages, rather than as part of the 'attr' project documentation, since it mostly relates to kernel details.
So, I'll adopt this page for the next man-pages release; I've just now copied the latest version from the 'attr' repo. Could you please take whatever steps are needed ensure that page conflicts do not result for downstreams who are taking man page feeds from both projects.
I'll move this page into Section 7, since that's where overview type pages such as this are normally placed in man-pages, but I'll also create a link in Section 5, so that acl(5) references will continue to work.
I've made a number of edits to the page. Some of these were just to bring the page closer to man-pages style, but others were to amend incorrect technical details and add new details. I'd be pleased if you checked over these commits:
d8ba769 attr.7: File capabilities are implemented using *security* attributes 03a93c3 attr.7: Clarify permissions required to work with 'user' EAs 6ad46a9 attr.7: The ext[234] block limitation applies to sum of all EAs 6db035a attr.7: Document VFS-imposed limits on EAs
edb159d attr.7: Describe limit on EA values for JFS, XFS, and Reiserfs 7f4f24e attr.7: Document EA limits for Btrfs
These changes are already pushed to 'master' at
http://git.kernel.org/pub/scm/docs/man-pages/man-pages
Thanks,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Michael,
2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 5 lines
Hi Andreas,
As we discussed offlist, it makes sense to have the attr(5) man page in man-pages, rather than as part of the 'attr' project documentation, since it mostly relates to kernel details.
thanks for that; I have removed the attr.5 man page from the attr package.
I'll reply to the man page changes separately.
Andreas
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 5 lines · Michael Kerrisk (man-pages)
Hi Andreas,
As we discussed offlist, it makes sense to have the attr(5) man page in man-pages, rather than as part of the 'attr' project documentation, since it mostly relates to kernel details.
Can you also rename it to xattr while we're at it?
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Michael,
2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 5 lines
Hi Andreas,
I'll move this page into Section 7, since that's where overview type pages such as this are normally placed in man-pages, but I'll also create a link in Section 5, so that acl(5) references will continue to work.
okay.
Quoted 2 lines
I've made a number of edits to the page. Some of these were just to bring the page closer to man-pages style,
The \(em dashes don't render in terminals very well.
Quoted 2 lines
but others were to amend incorrect technical details and add new details. I'd be pleased if you checked over these commits
Thanks, that all looks good.
In addition, I would remove the list of file systems with extended attribute support; they are supported pretty much everywhere to some degree at least, even on tmpfs.
I'm attaching a patch that also includes a few other minor changes.
Thanks,
Andreas
man7/attr.7 +5 -7
@@ -48,11 +48,8 @@ Extended attributes are accessed as atomic objects. Reading retrieves the whole value of an attribute and stores it in a buffer. Writing replaces any previous value with the new value. .PP -Space consumed for extended attributes is counted towards the disk quotas +Space consumed for extended attributes may be counted towards the disk quotas of the file owner and file group. -.PP -Currently, the filesystems that support extended attributes include -Btrfs, ext2, ext3, ext4, XFS, JFS, and Reiserfs. .SS Extended attribute namespaces Attribute names are null-terminated strings. The attribute name is always specified in the fully qualified
@@ -130,12 +127,13 @@ and access to extended user attributes is restricted to the owner and to users with appropriate capabilities for directories with the sticky bit set (see the .BR chmod (1) -manual page for an explanation of Sticky Directories). +manual page for an explanation of the sticky bit). .SS Filesystem differences The kernel and the filesystem may place limits on the maximum number and size of extended attributes that can be associated with a file. The VFS imposes limitations that an attribute names is limited to 255 bytes -and an attribute value if limited to 64kB. +and an attribute value if limited to 64 kB. The list of attribute names that +can be returned is also limited to 64 kB. Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), require the filesystem to be mounted with the
@@ -160,7 +158,7 @@ In the Btrfs filesystem implementation, the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem .I nodesize -value (16kB by default). +value (16 kB by default). .SH CONFORMING TO Extended attributes are not specified in POSIX.1, but some other systems (e.g., the BSDs and Solaris) provide a similar feature.
Quoted 8 lines · Christoph Hellwig
Quoted 5 lines · Michael Kerrisk (man-pages)
Hi Andreas,
As we discussed offlist, it makes sense to have the attr(5) man page in man-pages, rather than as part of the 'attr' project documentation, since it mostly relates to kernel details.
Can you also rename it to xattr while we're at it?
While I actually like the name "xattr" more, I'm a little reluctant to change this, because the page has been around for a long time under the other name. But, I'm open for further argumentation about it. Andreas, what do you think?
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Michael Kerrisk (man-pages)
AppliedHi Andreas,
Quoted 9 lines · Andreas Grünbacher
Michael,
2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 5 lines
Hi Andreas,
I'll move this page into Section 7, since that's where overview type pages such as this are normally placed in man-pages, but I'll also create a link in Section 5, so that acl(5) references will continue to work.
Quoted 6 lines
okay.
Quoted 2 lines
I've made a number of edits to the page. Some of these were just to bring the page closer to man-pages style,
The \(em dashes don't render in terminals very well.
What's the problem? (Many existing pages use \(em dashes so this change was just for consistency.)
Quoted 4 lines
Quoted 2 lines
but others were to amend incorrect technical details and add new details. I'd be pleased if you checked over these commits
Thanks, that all looks good.
Thanks for checking.
Quoted 3 lines
In addition, I would remove the list of file systems with extended attribute support; they are supported pretty much everywhere to some degree at least, even on tmpfs.
Fair enough. I see your patch does that.
Quoted 1 line
I'm attaching a patch that also includes a few other minor changes.
Thanks! Applied.
By the way, the piece
The list of attribute names that can be returned is also limited to 64 kB.
Is a limitation that affects listxattr(2), right? Maybe I should add a sentence on that point to that page.
Also, what does this mean is someone (tries to) create(s) more than 64 kB of attribute names on a file? Do you get an error on setxattr(), or is it the case that some names are unretrievable?
Hmm... some light testing (using XFS) suggests that one can create more than 64 kB of attribute names, but then listxattr() fails with E2BIG. That seems like a sad corner case :-(.
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
2015-04-22 13:36 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 7 lines · Christoph Hellwig
Quoted 1 line
Can you also rename it to xattr while we're at it?
While I actually like the name "xattr" more, I'm a little reluctant to change this, because the page has been around for a long time under the other name. But, I'm open for further argumentation about it. Andreas, what do you think?
attr.5 as an alias to xattr.7 maybe?
Andreas
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
2015-04-22 13:58 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
I've made a number of edits to the page. Some of these were just to bring the page closer to man-pages style,
The \(em dashes don't render in terminals very well.
What's the problem? (Many existing pages use \(em dashes so this change was just for consistency.)
It's just ugly; there isn't a big difference between a hyphen and an em-dash.
Quoted 10 lines
Quoted 3 lines
In addition, I would remove the list of file systems with extended attribute support; they are supported pretty much everywhere to some degree at least, even on tmpfs.
Fair enough. I see your patch does that.
Quoted 1 line
I'm attaching a patch that also includes a few other minor changes.
Thanks! Applied.
Quoted 7 lines
By the way, the piece
The list of attribute names that can be returned is also limited to 64 kB.
Is a limitation that affects listxattr(2), right? Maybe I should add a sentence on that point to that page.
Yes, thanks.
Quoted 7 lines
Also, what does this mean is someone (tries to) create(s) more than 64 kB of attribute names on a file? Do you get an error on
setxattr(), or is it the case that some names are unretrievable?Hmm... some light testing (using XFS) suggests that one can create more than 64 kB of attribute names, but then
listxattr()fails with E2BIG. That seems like a sad corner case :-(.
That's what will happen, yes. I don't have a good idea how to fix this.
Andreas
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 5 lines · Andreas Gr??nbacher
Quoted 3 lines
Hmm... some light testing (using XFS) suggests that one can create more than 64 kB of attribute names, but then
listxattr()fails with E2BIG. That seems like a sad corner case :-(.That's what will happen, yes. I don't have a good idea how to fix this.
We could use the same iterator style for listxattr as we do for readdir. For XFS that would be really easy as the code is already internally structured like that.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 11 lines · Andreas Grünbacher
2015-04-22 13:36 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 7 lines · Christoph Hellwig
Quoted 1 line
Can you also rename it to xattr while we're at it?
While I actually like the name "xattr" more, I'm a little reluctant to change this, because the page has been around for a long time under the other name. But, I'm open for further argumentation about it. Andreas, what do you think?
attr.5 as an alias to xattr.7 maybe?
Yes, I was wondering about that, but waited to see what you thought about the name change idea. I've made the change. xattr(7) it is. (I'll add a note in the page text about the former name.)
Thanks,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Andreas,
Quoted 35 lines · Andreas Grünbacher
2015-04-22 13:58 GMT+02:00 Michael Kerrisk (man-pages) <[email protected]>:
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
I've made a number of edits to the page. Some of these were just to bring the page closer to man-pages style,
The \(em dashes don't render in terminals very well.
What's the problem? (Many existing pages use \(em dashes so this change was just for consistency.)
It's just ugly; there isn't a big difference between a hyphen and an em-dash.
Quoted 10 lines
Quoted 3 lines
In addition, I would remove the list of file systems with extended attribute support; they are supported pretty much everywhere to some degree at least, even on tmpfs.
Fair enough. I see your patch does that.
Quoted 1 line
I'm attaching a patch that also includes a few other minor changes.
Thanks! Applied.
Quoted 7 lines
By the way, the piece
The list of attribute names that can be returned is also limited to 64 kB.
Is a limitation that affects listxattr(2), right? Maybe I should add a sentence on that point to that page.
Yes, thanks.
Quoted 4 lines
Also, what does this mean is someone (tries to) create(s) more than 64 kB of attribute names on a file? Do you get an error on
setxattr(), or is it the case that some names are unretrievable?
Quoted 5 lines
Quoted 3 lines
Hmm... some light testing (using XFS) suggests that one can create more than 64 kB of attribute names, but then
listxattr()fails with E2BIG. That seems like a sad corner case :-(.That's what will happen, yes. I don't have a good idea how to fix this.
:-(. Okay, I've documented that error in listxattr(2) and added a BUGS section pointing out that corner case.
Thanks,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html