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")
troff:<stdin>:56: warning: trailing space in the line
troff:<stdin>:60: warning: trailing space in the line
troff:<stdin>:81: warning: trailing space in the line
troff:<stdin>:85: warning: trailing space in the line
troff:<stdin>:89: warning: trailing space in the line
troff:<stdin>:117: warning: trailing space in the line
troff:<stdin>:119: warning: trailing space in the line
* 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_init.3
Output from "mandoc -T lint avc_init.3": (shortened list)
1 input text line longer than 80 bytes: Functions with a ret...
1 input text line longer than 80 bytes: If a netlink thread ...
1 input text line longer than 80 bytes: Linux kernel version...
1 input text line longer than 80 bytes: SELinux status state...
1 input text line longer than 80 bytes: The purpose of this ...
1 input text line longer than 80 bytes: The userspace AVC ca...
1 input text line longer than 80 bytes: a dedicated thread w...
1 input text line longer than 80 bytes: callback should crea...
1 input text line longer than 80 bytes: currently has a leng...
1 input text line longer than 80 bytes: does not set threadi...
1 input text line longer than 80 bytes: events will have the...
1 input text line longer than 80 bytes: freeing any resource...
1 input text line longer than 80 bytes: initializes the user...
1 input text line longer than 80 bytes: structure to specify...
1 input text line longer than 80 bytes: style format and arg...
1 input text line longer than 80 bytes: the AVC will default...
1 input text line longer than 80 bytes: to initialize the se...
1 input text line longer than 80 bytes: will be prepended to...
9 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z avc_init.3": (shortened list)
7 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
9
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
166:to initialize the selinux status state. If successfully initialized, the
userspace AVC will default to single-threaded mode and ignore the
170:callbacks. All callbacks set via
198:does not set threading or locking callbacks. In the fallback case, the
userspace AVC checks for new netlink messages at the start of each permission
query. If threading and locking callbacks are passed to
-.-.
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 32, length 109
initializes the userspace AVC and must be called before any other AVC operation
can be performed. A non-NULL
Line 34, length 184
will be prepended to all audit messages produced by the userspace AVC. The
default is `uavc'. The remaining arguments, if non-NULL, specify callbacks to
be used by the userspace AVC.
Line 37, length 138
The userspace AVC can be directed how to perform memory allocation, logging,
thread creation, and locking via callback functions passed to
Line 39, length 130
The purpose of this functionality is to allow the userspace AVC to be smoothly
integrated into existing userspace object managers.
Line 83, length 120
style format and arguments and log them as desired. The default behavior
prints the message on the standard error. The
Line 113, length 108
callback should create a new thread and return a pointer which references it.
The thread should execute the
Line 127, length 87
structure to specify functions to create, obtain, and release locks for use by
threads.
Line 156, length 185
freeing any resources associated with it. The default behavior is not to
perform any locking. Note that undefined behavior may result if threading is
used without appropriate locking.
Line 159, length 103
Linux kernel version 2.6.37 supports the SELinux kernel status page, enabling
userspace applications to
Line 161, length 92
SELinux status state in read-only mode to avoid system calls during the cache
hit code path.
Line 166, length 138
to initialize the selinux status state. If successfully initialized, the
userspace AVC will default to single-threaded mode and ignore the
Line 190, length 114
the AVC will default to the netlink fallback mechanism, which opens a netlink
socket for receiving status updates.
Line 194, length 133
events will have the same results as for the status page implementation, but
all status update checks will now require a system call.
Line 198, length 204
does not set threading or locking callbacks. In the fallback case, the
userspace AVC checks for new netlink messages at the start of each permission
query. If threading and locking callbacks are passed to
Line 200, length 246
a dedicated thread will be started to listen on the netlink socket. This may
increase performance in the absence of the status page and will ensure that log
messages are generated immediately rather than at the time of the next
permission query.
Line 203, length 84
Functions with a return value return zero on success. On error, \-1 is
returned and
Line 212, length 81
currently has a length limit of 15 characters and will be truncated if
necessary.
Line 221, length 160
If a netlink thread has been created and an error occurs on the socket (such as
an access error), the thread may terminate and cause the userspace AVC to return
Longest line is number 200 with 246 characters
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
avc_init.3:221:If a netlink thread has been created and an error occurs on the
socket (such as an access error), the thread may terminate and cause the
userspace AVC to return
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
avc_init.3:166:to initialize the selinux status state. If successfully
initialized, the userspace AVC will default to single-threaded mode and ignore
the
avc_init.3:170:callbacks. All callbacks set via
avc_init.3:198:does not set threading or locking callbacks. In the fallback
case, the userspace AVC checks for new netlink messages at the start of each
permission query. If threading and locking callbacks are passed to
-.-.
Put a subordinate sentence (after a comma) on a new line.
avc_init.3:34:will be prepended to all audit messages produced by the userspace
AVC. The default is `uavc'. The remaining arguments, if non-NULL, specify
callbacks to be used by the userspace AVC.
avc_init.3:37:The userspace AVC can be directed how to perform memory
allocation, logging, thread creation, and locking via callback functions passed
to
avc_init.3:115:argument, which does not return under normal conditions. The
avc_init.3:119:By default, threading is not used; see
avc_init.3:127:structure to specify functions to create, obtain, and release
locks for use by threads.
avc_init.3:144:callback should create a new lock, returning a pointer which
references it. The
avc_init.3:159:Linux kernel version 2.6.37 supports the SELinux kernel status
page, enabling userspace applications to
avc_init.3:166:to initialize the selinux status state. If successfully
initialized, the userspace AVC will default to single-threaded mode and ignore
the
avc_init.3:183:events will change the effective enforcing state used within the
AVC, and
avc_init.3:190:the AVC will default to the netlink fallback mechanism, which
opens a netlink socket for receiving status updates.
avc_init.3:194:events will have the same results as for the status page
implementation, but all status update checks will now require a system call.
avc_init.3:198:does not set threading or locking callbacks. In the fallback
case, the userspace AVC checks for new netlink messages at the start of each
permission query. If threading and locking callbacks are passed to
avc_init.3:203:Functions with a return value return zero on success. On error,
\-1 is returned and
avc_init.3:218:appropriately on error, userspace AVC calls may exhibit the
avc_init.3:221:If a netlink thread has been created and an error occurs on the
socket (such as an access error), the thread may terminate and cause the
userspace AVC to return
-.-.
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_init.3:4:.TH "avc_init" "3" "27 May 2004" "" "SELinux API documentation"
avc_init.3:5:.SH "NAME"
avc_init.3:8:.SH "SYNOPSIS"
avc_init.3:21:.BI "const struct avc_lock_callback *" lock_callbacks ");"
avc_init.3:23:.SH "DESCRIPTION"
avc_init.3:36:.SH "CALLBACKS"
avc_init.3:207:.SH "NOTES"
avc_init.3:227:.SH "AUTHOR"
-.-.
Space character after a macro call.
13:.BI "int avc_init(const char *" msgprefix ,
224:.B avc_destroy
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
5:.SH "NAME"
8:.SH "SYNOPSIS"
23:.SH "DESCRIPTION"
36:.SH "CALLBACKS"
158:.SH "KERNEL STATUS PAGE"
187:.SH "NETLINK NOTIFICATION"
202:.SH "RETURN VALUE"
207:.SH "NOTES"
227:.SH "AUTHOR"
230:.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>:56: warning: trailing space in the line
troff:<stdin>:60: warning: trailing space in the line
troff:<stdin>:81: warning: trailing space in the line
troff:<stdin>:85: warning: trailing space in the line
troff:<stdin>:89: warning: trailing space in the line
troff:<stdin>:117: warning: trailing space in the line
troff:<stdin>:119: warning: trailing space in the line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- avc_init.3 2025-04-02 19:24:28.440500420 +0000
+++ avc_init.3.new 2025-04-02 19:49:33.133594422 +0000
@@ -1,16 +1,16 @@
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Author: Eamon Walsh (ewa...@tycho.nsa.gov) 2004
-.TH "avc_init" "3" "27 May 2004" "" "SELinux API documentation"
-.SH "NAME"
+.TH avc_init 3 "27 May 2004" "" "SELinux API documentation"
+.SH NAME
avc_init \- legacy userspace SELinux AVC setup
.
-.SH "SYNOPSIS"
+.SH SYNOPSIS
.B #include <selinux/selinux.h>
.br
.B #include <selinux/avc.h>
.sp
-.BI "int avc_init(const char *" msgprefix ,
+.BI "int avc_init(const char *" msgprefix ,
.in +\w'int avc_init('u
.BI "const struct avc_memory_callback *" mem_callbacks ,
.br
@@ -20,7 +20,7 @@ avc_init \- legacy userspace SELinux AVC
.br
.BI "const struct avc_lock_callback *" lock_callbacks ");"
.
-.SH "DESCRIPTION"
+.SH DESCRIPTION
.BR avc_init ()
is deprecated; please use
.BR avc_open (3)
@@ -29,14 +29,25 @@ in conjunction with
in all new code.
.BR avc_init ()
-initializes the userspace AVC and must be called before any other AVC
operation can be performed. A non-NULL
+initializes the userspace AVC
+and must be called
+before any other AVC operation can be performed.
+A non-NULL
.I msgprefix
-will be prepended to all audit messages produced by the userspace AVC. The
default is `uavc'. The remaining arguments, if non-NULL, specify callbacks to
be used by the userspace AVC.
+will be prepended to all audit messages produced by the userspace AVC.
+The default is `uavc'.
+The remaining arguments,
+if non-NULL,
+specify callbacks to be used by the userspace AVC.
.
-.SH "CALLBACKS"
-The userspace AVC can be directed how to perform memory allocation, logging,
thread creation, and locking via callback functions passed to
+.SH CALLBACKS
+The userspace AVC can be directed how to perform memory allocation,
+logging,
+thread creation,
+and locking via callback functions passed to
.BR avc_init ().
-The purpose of this functionality is to allow the userspace AVC to be smoothly
integrated into existing userspace object managers.
+The purpose of this functionality is to allow the userspace AVC to be
+smoothly integrated into existing userspace object managers.
Use an
.B avc_memory_callback
@@ -53,11 +64,12 @@ struct avc_memory_callback {
.ta
.RE
-The two fields of the structure should be pointers to functions which behave
as
+The two fields of the structure should be pointers to functions
+which behave as
.BR malloc (3)
and
.BR free (3),
-which are used by default.
+which are used by default.
Use an
.B avc_log_callback
@@ -78,15 +90,19 @@ struct avc_log_callback {
The
.B func_log
-callback should accept a
+callback should accept a
.BR printf (3)
-style format and arguments and log them as desired. The default behavior
prints the message on the standard error. The
+style format
+and arguments
+and log them as desired.
+The default behavior prints the message on the standard error.
+The
.B func_audit
-callback should interpret the
+callback should interpret the
.I auditdata
parameter for the given
.IR class ,
-printing a human-readable interpretation to
+printing a human-readable interpretation to
.I msgbuf
using no more than
.I msgbufsize
@@ -110,13 +126,20 @@ struct avc_thread_callback {
The
.B func_create_thread
-callback should create a new thread and return a pointer which references it.
The thread should execute the
+callback should create a new thread
+and return a pointer
+which references it.
+The thread should execute the
.I run
-argument, which does not return under normal conditions. The
+argument,
+which does not return under normal conditions.
+The
.B func_stop_thread
-callback should cancel the running thread referenced by
+callback should cancel the running thread referenced by
.IR thread .
-By default, threading is not used; see
+By default,
+threading is not used;
+see
.B KERNEL STATUS PAGE
and
.B NETLINK NOTIFICATION
@@ -124,7 +147,9 @@ below.
Use an
.B avc_lock_callback
-structure to specify functions to create, obtain, and release locks for use by
threads.
+structure to specify functions to create,
+obtain,
+and release locks for use by threads.
.RS
.ta 4n 10n 24n
@@ -141,7 +166,10 @@ struct avc_lock_callback {
The
.B func_alloc_lock
-callback should create a new lock, returning a pointer which references it.
The
+callback should create a new lock,
+returning a pointer
+which references it.
+The
.B func_get_lock
callback should obtain
.IR lock ,
@@ -153,21 +181,30 @@ The
.B func_free_lock
callback should destroy
.IR lock ,
-freeing any resources associated with it. The default behavior is not to
perform any locking. Note that undefined behavior may result if threading is
used without appropriate locking.
+freeing any resources associated with it.
+The default behavior is not to perform any locking.
+Note that undefined behavior may result
+if threading is used without appropriate locking.
.
-.SH "KERNEL STATUS PAGE"
-Linux kernel version 2.6.37 supports the SELinux kernel status page, enabling
userspace applications to
+.SH KERNEL STATUS PAGE
+Linux kernel version 2.6.37 supports the SELinux kernel status page,
+enabling userspace applications to
.BR mmap (2)
-SELinux status state in read-only mode to avoid system calls during the cache
hit code path.
+SELinux status state in read-only mode
+to avoid system calls during the cache hit code path.
.BR avc_init ()
calls
.BR selinux_status_open (3)
-to initialize the selinux status state. If successfully initialized, the
userspace AVC will default to single-threaded mode and ignore the
+to initialize the selinux status state.
+If successfully initialized,
+the userspace AVC will default to single-threaded mode
+and ignore the
.B func_create_thread
and
.B func_stop_thread
-callbacks. All callbacks set via
+callbacks.
+All callbacks set via
.BR selinux_set_callback (3)
will still be honored.
@@ -180,54 +217,75 @@ at the start of each permission query an
Two status types are currently implemented.
.B setenforce
-events will change the effective enforcing state used within the AVC, and
+events will change the effective enforcing state
+used within the AVC,
+and
.B policyload
events will result in a cache flush.
.
-.SH "NETLINK NOTIFICATION"
+.SH NETLINK NOTIFICATION
In the event that the kernel status page is not successfully
.BR mmap (2)'ed
-the AVC will default to the netlink fallback mechanism, which opens a netlink
socket for receiving status updates.
+the AVC will default to the netlink fallback mechanism,
+which opens a netlink socket for receiving status updates.
.B setenforce
and
.B policyload
-events will have the same results as for the status page implementation, but
all status update checks will now require a system call.
+events will have the same results
+as for the status page implementation,
+but all status update checks will now require a system call.
By default,
.BR avc_open (3)
-does not set threading or locking callbacks. In the fallback case, the
userspace AVC checks for new netlink messages at the start of each permission
query. If threading and locking callbacks are passed to
+does not set threading
+or locking callbacks.
+In the fallback case,
+the userspace AVC checks for new netlink messages
+at the start of each permission query.
+If threading and locking callbacks are passed to
.BR avc_init (),
-a dedicated thread will be started to listen on the netlink socket. This may
increase performance in the absence of the status page and will ensure that log
messages are generated immediately rather than at the time of the next
permission query.
+a dedicated thread will be started to listen on the netlink socket.
+This may increase performance in the absence of the status page
+and will ensure
+that log messages are generated immediately
+rather than at the time of the next permission query.
.
-.SH "RETURN VALUE"
-Functions with a return value return zero on success. On error, \-1 is
returned and
+.SH RETURN VALUE
+Functions with a return value return zero on success.
+On error,
+\-1 is returned and
.I errno
is set appropriately.
.
-.SH "NOTES"
+.SH NOTES
The
.I msgprefix
argument to
.BR avc_init ()
-currently has a length limit of 15 characters and will be truncated if
necessary.
+currently has a length limit of 15 characters
+and will be truncated if necessary.
If a provided
.B func_malloc
callback does not set
.I errno
-appropriately on error, userspace AVC calls may exhibit the
-same behavior.
+appropriately on error,
+userspace AVC calls may exhibit the same behavior.
-If a netlink thread has been created and an error occurs on the socket (such
as an access error), the thread may terminate and cause the userspace AVC to
return
+If a netlink thread has been created
+and an error occurs on the socket
+(such as an access error),
+the thread may terminate
+and cause the userspace AVC to return
.B EINVAL
on all further permission checks until
-.B avc_destroy
+.B avc_destroy
is called.
.
-.SH "AUTHOR"
+.SH AUTHOR
Eamon Walsh <ewa...@tycho.nsa.gov>
.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR avc_open (3),
.BR selinux_status_open (3),
.BR selinux_status_updated (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)
-.-
