Package: libcap2-bin
Version: 1:2.66-5
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint capsh.1": (possibly shortened list)
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
-.-.
Use a macro to change to the italic font, instead of \fI, if
possible (see man-pages(7)).
The macros have the italic corrections, but "\c" removes the "\/" part,
which is in the macro.
So "\/" must be added between the italic argument and the "\c" string.
Or
add the italic corrections.
6:[\fIOPTION\fR]...
240:\fIcap_xxx\fP, one can provide a decimal number and \fBcapsh\fP will
257:\fBcapsh\fP, and display all descriptions that include \fIphrase\fP.
320:The text conventions used for \fIxxx\fP are those of
-.-.
Wrong distance between sentences.
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 is too large to be in the 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 <mor...@kernel.org>.
-.-.
"[" and "]", showing optional arguments to options, should be typeset in roman.
27:.BI \-\- " [args]"
34:.BI \-\+ " [args]"
39:.BI == " [args]"
54:.BI =\+ " [args]"
-.-.
SYNOPSIS: put a space on both sides of "[" and "]" to increase
readability (?)
capsh.1:[\fIOPTION\fR]...
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z
-rCHECKSTYLE=0":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':636: string
'an-result'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':642: macro 'BI'
troff: backtrace: file '<stdin>':34
troff:<stdin>:34: warning: ignoring escape character before '+'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':636: string
'an-result'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':642: macro 'BI'
troff: backtrace: file '<stdin>':54
troff:<stdin>:54: warning: ignoring escape character before '+'
-- System Information:
Debian Release: trixie/sid
APT prefers testing-proposed-updates
APT policy: (500, 'testing-proposed-updates'), (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-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.38-11
ii libcap2 1:2.66-5
Versions of packages libcap2-bin recommends:
pn libpam-cap <none>
libcap2-bin suggests no packages.
-- no debconf information
--- capsh.1 2024-05-19 12:40:13.238016918 +0000
+++ capsh.1.new 2024-05-19 14:04:02.034788280 +0000
@@ -3,7 +3,7 @@
capsh \- capability shell wrapper
.SH SYNOPSIS
.B capsh
-[\fIOPTION\fR]...
+.RI [ OPTION ]...
.SH DESCRIPTION
Linux capability support and use can be explored and constrained with
this tool. This tool provides a handy wrapper for certain types
@@ -22,21 +22,24 @@ Display the list of commands supported b
Display prevailing capability and related state.
.TP
.B \-\-current
-Display prevailing capability state, 1e capabilities and IAB vector.
+Display prevailing capability state, i.e.\& capabilities and IAB vector.
+.\".BI \-\- " [args]"
.TP
-.BI \-\- " [args]"
+.BI \-\- " \fR[\fPargs\fR]"
Execute
.B /bin/bash
with trailing arguments. Note, you can use
.B \-c 'command to execute'
for specific commands.
.TP
-.BI \-\+ " [args]"
-Uses \fBcap_launch\fP(3) to fork a child to execute the shell. When
+.BI \-+ " \fR[\fPargs\fR]"
+Uses
+.BR cap_launch (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]"
+.BI == " \fR[\fPargs\fR]"
Execute
.B capsh
again with the remaining arguments. Useful for testing
@@ -51,8 +54,10 @@ 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]"
-Uses \fBcap_launch\fP(3) to fork a child to re-execute
+.BI =+ " \fR[\fPargs\fR]"
+Uses
+.BR cap_launch (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
signal.
@@ -237,24 +242,29 @@ program exits with status 1.
.BI \-\-explain= cap_xxx
Give a brief textual description of what privileges the specified
capability makes available to a running program. Note, instead of
-\fIcap_xxx\fP, one can provide a decimal number and \fBcapsh\fP will
-look up the corresponding capability's description.
+.IR cap_xxx ,
+one can provide a decimal number and
+.B capsh
+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
+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
.BI \-\-suggest= phrase
-Scan each of the textual descriptions of capabilities, known to
-\fBcapsh\fP, and display all descriptions that include \fIphrase\fP.
+Scan each of the textual descriptions of capabilities,
+known to
+.BR capsh ,
+and display all descriptions that include
+.IR phrase .
.TP
.BI \-\-decode= N
This is a convenience feature. If you look at
@@ -317,7 +327,9 @@ in its (default) non-blocked state.
.TP
.BI \-\-iab= xxx
Attempts to set the IAB tuple of inheritable capability vectors.
-The text conventions used for \fIxxx\fP are those of
+The text conventions used for
+.I xxx
+are those of
.BR cap_iab_from_text (3).
.TP
.BI \-\-addamb= xxx
@@ -356,7 +368,7 @@ https://bugzilla.kernel.org/buglist.cgi?
.SH "SEE ALSO"
.BR libcap (3),
.BR cap_from_text (3),
-.BR cap_iab (3)
+.BR cap_iab (3),
.BR capabilities (7),
.BR captree (8),
.BR getcap (8),
