Moving attr(5) man page to man-pages

Moving attr(5) man page to man-pages

[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.

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

-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Andreas Grünbacher]

Michael,

2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Christoph Hellwig]

On Wed, Apr 22, 2015 at 10:55:42AM +0200, Michael Kerrisk (man-pages) wrote:
> 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Andreas Grünbacher]

[-- Attachment #1: Type: text/plain, Size: 946 bytes --]

Michael,

2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> 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.

> 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.

> 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

[-- Attachment #2: attr.7.diff --]
[-- Type: text/plain, Size: 1991 bytes --]

diff --git a/man7/attr.7 b/man7/attr.7
index 75379e6..3fc8f76 100644
--- a/man7/attr.7
+++ b/man7/attr.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.

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Michael Kerrisk (man-pages)]

On 04/22/2015 12:21 PM, Christoph Hellwig wrote:
> On Wed, Apr 22, 2015 at 10:55:42AM +0200, Michael Kerrisk (man-pages) wrote:
>> 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


-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Michael Kerrisk (man-pages)]

Hi Andreas,

On 04/22/2015 12:42 PM, Andreas Grünbacher wrote:
> Michael,
> 
> 2015-04-22 10:55 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>:
>> 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.
> 
>> 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.)

>> 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.

> 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.

> 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



-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Andreas Grünbacher]

2015-04-22 13:36 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> On 04/22/2015 12:21 PM, Christoph Hellwig wrote:
>> 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Andreas Grünbacher]

2015-04-22 13:58 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
>>> 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.

>> 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.
>
>> 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.

Yes, thanks.

> 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Christoph Hellwig]

On Wed, Apr 22, 2015 at 02:16:15PM +0200, Andreas Gr??nbacher wrote:
> > 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Michael Kerrisk (man-pages)]

On 04/22/2015 02:12 PM, Andreas Grünbacher wrote:
> 2015-04-22 13:36 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>:
>> On 04/22/2015 12:21 PM, Christoph Hellwig wrote:
>>> 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


-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Acl-devel] Moving attr(5) man page to man-pages

[Michael Kerrisk (man-pages)]

Hi Andreas,

On 04/22/2015 02:16 PM, Andreas Grünbacher wrote:
> 2015-04-22 13:58 GMT+02:00 Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>:
>>>> 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.
> 
>>> 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.
>>
>>> 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.
> 
> Yes, thanks.
> 
>> 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.

:-(. Okay, I've documented that error in listxattr(2) and added
a BUGS section pointing out that corner case.

Thanks,

Michael

-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html