[DSE-Dev] Bug#1094861: get_ordered_context_list.3: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Fri Jan 31 20:10:39 GMT 2025
Package: libselinux1-dev
Version: 3.7-3+b1
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 "groff -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>:36: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:54: 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.10-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.44-5
ii libselinux1 3.7-3+b1
ii libsepol-dev 3.7-1
libselinux1-dev recommends no packages.
libselinux1-dev suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is get_ordered_context_list.3
Output from "mandoc -T lint get_ordered_context_list.3": (shortened list)
1 input text line longer than 80 bytes: get_ordered_context_...
2 unterminated quoted argument
1 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z get_ordered_context_list.3": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
1 trailing space in the line
-.-.
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
-.-.
Wrong distance 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 "\&".
98:authorized contexts could not be obtained. Caller must free via
-.-.
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.
Line 1, length 84
.TH "get_ordered_context_list" "3" "1 January 2004" "russell at coker.com.au" "SELinux"
Line 3, length 296
get_ordered_context_list, get_ordered_context_list_with_level, get_default_context, get_default_context_with_level, get_default_context_with_role, get_default_context_with_rolelevel, query_user_context, manual_user_enter_context, get_default_role \- determine SELinux context(s) for user sessions
Line 10, length 98
.BI "int get_ordered_context_list(const char *" user ", const char *" fromcon ", char ***" list );
Line 12, length 132
.BI "int get_ordered_context_list_with_level(const char *" user ", const char *" level ", const char *" fromcon ", char ***" list );
Line 14, length 94
.BI "int get_default_context(const char *" user ", const char *" fromcon ", char **" newcon );
Line 16, length 128
.BI "int get_default_context_with_level(const char *" user ", const char *" level ", const char *" fromcon ", char **" newcon );
Line 18, length 127
.BI "int get_default_context_with_role(const char *" user ", const char *" role ", const char *" fromcon ", char **" newcon ");
Line 20, length 155
.BI "int get_default_context_with_rolelevel(const char *" user ", const char *" role ", const char *" level ", const char *" fromcon ", char **" newcon ");
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
36:.BR getseuserbyname(3)
-.-.
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.
1:.TH "get_ordered_context_list" "3" "1 January 2004" "russell at coker.com.au" "SELinux"
2:.SH "NAME"
5:.SH "SYNOPSIS"
28:.SH "DESCRIPTION"
-.-.
Use ".na" (no adjustment) instead of ".ad l" and then ".ad" to begin the
same adjustment again as before
116:.ad l
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
an.tmac:<stdin>:36: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:<stdin>:54: warning: trailing space in the line
-------------- next part --------------
--- get_ordered_context_list.3 2025-01-31 19:46:45.441603601 +0000
+++ get_ordered_context_list.3.new 2025-01-31 20:04:01.481292997 +0000
@@ -1,23 +1,34 @@
-.TH "get_ordered_context_list" "3" "1 January 2004" "russell at coker.com.au" "SELinux"
-.SH "NAME"
-get_ordered_context_list, get_ordered_context_list_with_level, get_default_context, get_default_context_with_level, get_default_context_with_role, get_default_context_with_rolelevel, query_user_context, manual_user_enter_context, get_default_role \- determine SELinux context(s) for user sessions
+.TH get_ordered_context_list 3 "1 January 2004" russell at coker.com.au SELinux
+.SH NAME
+get_ordered_context_list, get_ordered_context_list_with_level,
+get_default_context, get_default_context_with_level,
+get_default_context_with_role, get_default_context_with_rolelevel,
+query_user_context, manual_user_enter_context, get_default_role \- determine
+SELinux context(s) for user sessions
.
-.SH "SYNOPSIS"
+.SH SYNOPSIS
.B #include <selinux/selinux.h>
.br
.B #include <selinux/get_context_list.h>
.sp
-.BI "int get_ordered_context_list(const char *" user ", const char *" fromcon ", char ***" list );
+.BI "int get_ordered_context_list(const char *" user ", const char *" \
+fromcon ", char ***" list );
.sp
-.BI "int get_ordered_context_list_with_level(const char *" user ", const char *" level ", const char *" fromcon ", char ***" list );
+.BI "int get_ordered_context_list_with_level(const char *" user \
+", const char *" level ", const char *" fromcon ", char ***" list );
.sp
-.BI "int get_default_context(const char *" user ", const char *" fromcon ", char **" newcon );
+.BI "int get_default_context(const char *" user ", const char *" fromcon \
+", char **" newcon );
.sp
-.BI "int get_default_context_with_level(const char *" user ", const char *" level ", const char *" fromcon ", char **" newcon );
+.BI "int get_default_context_with_level(const char *" user ", const char *" \
+level ", const char *" fromcon ", char **" newcon );
.sp
-.BI "int get_default_context_with_role(const char *" user ", const char *" role ", const char *" fromcon ", char **" newcon ");
+.BI "int get_default_context_with_role(const char *" user ", const char *" \
+role ", const char *" fromcon ", char **" newcon );
.sp
-.BI "int get_default_context_with_rolelevel(const char *" user ", const char *" role ", const char *" level ", const char *" fromcon ", char **" newcon ");
+.BI "int get_default_context_with_rolelevel(const char *" user \
+", const char *" role ", const char *" level ", const char *" fromcon \
+", char **" newcon );
.sp
.BI "int query_user_context(char **" list ", char **" newcon );
.sp
@@ -25,15 +36,17 @@ get_ordered_context_list, get_ordered_co
.sp
.BI "int get_default_type(const char *" role ", char **" type );
.
-.SH "DESCRIPTION"
+.SH DESCRIPTION
This family of functions can be used to obtain either a prioritized list of
all reachable security contexts for a given SELinux user or a single default
(highest priority) context for a given SELinux user for use by login-like
-programs. These functions takes a SELinux user identity that must
-be defined in the SELinux policy as their input, not a Linux username.
+programs.
+These functions takes a SELinux user identity that must
+be defined in the SELinux policy as their input,
+not a Linux username.
Most callers should typically first call
-.BR getseuserbyname(3)
+.BR getseuserbyname (3)
to look up the SELinux user identity and level for a given
Linux username and then invoke one of
.BR get_ordered_context_list_with_level ()
@@ -51,11 +64,14 @@ context based on the global
.I \%/etc/selinux/{SELINUXTYPE}/contexts/default_contexts
file and the per-user
.I \%/etc/selinux/{SELINUXTYPE}/contexts/users/<username>
-file if it exists. The
+file if it exists.
+The
.I fromcon
parameter may be NULL to indicate that the current context should
-be used. The function returns the number of contexts in the
-list, or \-1 upon errors. The list must be freed using the
+be used.
+The function returns the number of contexts in the list,
+or \-1 upon errors.
+The list must be freed using the
.BR freeconary (3)
function.
@@ -79,8 +95,9 @@ function and applies the specified level
.BR get_default_context_with_role ()
is the same as
.BR get_default_context ()
-but only returns a context with the specified role, returning \-1 if no
-such context is reachable for the user.
+but only returns a context with the specified role,
+returning \-1
+if no such context is reachable for the user.
.BR get_default_context_with_rolelevel ()
invokes the
@@ -88,14 +105,16 @@ invokes the
function and applies the specified level.
.BR query_user_context ()
-takes a list of contexts, queries the user via stdin/stdout as to which context
-they want, and returns a new context as selected by the user (which has to be
-freed with
+takes a list of contexts,
+queries the user via stdin/stdout as to which context they want,
+and returns a new context as selected by the user
+(which has to be freed with
.BR freecon (3)).
.BR manual_user_enter_context ()
allows the user to manually enter a context as a fallback if a list of
-authorized contexts could not be obtained. Caller must free via
+authorized contexts could not be obtained.
+Caller must free via
.BR freecon (3).
.BR get_default_type ()
@@ -103,7 +122,8 @@ Get the default type (domain) for
.I role
and set
.I type
-to refer to it, which has to be freed with free.
+to refer to it,
+which has to be freed with free.
.
.SH "RETURN VALUE"
.BR get_ordered_context_list ()
@@ -113,7 +133,7 @@ return the number of contexts in the lis
The other functions return 0 for success or \-1 for errors.
.
.SH "SEE ALSO"
-.ad l
+.na
.nh
.BR selinux (8),
.BR freeconary (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.
Not beginning each input sentence on a new line.
Line length 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 -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 -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