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
Input file is avc_add_callback.3
Output from "mandoc -T lint avc_add_callback.3": (shortened list)
1 input text line longer than 80 bytes: A return value of \-...
1 input text line longer than 80 bytes: Indicates that the c...
1 input text line longer than 80 bytes: Support for dynamic ...
1 input text line longer than 80 bytes: avc_add_callback \- ...
1 input text line longer than 80 bytes: encountered to the c...
1 input text line longer than 80 bytes: indicating that the ...
1 input text line longer than 80 bytes: is called. In non-t...
1 input text line longer than 80 bytes: is used to register ...
1 input text line longer than 80 bytes: may be executed in t...
1 input text line longer than 80 bytes: specify the source a...
3 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z avc_add_callback.3": (shortened list)
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
3
-.-.
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 87
avc_add_callback \- additional event notification for SELinux userspace object
managers
Line 35, length 249
is used to register callback functions on security events. The purpose of this
functionality is to allow userspace object managers to take additional action
when a policy change, usually a policy reload, causes permissions to be granted
or revoked.
Line 49, length 132
specify the source and target SID's, target class, and specific permissions
that the callback wishes to monitor. The special symbol
Line 75, length 102
indicating that the change applies to all source and/or target SID's. Unless
otherwise indicated, the
Line 114, length 111
Indicates that the cache was flushed. The SID, class, and permission arguments
are unused and are set to NULL.
Line 159, length 285
A return value of \-1 from a callback is interpreted as a failed policy
operation. If such a return value is encountered, all remaining callbacks
registered on the event are called. In threaded mode, the netlink handler
thread may then terminate and cause the userspace AVC to return
Line 163, length 116
is called. In non-threaded mode, the permission check on which the error
occurred will return \-1 and the value of
Line 165, length 113
encountered to the caller. In both cases, a log message is produced and the
kernel may be notified of the error.
Line 175, length 145
may be executed in the context of the netlink handler thread. This will likely
introduce synchronization issues requiring the use of locks. See
Line 178, length 167
Support for dynamic revocation and retained permissions is mostly unimplemented
in the SELinux kernel module. The only security event that currently gets
exercised is
Longest line is number 159 with 285 characters
-.-.
Put a subordinate sentence (after a comma) on a new line.
avc_add_callback.3:35:is used to register callback functions on security
events. The purpose of this functionality is to allow userspace object
managers to take additional action when a policy change, usually a policy
reload, causes permissions to be granted or revoked.
avc_add_callback.3:49:specify the source and target SID's, target class, and
specific permissions that the callback wishes to monitor. The special symbol
avc_add_callback.3:62:of the callback should be zero on success, \-1 on error
with
avc_add_callback.3:75:indicating that the change applies to all source and/or
target SID's. Unless otherwise indicated, the
avc_add_callback.3:114:Indicates that the cache was flushed. The SID, class,
and permission arguments are unused and are set to NULL.
avc_add_callback.3:155:returns zero. On error, \-1 is returned and
avc_add_callback.3:159:A return value of \-1 from a callback is interpreted as
a failed policy operation. If such a return value is encountered, all
remaining callbacks registered on the event are called. In threaded mode, the
netlink handler thread may then terminate and cause the userspace AVC to return
avc_add_callback.3:163:is called. In non-threaded mode, the permission check
on which the error occurred will return \-1 and the value of
avc_add_callback.3:165:encountered to the caller. In both cases, a log message
is produced and the kernel may be notified of the error.
avc_add_callback.3:173:If the userspace AVC is running in threaded mode,
callbacks registered via
-.-.
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_add_callback.3:4:.TH "avc_add_callback" "3" "9 June 2004" "" "SELinux API
documentation"
avc_add_callback.3:5:.SH "NAME"
avc_add_callback.3:8:.SH "SYNOPSIS"
avc_add_callback.3:23:.BI "access_vector_t *" out_retained "),"
avc_add_callback.3:30:.BI "access_vector_t " perms ");"
avc_add_callback.3:33:.SH "DESCRIPTION"
avc_add_callback.3:167:.SH "ERRORS"
avc_add_callback.3:172:.SH "NOTES"
avc_add_callback.3:181:.SH "AUTHOR"
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
185:.ad l
-.-.
Space character after a macro call.
13:.BI "int avc_add_callback(int (*" callback ")(uint32_t " event ,
26:.BI "uint32_t " events ", security_id_t " ssid ,
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
5:.SH "NAME"
8:.SH "SYNOPSIS"
33:.SH "DESCRIPTION"
68:.SH "SECURITY EVENTS"
152:.SH "RETURN VALUE"
167:.SH "ERRORS"
172:.SH "NOTES"
181:.SH "AUTHOR"
184:.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")
troff:<stdin>:163: warning: trailing space in the line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- avc_add_callback.3 2025-04-01 17:54:53.188868709 +0000
+++ avc_add_callback.3.new 2025-04-01 18:12:39.741558151 +0000
@@ -1,16 +1,16 @@
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewa...@tycho.nsa.gov) 2004
-.TH "avc_add_callback" "3" "9 June 2004" "" "SELinux API documentation"
-.SH "NAME"
+.TH avc_add_callback 3 "9 June 2004" "" "SELinux API documentation"
+.SH NAME
avc_add_callback \- additional event notification for SELinux userspace object
managers
.
-.SH "SYNOPSIS"
+.SH SYNOPSIS
.B #include <selinux/selinux.h>
.br
.B #include <selinux/avc.h>
.sp
-.BI "int avc_add_callback(int (*" callback ")(uint32_t " event ,
+.BI "int avc_add_callback(int (*" callback ")(uint32_t " event ,
.in +\w'int avc_add_callback(int (*callback)('u
.BI "security_id_t " ssid ,
.br
@@ -20,19 +20,24 @@ avc_add_callback \- additional event not
.br
.BI "access_vector_t " perms ,
.br
-.BI "access_vector_t *" out_retained "),"
+.BI "access_vector_t *" out_retained ),
.in
.in +\w'int avc_add_callback('u
-.BI "uint32_t " events ", security_id_t " ssid ,
+.BI "uint32_t " events ", security_id_t " ssid ,
.br
.BI "security_id_t " tsid ", security_class_t " tclass ,
.br
-.BI "access_vector_t " perms ");"
+.BI "access_vector_t " perms );
.in
.
-.SH "DESCRIPTION"
+.SH DESCRIPTION
.BR avc_add_callback ()
-is used to register callback functions on security events. The purpose of
this functionality is to allow userspace object managers to take additional
action when a policy change, usually a policy reload, causes permissions to be
granted or revoked.
+is used to register callback functions on security events.
+The purpose of this functionality
+is to allow userspace object managers to take additional action
+when a policy change,
+usually a policy reload,
+causes permissions to be granted or revoked.
.I events
is the
@@ -46,7 +51,12 @@ below.
.IR tclass ,
and
.I perms
-specify the source and target SID's, target class, and specific permissions
that the callback wishes to monitor. The special symbol
+specify the source
+and target SID's,
+target class,
+and specific permissions
+that the callback wishes to monitor.
+The special symbol
.B SECSID_WILD
may be passed as the
.I source
@@ -59,20 +69,24 @@ is the callback function provided by the
.I event
argument indicates the security event which occurred; the remaining arguments
are interpreted according to the event as described below. The return value
-of the callback should be zero on success, \-1 on error with
+of the callback should be zero on success,
+\-1 on error with
.I errno
set appropriately (but see
.B RETURN VALUE
below).
.
-.SH "SECURITY EVENTS"
+.SH SECURITY EVENTS
In all cases below,
.I ssid
and/or
.I tsid
may be set to
.BR SECSID_WILD ,
-indicating that the change applies to all source and/or target SID's. Unless
otherwise indicated, the
+indicating
+that the change applies to all source
+and/or target SID's.
+Unless otherwise indicated, the
.I out_retained
parameter is unused.
.
@@ -111,7 +125,9 @@ with respect to
indicates the permissions to revoke.
.TP
.B AVC_CALLBACK_RESET
-Indicates that the cache was flushed. The SID, class, and permission
arguments are unused and are set to NULL.
+Indicates that the cache was flushed.
+The SID, class, and permission arguments are unused
+and are set to NULL.
.TP
.B AVC_CALLBACK_AUDITALLOW_ENABLE
The permissions given by
@@ -149,40 +165,62 @@ should no longer be audited when denied
with respect to
.IR tclass .
.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success,
.BR avc_add_callback ()
returns zero. On error, \-1 is returned and
.I errno
is set appropriately.
-A return value of \-1 from a callback is interpreted as a failed policy
operation. If such a return value is encountered, all remaining callbacks
registered on the event are called. In threaded mode, the netlink handler
thread may then terminate and cause the userspace AVC to return
+A return value of \-1 from a callback is interpreted as a failed policy
+operation.
+If such a return value is encountered,
+all remaining callbacks registered on the event are called.
+In threaded mode,
+the netlink handler thread may then terminate
+and cause the userspace AVC to return
.B EINVAL
on all further permission checks until
.BR avc_destroy (3)
-is called. In non-threaded mode, the permission check on which the error
occurred will return \-1 and the value of
+is called.
+In non-threaded mode,
+the permission check
+on which the error occurred
+will return \-1
+and the value of
.I errno
-encountered to the caller. In both cases, a log message is produced and the
kernel may be notified of the error.
+encountered to the caller.
+In both cases,
+a log message is produced
+and the kernel may be notified of the error.
.
-.SH "ERRORS"
+.SH ERRORS
.TP
.B ENOMEM
An attempt to allocate memory failed.
.
-.SH "NOTES"
-If the userspace AVC is running in threaded mode, callbacks registered via
+.SH NOTES
+If the userspace AVC is running in threaded mode,
+callbacks registered via
.BR avc_add_callback ()
-may be executed in the context of the netlink handler thread. This will
likely introduce synchronization issues requiring the use of locks. See
+may be executed in the context of the netlink handler thread.
+This will likely introduce synchronization issues requiring the use of
+locks.
+See
.BR avc_init (3).
-Support for dynamic revocation and retained permissions is mostly
unimplemented in the SELinux kernel module. The only security event that
currently gets exercised is
+Support for dynamic revocation
+and retained permissions is mostly unimplemented in the SELinux kernel
+module.
+The only security event
+that currently gets exercised is
.BR AVC_CALLBACK_RESET .
.
-.SH "AUTHOR"
+.SH AUTHOR
Eamon Walsh <ewa...@tycho.nsa.gov>
.
-.SH "SEE ALSO"
-.ad l
+.SH SEE ALSO
+.na
.nh
.BR avc_init (3),
.BR avc_has_perm (3),
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)
-.-
