Package: libcap2-bin
Version: 1:2.66-5+b1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find 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?
<stdin>:31: macro B: has more than one argument
troff:<stdin>:34: warning: ignoring escape character before '+'
troff:<stdin>:54: warning: ignoring escape character before '+'
an.tmac:<stdin>:247: style: .BI expects at least 2 arguments, got 1
* 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.11.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 libcap2-bin depends on:
ii libc6 2.40-3
ii libcap2 1:2.66-5+b1
Versions of packages libcap2-bin recommends:
pn libpam-cap <none>
libcap2-bin suggests no packages.
-- no debconf information
Input file is capsh.1
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
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.
Lines should thus be shorter.
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 of '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)
-.-.
Output from "mandoc -T lint capsh.1 ": (shortened list)
2 undefined escape, printing literally
-.-.
Output from "test-groff -mandoc -t -ww -b -z capsh.1 ": (shortened list)
1 .BI expects at least 2 arguments, got 1
1 has more than one argument
2 ignoring escape character before '+'
-.-.
Output from "mandoc -T lint capsh.1 ":
mandoc: capsh.1:34:7: WARNING: undefined escape, printing literally: \+
mandoc: capsh.1:54:6: WARNING: undefined escape, printing literally: \+
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
247:.BI \-\-strict
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
355 https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757
-.-.
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.
N.B.
The number of lines affected can be too large to be in a patch.
9:this tool. This tool provides a handy wrapper for certain types
10:of capability testing and environment creation. It also provides some
15:order they are provided. They are as follows:
30:with trailing arguments. Note, you can use
35:Uses \fBcap_launch\fP(3) to fork a child to execute the shell. When
42:again with the remaining arguments. Useful for testing
44:behavior. Note, PATH is searched when the running
46:was found via the shell's PATH searching. If the
51:as that running initially. This behavior is an intended feature as it
56:\fBcapsh\fP. When this child exits, \fBcapsh\fP exits with the status
69:Remove the listed capabilities from the prevailing bounding set. The
73:function. Use of this feature requires that
81:equal those provided in the comma separated list. For this action to
91:Assume the identity of the named user. That is, look up the user's
113:security mode. This is a set of securebits and prevailing capability
132:system call. This argument may require explicit preparation of the
138:function to set the UID of the current process. This performs all
140:process. Following this command the prevailing effective capabilities
163:Set the supplementary groups to the numerical list provided. The
166:system call. See
172:to the super-user. However, it is normally the case that when the
175:to some lesser user, then capabilities are dropped. For these
179:system call. This feature is known as
181:support. The way to activate it using this program is with this
182:argument. Setting the value to 1 will cause
184:to be active. Setting it to 0 will cause keep-caps to deactivate for
185:the current process. In all cases,
189:is performed. See
201:header file. The program will list these bits via the
221:seconds. The child will sleep that long and then exit with status
222:0. The purpose of this command is to support exploring the way
223:processes are killable in the face of capability changes. See the
225:command. Only one fork can be active at a time.
232:with the specified signal. The command then waits for the child to exit.
239:capability makes available to a running program. Note, instead of
249:\fB\-\-caps=\fP and \fB\-\-inh=\fP arguments. That is, when the
252:in the Permitted set. The strict mode defaults to off. Supplying this
260:This is a convenience feature. If you look at
282:As the kernel evolves, more capabilities are added. This option can be used
283:to verify the existence of a capability on the system. For example,
300:capabilities. If not,
339:This argument is ignored unless it is the first one. If present, it
346:exits with status 0. Following
351:Written by Andrew G. Morgan <[email protected]>.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
capsh.1:251:raised Inheritable Flag values (in strict mode) are limited to those
-.-.
"[" and "]", showing optional arguments to options, should be typeset in roman.
27:.BI \-\- " [args]"
34:.BI \-\+ " [args]"
39:.BI == " [args]"
54:.BI =\+ " [args]"
-.-.
Two or more space charaters between printable characters.
When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline", see man-pages(7)).
198:operation. The list of supported bits and their meaning can be found
203:command. The argument is expressed as a numeric bitmask, in any of
288:kernel 2.6.27. However, when run on kernel 2.6.38 it will silently
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
<stdin>:31: macro B: has more than one argument
troff: backtrace: file '<stdin>':34
troff:<stdin>:34: warning: ignoring escape character before '+'
troff: backtrace: file '<stdin>':54
troff:<stdin>:54: warning: ignoring escape character before '+'
an.tmac:<stdin>:247: style: .BI expects at least 2 arguments, got 1
-.-
Additional:
Change '\fB' to '\fP' at the end of a string.
--- capsh.1 2024-12-05 03:12:56.399899943 +0000
+++ capsh.1.new 2024-12-05 03:45:06.015383231 +0000
@@ -24,19 +24,19 @@ Display prevailing capability and relate
.B \-\-current
Display prevailing capability state, 1e capabilities and IAB vector.
.TP
-.BI \-\- " [args]"
+.BR \-\- " [" \fIargs\fP ]
Execute
.B /bin/bash
with trailing arguments. Note, you can use
-.B \-c 'command to execute'
+.BI "\-c '" "command to execute" '
for specific commands.
.TP
-.BI \-\+ " [args]"
+.BR \-+ " [" \fIargs\fP ]
Uses \fBcap_launch\fP(3) to fork a child to execute the shell. When
the child exits, \fBcapsh\fP exits with the status of the child or 1
in the case that the child was terminated by a signal.
.TP
-.BI == " [args]"
+.BR == " [" \fIargs\fP ]
Execute
.B capsh
again with the remaining arguments. Useful for testing
@@ -51,7 +51,7 @@ argument the PATH located binary may not
as that running initially. This behavior is an intended feature as it
can complete the chroot transition.
.TP
-.BI =\+ " [args]"
+.BR =+ " [" \fIargs\fP ]
Uses \fBcap_launch\fP(3) to fork a child to re-execute
\fBcapsh\fP. When this child exits, \fBcapsh\fP exits with the status
of the child or 1 in the case that the child was terminated by a
@@ -200,8 +200,9 @@ in the
.B <sys/secbits.h>
header file. The program will list these bits via the
.B \-\-print
-command. The argument is expressed as a numeric bitmask, in any of
-the formats permitted by
+command.
+The argument is expressed as a numeric bitmask,
+in any of the formats permitted by
.BR strtoul (3).
An alternative to this bit-twiddling is embedded in the
.B \-\-mode*
@@ -240,15 +241,17 @@ capability makes available to a running
\fIcap_xxx\fP, one can provide a decimal number and \fBcapsh\fP will
look up the corresponding capability's description.
.TP
-.BI \-\-shell =/full/path
+.BI \-\-shell= /full/path
This option changes the shell that is invoked when the argument
\fB==\fP is encountered.
.TP
-.BI \-\-strict
+.B \-\-strict
This option toggles the suppression of subsequent attempts to fixup
\fB\-\-caps=\fP and \fB\-\-inh=\fP arguments. That is, when the
-prevailing Effective flag does not contain \fBCAP_SETPCAP\fB the to be
-raised Inheritable Flag values (in strict mode) are limited to those
+prevailing Effective flag does not contain \fBCAP_SETPCAP\fP the to be
+raised Inheritable Flag values
+(in strict mode)
+are limited to those
in the Permitted set. The strict mode defaults to off. Supplying this
argument an even number of times restores this default behavior.
.TP
@@ -285,8 +288,8 @@ to verify the existence of a capability
will cause
.B capsh
to promptly exit with a status of 1 when run on
-kernel 2.6.27. However, when run on kernel 2.6.38 it will silently
-succeed.
+kernel 2.6.27.
+However, when run on kernel 2.6.38 it will silently succeed.
.TP
.BI \-\-has\-p= xxx
Exit with status 1 unless the
@@ -352,7 +355,7 @@ Written by Andrew G. Morgan <morgan@kern
.SH "REPORTING BUGS"
Please report bugs via:
.TP
-https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757
+https://bugzilla.kernel.org/\:buglist.cgi?component=\:libcap&list_id=1090757
.SH "SEE ALSO"
.BR libcap (3),
.BR cap_from_text (3),
