[DSE-Dev] Bug#1101951: avc_has_perm.3: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Wed Apr 2 20:19:51 BST 2025
Package: libselinux1-dev
Version: 3.8.1-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "grep -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:4: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.20-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages libselinux1-dev depends on:
ii libpcre2-dev 10.45-1
ii libselinux1 3.8.1-1
ii libsepol-dev 3.8.1-1
libselinux1-dev recommends no packages.
libselinux1-dev suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is avc_has_perm.3
Output from "mandoc -T lint avc_has_perm.3": (shortened list)
1 input text line longer than 80 bytes: Entry references can...
1 input text line longer than 80 bytes: If requested permiss...
1 input text line longer than 80 bytes: Originally Eamon Wal...
1 input text line longer than 80 bytes: argument, if supplie...
1 input text line longer than 80 bytes: avc_has_perm, avc_ha...
1 input text line longer than 80 bytes: callback and can be ...
1 input text line longer than 80 bytes: if non-NULL, to refe...
1 input text line longer than 80 bytes: will be updated to r...
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z avc_has_perm.3": (shortened list)
10 Use macro '.B' for one argument or split argument.
1 Use macro '.I' for one argument or split argument.
10 .BR is for at least 2 arguments, got 1
1 .IR is for at least 2 arguments, got 1
1 line(s) with a trailing space
Remove trailing space with: sed -e 's/ *$//'
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 6, length 110
avc_has_perm, avc_has_perm_noaudit, avc_audit, avc_entry_ref_init \- obtain and audit SELinux access decisions
Line 87, length 153
if non-NULL, to refer to a cache entry with the resulting decision. The granting or denial of permissions is audited in accordance with the policy. The
Line 119, length 82
callback and can be used to add supplemental information to the audit message; see
Line 123, length 142
Entry references can be used to speed cache performance for repeated queries on the same subject and target. The userspace AVC will check the
Line 125, length 101
argument, if supplied, before searching the cache on a permission query. After a query is performed,
Line 127, length 181
will be updated to reference the cache entry for that query. A subsequent query on the same subject and target will then have the decision at hand without having to walk the cache.
Line 141, length 134
If requested permissions are granted, zero is returned. If requested permissions are denied or an error occurred, \-1 is returned and
Line 179, length 84
Originally Eamon Walsh. Updated by Stephen Smalley <stephen.smalley.work at gmail.com>
Longest line is number 127 with 181 characters
-.-.
Split a punctuation mark from a single argument for a two-font macro
55:.BR selinux_set_callback(3).
184:.BR selinux_check_access(3),
185:.BR string_to_security_class(3),
186:.BR string_to_av_perm(3),
187:.BR selinux_set_callback(3),
188:.BR selinux_set_mapping(3),
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
40:.BR selinux_check_access(3)
47:.BR string_to_security_class(3)
49:.BR string_to_av_perm(3)
55:.BR selinux_set_callback(3).
58:.BR selinux_set_mapping(3)
184:.BR selinux_check_access(3),
185:.BR string_to_security_class(3),
186:.BR string_to_av_perm(3),
187:.BR selinux_set_callback(3),
188:.BR selinux_set_mapping(3),
-.-.
Put a subordinate sentence (after a comma) on a new line.
avc_has_perm.3:46:classes or permissions as inputs, use
avc_has_perm.3:51:These values may change across a policy reload, so they should be
avc_has_perm.3:64:However, this also requires setting up a callback as above
avc_has_perm.3:87:if non-NULL, to refer to a cache entry with the resulting decision. The granting or denial of permissions is audited in accordance with the policy. The
avc_has_perm.3:125:argument, if supplied, before searching the cache on a permission query. After a query is performed,
avc_has_perm.3:141:If requested permissions are granted, zero is returned. If requested permissions are denied or an error occurred, \-1 is returned and
avc_has_perm.3:145:In permissive mode, zero will be returned and
avc_has_perm.3:171:to be returned unexpectedly. For example, netlink socket errors may produce
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
avc_has_perm.3:4:.TH "avc_has_perm" "3" "27 May 2004" "" "SELinux API documentation"
avc_has_perm.3:5:.SH "NAME"
avc_has_perm.3:8:.SH "SYNOPSIS"
avc_has_perm.3:13:.BI "void avc_entry_ref_init(struct avc_entry_ref *" aeref ");"
avc_has_perm.3:19:.BI "struct avc_entry_ref *" aeref ", void *" auditdata ");"
avc_has_perm.3:26:.BI "struct avc_entry_ref *" aeref ", struct av_decision *" avd ");"
avc_has_perm.3:33:.BI "struct av_decision *" avd ", int " result ", void *" auditdata ");"
avc_has_perm.3:36:.SH "DESCRIPTION"
avc_has_perm.3:151:.SH "ERRORS"
avc_has_perm.3:168:.SH "NOTES"
avc_has_perm.3:178:.SH "AUTHOR"
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
182:.ad l
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
5:.SH "NAME"
8:.SH "SYNOPSIS"
36:.SH "DESCRIPTION"
122:.SH "ENTRY REFERENCES"
140:.SH "RETURN VALUE"
151:.SH "ERRORS"
168:.SH "NOTES"
178:.SH "AUTHOR"
181:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
an.tmac:<stdin>:4: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:40: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:47: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:49: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:55: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:58: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:75: warning: trailing space in the line
an.tmac:<stdin>:79: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:184: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:185: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:186: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:187: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:188: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-------------- next part --------------
--- avc_has_perm.3 2025-04-02 18:43:21.198773404 +0000
+++ avc_has_perm.3.new 2025-04-02 19:09:33.035798929 +0000
@@ -1,67 +1,72 @@
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewalsh at tycho.nsa.gov) 2004
-.TH "avc_has_perm" "3" "27 May 2004" "" "SELinux API documentation"
-.SH "NAME"
-avc_has_perm, avc_has_perm_noaudit, avc_audit, avc_entry_ref_init \- obtain and audit SELinux access decisions
+.TH avc_has_perm 3 "27 May 2004" "" "SELinux API documentation"
+.SH NAME
+avc_has_perm, avc_has_perm_noaudit, avc_audit, avc_entry_ref_init
+\- obtain and audit SELinux access decisions
.
-.SH "SYNOPSIS"
+.SH SYNOPSIS
.B #include <selinux/selinux.h>
.br
.B #include <selinux/avc.h>
.sp
-.BI "void avc_entry_ref_init(struct avc_entry_ref *" aeref ");"
+.BI "void avc_entry_ref_init(struct avc_entry_ref *" aeref );
.sp
.BI "int avc_has_perm(security_id_t " ssid ", security_id_t " tsid ,
.in +\w'int avc_has_perm('u
.BI "security_class_t " tclass ", access_vector_t " requested ,
.br
-.BI "struct avc_entry_ref *" aeref ", void *" auditdata ");"
+.BI "struct avc_entry_ref *" aeref ", void *" auditdata );
.in
.sp
.BI "int avc_has_perm_noaudit(security_id_t " ssid ", security_id_t " tsid ,
.in +\w'int avc_has_perm('u
.BI "security_class_t " tclass ", access_vector_t " requested ,
.br
-.BI "struct avc_entry_ref *" aeref ", struct av_decision *" avd ");"
+.BI "struct avc_entry_ref *" aeref ", struct av_decision *" avd );
.in
.sp
.BI "void avc_audit(security_id_t " ssid ", security_id_t " tsid ,
.in +\w'void avc_audit('u
.BI "security_class_t " tclass ", access_vector_t " requested ,
.br
-.BI "struct av_decision *" avd ", int " result ", void *" auditdata ");"
+.BI "struct av_decision *" avd ", int " result ", void *" auditdata );
.in
.
-.SH "DESCRIPTION"
+.SH DESCRIPTION
Direct use of these functions is generally discouraged in favor of
the higher level interface
-.BR selinux_check_access(3)
+.BR selinux_check_access (3)
since the latter automatically handles the dynamic mapping of class
and permission names to their policy values and proper handling of
allow_unknown.
-When using any of the functions that take policy integer values for
-classes or permissions as inputs, use
-.BR string_to_security_class(3)
+When using any of the functions
+that take policy integer values for classes
+or permissions as inputs, use
+.BR string_to_security_class (3)
and
-.BR string_to_av_perm(3)
-to map the class and permission names to their policy values.
-These values may change across a policy reload, so they should be
-re-acquired on every use or using a
+.BR string_to_av_perm (3)
+to map the class
+and permission names to their policy values.
+These values may change across a policy reload,
+so they should be re-acquired on every use
+or using a
.B SELINUX_CB_POLICYLOAD
callback set via
-.BR selinux_set_callback(3).
+.BR selinux_set_callback (3).
An alternative approach is to use
-.BR selinux_set_mapping(3)
+.BR selinux_set_mapping (3)
to create a mapping from class and permission index values
used by the application to the policy values,
thereby allowing the application to pass its own
fixed constants for the classes and permissions to
these functions and internally mapping them on demand.
-However, this also requires setting up a callback as above
+However,
+this also requires setting up a callback as above
to address policy reloads.
.BR avc_entry_ref_init ()
@@ -72,11 +77,11 @@ structure; see
below. This function may be implemented as a macro.
.BR avc_has_perm ()
-checks whether the
+checks whether the
.I requested
permissions are granted
for subject SID
-.IR ssid
+.I ssid
and target SID
.IR tsid ,
interpreting the permissions
@@ -84,7 +89,12 @@ based on
.I tclass
and updating
.IR aeref ,
-if non-NULL, to refer to a cache entry with the resulting decision. The granting or denial of permissions is audited in accordance with the policy. The
+if non-NULL,
+to refer to a cache entry with the resulting decision.
+The granting
+or denial of permissions
+is audited in accordance with the policy.
+The
.I auditdata
parameter is for supplemental auditing; see
.BR avc_audit ()
@@ -116,15 +126,23 @@ The
.I auditdata
parameter is passed to the user-supplied
.B func_audit
-callback and can be used to add supplemental information to the audit message; see
+callback
+and can be used to add supplemental information to the audit message;
+see
.BR avc_init (3).
.
-.SH "ENTRY REFERENCES"
-Entry references can be used to speed cache performance for repeated queries on the same subject and target. The userspace AVC will check the
+.SH ENTRY REFERENCES
+Entry references can be used to speed cache performance
+for repeated queries on the same subject and target.
+The userspace AVC will check the
.I aeref
-argument, if supplied, before searching the cache on a permission query. After a query is performed,
+argument, if supplied,
+before searching the cache on a permission query.
+After a query is performed,
.I aeref
-will be updated to reference the cache entry for that query. A subsequent query on the same subject and target will then have the decision at hand without having to walk the cache.
+will be updated to reference the cache entry for that query.
+A subsequent query on the same subject and target
+will then have the decision at hand without having to walk the cache.
After declaring an
.B avc_entry_ref
@@ -137,18 +155,23 @@ or
for the first time.
Using an uninitialized structure will produce undefined behavior.
.
-.SH "RETURN VALUE"
-If requested permissions are granted, zero is returned. If requested permissions are denied or an error occurred, \-1 is returned and
+.SH RETURN VALUE
+If requested permissions are granted,
+zero is returned.
+If requested permissions are denied
+or an error occurred,
+\-1 is returned and
.I errno
is set appropriately.
-In permissive mode, zero will be returned and
+In permissive mode,
+zero will be returned and
.I errno
unchanged even if permissions were denied.
.BR avc_has_perm ()
will still produce an audit message in this case.
.
-.SH "ERRORS"
+.SH ERRORS
.TP
.B EACCES
A requested permission was denied.
@@ -165,27 +188,30 @@ are not recognized by the currently load
.B ENOMEM
An attempt to allocate memory failed.
.
-.SH "NOTES"
+.SH NOTES
Internal errors encountered by the userspace AVC may cause certain values of
.I errno
-to be returned unexpectedly. For example, netlink socket errors may produce
+to be returned unexpectedly.
+For example,
+netlink socket errors may produce
.B EACCES
or
.BR EINVAL .
Make sure that userspace object managers are granted appropriate access to
netlink by the policy.
.
-.SH "AUTHOR"
-Originally Eamon Walsh. Updated by Stephen Smalley <stephen.smalley.work at gmail.com>
+.SH AUTHOR
+Originally Eamon Walsh.
+Updated by Stephen Smalley <stephen.smalley.work at gmail.com>
.
-.SH "SEE ALSO"
-.ad l
+.SH SEE ALSO
+.na
.nh
-.BR selinux_check_access(3),
-.BR string_to_security_class(3),
-.BR string_to_av_perm(3),
-.BR selinux_set_callback(3),
-.BR selinux_set_mapping(3),
+.BR selinux_check_access (3),
+.BR string_to_security_class (3),
+.BR string_to_av_perm (3),
+.BR selinux_set_callback (3),
+.BR selinux_set_mapping (3),
.BR avc_init (3),
.BR avc_context_to_sid (3),
.BR avc_cache_stats (3),
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
More information about the SELinux-devel
mailing list