Michael Kerrisk [Wed, 20 May 2020 12:45:23 +0000 (14:45 +0200)]
standards.7: Remove mention of bogus "POSIX" names
The terms POSIX.1-{2003,2004,2013,2016} were inventions of
my imagination, as confirmed by consulting Geoff Clare of
The Open Group. Remove these names.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Avoid implying that use of IFUNC is the only way to produce a
symbol with NULL value. Give more scenarios how a symbol may get
NULL value, but explain that in those scenarios dlsym() will fail
with Glibc's ld.so due to an implementation inconsistency.
Signed-off-by: Alexander Monakov <amonakov@ispras.ru> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Devin J. Pohly [Mon, 18 May 2020 20:58:28 +0000 (15:58 -0500)]
veth.4: Add a more direct example
iproute2 allows you to specify the netns for either side of a veth
interface at creation time. Add an example of this to veth(4) so
it doesn't sound like you have to move the interfaces in a
separate step.
Verified with commands:
# ip netns add alpha
# ip netns add bravo
# ip link add foo netns alpha type veth peer bar netns bravo
# ip -n alpha link show
# ip -n bravo link show
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Thomas Piekarski [Tue, 19 May 2020 15:34:33 +0000 (17:34 +0200)]
hier.7: Updating from FHS 2.3 to 3.0
Adding description of new directories (/run, /usr/libexec,
/usr/share/color,/usr/share/ppd, /var/lib/color), stating
/usr/X11R6 as removed and updating URL to and version of FHS.
See https://bugzilla.kernel.org/show_bug.cgi?id=206693
Reported-by: Gary Perkins <glperkins@lit.edu> Signed-off-by: Thomas Piekarski <t.piekarski@deloquencia.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 19 May 2020 19:41:08 +0000 (21:41 +0200)]
clone.2: Note a performance benefit of CLONE_INTO_CGROUP
As noted in email by Christian Brauner:
I forgot to mention that spawning directly into a target
cgroup is also more efficient than moving it after creation.
The specific reason is mentioned in the commit message
[ef2c41cf38a], the write lock of the semaphore need not be
taken in contrast to when it is moved afterwards. That
implementation details is not that interesting but it might
be interesting to know that it provides performance benefits
in general.
Reported-by: Christian Brauner <christian.brauner@ubuntu.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Kir Kolyshkin [Sat, 16 May 2020 23:34:25 +0000 (16:34 -0700)]
Various pages: Add missing commas in SEE ALSO part II
This is a sequel to commit baf17bc4f2a3f3b02d, addressing the
issues with missing commas in the middle of SEE ALSO lists that
emerged since.
The awk script from the original commit was not working and had to
be slightly modified (s/["]SEE ALSO["]/"?SEE ALSO/), otherwise it
works like a charm. Here's the fixed script and its output just
before this commit:
for f in man*/*; do
awk '
/^.SH "?SEE ALSO/ {
sa=1; print "== " FILENAME " =="; print; next
}
/^\.(PP|SH)/ {
sa=0; no=0; next
}
/^\.BR/ {
if (sa==1) {
print;
if (no == 1)
print "Missing comma in " FILENAME " +" FNR-1; no=0
}
}
/^\.BR .*)$/ {
if (sa==1)
no=1;
next
}
/\.\\"/ {next}
/.*/ {
if (sa==1) {
print; next
}
}
' $f; done | grep Missing
Missing comma in man1/memusage.1 +272
Missing comma in man2/adjtimex.2 +597
Missing comma in man2/adjtimex.2 +598
Missing comma in man2/mkdir.2 +252
Missing comma in man2/sigaction.2 +1045
Missing comma in man2/sigaction.2 +1047
Missing comma in man3/mbsnrtowcs.3 +198
Missing comma in man3/ntp_gettime.3 +142
Missing comma in man3/strcmp.3 +219
Missing comma in man3/strtol.3 +302
Missing comma in man3/wcstombs.3 +120
Missing comma in man7/user_namespaces.7 +1378
Missing comma in man7/xattr.7 +198
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:57 +0000 (17:36 +0100)]
prctl.2: Clarify the unsupported hardware case of EINVAL
prctls that are architecture-specific won't work on other
architectures, and arch-specific prctls that manipulate optional
hardware features likewise won't work if that hardware feature is
not present.
The established pattern seems to be to treat such prctls as if they
are unimplemented, when attempted on the wrong hardware.
Cover these cases with some generic weasel words in the closet
existing EINVAL clause.
Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:52 +0000 (17:36 +0100)]
prctl.2: Document removal of Intel MPX prctls
The Intel MPX API was removed from Linux 5.4. See Linux
commit f240652b6032 ("x86/mpx: Remove MPX APIs")
Acked-by: Dave Hansen <dave.hansen@linux.intel.com> Signed-off-by: Dave Martin <Dave.Martin@arm.com> Cc: Dave Hansen <dave.hansen@linux.intel.com> Cc: Thomas Gleixner <tglx@linutronix.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:50 +0000 (17:36 +0100)]
prctl.2: Sort prctls into alphabetical order
The prctl list has historically been sorted by prctl name (ignoring
any SET_ or GET_ prefix) to make individual prctls easier to find.
Some noise seems to have crept in since.
Sort the list back into order. Similarly, reorder the list of
prctls specified to return non-zero values on success.
Content movement only. No semantic change.
Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:49 +0000 (17:36 +0100)]
prctl.2: srcfix: add comments for navigation
The prctl.2 source is unnecessarily hard to navigate, not least
because prctl option flags are traditionally named PR_* and so look
just like prctl names.
For each actual prctl, add a comment of the form
.\" prctl PR_FOO
to make it move obvious where each top-level prctl starts.
Of course, we could add some clever macros, but let's not confuse
dumb parsers.
Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:47 +0000 (17:36 +0100)]
prctl.2: Add health warning
In reality, almost every prctl interferes with assumptions that the
compiler and C library / runtime rely on. prctl() can therefore
make userspace explode in a variety ways that are likely to be hard
to debug.
This is not obvious to the uninitiated, so add a warning.
Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 12 May 2020 16:36:48 +0000 (17:36 +0100)]
prctl.2: Fix mis-description of thread ID values in procfs
Under PR_SET_NAME, the [tid] value seen in procfs as
/proc/self/task/[tid] is mistakenly described as the name of the
thread, whereas really the name is on /proc/self/task/[tid]/comm.
Fix it.
Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Fri, 8 May 2020 15:44:01 +0000 (17:44 +0200)]
close.2: Note behavior when close() happens in a parallel thread
If one thread is blocked in an I/O system call on a file descriptor
that is closed in another thread, then the blocking system call
does not return immediately, but rather when the I/O operation
completes. This surprises some people, but is longstanding
behavior.
See https://bugzilla.kernel.org/show_bug.cgi?id=53781
and
https://lore.kernel.org/lkml/3B1E3D86.C7A7874@canal-plus.fr/
To: linux-kernel@vger.kernel.org
Subject: PROBLEM: I/O system call never returns if file desc is closed in the meantime
Date: Wed, 06 Jun 2001 16:26:14 +0200
Examples where people are surprised by this behavior:
https://www.linuxquestions.org/questions/linux-networking-3/recv-is-not-coming-out-of-blocking-after-closing-the-socket-459461/
https://stackoverflow.com/questions/3589723/can-a-socket-be-closed-from-another-thread-when-a-send-recv-on-the-same-socket
Reported-by: Thierry Lelegard <thierry.lelegard@canal-plus.fr> Reported-by: Lukas Czerner <lczerner@redhat.com> Reported-by: Peter Schiffer <pschiffe@redhat.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dave Martin [Tue, 5 May 2020 15:24:39 +0000 (16:24 +0100)]
syscall.2: arm: Use real register names for arm/OABI
The arm OABI syscall interface is currently documented in terms of
register name aliases defined by the ARM Procedure Call Standard
(APCS). However, these don't make sense in the context of a
binary interface that doesn't comply (or need to comply) with
APCS.
Use the real architectural register names instead.
The names a1-a4, v1... are just aliases for r0-r3, r4... anyway,
so the interface is just the same regardless of which set of names
is used.
Acked-by: Russell King <rmk+kernel@armlinux.org.uk> Signed-off-by: Dave Martin <Dave.Martin@arm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Wed, 6 May 2020 09:33:21 +0000 (11:33 +0200)]
loop.4: 'lo_flags' is nowadays "r/w"
Since kernel commit 96c5865559cee0f9cbc5173f3c949f6ce3525581,
the 'lo_flags' field is modifiable via the LOOP_SET_STATUS and
LOOP_SET_STATUS64 ioctl() operations.
See https://bugzilla.kernel.org/show_bug.cgi?id=203417
Reported-by: Vlad <cvazir@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Mon, 27 Apr 2020 05:13:22 +0000 (07:13 +0200)]
zdump.8: Update to latest upstream tz release
This update addresses an issue described in
https://bugzilla.kernel.org/show_bug.cgi?id=207345
In answer to my question, Paul Eggert noted:
> Where do I find it?
https://www.iana.org/time-zones
Look under "Latest version", which is 2020a.
Reported-by: Paul Eggert <eggert@cs.ucla.edu> Reported-by: Marco Curreli <marcocurreli@tiscali.it> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Bruno Haible [Sat, 26 Jan 2019 13:31:56 +0000 (14:31 +0100)]
ptsname.3: Fix description of failure behaviour of ptsname_r()
The Linux man page for ptsname_r, when describing the behaviour
in the error case, is
- not consistent with the future POSIX standard (POSIX Issue 8).
- not consistent with musl libc.
Find attached a patch to
- keep it consistent with what glibc does,
- make it consistent with musl libc,
- make it consistent with the future POSIX standard (POSIX
Issue 8).
Details:
glibc's implementation of ptsname_r, when it fails, returns the
error code as return value AND sets errno. See
https://sourceware.org/git/?p=glibc.git;a=blob;f=login/ptsname.c
https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/mach/hurd/ptsname.c
https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/ptsname.c
musl's implementation of ptsname_r, when it fails, returns the error code
but does NOT set errno. See
https://git.musl-libc.org/cgit/musl/tree/src/misc/pty.c
The proposal to add ptsname_r to POSIX, with text
"If successful, the ptsname_r( ) function shall return zero.
Otherwise, an error number shall be returned to indicate the
error."
has been accepted for inclusion in POSIX Issue 8.
http://austingroupbugs.net/view.php?id=508
Therefore a portable program should look at the return value from
ptsname_r, NOT the errno value. The current text in the man page
suggests to look at the errno value, which is wrong (because of
musl libc) and not future-proof (because of future POSIX).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Thu, 23 Apr 2020 12:31:27 +0000 (14:31 +0200)]
fanotify_mark.2: Remove mention of FAN_Q_OVERFLOW as an input value in 'mask'
See https://bugzilla.kernel.org/show_bug.cgi?id=198569.
Reported-by: Alexander Morozov <alexandermv@gmail.com> Reported-by: Amir Goldstein <amir73il@gmail.com> Reported-by: Jan Kara <jack@suse.cz> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
projects / thirdparty / man-pages.git / log
