Michael Kerrisk [Sun, 23 Dec 2018 16:50:02 +0000 (17:50 +0100)]
write.2: RETURN VALUE: clarify details of partial write and
As reported by Nadav Har'El in
https://bugzilla.kernel.org/show_bug.cgi?id=197961
The write(2) manual page has this paragraph:
"On success, the number of bytes written is returned
(zero indicates nothing was written). It is not an error
if this number is smaller than the number of bytes
requested; this may happen for example because the disk
device was filled. See also NOTES."
I find a few problems with this paragraph:
1. It's not clear what "See also NOTES." refers to (does it
refer to anything?). What in the NOTES is relevant here?
2. The paragraph seems to suggest that write(2) of a
non-empty buffer may sometimes return even 0 in case of an
error like the device being filled. I think this is wrong
- if there was an error after already writing some number
of bytes, this non-zero number is returned. But if there's
an error before writing any bytes, -1 will be returned
(and the error reason in errno) - 0 will not be returned
unless the given count is 0 (that case is explained in the
following paragraph).
3. The paragraph doesn't explain what a user should do
after a short write (i.e., write(2) returning less than
count). How would the user know why there was an error, or
if there even was one? I think users should be told what
to do next because this information is part of how to use
this API correctly. I think users should be told to retry
the rest of the write (i.e., write(fd, buf+ret, count-ret)
and this will either succeed in writing some more data if
the error reason was solved, or the second write will
return -1 and the error reason in errno.
Reported-by: Nadav Har'El <nyh@math.technion.ac.il> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Sun, 23 Dec 2018 16:36:18 +0000 (17:36 +0100)]
getxattr.2, removexattr.2, setxattr.2: ERRORS: replace ENOATTR with ENODATA
ENOATTR is not a standard error code, but rather one that is
defined in 'libattr' as a synonym for ENODATA. The manual pages
should use the error code actually returned by the kernel APIs.
See also https://bugzilla.kernel.org/show_bug.cgi?id=201995
Reported-by: Enrico Scholz <enrico.scholz@sigma-chemnitz.de> Reviewed-by: Andreas Gruenbacher <agruenba@redhat.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
snyh [Sat, 8 Dec 2018 13:44:15 +0000 (14:44 +0100)]
syscall.2: Fix wrong retval register number in alpha architecture
alpha use v0 e.g. $0 as the return value register both in
syscall ABI and C ABI.
see also
https://github.com/torvalds/linux/blob/master/arch/alpha/kernel/entry.S#L479
The normal Alpha C ABI use a0~a5 to pass arguments and use v0 as
the return value register. See here
https://www2.cs.arizona.edu/projects/alto/Doc/local/alpha.register.html
The syscall ABI use v0 as the trap number, a0~a5 to pass arguments
and use a3 as a indicator (bool type) whether has a error occurred.
We can also see the libc's syscall wrapper implements at
https://code.woboq.org/userspace/glibc/sysdeps/unix/sysv/linux/alpha/syscall.S.html
The v0 is the normal used as return register, and we can see the
return processing doesn't do anything about a0 which is the wrong
register of currently syscall(2) description.
p.s. I found this wrong description because I'm porting Go gc to
a new CPU architecture which is similar to Alpha, And I use the
wrong register at first, then I have inspect the kernel code and
objdump to ensure the right syscall ABI.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Vince Weaver [Mon, 3 Dec 2018 20:23:42 +0000 (15:23 -0500)]
perf_event_open.2: Fix wording in multiplexing description
Back in 2014 (37bee118ad692e120559c71bc2b2428d31637c5e) the text
describing when multiplexing happens was changed in a confusing way.
This is an attempt to clarify things a bit.
Signed-off-by: Vince Weaver <vincent.weaver@maine.edu> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michal Hocko [Thu, 29 Nov 2018 18:10:48 +0000 (19:10 +0100)]
madvise.2: MADV_FREE clarify swapless behavior
Since 93e06c7a6453 ("mm: enable MADV_FREE for swapless system") we
handle MADV_FREE on a swapless system the same way as with the
swap available. Clarify that fact in the man page.
Reported-by: Niklas Hambüchen <mail@nh2.me> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Dmitry V. Levin [Mon, 26 Nov 2018 21:18:47 +0000 (00:18 +0300)]
ptrace.2: Do not say that PTRACE_O_TRACESYSGOOD may not work
Remove the old statement that PTRACE_O_TRACESYSGOOD may not work
on all architectures. As far as I can tell, all kernel code
properly tests PT_TRACESYSGOOD flag and sets the 7th bit in the
exit code passed to ptrace_notify().
Signed-off-by: Dmitry V. Levin <ldv@altlinux.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Sat, 24 Nov 2018 11:48:35 +0000 (12:48 +0100)]
prctl.2: Explain the circumstances in which the parent-death signal is sent
To test the behavior documented by this patch, the following
demos employ the program shown at the foot of this commit message.
First, show that the pdeath signal is sent when the parent
terminates:
$ ./pdeath_signal 0 10 4
Parent (18595) about to sleep for 4 seconds
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18595) terminating
*********** Child (18596) got signal; si_pid = 18595; si_uid = 1000
Parent PID is now 1403
$ Child about to exit
But the signal is not sent if the parent terminates before the
child uses PR_SET_PDEATHSIG:
$ ./pdeath_signal 2 10 0
Parent (18707) about to sleep for 0 seconds
Parent (18707) terminating
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
$ Child about to set PR_SET_PDEATHSIG
Child about to sleep
Child about to exit
Demonstrate that the pdeath signal is sent on termination of each
ancestor subreaper process:
$ ./pdeath_signal 2 10 3 7 6 5
18786 marked itself as a subreaper
18786 subreaper about to sleep 7 seconds
18787 marked itself as a subreaper
18787 subreaper about to sleep 6 seconds
18788 marked itself as a subreaper
18788 subreaper about to sleep 5 seconds
Parent (18789) about to sleep for 3 seconds
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18789) terminating
*********** Child (18790) got signal; si_pid = 18789; si_uid = 1000
Parent PID is now 18788
18788 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18788; si_uid = 1000
Parent PID is now 18787
18787 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18787; si_uid = 1000
Parent PID is now 18786
18786 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18786; si_uid = 1000
Parent PID is now 1403
$ Child about to exit
But in the case where some subreapers terminate before they
have a chance to adopt the child, the terminations of those
subreapers do not result in a signal for the child:
$ ./pdeath_signal 2 10 3 5 6 7
18836 marked itself as a subreaper
18836 subreaper about to sleep 5 seconds
18837 marked itself as a subreaper
18837 subreaper about to sleep 6 seconds
18838 marked itself as a subreaper
18838 subreaper about to sleep 7 seconds
Parent (18839) about to sleep for 3 seconds
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18839) terminating
*********** Child (18840) got signal; si_pid = 18839; si_uid = 1000
Parent PID is now 18838
18836 subreaper about to terminate
$ 18837 subreaper about to terminate
18838 subreaper about to terminate
*********** Child (18840) got signal; si_pid = 18838; si_uid = 1000
Parent PID is now 1403
Child about to exit
childPreSleep = atoi(argv[1]);
if (argc > 2)
childPostSleep = atoi(argv[2]);
if (argc > 3)
parentSleep = atoi(argv[3]);
/* Optionally create a series of subreapers */
if (argc > 4) {
for (int sr = 4; sr < argc; sr++) {
if (prctl(PR_SET_CHILD_SUBREAPER, 1) == -1)
errExit("prctl");
printf("%ld marked itself as a subreaper\n", (long) getpid());
switch (fork()) {
case -1:
errExit("fork");
case 0:
break;
default:
printf("%ld subreaper about to sleep %s seconds\n",
(long) getpid(), argv[sr]);
sleep(atoi(argv[sr]));
printf("%ld subreaper about to terminate\n", (long) getpid());
exit(EXIT_SUCCESS);
}
}
}
switch (fork()) {
case -1:
errExit("fork");
case 0:
sa.sa_flags = SA_SIGINFO;
sigemptyset(&sa.sa_mask);
sa.sa_sigaction = handler;
if (sigaction(SIGUSR1, &sa, NULL) == -1)
errExit("sigaction");
if (childPreSleep > 0) {
printf("Child about to sleep %d seconds before setting "
"PR_SET_PDEATHSIG\n", childPreSleep);
sleep(childPreSleep);
}
printf("Child about to set PR_SET_PDEATHSIG\n");
if (prctl(PR_SET_PDEATHSIG, SIGUSR1) == -1)
errExit("prctl");
printf("Child about to sleep\n");
for (int j = 0; j < childPostSleep; j++)
sleep(1);
printf("Child about to exit\n");
exit(EXIT_SUCCESS);
default:
printf("Parent (%ld) about to sleep for %d seconds\n",
(long) getpid(), parentSleep);
sleep(parentSleep);
printf("Parent (%ld) terminating\n", (long) getpid());
exit(EXIT_SUCCESS);
}
}
Reported-by: Jann Horn <jann@thejh.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Jann Horn [Fri, 22 Jun 2018 15:44:41 +0000 (17:44 +0200)]
ptrace.2: BUGS: ptrace() may set errno to zero
ptrace() with requests PTRACE_PEEKTEXT, PTRACE_PEEKDATA and
PTRACE_PEEKUSER can set errno to zero. AFAICS this is for a good
reason (so that you can tell the difference between a successful
PEEK with a result of -1 and a failed PEEK, even if you forget to
clear errno yourself), but it technically violates the rules
described in the errno.3 manpage.
glibc snippet from sysdeps/unix/sysv/linux/ptrace.c:
Michael Kerrisk [Mon, 19 Nov 2018 15:23:28 +0000 (16:23 +0100)]
pid_namespaces.7: Clarify the semantics for the adoption of orphaned processes
Because of setns() semantics, the parent of a process may reside
in the outer PID namespace. If that parent terminates, then the
child is adopted by the "init" in the outer PID namespace (rather
than the "init" of the PID namespace of the child).
Thus, in a scenario such as the following, if process M
terminates, P is adopted by the init process in the initial
PID namespace, and if P terminates, Q is adopted by the init
process in the inner PID namespace.
Michael Kerrisk [Mon, 19 Nov 2018 12:06:53 +0000 (13:06 +0100)]
clone.2, prctl.2, st.4, proc.5: Change references to '2.6.0-test*' series kernels to just '2.6.0'
The extra detail has little of noting with -test 2.6.0
added a particular feature has little value these days,
and is likely to confuse some readers who don't know
(and probably don't care) about the historical details.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Sat, 17 Nov 2018 09:10:30 +0000 (10:10 +0100)]
signal.7: Unify signal lists into a signal table that embeds standards info
Having the signals listed in three different tables reduces
readability, and would require more table splits if future
standards specify other signals.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Carlos O'Donell [Thu, 15 Nov 2018 15:03:41 +0000 (10:03 -0500)]
pthread_rwlockattr_setkind_np.3: Remove bug notes
The notes in pthread_rwlockattr_setkind_np.3 imply there is a bug
in glibc's implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP (a
non-portable constant anyway), but this is not true. The
implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP is made almost
impossible by the POSIX standard requirement that reader locks be
allowed to be recursive, and that requirement makes writer
preference deadlock without an impossibly complex requirement that
we track all reader locks. Therefore the only sensible solution
was to add PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP and
disallow recursive reader locks if you want writer preference.
This patch removes the bug description and documents the current
state and recommendations for glibc. I have also updated bug 7057
with this information, answering Steven Munroe's almost 10 year
old question :-) I hope Steven is enjoying his much earned
retirement.
Should we move the glibc discussion to some footnote? Some libc
may be able to implement the requirement to avoid deadlocks in the
future, but I doubt it (fundamental CS stuff).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Sat, 17 Nov 2018 06:03:07 +0000 (07:03 +0100)]
capabilities.7: Update URL for libcap tarballs
The previous location does not seem to be getting updated.
(For example, at the time of this commit, libcap-2.26
had been out for two months, but was not present at
http://www.kernel.org/pub/linux/libs/security/linux-privs.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Keith Thompson [Fri, 9 Nov 2018 03:55:55 +0000 (04:55 +0100)]
strfry.3: Remove incorrect reference to rand(3)
The strfry(3) function does not use rand(). The original version
from 1995 did, but it was changed to use a different PRNG in glibc
commit 4770745624b7f7f25623f1f10d46a4c4d6aec25c, 1996-12-04.
This C program demonstrates the behavior. By not calling srand(),
it gets the same values for successive calls to rand(), but
strfry() returns a different value each time the program is run.
If strfry() called srand(), it would alter the sequence of numbers
return by rand().
Michael Kerrisk [Wed, 7 Nov 2018 20:41:34 +0000 (21:41 +0100)]
signal.7: Reorder the architectures in the signal number lists
x86 and ARM are the most common architectures, but currently
are in the second subfield in the signal number lists.
Instead, swap that info with subfield 1, so the most
common architectures are first in the list.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Helge Deller [Wed, 7 Nov 2018 06:58:55 +0000 (07:58 +0100)]
signal.7: Add signal numbers for parisc
This patch adds the signal numbers for parisc to the signal(7) man page.
Those parisc-specific values for the various signals are valid since the
Linux kernel upstream commit ("parisc: Reduce SIGRTMIN from 37 to 32 to
behave like other Linux architectures") during development of kernel 3.18:
http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=1f25df2eff5b25f52c139d3ff31bc883eee9a0ab
Signed-off-by: Helge Deller <deller@gmx.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Helge Deller [Tue, 6 Nov 2018 21:27:23 +0000 (22:27 +0100)]
syscalls.2: parisc Linux does not any longer emulate HP-UX
Initially it was planned that the parisc linux port would natively
support 32-bit HP-UX binaries, but this compatibility was never
reached and finally dropped with Linux kernel 3.14.
With that background, drop parisc from the list of of platforms
which supports it's proprietary operating-system.
Additional notes from mtk:
The most relevant commit from the Linux 3.14 change log was:
parisc: Make EWOULDBLOCK be equal to EAGAIN on parisc
On Linux, only parisc uses a different value for EWOULDBLOCK which
causes a lot of troubles for applications not checking for both values.
Since the hpux compat is long dead, make EWOULDBLOCK behave the same as
all other architectures.
]]
Additional notes from Helge:
The patch above is the initial and most important one with which
we stopped the HP-UX compatibility.
Then, with this commit in kernel 3.18 there is no way back:
"parisc: Reduce SIGRTMIN from 37 to 32 to behave like
other Linux architectures"
commit 1f25df2eff5b25f52c139d3ff31bc883eee9a0ab
And in kernel 4.0 we finally dropped the HP-UX compat layer
from Linux kernel source code with the commit series
"parisc: hpux - Drop support for HP-UX binaries":
commit 04c1614977168fb8f002e2d81f704eeabe0c5ebd
Signed-off-by: Helge Deller <deller@gmx.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Helge Deller [Tue, 6 Nov 2018 21:39:59 +0000 (22:39 +0100)]
syscall.2: parisc needs care with syscall parameters
On parisc one needs to take care of the 32-bit calling conventions
with 64-bit syscall parameters on a 32-bit kernel. So on parisc we
suffer from the same issues like ARM, PowerPC and Xtensa.
Signed-off-by: Helge Deller <deller@gmx.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Mon, 5 Nov 2018 16:24:19 +0000 (17:24 +0100)]
rename.2: Rework list of supported filesystems for RENAME_NOREPLACE
There was probably a little too much detail in
Lukas Werkmeister's patch. Simplify, by removing a few
file systems, and arrange the information as a bulleted
list for easier readability.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
projects / thirdparty / man-pages.git / log
