Hello Andreas,
Here, some comments on the getrichacl(1) page.
> .\"
> .\" Richacl Manual Pages
> .\"
> .\" Copyright (C) 2015 Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <[email protected]>
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual. If not, see
> .\" <http://www.gnu.org/licenses/>.
> .\"
> .TH GETRICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
>
> .SH NAME
> getrichacl \- Get Rich Access Control Lists
>
> .SH SYNOPSIS
> .B getrichacl
> .RI [ OPTION "]... [" FILE ]...
In man-pages, at least, the convention is to use lower case for these
pieces (and thus through the remainder of the page), so:
> .RI [ option "]... [" file ]...
> .SH DESCRIPTION
> For each file, getrichacl displays the file name and Rich Access Control List
For man-pages, at least, the convention is that the references to the
function/command name explained in the page are bold, do:
.BR getrichacl
> (richacl).
For what it's worth, I think it would be worthwhile to start with
a consistent abbreviation comment here (and use it throughout all of the
man pages): "RichACL" (or "richACL"), rather than "richacl"; that seems
more consistent with the traditional abbreviation "ACL".
>
> By default, getrichacl displays the effective permissions remaining after
.BR getrichacl
> applying the file masks to the ACL. The file masks and underlying NFSv4 ACL
> can be displayed with the \-\-raw option.
Use
.BR \-\-raw
>
> The output format of getrichacl is as follows:
.BR getrichacl
> .fam C
> .RS
> .nf
> 1: file:
> 2: flags:a
> 3: owner:rwp-------------::mask
> 4: group:r-p-------------::mask
> 5: other:r---------------::mask
> 6: owner@:rwp-------------::allow
> 7: user:foo:r-p-------------::allow
> 8: group@:r-p-------------::allow
> 9: group:bar:r-p-------------::allow
> 10: everyone@:r---------------::allow
> 11:
> .fi
> .RE
> .fam T
>
> Line 1 contains the file name, followed by a colon.
>
> Line 2 contains the ACL flags. This line is omitted if no flags are set.
>
> Lines 3--5 indicate the owner, group, and other file masks, which are only
> shown if the \-\-raw option is specified.
>
> Lines 6--10 indicate different ACL entries for the file owner
> .RB ( owner@ ),
> user foo, the owning group
> .RB ( group@ ),
> group bar, and for everyone
.IR bar ,
> .RB ( everyone@ ).
>
> A blank line follows at the end.
>
> By default, getrichacl displays the the single-letter forms of flags and
.BR getrichacl
s/the the/the/
> permissions, the identifiers of ACL entryies are right justified, the
s/entryies/entries/
> permissions are vertically aligned, and permissions which are always
> granted
> .RB ( read_attributes ", " read_acl ", " synchronize )
> are omitted. See the richacl(7) manual page for the defined flags and
Use
.BR richachl (7)
for page cross references.
> permissions.
>
> When getrichacl is used on a file that does not have a richacl or on a
.BR getrichacl
> filesystem that does not support richacls, getrichacl displays the access
.BR getrichacl
> permissions defined by the traditional file permission bits as a richacl. When
> getrichacl is used on a file that has a POSIX ACL, it prints an error message.
.BR getrichacl
And then:
[...] has a POSIX ACL (see
.BR acl (7)), it prints [...]
>
> .SH OPTIONS
> .TP
> \fB\-\-long\fR, \fB\-l\fR
> Display access masks and flags in their long form.
> .TP
> \fB\-\-full\fR
> Also show permissions which are always implicitly allowed.
> .TP
> \fB\-\-raw\fR
> Show acls as stored on the file system including the file masks. Implies
s/axls/ACLs/
> \fB\-\-full\fR.
> .TP
> \fB\-\-unaligned\fR
> Do not align ACL entries or pad missing permissions with '-'.
> .TP
> \fB\-\-numeric-ids\fR
> Display numeric user and group IDs instead of names.
> .TP
> \fB\-\-access\fR [=\fIuser\fR[:\fIgroup\fR:...]}, \fB\-a\fR[\fIuser\fR[:\fIgroup\fR:...]}
> Instead of the ACL, show which permissions the caller or a specified user has
"caller"? "the user running the command, "
> for file(s). When a list of groups is given, this overrides the groups the
s/file(s)/specified file(s)/
> user is in.
The preceding text is not very clear.
> .TP
> \fB\-\-version\fR, \fB\-v\fR
> Display the version of getrichacl and exit.
.BR getrichacl
> .TP
> \fB\-\-help\fR, \fB\-h\fR
> Display command-line usage help text.
>
> .SH AUTHOR
> Written by Andreas Grünbacher <[email protected]>.
>
> Please send your bug reports, suggested features and comments to the above address.
>
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
>
> .SH SEE ALSO
> .BR setrichacl (1),
> .BR richacl (7)
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Am Sonntag, 7. Februar 2016, 17:30:49 CET schrieb Michael Kerrisk (man-pages):
> Hello Andreas,
>
> Here, some comments on the getrichacl(1) page.
I know that the command names are based on setfacl and getfacl. But sometimes
I still wonder about these names. They just don´t fit.
Its chsomething for changing things in Unix traditionally – chown, chmod,
chattr, chage chsh, you name it –, but there is nothing for querying things.
So I get where this is coming from, yet I always found setfacl and getfacl
command names cumbersome.
Sorry, for posting here instead of a previous richacl implementation patchset.
I fully appreciate that it may be too late to change anything regarding
command names. Also considering usermod and groupmod the command naming in
Unix / Linux appears to be a big mess anyway.
Thanks,
--
Martin
Hi Andreas,
Here's a few more comments on the current getrichacl(1) page
that I fetched from the git repo.
> .\"
> .\" RichACL Manual Pages
> .\"
> .\" Copyright (C) 2015,2016 Red Hat, Inc.
> .\" Written by Andreas Gruenbacher <[email protected]>
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual. If not, see
> .\" <http://www.gnu.org/licenses/>.
> .\"
> .TH GETRICHACL 7 2015-09-01 "Linux" "Rich Access Control Lists"
>
> .SH NAME
> getrichacl \- Get Rich Access Control Lists
>
> .SH SYNOPSIS
> .B getrichacl
> .RI [ option "]... [" file ]...
>
> .SH DESCRIPTION
> For each file,
> .B getrichacl
> displays the file name and the file's Rich Access Control List (RichACL).
>
> The output format of
> .B getrichacl
> is as follows:
Add a blank line here.
> .fam C
> .RS
> .nf
> 1: file:
> 2: flags:a
> 3: owner:rwp-------------::mask
> 4: group:r-p-------------::mask
> 5: other:r---------------::mask
> 6: owner@:rwp-------------::allow
> 7: user:foo:r-p-------------::allow
> 8: group@:r-p-------------::allow
> 9: group:bar:r-p-------------::allow
> 10: everyone@:r---------------::allow
> 11:
> .fi
> .RE
> .fam T
>
> Line 1 contains the file name, followed by a colon.
>
> Line 2 contains the ACL flags. This line is omitted if no flags are set.
>
> Lines 3--5 indicate the owner, group, and other file masks, which are only
> shown if the \fB\-\-raw\fR option is specified.
>
> Lines 6--10 indicate different ACL entries for the file owner
> .RB ( owner@ ),
> user \fIfoo\fR, the owning group
> .RB ( group@ ),
> group \fIbar\fR, and for everyone
> .RB ( everyone@ ).
>
> A blank line follows at the end.
>
> The default output format uses the single-letter forms of flags and
> permissions, identifiers of ACL entries are right justified, permissions are
> vertically aligned, and permissions which are always granted
> .RB ( read_attributes ", " read_acl ", " synchronize )
> are omitted. See the
> .BR richacl (7)
> manual page for the defined flags and permissions.
>
> By default,
> .B getrichacl
> displays the effective permissions remaining after applying the file masks to
> the ACL. The file masks and underlying NFSv4 ACL can be displayed with the
> \fB\-\-raw\fR option.
>
> When
> .B getrichacl
> is used on a file that does not have a RichACL or on a filesystem that does not
> support RichACLs,
> .B getrichacl
Replace the previous line with "it".
> displays the access permissions defined by the traditional file permission bits
> as a RichACL. When
> .B getrichacl
> is used on a file that has a POSIX ACL (see
> .BR acl (5)),
> it prints an error message.
>
> .SH OPTIONS
> .TP
> \fB\-\-long\fR, \fB\-l\fR
> Display access masks and flags in their long form.
> .TP
> \fB\-\-full\fR
> Also show permissions which are always implicitly allowed.
> .TP
> \fB\-\-raw\fR
> Show ACLs as stored on the file system, including the file masks. Implies
> \fB\-\-full\fR.
> .TP
> \fB\-\-unaligned\fR
> Do not align ACL entries or pad missing permissions with '-'.
> .TP
> \fB\-\-numeric-ids\fR
> Display numeric user and group IDs instead of names.
> .TP
> \fB\-\-access\fR [=\fIuser\fR[:\fIgroup\fR:...]}, \fB\-a\fR[\fIuser\fR[:\fIgroup\fR:...]}
> Instead of showing the ACL, show which permissions the user running the command
> has for the specified file(s). When \fIuser\fR is specified, show which
> permissions the specified user has instead. If \fIuser\fR is followed by a
> colon and a (possibly empty) list of groups, assume that \fIuser\fR is a member
> in the specified groups; otherwise,
> .BR getgrouplist (3)
> is used to determine the groups \fIuser\fR is a member in.
s/in/of/
> .TP
> \fB\-\-version\fR, \fB\-v\fR
> Display the version of
> .B getrichacl
> and exit.
> .TP
> \fB\-\-help\fR, \fB\-h\fR
> Display command-line usage help text.
>
> .SH AUTHOR
> Written by Andreas Grünbacher <[email protected]>.
>
> Please send your bug reports, suggested features and comments to the above address.
>
> .SH CONFORMING TO
> Rich Access Control Lists are Linux-specific.
>
> .SH SEE ALSO
> .BR richacl (7),
> .BR setrichacl (1)
Cheers,
Michael