strerror.3: Change strerror() reference from MT-Unsafe to MT-Safe
The information in this patch was obtained from a glibc upstream patch,
commit 28aff047818eb1726394296d27b9c7885340bead ("string: Implement
strerror in terms of strerror_l").
According to the patch above, for glibc versions >=2.32, strerror() is
MT-Safe.
Signed-off-by: Shani Leviim <sleviim@redhat.com> Cc: Florian Weimer <fweimer@redhat.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Sergei Gromeniuk <sgromeni@redhat.com> Cc: Gobinda Das <godas@redhat.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Also ignore case, since otherwise a version sort would collate 'Z'
before 'a'. We don't need LC_COLLATE anymore.
Version sort has some issues for our purpose: underscores and dashes
have special (and different) meaning. We want to ignore underscores or
dashes that aren't next to digits, so that _exit(2) remains next to
exit(2). However, we want to keep them next to digits, such as in
iso-8859-1(7), to keep the right order for pages with numbers. For
that, we need some extra sed(1) magic.
Reported-by: Brian Inglis <Brian.Inglis@Shaw.ca> Cc: Deri James <deri@chuzzlewit.myzen.co.uk> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Sargun Dhillon [Thu, 10 Aug 2023 02:26:03 +0000 (19:26 -0700)]
clone.2: Fix erroneous statement about CLONE_NEWPID|CLONE_PARENT
CLONE_NEWPID|CLONE_PARENT was only prohibited during a short period.
That prohibition was introduced in Linux 3.12, in commit 40a0d32d1eaf
("fork: unify and tighten up CLONE_NEWUSER/CLONE_NEWPID checks"), but
was a regression, and was fixed in Linux 3.13, in commit 1f7f4dde5c94
("fork: Allow CLONE_PARENT after setns(CLONE_NEWPID)").
*.mk: [un]install-manintro: Add target to [un]install intro(*) pages separately
Debian installs intro(*) pages --including intro(3)-- in the manpages
package, not in manpages-dev, even if they would otherwise belong to the
-dev one due to their section. This is because even if someone may not
be interested in installing development manual pages, an introduction to
the section, explaining what one could find there when installed, is
useful.
Let's make it easy to do that with a specialized target that installs
all intro(*) pages.
This is a breaking change, since from now on, the only way to install
intro(*) pages is through this new target, and the old install-man*
targets won't install their own intro(*) pages. However, of course, the
wrapper targets `install` and `install-man` still install the intro(*)
pages.
scripts/sortman: Support pages with suffixes (not subsections)
Some projects have pages with suffixes like '.man' or '.in'. Don't
misinterpret those as subsections. Pages with subsections should match
the following regex: '\.[[:digit:]][[:alnum:]]\>'.
scripts/sortman: Add script to sort manual pages in book order
`LC_COLLATE=en_US.UTF-8` is needed to collate pages like _exit(3) next
to exit(3), instead of having all pages with a leading underscore
grouped at the beginning of a section.
intro(*), of course, is the fist page of each section, and subsections
go after the last page in the main corresponding section.
наб [Sat, 12 Aug 2023 20:03:30 +0000 (22:03 +0200)]
tmpfs.5: Document that size/blocks=0 and nr_inodes=0 remove the limits
Bitten by this again. Behaviour blames back to at least 2005
(probably original to shmem.c), documented upstream in
Documentation/filesystems/tmpfs.rst (formerly .txt).
For example:
# mount -t tmpfs -o size=0 tmpfs /etc/
# df /etc/
Filesystem 1k-blocks Used Avail Use% Mounted on
tmpfs 0 0 0 - /etc
# head -c100M < /dev/urandom > /etc/passwd
# df /etc/
Filesystem 1k-blocks Used Avail Use% Mounted on
tmpfs 0 0 0 - /etc
# ls -l /etc/passwd
-rw-r--r-- 1 0 0 104857600 08-12 19:55 /etc/passwd
# du /etc/passwd
204800 /etc/passwd
whereas the current manual insinuates head should ENOSPC instantly.
наб [Fri, 4 Aug 2023 15:03:28 +0000 (17:03 +0200)]
fsync.2: There are no writability requirements
Since Issue 3 (original release), fsync() was required to operate on
all valid fds. Since Issue 7 2018, fdatasync() is as well (and required
writability only by editorial mistake):
https://www.austingroupbugs.net/view.php?id=501
"Some UNIXes require the fd to be writable" is a
needlessly-adversarial-to-the-user ‒
https://101010.pl/@eater@cijber.social/110824211348995583
‒ way of saying "HP-UX and AIX have always been broken": just say that.
Originally appeared in 4.2BSD (4.1c.2BSD) so touch that as well since
we're mentioning the original interface.
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Guillem Jover <guillem@hadrons.org> Cc: Sam James <sam@gentoo.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
After this patch, you can do 2>/dev/null to only see one line per
Makefile recipe being run, which is nice and useful (for example, to
have an overview of which pages are failing, without having to care
about the specific errors). I used this for example, to know which
files need to be touched to silence the known positives in `make lint`
in the Debian packaging is override_dh_test_auto.
In checkpatch(1), it's the program that writes to stdout. Redirect it.
In clang-tidy(1) and cppcheck(1), it was a mistake of mine, since I
redirected to stdout to filter the output, and then forgot to redirect
back to stderr.
Fixes: acaa21bc4a6f ("Makefile, etc/clang-tidy/config.yaml: lint-clang-tidy: Add target to run clang-tidy(1) to lint example programs") Fixes: eb1bdc8c117a ("Makefile: lint-iwyu: Be silent if there are no problems") Signed-off-by: Alejandro Colomar <alx@kernel.org>
Debian packaging (gbp-buildpackage(1)) produces a .pc/ dir in the root
of the repo, which then produces a build failure in dh_auto_test
(`make check -j4`). Let's ignore dot-dirs, since they won't likely
contain anything useful for our build system.
Changes.old: 6.04: Document the addition of `make check`
This caused trouble to the Debian packaging, since it runs `make check`
if the package supports it, and since we have a few pages that trigger
errors there, the packaging failed to work for 6.04.
Protect literals in a (very long) paragraph tag from hyphenation by
using hypenation control escape sequences, instead of `nh` and `hy`
requests. The latter approach is incorrect for use with groff(1) since
'.hy' does not restore the previous hyphenation mode but sets it to 1,
which is not appropriate for the English-language hyphenation patterns
groff uses. (Also, AT&T man(7) used a hyphenation mode of 14.)
Also wrap long input line with \newline escape sequence.
Protect (non-cross-referenced) man page names from hyphenation. Use the
hyphenation control escape sequence `\%` to do this rather than
bracketing a region of the page with `na` and `hy` requests, which
enables automatic hyphenation even when it is not desired and uses the
wrong hyphenation mode for English to boot.
4 pages issued requests to manipulate adjustment and automatic
hyphenation around tbl(1) tables in a different order from the other 525
documents in the tree that performed this trick.
I produced this change with the following GNU sed script.
Use font style alternation macros instead of font selection escape
sequences to mark up man page cross references in table entry text
blocks. Also protect them from hyphenation. (`MR` will take care of
that for us.)
* Refer to the info sec property of confidentiality[1] instead of saying,
vaguely, "security-critical".
* Try not to confuse anyone who's studied the analysis of algorithms:
don't say "constant time" when "deterministic time" is meant. The
time to perform the memory comparison remains linear (O(n)), not
constant (O(1)).
* Tighten wording.
Mark up ellipses properly. They should be in roman. The item preceding
an ellipsis should be in the singular. Use unbreakable space between
metasyntactic variable and subsequent ellipsis. (Whitespace-separated
arguments should be separated from a subsequent ellipsis. "[-v...]"
suggests that both "-vv" and "-v -v" are permitted; "[-v ...]" suggests
only the latter.)
Quoting groff_man_style(7):
• Symbols that are neither to be typed literally nor replaced at the
user’s discretion appear in the roman style; brackets surround
optional arguments, and an ellipsis indicates that the previous
syntactical element may be repeated arbitrarily.
[...]
• The dummy character escape sequence \& follows the ellipsis when
further text will follow after space on the output line, keeping
its last period from being interpreted as the end of a sentence
and causing additional inter‐sentence space to be placed after it.
[...]
\| Thin space (one‐sixth em on typesetters, zero‐width on
terminals); a non‐breaking space. Used primarily in ellipses
(“.\|.\|.”) to space the dots more pleasantly on typesetting
devices like dvi, pdf, and ps.
[...]
Several features of the above example are of note. [...]
• The non‐breaking adjustable space escape sequence \~ is used to
prevent the output line from being broken within the option
brackets; see subsection “Portability” below.
[...]
• Why doesn’t the package provide a string to insert an ellipsis?
Examples of ellipsis usage are shown above, in subsection
“Command synopsis macros”. The idiomatic roff ellipsis is three
dots (periods) with thin space escape sequences \| internally
separating them. Since dots both begin control lines and are
candidate end‐of‐sentence characters, however, it is sometimes
necessary to prefix and/or suffix an ellipsis with the dummy
character escape sequence \&. That fact stands even if a string
is defined to contain the sequence; further, if the string ends
with \&, end‐of‐sentence detection is defeated when you use the
string at the end of an actual sentence. (Ending a sentence
with an ellipsis is often poor style, but not always.) A
hypothetical string EL that contained an ellipsis, but not the
trailing dummy character \&, would then need to be suffixed with
the latter when not ending a sentence.
Instead of... ...do this.
──────────────────────────────────────────────────
.ds EL \&.\|.\|. Arguments are
Arguments are .IR src‐file\~ .\|.\|.\&
.IR src‐file\~ \*(EL\& .IR dest‐dir .
.IR dest‐dir .
──────────────────────────────────────────────────
The first column practices a false economy; the savings in
typing is offset by the cost of obscuring even the suggestion of
an ellipsis to a casual reader of the source document, and
reduced portability to non‐roff man page formatters that cannot
handle string definitions.
There is an ellipsis code point in Unicode, and some fonts have
an ellipsis glyph, which some man pages have accessed in a non‐
portable way with the font‐dependent \N escape sequence. We
discourage the use of these; on terminals, they may crowd the
dots into a half‐width character cell, and will not render at
all if the output device doesn’t have the glyph. In syntax
synopses, missing ellipses can cause great confusion. Dots and
space are universally supported.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Lennart Jablonka [Sat, 29 Jul 2023 13:41:46 +0000 (13:41 +0000)]
string_copying.7: tfix
On some of the commas: There are a few of instances of
Subject verb object partclause, advphrase.
For example:
This function catenates the input character sequence
| subject | verb | object |
contained in a null-padded wixed-width buffer,
| participial clause |
into a destination string.
| adverbial phrase |
Imagining the participial clause away, there shouldn't be a comma
preceding the restrictive adverbial phrase: The input character sequence
is really, always catenated into a destination string; that is
essential. For example:
This function catenates the input character sequence into
a destination string.
The participial clause, being non-restrictive---there is but one input
character sequence that could be meant---, should be enclosed by commas.
That is the existing comma's purpose and doesn't work without the added,
first comma.
The `\c` escape sequence works in an argument to a macro call that is
part of a paragraph tag with font style alternation macros, but not the
ordinary font macros `B` and `I`. This is because `TP`, `B`, and `I`
all set up input traps; the six font style alternation macros do not.
The old formatting would, for some versions of some formatters, set the
"[trailer]" text as part of the paragraph body, not the tag--like this.
.UE [trailer] Terminate the link text of the preceding .UR
macro, with the optional trailer (if present, usually a
(and so on)
This was a poorly understood--and undocumented--interaction of man(7)
features until recently. Gory details involving nroff on Unix Version 7
(1979) running on a simulated PDP-11/45 are available.[1]
Here is a comparison of the former and new markup.
before
======
groff 1.22.3: BAD
groff 1.22.4: GOOD
groff 1.23.0: BAD
mandoc 1.14.6: BAD
now
===
groff 1.22.3: BAD
groff 1.22.4: GOOD
groff 1.23.0: GOOD
mandoc 1.14.6: GOOD
Lennart Jablonka [Fri, 28 Jul 2023 19:22:10 +0000 (19:22 +0000)]
string_copying.7: don't grant strl{cpy,cat} magic
A function can't check whether a pointer points to the start of a
string. What it certainly can do is to keep reading until you either
find a null byte or read the secret key that lies adjacent in memory and
post it to your favorite mailing list.
strlcpy and strlcat behave the exact same way any other function
accepting a string behaves: If you don't pass a string, the behavior is
undefined. And that, I believe, does not deserve a special mention
here, seeing as all the other string functions don't get such a mention
either.
Link: <https://lore.kernel.org/linux-man/ZMQVYtquNN-s0IJr@beryllium/T/#u> Signed-off-by: Lennart Jablonka <humm@ljabl.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Drop spurious, nilpotent uses of *roff `\c` escape sequence.
Quoting groff_man_style(7):
\c End a text line without inserting space or attempting a break.
Normally, if filling is enabled, the end of a text line is
treated like a space; an output line _may_ be broken there (if
not, an adjustable space is inserted); if filling is disabled,
the line _will_ be broken there, as in .EX/.EE examples. The
next line is interpreted as usual and can include a macro call
(contrast with \newline). \c is useful when three font styles
are needed in a single word, as in a command synopsis.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
\& Dummy character. Insert at the beginning of an input line to
prevent a dot or apostrophe from being interpreted as beginning
a roff control line. Append to an end‐of‐sentence punctuation
sequence to keep it from being recognized as such.
Neither case applies to the uses in this page.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Zijun Zhao [Mon, 5 Jun 2023 18:45:49 +0000 (11:45 -0700)]
gettimeofday.2: Add details about the nullability of tv in different libc's
tv arg is allowed to be NULL in bionic.
POSIX says this behavior is undefined, and bionic just exposes the Linux
syscall directly. There's no code in bionic for
gettimeofday/settimeofday; just a description of the syscall name and
arguments from which an assembler stub is automatically generated at
build time. musl and glibc go out of their way to behave differently
from the Linux kernel, but no idea why.
Michael Weiß [Fri, 21 Jul 2023 12:06:36 +0000 (14:06 +0200)]
bpf.2: Added missing EAGAIN error case for BPF_PROG_LOAD
Since commit c3494801cd1785e2 ("bpf: check pending signals while
verifying programs"), bpf() may also fail with EAGAIN if the verifier
detects pending signals.
This was triggered in the cmld of GyroidOS when loading a cgroups device
program during container start. We had a look in the man page and were
confused that EAGAIN was not listed as possible error. Digging in the
kernel source revealed the EAGAIN in the verifier introduced by the
commit above. Further investigation showed that libbpf already wraps
that case, by a retry loop.
Since GyroidOS uses the system call directly and not libbpf, we missed
to handle this error correctly. Thus, this hint in the man page for the
bpf() system call should be helpful for others who implement on the
low-level interface, too.
Clarify that atexit(3)/on_exit(3) are not called because those are
called only on normal process termination (as documented on their
respective manual pages).
John Hubbard [Wed, 19 Jul 2023 02:05:33 +0000 (19:05 -0700)]
tmpfs.5: Update reference to CONFIG_TRANSPARENT_HUGEPAGE
In commit 462a385e9a2 ("tmpfs.5: Document current mount options"), there
is a reference to CONFIG_TRANSPARENT_HUGE_PAGECACHE. However, that
option was removed from the kernel via commit 396bcc5299c2 ("mm: remove
CONFIG_TRANSPARENT_HUGE_PAGECACHE"), a couple of years later.
The net effect is that CONFIG_TRANSPARENT_HUGEPAGE is now used in all
the remaining places in the kernel where
CONFIG_TRANSPARENT_HUGE_PAGECACHE had previously been used.
This has caused some minor confusion at the man page level, though. So
let's fix it by updating the man page to refer to
CONFIG_TRANSPARENT_HUGEPAGE.
Reported-by: Vahid Noormofidi <vnoormof@nvidia.com> Cc: Matthew Wilcox (Oracle) <willy@infradead.org> Cc: Kirill A. Shutemov <kirill.shutemov@linux.intel.com> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Carsten Grohmann <carstengrohmann@gmx.de> Cc: Mike Frysinger <vapier@gentoo.org> Signed-off-by: John Hubbard <jhubbard@nvidia.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
* Stop disabling adjustment and automatic hyphenation before tables,
and incorrectly "restoring" it afterward. In addition to repetitious
boilerplate around tables, the `ad` and `hy` requests, when not given
arguments, do not behave as many man page authors expect. If
adjustment was initially disabled when rendering the page, it was
being activated after `TE` calls, frustrating the desire of the
reader. Furthermore, `hy` when given no argument enables automatic
hyphenation in mode "1", which is not an appropriate value for the
TeX-based hyphenation patterns for English that groff has used for
over 30 years. And analogously to `ad`, a simple `hy` request would
reactivate automatic hyphenation even if the reader had disabled it.
Moreover, such fiddling is often unnecessary. tbl(1) from groff
1.23.0 describes how tbl(1) has always worked, dating back to Michael
Lesk's original implementation at Bell Labs in the 1970s.
"Ordinarily, a table entry is typeset rigidly. It is not filled,
broken, hyphenated, adjusted, or populated with additional inter-
sentence space. ... Text blocks are formatted as was the text prior
to the table, modified by applicable column descriptors. ... Add na
or ad requests to the beginning of a text block to alter its
adjustment distinctly from other text in the document. As with other
table entries, when a text block ends, any alterations to formatting
parameters are discarded. They do not affect subsequent table
entries, not even other text blocks."
* Apropos of the foregoing, add `na` and `nh` requests to the
"Interface" columns of MT-safety tables in pages' "ATTRIBUTES"
sections, so that C function names are not inappropriately hyphenated.
I produced this change with the following GNU sed script.
:start
/^\.ad l/{N;/\n\.nh/{N;/\n\.TS/s/.*/.TS/}}
/^\.TE/{N;/\n\.hy/{N;/\n\.ad/s/.*/.TE/}}
/^Interface.*Attribute.*Value/{N;/\nT{/s/.*/&\n.na\n.nh/
:loop
n
/T{/s/.*/&\n.na\n.nh/
/^\.TE/b start;
b loop
}
Protect instances of some literals from hyphenation. These are only
those necessary to improve analyzability of a large-scale (500+ file),
sed-driven change to improve adjustment and hyphenation enablement
management around tables.
* man2/getrlimit.2: Protect some instances of `RLIMIT_MSGQUEUE`,
`RLIMIT_SIGPENDING`, `RLIMIT_FSIZE`, and `getrlimit` from
hyphenation.
* man2/sigaltstack.2: Protect an instance of `setrlimit` from
hyphenation.
* man3/gethostbyname.3: Protect an instance of `endhostent` from
hyphenation.
* man3/getmntent.3: Protect an instance of `getmntinfo` from
hyphenation.
Matthew House [Tue, 18 Jul 2023 17:26:08 +0000 (13:26 -0400)]
recv.2: Document MSG_CMSG_CLOEXEC as returned in msg_flags
Ever since commit 4a19542e5f69 ("O_CLOEXEC for SCM_RIGHTS") added the
MSG_CMSG_CLOEXEC flag to recvmsg(2), the flag has also been copied into
the returned msg->msg_flags when specified, regardless of whether any
file descriptors were actually received, or whether the protocol
supports receiving file descriptors at all. This behavior was primarily
an implementation artifact: by copying MSG_CMSG_CLOEXEC into the
msg_flags, scm_detach_fds() in net/core/scm.c (and its _compat()
counterpart in net/compat.c) could determine whether it was set without
having to receive a copy of the recvmsg(2) flags.
This mechanism was closely modeled after the internal MSG_CMSG_COMPAT
flag, which is passed by the compat versions of the send[m]msg(2) and
recv[m]msg(2) syscalls to inform various functions that user space
expects a compat layout. When the flag was first implemented by commits 3225fc8a85f4 ("[NET]: Simplify scm handling and sendmsg/recvmsg
invocation, consolidate net compat syscalls.") and 7e8d06bc1d90
("[COMPAT]: Fix MSG_CMSG_COMPAT flag passing, kill
cmsg_compat_recvmsg_fixup.") (in history/history.git), the behavior was
very similar: recvmsg(2) would add MSG_CMSG_COMPAT to the msg_flags, and
put_cmsg() and scm_detach_fds() in net/core/scm.c would read the flag to
determine whether to delegate to their _compat() counterparts.
However, after the initial implementation, more work was done to hide
MSG_CMSG_COMPAT from user space. First, commit 37f7f421cce1 ("[NET]: Do
not leak MSG_CMSG_COMPAT into userspace.") started scrubbing the bit
from msg_flags right before copying it back into user space. Then,
since passing the MSG_CMSG_COMPAT flag into the syscalls from non-compat
code could confuse the kernel, commits 1be374a0518a ("net: Block
MSG_CMSG_COMPAT in send(m)msg and recv(m)msg") and a7526eb5d06b ("net:
Unbreak compat_sys_{send,recv}msg") made them return -EINVAL if user
space attempted to pass the flag. But to reduce breakage, commit d720d8cec563 ("net: compat: Ignore MSG_CMSG_COMPAT in
compat_sys_{send, recv}msg") rolled that back somewhat, making
MSG_CMSG_COMPAT an error for the non-compat syscalls and a no-op for the
compat syscalls, which is the current status quo.
Even though MSG_CMSG_CLOEXEC was implemented after the kernel started
scrubbing MSG_CMSG_COMPAT from the returned msg_flags, the newer flag
never received the same treatment. At this point, this behavior has
effectively become part of the user-space API, to the extent that
io_uring has been careful in commit 9bb66906f23e ("io_uring: support
multishot in recvmsg") to replicate the behavior in its multishot
IORING_OP_RECVMSG operation.
Therefore, document this behavior to avoid confusion when user space
sees MSG_CMSG_CLOEXEC returned in msg->msg_flags.
On 2023-07-18 15:24, Ulrich Drepper wrote:
> On Tue, Jul 18, 2023 at 2:10 PM Alejandro Colomar <alx@kernel.org> wrote:
>> On 2023-07-18 08:00, Matthew House wrote:
>>>
>>> As for the original purpose of the behavior, it's not really clear,
>>> and it may well have been an implementation artifact that got
>>> enshrined in the user space ABI.
>>> (Even io_uring is careful to replicate this behavior!)
>>
>> This is what worries me. I've CCd a bunch of people to see if they can
>> bring some light.
>
> It definitely was an artifact of the implementation. I haven't tested
> getting the close-on-exec flag information for all interfaces. The
> assumption was that the information about the close-on-exec flag is
> received with the universal fcntl() call.
Cc: linux-api@vger.kernel.org Cc: netdev@vger.kernel.org Cc: Ulrich Drepper <drepper@redhat.com> Cc: "David S. Miller" <davem@davemloft.net> Cc: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Matthew House <mattlloydhouse@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
grantpt.3: It's a no-op on modern glibc and other UNIXes; HISTORYise
FreeBSD, OpenBSD, and Linux (/dev/ptmx) do all intialisation in open(2),
and grantpt(3) is a no-op (that checks whether the fd is a pty, except
on musl).
The illumos gate and NetBSD do a ioctl (and, indeed, illumos-gate commit facf4a8d7b59fde89a8662b4f4c73a758e6c402c ("PSARC/2003/246 Filesystem
Driven Device Naming"), which kills pt_chmod, notes that it's been
"6464196 bfu should remove pt_chmod, obsoleted by /dev filesystem").
glibc 2.33 completely kills BSD PTY support on Linux
(Debian hasn't configured with them on any architecture since 2007:
https://bugs.debian.org/338404
and even earlier on some arches; they're really just trivia under
Linux ‒ this may be better served stuffed into HISTORY as an explainer
for the SIGCHLD thing, since regardless of the "version", the behaviour
is well-defined and consistent).
There really aren't many cohesive "versions" of this ‒ indeed, so long
as grantpt(3) exists it behaves precisely as described here ‒
inasmuch as different systems, historically, had different ptys,
and thus different implementations. These are all but trivia.
Add an empty double-colon rule that targets the makefiles, to instruct
make(1) to not remake makefiles. This improves (considerably reduces)
the output of 'make -d'.
Xi Ruoyao [Sun, 16 Jul 2023 01:51:25 +0000 (09:51 +0800)]
crypt.3, encrypt.3: Fix library name and description
libcrypt is the password hashing library, and libcrypto is a completely
different library (OpenSSL cryptography library). While the encrypt()
function can "encrypt" things, it uses a broken algorithm so let's not
call libcrypt an "encryption" library at all. In crypt.3, also replace
"encrypt" with "hash" except several places where it really means
"encrypt".
Signed-off-by: Xi Ruoyao <xry111@xry111.site> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Which don't behave like you may expect them to;
unprimed, I expected the natural extension of either:
files (being a filesystem object), always returning 0 if no data, or
sockets (being an IPC mechanism), always EAGAINing if no data.
The pipe semantics make sense of course ‒ pipes can be modelled as
sockets if there aren't writers, but files if there are; indeed,
this makes sense as the writer continuously appending a sliding
"window" over a file ‒ but they're unique amongst the UNIX file types,
but arriving at that specific interaction table is non-obvious,
especially to a user.
Quoth Issue 8 Draft 3:
60746 When attempting to read from an empty pipe or FIFO:
60747 • If no process has the pipe open for writing, read( ) shall return 0 to indicate end-of-file.
60748 • If some process has the pipe open for writing and O_NONBLOCK is set, read( ) shall return
60749 −1 and set errno to [EAGAIN].
60750 • If some process has the pipe open for writing and O_NONBLOCK is clear, read( ) shall
60751 block the calling thread until some data is written or the pipe is closed by all processes that
60752 had the pipe open for writing.
Paul Eggert [Sun, 9 Jul 2023 06:07:55 +0000 (23:07 -0700)]
man*/: Prefer off_t over off64_t for splice(2), etc.
For the few functions that come only in 64-bit off_t flavors,
document their APIs as using off_t instead of off64_t,
and say also that code should #define _FILE_OFFSET_BITS 64.
This documents what user code is (and should be) doing anyway,
if it needs to work on traditional x86 and ARM Linux.
Reported-by: Rich Felker <dalias@libc.org> Fixes: 9bebb17e5b57 ("splice.2: Use 'off64_t' instead of 'loff_t'") Fixes: 76c5631fb442 ("copy_file_range.2: Document glibc wrapper instead of kernel syscall") Fixes: 5cabfa06b407 ("man-pages 1.68") Fixes: 3ca974e3988a ("New page for sync_file_range(2), new in kernel 2.6.17.") Fixes: 9bebb17e5b57 ("sync_file_range.2: Document the architecture-specific sync_file_range2() system call") Fixes: 79bf8cdcf36a ("Document fopencookie(3), a library function that allows custom implementation of a stdio stream.") Signed-off-by: Paul Eggert <eggert@cs.ucla.edu> Reviewed-by: Sam James <sam@gentoo.org> Cc: Jonathan Wakely <jwakely@redhat.com> Cc: Szabolcs Nagy <nsz@port70.net> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: A. Wilcox <AWilcox@wilcox-tech.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
On 2023-07-08 22:14, Martin (Joey) Schulze wrote:
> For the record,
>
> I would like to re-license dir_colors(5) under the GPLv2+
>
> Please adjust the manpage source accordingly.
>
> .\" Copyright (c) 2001 Martin Schulze <joey@infodrom.org>
> .\"
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual; if not, write to the Free
> .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
> .\" USA.
>
> This should help keep the manpage free and a version in Fedora.
Link: <https://gitlab.com/fedora/legal/fedora-license-data/-/issues/211> Reported-by: Adam Dobes <adobes@redhat.com> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Cc: Martin (Joey) Schulze <joey@infodrom.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Quoting myself from #musl:
01:59:40 hm, I think this was just invented for symmetry with bfree/bavail
02:00:46 FFS has minfree for space but nothing equivalent for inodes
02:32:31 (this is mirrored in ext4;
a global grep over DragonFlyBSD and the illumos gate
showed just NFSv3 forwarding from the server;
OpenBSD always sets it to the same thing as f_ffree;
oddly, NetBSD /does/ calculate it differently
for LFS and FFS but due to queued writes or
w/e not because of root reservation;
and as expected a lot of "/* what to put in here? */"
and "// XXX same??")
Paul E. McKenney [Fri, 30 Jun 2023 23:33:28 +0000 (16:33 -0700)]
proc.5: Clarify that boot arguments can be embedded in image
With the advent of the CONFIG_BOOT_CONFIG Kconfig option, kernel boot
arguments can now be embedded in the kernel image, either attached
to the end of initramfs or embedded in the kernel itself. Document
this possibility in the /proc/cmdline entry of proc.5.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org> Cc: Michael Kerrisk <mtk.manpages@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Nick Desaulniers <ndesaulniers@google.com> Cc: Vlastimil Babka <vbabka@suse.cz> Cc: Johannes Weiner <hannes@cmpxchg.org> Reviewed-by: Masami Hiramatsu <mhiramat@kernel.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
inotify.7: wds are in the range [1, INT_MAX], not [0,
Naturally, the first inotify_add_watch() returns 1,
but also fs/notify/inotify.c:inotify_add_to_idr() allocates them with
idr_alloc_cyclic(idr, i_mark, start=1, end=0, GFP_NOWAIT);
(start inclusive, end exclusive).
(From SYSCALL_DEFINE3(inotify_add_watch, ...),
from inotify_update_watch(),
from inotify_new_watch()).
наб [Sat, 24 Jun 2023 12:13:29 +0000 (14:13 +0200)]
poll.2: explicitly say what happens for regular files &c.
Naively, one may consider being "ready" to mean, for example,
lseek(0, 0, SEEK_END); poll({.fd = 0, .events = POLLIN}, 0);
to be able to say whether new data has appeared at the end of the file.
This is not the case, and poll() is only meaningful as
"will a read or a write sleep": regular files and block devices are
always ready to return an empty read in this case, for example,
and you need to use inotify to achieve this.
Under Linux this is governed by DEFAULT_POLLMASK
(EPOLLIN | EPOLLOUT | EPOLLRDNORM | EPOLLWRNORM)
being returned if no explicit poll operation is defined for the file.
As contrast, unpollables like the above are refused by epoll_ctl(ADD).
I explicitly hit the two keywords I searched for (regular, block)
before just writing a test program to confirm that poll() behaved as
expected and is not a good fit for my use-case.
This behaviour is guaranteed by POSIX (Issue 8 Draft 3):
51381 The poll( ) and ppoll( ) functions shall support regular files, terminal and pseudo-terminal
51382 devices, FIFOs, pipes, and sockets. The behavior of poll( ) and ppoll( ) on elements of fds that refer
51383 to other types of file is unspecified.
51384 Regular files shall always poll TRUE for reading and writing.
51385 A file descriptor for a socket that is listening for connections shall indicate that it is ready for
51386 reading, once connections are available. A file descriptor for a socket that is connecting
51387 asynchronously shall indicate that it is ready for writing, once a connection has been established.
On 6/18/23 22:05, Oskari Pirhonen wrote:
> On Sat, Jun 17, 2023 at 13:11:29 +0200, Helge Kreutzmann wrote:
>> Hello Alejandro,
>> On Sun, Mar 12, 2023 at 12:31:37AM +0100, Alejandro Colomar wrote:
>>> On 3/11/23 18:13, Helge Kreutzmann wrote:
>>>> Without further ado, the following was found:
>>>>
>>>> Issue: This is true only on x86 and Lilo is probably not much
>>>> used anymore; also systemd has its own (?) bootloader
>>
>> Lilo has just been removed from Debian, so to my knowledge only
>> Mageia ships it.
>>
>
> FWIW, Gentoo still has LILO in the repos. This doesn't change the
> fact that it probably does not see much use anymore. Definitely not
> enough to warrant being mentioned as "is often". Maybe a historical
> note, if anything.
Bruno Haible [Sun, 21 May 2023 11:05:29 +0000 (13:05 +0200)]
List a fifth condition when iconv(3) may stop.
The wording regarding transliteration is vague, because this man page is not
the right place for going into the details of the transliteration.
Here are the details:
GNU libc and GNU libiconv support transliteration, for example, of "½" to "1/2",
or of "å" to "aa" in a Danish locale. The transliteration maps a multibyte
character of the input encoding to zero or more characters in the output.
There are two kinds of transliteration rules:
- Those that are valid regardless of locale. Typically this means that the
original and the transliterated character have similar glyphs, such as
in the case "½" to "1/2".
In GNU libc, these are collected in the files
glibc/localedata/locales/translit_*.
- Those that are valid in a single locale only. Often such a rule
reflects similar pronounciation of the original and the transliterated
characters. Some locales have script-based transliteration, for example
from the Cyrillic script to the Latin script.
In GNU libc, these are collected in the file
glibc/localedata/locales/<locale>.
In GNU libiconv, transliterations of this kind are not supported.
projects / thirdparty / man-pages.git / log
