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>:4: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:165: warning: trailing space in the line
troff:<stdin>:167: 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 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_from_text.3
Output from "mandoc -T lint cap_from_text.3": (shortened list)
2 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z cap_from_text.3": (shortened list)
2 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
2
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
199:#define handle_error(msg) \\
209: fprintf(stderr, "%s <textual\-cap\-set>\\n", argv[0]);
221: printf("caps_to_text() returned \\"%s\\"\\n", txt_caps);
-.-.
Use the word (in)valid instead of (il)legal,
if not related to legal matters.
See "www.gnu.org/prep/standards".
Think about translations into other languages!
cap_from_text.3:101:pairs. Legal operators are:
cap_from_text.3:103:Legal flags are:
-.-.
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 "\&".
23:functions in working storage. The textual representation is a structured,
27:allocates and initializes a capability state in working storage. It
82:to a libcap-allocated textual string. This string should be
114:Unnamed capabilities can also be specified by number. This feature
116:at the time libcap was compiled. However, generally upgrading libcap
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
cap_from_text.3:161:returns 0 for success, and \-1 on failure (unknown
capability).
-.-.
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>:165: warning: trailing space in the line
troff:<stdin>:167: warning: trailing space in the line
--- cap_from_text.3 2025-01-30 02:35:57.491755889 +0000
+++ cap_from_text.3.new 2025-01-30 02:48:59.104602022 +0000
@@ -1,7 +1,7 @@
.\"
.\" written by Andrew Main <zef...@dcs.warwick.ac.uk>
.\"
-.TH CAP_FROM_TEXT 3 "2022-09-22" "" "Linux Programmer's Manual"
+.TH CAP_FROM_TEXT 3 2022-09-22 "" "Linux Programmer's Manual"
.SH NAME
cap_from_text, cap_to_text, cap_to_name, cap_from_name \- capability
state textual representation translation
@@ -20,14 +20,16 @@ Link with \fI\-lcap\fP.
These functions translate a capability state between
an internal representation and a textual one.
The internal representation is managed by the capability
-functions in working storage. The textual representation is a structured,
+functions in working storage.
+The textual representation is a structured,
human-readable string suitable for display.
.PP
.BR cap_from_text ()
-allocates and initializes a capability state in working storage. It
+allocates and initializes a capability state in working storage.
+It
then sets the contents of this newly created capability state to the
-state represented by a human-readable, nul-terminated character
-string pointed to by
+state represented by a human-readable,
+nul-terminated character string pointed to by
.IR buf_p .
It returns a pointer to the newly created capability state.
When the capability state in working storage is no longer required,
@@ -36,26 +38,31 @@ by calling
.BR cap_free ()
with
.I cap_t
-as an argument. The function returns an error if it cannot parse the
+as an argument.
+The function returns an error if it cannot parse the
contents of the string pointed to by
.I buf_p
or does not recognize any
.I capability_name
-or flag character as valid. The function also returns an error if any flag
+or flag character as valid.
+The function also returns an error if any flag
is both set and cleared within a single clause.
.PP
.BR cap_to_text ()
converts the capability state in working storage identified by
.I caps
-into a nul-terminated human-readable string. This function allocates
-any memory necessary to contain the string, and returns a pointer to
-the string. If the pointer
+into a nul-terminated human-readable string.
+This function allocates
+any memory necessary to contain the string,
+and returns a pointer to the string.
+If the pointer
.I len_p
is not NULL,
the function shall also return the full length of the string (not including
the nul terminator) in the location pointed to by
.IR len_p .
-The capability state in working storage, identified by
+The capability state in working storage,
+identified by
.IR caps ,
is completely represented in the character string.
When the capability state in working storage is no longer required,
@@ -64,7 +71,8 @@ the caller should free any releasable me
with the returned string pointer as an argument.
.PP
.BR cap_from_name ()
-converts a text representation of a capability, such as "cap_chown",
+converts a text representation of a capability,
+such as "cap_chown",
to its numerical representation
.RB ( CAP_CHOWN=0 ),
writing the decoded value into
@@ -72,14 +80,16 @@ writing the decoded value into
If
.I cap_p
is NULL
-no result is written, but the return code of the function indicates
+no result is written,
+but the return code of the function indicates
whether or not the specified capability can be represented by the
library.
.PP
.BR cap_to_name ()
converts a capability index value,
.IR cap ,
-to a libcap-allocated textual string. This string should be
+to a libcap-allocated textual string.
+This string should be
deallocated with
.BR cap_free ().
.SH "TEXTUAL REPRESENTATION"
@@ -87,7 +97,8 @@ A textual representation of capability s
whitespace-separated
.IR clauses .
Each clause specifies some operations on a capability set; the set
-starts out with all capabilities lowered, and the meaning of the
+starts out with all capabilities lowered,
+and the meaning of the
string is the state of the capability set after all the clauses have
been applied in order.
.PP
@@ -98,55 +109,73 @@ followed by an
.IR action-list .
An action-list consists of a sequence of
.I operator flag
-pairs. Legal operators are:
+pairs.
+Valid operators are:
.RB ` = "', '" + "', and `" \- "'."
-Legal flags are:
+Valid flags are:
.RB ` e "', `" i "', and `" p "'."
-These flags are case-sensitive and specify the Effective, Inheritable
+These flags are case-sensitive and specify the Effective,
+Inheritable
and Permitted sets respectively.
.PP
-In the capability name lists, all names are case-insensitive. The
+In the capability name lists,
+all names are case-insensitive.
+The
special name
.RB ` all '
specifies all capabilities; it is equivalent to a list naming every
capability individually.
.PP
-Unnamed capabilities can also be specified by number. This feature
+Unnamed capabilities can also be specified by number.
+This feature
ensures that libcap can support capabilities that were not allocated
-at the time libcap was compiled. However, generally upgrading libcap
+at the time libcap was compiled.
+However,
+generally upgrading libcap
will add names for recently allocated capabilities.
.PP
The
.RB ` = '
operator indicates that the listed capabilities are first reset in
-all three capability sets. The subsequent flags (which are optional
+all three capability sets.
+The subsequent flags (which are optional
when associated with this operator) indicate that the listed
-capabilities for the corresponding set are to be raised. For example:
+capabilities for the corresponding set are to be raised.
+For example:
"all=p" means lower every capability in the Effective and Inheritable
sets but raise all of the Permitted capabilities;
-or, "cap_fowner=ep" means raise the Effective and Permitted
-override-file-ownership capability, while lowering this Inheritable
-capability.
+or,
+"cap_fowner=ep" means raise the Effective and Permitted
+override-file-ownership capability,
+while lowering this Inheritable capability.
.PP
In the case that the leading operator is
.RB ` = ',
-and no list of capabilities is provided, the action-list is assumed to
-refer to `all' capabilities. For example, the following three
+and no list of capabilities is provided,
+the action-list is assumed to
+refer to `all' capabilities.
+For example,
+the following three
clauses are equivalent to each other (and indicate a completely empty
capability set): "all="; "="; "cap_chown,<every-other-capability>=".
.PP
-The operators, `+' and `\-' both require an explicit preceding
-capability list and one or more explicit trailing flags. The `+'
+The operators,
+`+' and `\-' both require an explicit preceding
+capability list and one or more explicit trailing flags.
+The `+'
operator will raise all of the listed capabilities in the flagged
-capability sets. The `\-' operator will lower all of the listed
-capabilities in the flagged capability sets. For example:
+capability sets.
+The `\-' operator will lower all of the listed
+capabilities in the flagged capability sets.
+For example:
"all+p" will raise all of the Permitted capabilities and
"cap_fowner\-i" will lower the override-file-ownership in the Inheritable set.
.PP
The action list can consist of multiple
.I operator flag
pairs; the actions are performed in left-to-right order.
-Thus, for example,
+Thus,
+for example,
"cap_fowner+p\-i"
is equivalent to "cap_fowner+p cap_fowner\-i".
As another example,
@@ -156,15 +185,18 @@ As another example,
.BR cap_to_text ()
and
.BR cap_to_name ()
-return a non-NULL value on success, and NULL on failure.
+return a non-NULL value on success,
+and NULL on failure.
.BR cap_from_name ()
-returns 0 for success, and \-1 on failure (unknown capability).
+returns 0 for success,
+and \-1 on failure
+(unknown capability).
.PP
On failure,
.I errno
-is set to
+is set to
.BR EINVAL ,
-or
+or
.BR ENOMEM .
.SH "CONFORMING TO"
.BR cap_from_text ()
@@ -196,7 +228,7 @@ The source code of the program is as fol
#include <stdio.h>
#include <sys/capability.h>
-#define handle_error(msg) \\
+#define handle_error(msg) \e
do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
@@ -206,7 +238,7 @@ main(int argc, char *argv[])
char *txt_caps;
if (argc != 2) {
- fprintf(stderr, "%s <textual\-cap\-set>\\n", argv[0]);
+ fprintf(stderr, "%s <textual\-cap\-set>\en", argv[0]);
exit(EXIT_FAILURE);
}
@@ -218,7 +250,7 @@ main(int argc, char *argv[])
if (txt_caps == NULL)
handle_error("cap_to_text");
- printf("caps_to_text() returned \\"%s\\"\\n", txt_caps);
+ printf("caps_to_text() returned \e"%s\e"\en", txt_caps);
if (cap_free(txt_caps) != 0 || cap_free(caps) != 0)
handle_error("cap_free");
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)
-.-
