Break lines containing two man page references into a line for each.
This is not only more consistent with our guidelines (man-pages(7));
it also helps prepare for the future adoption of the MR man(7) macro.
INSTALL, RELEASE, cmd.mk, lint-man.mk: Use expr(1) instead of bc(1)
Both bc(1) and expr(1) are in POSIX. However, expr(1) is provided by
GNU coreutils, and seems simpler to use. This will simplify the
dependencies required to package the project.
This macro is an example of how C++-style casts can be implemented in C.
They are better than C's casts because they only allow certain
conversions, while disallowing most. This adds considerable type
safety. They also make code more greppable.
A macro similar to const_cast() can also be implemented in a similar
manner:
Various pages: SYNOPSIS: Use VLA syntax in function parameters
The WG14 charter for C23 added one principle to the ones in
previous standards:
[
15. Application Programming Interfaces (APIs) should be
self-documenting when possible. In particular, the order of
parameters in function declarations should be arranged such that
the size of an array appears before the array. The purpose is to
allow Variable-Length Array (VLA) notation to be used. This not
only makes the code's purpose clearer to human readers, but also
makes static analysis easier. Any new APIs added to the Standard
should take this into consideration.
]
ISO C doesn't allow using VLA syntax when the parameter used for
the size of the array is declared _after_ the parameter that is a
VLa. That's a minor issue that could be easily changed in the
language without backwards-compatibility issues, and in fact it
seems to have been proposed, and not yet discarded, even if it's
not going to change in C23.
Since the manual pages SYNOPSIS are not bounded by strict C legal
syntax, but we already use some "tricks" to try to convey the most
information to the reader even if it might not be the most legal
syntax, we can also make a small compromise in this case, using
illegal syntax (at least not yet legalized) to add important
information to the function prototypes.
If we're lucky, compiler authors, and maybe even WG14 members, may
be satisfied by the syntax used in these manual pages, and may
decide to implement this feature to the language.
It seems to me a sound syntax that isn't ambiguous, even if it
deviates from the common pattern in C that declarations _always_
come before use. But it's a reasonable tradeoff.
This change will make the contract between the programmer and the
implementation clearer just by reading a prototype. For example,
the second prototype above makes it clear that the 'dst' buffer
will be safe from overflow, but the 'src' one clearly needs to be
NUL-terminated, or it might cause UB, since nothing tells the
function how long it is.
lint-man.mk: lint-man-mandoc: Silence warnings about lowercase in TH
The warning will be removed soon, since Ingo, Branden, and I agreed to
move forward to a better letter case in the page title. Let's just
ignore it while it still exists.
ISO C23 will declare the noreturn macro and the _Noreturn function
specifier as obsolescent features. They are replaced by the
C++-compatible [[noreturn]] attribute.
Zach O'Keefe [Tue, 1 Nov 2022 15:03:23 +0000 (08:03 -0700)]
madvise.2: add documentation for MADV_COLLAPSE
Linux 6.1 introduced MADV_COLLAPSE in upstream commit 7d8faaf15545
("mm/madvise: introduce MADV_COLLAPSE sync hugepage collapse") and
upstream commit 34488399fa08 ("mm/madvise: add file and shmem support to
MADV_COLLAPSE"). Update the man-pages for madvise(2) and
process_madvise(2).
In the DESCRIPTION, where the Permissions column of /proc/keys is
explained, the 0x02 value was written as Ox02. In case one cannot spot
the difference: the first character was letter o (U+004F), while it
should be digit zero (U+0030).
It seems the source tree does not contain any other "Ox" instances
except at the beginning of "Oxford".
Signed-off-by: Grzegorz Szymaszek <gszymaszek@short.pl> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Zach O'Keefe [Fri, 21 Oct 2022 22:32:59 +0000 (15:32 -0700)]
process_madvise.2: fix capability and ptrace requirements
The initial commit of process_madvise(2) to Linux, commit ecb8ac8b1f14
("mm/madvise: introduce process_madvise() syscall: an external memory
hinting API"), relied on PTRACE_MODE_ATTACH_FSCREDS (see ptrace(2)),
but was amended by commit 96cfe2c0fd23 ("mm/madvise: replace ptrace
attach requirement for process_madvise") which replaced this with a
combination of PTRACE_MODE_READ and CAP_SYS_NICE (PTRACE_MODE_READ to
prevent leaking ASLR metadata and CAP_SYS_NICE for influencing process
performance).
The initial commit of process_madvise(2) to man-pages project, made
after the second patch, included two errors:
1) CAP_SYS_ADMIN instead of CAP_SYS_NICE
2) PTRACE_MODE_READ_REALCREDS instead of PTRACE_MODE_READ_FSCREDS
Correct this in the man-page for process_madvise(2).
get_nprocs.3, get_nprocs_conf.3, program_invocation_name.3, sysvipc.7: Match page title with file name and NAME section
Manually tweak a few pages that weren't covered by the scripts
used in the 2 previous commits.
On 10/30/22 23:00, G. Branden Robinson wrote:
> For those to whom this change is coming as an unpleasant surprise, the
> forthcoming groff 1.23.0 features an option that will reverse this
> change at rendering time.
>
> From groff_man(7):
>
> -rCT=1 Capitalize titles, setting the man page title (the first
> argument to .TH) in full capitals in headers and footers.
> This transformation is off by default because it discards
> case distinction information.
>
> This register can also be set in a site-local "man.local" file to force
> it on for all pages. On Debian-based systems, this file is in
> /etc/groff. The following line will do the trick.
>
> .nr CT 1
>
> The groff_man_style(7) man page offers further examples of such
> rendering customization.
>
> /usr/local/share/groff/site-tmac/man.local
> Put site‐local changes and customizations into this file.
>
> .\" Use narrower indentation on terminals and similar.
> .if n .nr IN 4n
> .\" Put only one space after the end of a sentence.
> .ss 12 0 \" See groff(7).
> .\" Keep pages narrow even on wide terminals.
> .if n .if \n[LL]>78n .nr LL 78n
> .\" Ensure hyperlinks are enabled for terminals.
> .nr U 1
>
> On multi‐user systems, it is more considerate to users whose
> preferences may differ from the administrator’s to be less
> aggressive with such settings, or to permit their override
> with a user‐specific man.local file. This can be achieved by
> placing one or both of following requests at the end of the
> site‐local file.
> .soquiet \V[XDG_CONFIG_HOME]/man.local
> .soquiet \V[HOME]/.man.local
> However, a security‐sandboxed man(1) program may lack
> permission to open such files.
Various pages: Use correct letter case in page titles (TH)
Semi-scripted change:
$ find man* -type f \
| xargs grep -L '\.so' \
| while read f; do
P=$(basename $f);
T=$(grep '\.TH ' $f | cut -f2,3 -d' ' | sed 's/ /./');
p=$(echo $P | tr '[:upper:]' '[:lower:]');
t=$(echo $T | tr '[:upper:]' '[:lower:]');
Tn=$(echo $T | sed 's/\.[^.]\+$//')
Pn=$(echo $P | sed 's/\.[^.]\+$//')
N=$(man_section $f NAME \
| sed -n '/NAME/,/ - /p' \
| sed 's/ - .*//' \
| grep -v '^NAME$' \
| tr ', ' '\n' \
| grep -i "^$Pn$" \
| head -n1)
test $P = $T \
&& test -n $N \
&& continue;
if test "x$p" != "x$t"; then
echo 1 $P $T $N;
elif test -z "$N"; then
sed -i "/\.TH /s/$Tn/$Pn/" $f;
fi;
done;
Most of the changes produced by this script needed to be reverted,
but the some of them were good.
On 10/30/22 23:00, G. Branden Robinson wrote:
> For those to whom this change is coming as an unpleasant surprise, the
> forthcoming groff 1.23.0 features an option that will reverse this
> change at rendering time.
>
> From groff_man(7):
>
> -rCT=1 Capitalize titles, setting the man page title (the first
> argument to .TH) in full capitals in headers and footers.
> This transformation is off by default because it discards
> case distinction information.
>
> This register can also be set in a site-local "man.local" file to force
> it on for all pages. On Debian-based systems, this file is in
> /etc/groff. The following line will do the trick.
>
> .nr CT 1
>
> The groff_man_style(7) man page offers further examples of such
> rendering customization.
>
> /usr/local/share/groff/site-tmac/man.local
> Put site‐local changes and customizations into this file.
>
> .\" Use narrower indentation on terminals and similar.
> .if n .nr IN 4n
> .\" Put only one space after the end of a sentence.
> .ss 12 0 \" See groff(7).
> .\" Keep pages narrow even on wide terminals.
> .if n .if \n[LL]>78n .nr LL 78n
> .\" Ensure hyperlinks are enabled for terminals.
> .nr U 1
>
> On multi‐user systems, it is more considerate to users whose
> preferences may differ from the administrator’s to be less
> aggressive with such settings, or to permit their override
> with a user‐specific man.local file. This can be achieved by
> placing one or both of following requests at the end of the
> site‐local file.
> .soquiet \V[XDG_CONFIG_HOME]/man.local
> .soquiet \V[HOME]/.man.local
> However, a security‐sandboxed man(1) program may lack
> permission to open such files.
Many pages: Use correct letter case in page titles (TH)
Scripted change:
$ find man* -type f \
| xargs grep -L '\.so' \
| while read f; do
P=$(basename $f);
T=$(grep '\.TH ' $f | cut -f2,3 -d' ' | sed 's/ /./');
p=$(echo $P | tr '[:upper:]' '[:lower:]');
t=$(echo $T | tr '[:upper:]' '[:lower:]');
Tn=$(echo $T | sed 's/\.[^.]\+$//')
Pn=$(echo $P | sed 's/\.[^.]\+$//')
N=$(man_section $f NAME \
| sed -n '/NAME/,/ - /p' \
| sed 's/ - .*//' \
| grep -v '^NAME$' \
| tr ', ' '\n' \
| grep -i "^$Pn$" \
| head -n1)
test $P = $T \
&& test -n $N \
&& continue;
if test "x$p" != "x$t"; then
echo 1 $P $T $N;
elif test -z "$N"; then
echo 2 $P $T $N;
else
sed -i "/\.TH /s/$Tn/$N/" $f;
fi;
done;
On 10/30/22 23:00, G. Branden Robinson wrote:
> For those to whom this change is coming as an unpleasant surprise, the
> forthcoming groff 1.23.0 features an option that will reverse this
> change at rendering time.
>
> From groff_man(7):
>
> -rCT=1 Capitalize titles, setting the man page title (the first
> argument to .TH) in full capitals in headers and footers.
> This transformation is off by default because it discards
> case distinction information.
>
> This register can also be set in a site-local "man.local" file to force
> it on for all pages. On Debian-based systems, this file is in
> /etc/groff. The following line will do the trick.
>
> .nr CT 1
>
> The groff_man_style(7) man page offers further examples of such
> rendering customization.
>
> /usr/local/share/groff/site-tmac/man.local
> Put site‐local changes and customizations into this file.
>
> .\" Use narrower indentation on terminals and similar.
> .if n .nr IN 4n
> .\" Put only one space after the end of a sentence.
> .ss 12 0 \" See groff(7).
> .\" Keep pages narrow even on wide terminals.
> .if n .if \n[LL]>78n .nr LL 78n
> .\" Ensure hyperlinks are enabled for terminals.
> .nr U 1
>
> On multi‐user systems, it is more considerate to users whose
> preferences may differ from the administrator’s to be less
> aggressive with such settings, or to permit their override
> with a user‐specific man.local file. This can be achieved by
> placing one or both of following requests at the end of the
> site‐local file.
> .soquiet \V[XDG_CONFIG_HOME]/man.local
> .soquiet \V[HOME]/.man.local
> However, a security‐sandboxed man(1) program may lack
> permission to open such files.
Zach O'Keefe [Fri, 21 Oct 2022 22:32:58 +0000 (15:32 -0700)]
madvise.2: document reliable probe for advice support
EINVAL is an overloaded error code for madvise(2) and it's not clear
under what context it means "advice is not valid" vs another error.
Explicitly document that madvise(0, 0, advice) can reliably be used to
probe for kernel support for "advice", returning zero iff "advice" is
supported by the kernel.
Zach O'Keefe [Fri, 21 Oct 2022 22:32:57 +0000 (15:32 -0700)]
madvise.2: update THP file/shmem documentation for +5.4
Since Linux 5.4, Transparent Huge Pages now support both file-backed
memory and shmem memory. Update MADV_HUGEPAGE advice description to
reflect this.
Additionally, expand the description of requirements for memory to be
considered eligible for THP: alignment / mapping requirements, VMA
flags, prctl(2) settings, inode status, etc.
Tagged paragraphs
These are fixed in a separate commit (the previous one).
They are used for a list of tags and their descriptions.
An example is this commit message itself.
Ordered lists
Elements are preceeded by a number in parentheses.
These represent a set of steps that have an order.
When there are substeps, they will be numbered like (4.2).
Positional lists
Elements are preceeded by a number in square brackets
(index). These represent fields in a set. The index will
start at:
0 fields of a C data structure, to be consistent
with arrays.
1 fields of a file, to be consistent with tools like
cut(1).
Alternatives list
Elements are preceeded by a letter in parentheses.
These represent a set of (normally) exclusive
alternatives.
Bullet lists
Elements are preceeded by bullet symbols. Anything that
doesn't fit elsewhere usually is covered by this type of
list.
Notes
Not really a list, but the syntax is identical to
"positional lists".
There should always be 2 spaces between the list symbol and the
elements. This doesn't apply to "tagged paragraphs", which use
the default indentation rules.
Reported-by: Mike Frysinger <vapier@gentoo.org> Cc: <groff@gnu.org> Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
наб [Mon, 17 Oct 2022 01:22:57 +0000 (03:22 +0200)]
ascii.7: Chase down History to earliest
Cf., well, the UNIX Programmer's Manual:
https://www.tuhs.org/Archive/Distributions/Research/Dennis_v1/UNIX_ProgrammersManual_Nov71.pdf
PDF page 191; yes, the typographical convention here is insane, and
the contemprary-correct way to refer to this page from within the manual
would be /just/ "/etc/ascii", but, given the context, "/etc/ascii (VII)"
makes the most sense to me
dist.mk: Force adding version to tarball man pagesat 'make dist'
When creating a tarball with 'make dist', force the addition of
the date and version to the pages. Otherwise, if a tarball had
already been created from a previous commit, and the page hasn't
been touched, make will consider the one in the tarball
up-to-date, and will keep the old version.
Makefile: Remove installdirs* and builddirs* targets
Since our makefiles correctly state the dependencies of all
targets, and allow fully-parallel builds and installs, there's no
reason at all to allow creating the directories separately. That
was an old recommendation for when makefiles were buggy, and you
couldn't fully trust in them not having races or incorrect
dependencies.
It's obvious that it belongs to man-pages, since it's inside the
repository tree. Also, since the file is emailed to the LSM
project, it doesn't matter what name we give to it. Let's
simplify the name.
Now only MANDIRS start with 'man*', which is a good thing.
Let's start making the repository self-contained. The README
should be enough to guide a user into everything that has to do
with the project. The website should be a secondary source, for
those who don't know about the repository yet.
I merged some of the information found in the .Announce file,
which I'll remove.
cmd.mk, install.mk: Avoid modifying existing directories at 'make install'
'install -d' has an issue compared to 'mkdir -p': it doesn't
respect existing directories. It will set the ownership, file
mode, and SELinux contexts (and any other property that would be
set by install(1) to a newly-created directory), overwriting any
existing properties of the existing directory.
'mkdir -p' doesn't have this issue: it is a no-op if the
directory exists. However, it's not an ideal solution either,
since it can't be used to set the properties (owner, mode, ...) of
a newly-created directory.
Therefore, the best solution is to use install(1), but only after
making sure that the directory doesn't exist with test(1).
Some notes:
* glibc is the only libc I'm aware of implementing _TIME_BITS for time64
compatibility. It was introduced in glibc-2.34;
* musl libc made a hard switch in 1.2.0, see https://musl.libc.org/time64.html;
* Using _TIME_BITS=64 with glibc requires _FILE_OFFSET_BITS=64 (which is used
for Large File Support)! Extraordinary claims require (some) evidence, so see
https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/features-time64.h;h=84d56ee3ff2ecfa0d2499385623f30606f84a1bf.
Reference: https://wiki.gentoo.org/wiki/Project:Toolchain/time64_migration
Reference: https://sourceware.org/pipermail/libc-alpha/2022-January/134985.html Signed-off-by: Sam James <sam@gentoo.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
