Package: libcap-dev
Version: 1:2.66-5+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>:1: 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.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 libcap-dev depends on:
ii libc6 2.40-6
ii libcap2 1:2.66-5+b1
libcap-dev recommends no packages.
Versions of packages libcap-dev suggests:
ii manpages-dev 6.9.1-1
-- no debconf information
Input file is cap_launch.3
Output from "mandoc -T lint cap_launch.3": (shortened list)
1 input text line longer than 80 bytes: a new context from t...
-.-.
Output from "test-groff -mandoc -t -ww -z cap_launch.3": (shortened list)
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
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
87: printf("launcher callback set detail to %d\\n", *detail);
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is a minus,
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
83: MAP_SHARED | MAP_ANONYMOUS, -1, 0);
149:privilege), the launch will fail and return -1.
157:returns -1 in the case of an error.
165:2.33. It primarily addresses a complexity with \fI-lpsx\fP linked
-.-.
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)
172 https://sites.google.com/site/fullycapable/who-ordered-libpsx for an
-.-.
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 "\&".
29:security context. Essentially it provides a mechanism for a program to
35:a new program. When the application links to \fI\-lpsx\fP this support
51:to execute that \fIlauncher\fP. In such cases, a non-negative return
65:value may be reused for multiple independent launches. The
70:customize the invocation of the launch. Care must be taken to leverage
76:outside the main process of the calling application. An example of
98:will be aborted. If detail of the failure is important to the caller,
105:of the calling program. Such modifications must be performed prior to
107:effect. Further, they are only invoked after any installed callback
108:has completed. For example, one can drop or modify capabilities,
124:the launcher. Calling this function with an IAB value of NULL will
126:\fBcap_iab\fP(3) for details on the IAB set. Note, the launcher is
128:make a copy of it. This iab value is locked to the laucher and cannot
129:be modified while associated with the launcher. Set with NULL to
159:In all such cases a return value of 0 implies success. In other cases,
165:2.33. It primarily addresses a complexity with \fI-lpsx\fP linked
171:exposure to privilege escalation. (See
-.-.
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 31, length 100
a new context from that of the main program manipulate capability and other
privileged state in that
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
166:pthreads(7) applications that use capabilities but also honor POSIX
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
cap_launch.3:112:of this sort (note some require permitted capability bits to
succeed):
cap_launch.3:125:configure the launcher to not set an IAB value (the default).
See
-.-.
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 CAP_LAUNCH 3 "2021-08-01" "" "Linux Programmer's Manual"
151:.SH "ERRORS"
163:.SH "HISTORY"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:82: warning: trailing space in the line
lexgrog: cap_launch.3: parse failed
-.-.
Additionally:
Spelling (codespell):
laucher ==> launcher
privilge ==> privilege
-.-
Added a missing line for the NAME section.
-.-
Added a missing ".SH SYNOPIS" line.
--- cap_launch.3 2025-01-30 19:19:40.208520354 +0000
+++ cap_launch.3.new 2025-01-30 20:34:01.164330301 +0000
@@ -1,5 +1,8 @@
-.TH CAP_LAUNCH 3 "2021-08-01" "" "Linux Programmer's Manual"
+.TH CAP_LAUNCH 3 2021-08-01 "" "Linux Programmer's Manual"
.SH NAME
+cap_launch... \- provide a mechanism for code to execute a callback function
+\&...
+.SH SYNOPSIS
.nf
#include <sys/capability.h>
@@ -26,15 +29,18 @@ Link with \fI\-lcap\fP.
.SH DESCRIPTION
A launcher provides a mechanism for code to execute a callback
function and/or a program executable in an environment with a modified
-security context. Essentially it provides a mechanism for a program to
+security context.
+Essentially it provides a mechanism for a program to
.BR fork (2)
-a new context from that of the main program manipulate capability and other
privileged state in that
+a new context from that of the main program manipulate capability
+and other privileged state in that
.BR fork (2)d
process before (optionally)
.BR execve (2)ing
-a new program. When the application links to \fI\-lpsx\fP this support
+a new program.
+When the application links to \fI\-lpsx\fP this support
is needed to robustly execute the launched code without modifying the
-privilge of the whole (POSIX semantics honoring) main application.
+privilege of the whole (POSIX semantics honoring) main application.
.PP
A launcher is defined by one of these two functions:
.BR cap_new_launcher ()
@@ -48,9 +54,11 @@ Once defined, a
.B cap_launch_t
value can be used with
.BR cap_launch ()
-to execute that \fIlauncher\fP. In such cases, a non-negative return
-value indicates success: zero meaning success without a program being
-invoked; non-zero being equal to the process ID
+to execute that \fIlauncher\fP.
+In such cases,
+a non-negative return value indicates success:
+zero meaning success without a program being invoked;
+non-zero being equal to the process ID
.RB ( pid_t )
of the newly launched program.
.PP
@@ -62,54 +70,64 @@ Before being
.BR cap_free (3)d
a
.B cap_value_t
-value may be reused for multiple independent launches. The
+value may be reused for multiple independent launches.
+The
.I detail
argument to
.BR cap_launch (),
-in conjunction with the launcher's callback function, can be used to
-customize the invocation of the launch. Care must be taken to leverage
+in conjunction with the launcher's callback function,
+can be used to customize the invocation of the launch.
+Care must be taken to leverage
custom shared memory (see
.BR mmap (2))
or some other IPC to return values to the main program via
.I detail
since the callback and any subsequent program execution will occur
-outside the main process of the calling application. An example of
+outside the main process of the calling application.
+An example of
this would be to allocate detail as follows:
.nf
const *char[] args = { "echo", "hello", NULL };
cap_launch_t cmd = cap_new_launcher("/usr/bin/echo", args, NULL);
- int *detail = mmap(NULL, sizeof(int), PROT_READ | PROT_WRITE,
- MAP_SHARED | MAP_ANONYMOUS, -1, 0);
+ int *detail = mmap(NULL, sizeof(int), PROT_READ | PROT_WRITE,
+ MAP_SHARED | MAP_ANONYMOUS, \-1, 0);
cap_launcher_callback(cmd, &answer_detail_fn);
*detail = 41;
pid_t pid = cap_launch(cmd, detail);
- printf("launcher callback set detail to %d\\n", *detail);
+ printf("launcher callback set detail to %d\en", *detail);
munmap(detail, sizeof(int));
.fi
.PP
-Unless modified by the callback function, the launched code will
-execute with the capability and other security context of the
-application.
+Unless modified by the callback function,
+the launched code will execute with the capability
+and other security context of the application.
-If the callback function returns anything other than zero, a
+If the callback function returns anything other than zero,
+a
.BR cap_launch ()
-will be aborted. If detail of the failure is important to the caller,
+will be aborted.
+If detail of the failure is important to the caller,
it should be communicated via the
.I detail
argument.
The following functions can be used to instruct the launcher to modify
the security state of the invoked program without altering the state
-of the calling program. Such modifications must be performed prior to
+of the calling program.
+Such modifications must be performed prior to
calling \fBcap_launch\fP() if they are to have the desired
-effect. Further, they are only invoked after any installed callback
-has completed. For example, one can drop or modify capabilities,
+effect.
+Further,
+they are only invoked after any installed callback has completed.
+For example,
+one can drop or modify capabilities,
\fIjust\fP for executing a file.
.PP
The following functions instruct the launcher to do some common tasks
-of this sort (note some require permitted capability bits to succeed):
+of this sort
+(note some require permitted capability bits to succeed):
.sp
.BR cap_launcher_callback ()
can be used to install or replace the currently installed callback
@@ -121,12 +139,17 @@ the desired one.
.sp
.BR cap_launcher_set_iab ()
This function returns the \fBcap_iab_t\fP previously associated with
-the launcher. Calling this function with an IAB value of NULL will
-configure the launcher to not set an IAB value (the default). See
-\fBcap_iab\fP(3) for details on the IAB set. Note, the launcher is
-associated directly with the supplied \fIiab\fP value, and does not
-make a copy of it. This iab value is locked to the laucher and cannot
-be modified while associated with the launcher. Set with NULL to
+the launcher.
+Calling this function with an IAB value of NULL will
+configure the launcher to not set an IAB value
+(the default).
+See \fBcap_iab\fP(3) for details on the IAB set.
+Note,
+the launcher is associated directly with the supplied \fIiab\fP value,
+and does not make a copy of it.
+This iab value is locked to the launcher and cannot
+be modified while associated with the launcher.
+Set with NULL to
regain control over the memory associated with that IAB value,
otherwise the IAB value will be \fBcap_free\fI()\fP'd when the
launcher is.
@@ -144,32 +167,38 @@ This function causes the launched progra
with the specified primary and supplementary group IDs.
.sp
.PP
-Note, if any of the launcher enhancements made by the above functions
-should fail to take effect (typically for a lack of sufficient
-privilege), the launch will fail and return -1.
+Note,
+if any of the launcher enhancements made by the above functions
+should fail to take effect
+(typically for a lack of sufficient privilege),
+the launch will fail and return \-1.
-.SH "ERRORS"
+.SH ERRORS
A return of NULL for a
.B cap_launch_t
should be considered an error.
.PP
.BR cap_launch ()
-returns -1 in the case of an error.
+returns \-1 in the case of an error.
.PP
-In all such cases a return value of 0 implies success. In other cases,
+In all such cases a return value of 0 implies success.
+In other cases,
consult
.BR errno (3)
for further details.
-.SH "HISTORY"
+.SH HISTORY
The \fBcap_launch\fP() family of functions were introduced in libcap
-2.33. It primarily addresses a complexity with \fI-lpsx\fP linked
-pthreads(7) applications that use capabilities but also honor POSIX
-semantics.
+2.33.
+It primarily addresses a complexity with \fI\-lpsx\fP linked
+.BR pthreads (7)
+applications
+that use capabilities but also honor POSIX semantics.
Using \fI\-lcap\fP and \fI\-lpthread\fP together without the POSIX
semantics support from \fI\-lpsx\fP introduces a subtle class of
-exposure to privilege escalation. (See
-https://sites.google.com/site/fullycapable/who-ordered-libpsx for an
+exposure to privilege escalation.
+(See
+https://sites.google.com/\:site/\:fullycapable/\:who-ordered-libpsx for an
explanation.)
.SH "SEE ALSO"
.BR libpsx (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.
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)
-.-
