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")
an.tmac:<stdin>:54: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:57: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:122: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:124: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
* 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_get_file.3
Output from "mandoc -T lint cap_get_file.3": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z cap_get_file.3": (shortened list)
3 Use macro '.B' for one argument or split argument.
1 Use macro '.I' for one argument or split argument.
3 .BR is for at least 2 arguments, got 1
1 .IR is for at least 2 arguments, got 1
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
54:.IR cap_p
57:.BR CAP_SETFCAP
-.-.
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 "\&".
67:use in a specific user namespace. It is possible to get and set this value
72:respectively. The root user ID is ignored by the libcap library in all cases
73:other than when the capability is written to a file. Only if the value
-.-.
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")
an.tmac:<stdin>:54: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:57: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:122: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:124: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
--- cap_get_file.3 2025-01-30 15:15:09.644898561 +0000
+++ cap_get_file.3.new 2025-01-30 15:24:17.696311025 +0000
@@ -1,7 +1,7 @@
.\"
.\" written by Andrew Main <zef...@dcs.warwick.ac.uk>
.\"
-.TH CAP_GET_FILE 3 "2021-03-06" "" "Linux Programmer's Manual"
+.TH CAP_GET_FILE 3 2021-03-06 "" "Linux Programmer's Manual"
.SH NAME
cap_get_file, cap_set_file, cap_get_fd, cap_set_fd \- capability
manipulation on files
@@ -28,10 +28,12 @@ capability state of the pathname pointed
or the file open on descriptor
.IR fd .
These functions return a pointer to the newly created capability
-state. The effects of reading the capability state from any file
-other than a regular file is undefined. The caller should free any
-releasable memory, when the capability state in working storage is no
-longer required, by calling
+state.
+The effects of reading the capability state from any file
+other than a regular file is undefined.
+The caller should free any releasable memory,
+when the capability state in working storage is no longer required,
+by calling
.BR cap_free ()
with the used
.I cap_t
@@ -51,38 +53,46 @@ The new capability state of the file is
contents of
.IR cap_p .
A NULL value for
-.IR cap_p
+.I cap_p
is used to indicate that capabilities for the file should be deleted.
-For these functions to succeed, the calling process must have the
-.BR CAP_SETFCAP
+For these functions to succeed,
+the calling process must have the
+.B CAP_SETFCAP
capability in its effective set
and either the effective user ID of the process must match the
file owner or the calling process must have the
.B CAP_FOWNER
-capability in its effective capability set. The effects of writing the
+capability in its effective capability set.
+The effects of writing the
capability state to any file type other than a regular file are
undefined.
.PP
A capability set held in memory can be associated with the root user ID in
-use in a specific user namespace. It is possible to get and set this value
-(in the memory copy) with
+use in a specific user namespace.
+It is possible to get and set this value
+(in the memory copy)
+with
.BR cap_get_nsowner ()
and
.BR cap_set_nsowner ()
-respectively. The root user ID is ignored by the libcap library in all cases
-other than when the capability is written to a file. Only if the value
+respectively.
+The root user ID is ignored by the libcap library in all cases
+other than when the capability is written to a file.
+Only if the value
is non-zero will the library attempt to include it in the written file
capability set.
.SH "RETURN VALUE"
.BR cap_get_file ()
and
.BR cap_get_fd ()
-return a non-NULL value on success, and NULL on failure.
+return a non-NULL value on success,
+and NULL on failure.
.PP
.BR cap_set_file ()
and
.BR cap_set_fd ()
-return zero on success, and \-1 on failure.
+return zero on success,
+and \-1 on failure.
.PP
On failure,
.I errno
@@ -101,11 +111,14 @@ These functions are specified by withdra
.SH NOTES
Support for file capabilities is provided on Linux since version 2.6.24.
-On Linux, the file Effective set is a single bit.
-If it is enabled, then all Permitted capabilities are enabled
-in the Effective set of the calling process when the file is executed;
-otherwise, no capabilities are enabled in the process's Effective set
-following an
+On Linux,
+the file Effective set is a single bit.
+If it is enabled,
+then all Permitted capabilities are enabled
+in the Effective set of the calling process
+when the file is executed;
+otherwise,
+no capabilities are enabled in the process's Effective set following an
.BR execve (2).
Because the file Effective set is a single bit,
if any capability is enabled in the Effective set of the
@@ -116,12 +129,14 @@ or
.BR cap_set_fd (),
then all capabilities whose Permitted or Inheritable flag
is enabled must also have the Effective flag enabled.
-Conversely, if the Effective bit is enabled on a file, then the
+Conversely,
+if the Effective bit is enabled on a file,
+then the
.I cap_t
returned by
-.BR cap_get_file()
+.BR cap_get_file ()
and
-.BR cap_get_fd()
+.BR cap_get_fd ()
will have the Effective flag enabled for each capability that has the
Permitted or Inheritable flag enabled.
.SH "SEE ALSO"
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)
-.-
