For a better visual result, disable justification and hyphenation
in SEE ALSO where page names are long.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Eric Dumazet noted that EINVAL was not documented. Some further
digging shows that it's also not diagnosed consistently.
See https://bugzilla.kernel.org/show_bug.cgi?id=47111.
Reported-by: Eric Dumazet <edumazet@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Executive summary: a sane application can't rely on any
particular behavior if another thread closes a file descriptor
being monitored by select().
See https://bugzilla.kernel.org/show_bug.cgi?id=40852
Reported-by: Stephane Fillod <fillods@users.sf.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Fredrik (and as far as I can tell the problem
went back to 2.6.0):
The timeout argument has an upper limit. Any values above that
limit are treated the same as -1, i.e. to wait indefinitely.
The limit is given by:
#define EP_MAX_MSTIMEO min(1000ULL * MAX_SCHEDULE_TIMEOUT / HZ, \
(LONG_MAX - 999ULL) / HZ)
That is, the limit depends on the size of a long and the timer
frequency. Assuming the a long is never smaller than 32 bits
and HZ never larger than 1000, the worst case is 35 minutes.
I think this should be mentioned under "BUGS".
Although this is likely to be fixed in the future
(http://lkml.org/lkml/2010/8/8/144), the problem exists in
at least 2.6.14 - 2.6.35. I don't know if select(2) and poll(2)
are affected.
https://bugzilla.kernel.org/show_bug.cgi?id=20762
Reported-by: Fredrik Arnerup <arnerup@kth.se>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Rasmus:
Both my system's man-pages (3.22) and the latest online
(3.41) show:
int mprotect(const void *addr, size_t len, int prot);
as the prototype for mprotect(2). However, POSIX [1] and the
actual sys/mman.h (on all the systems I checked) do not have
the const qualifier on the first argument.
Reported-by: Rasmus Villemoes <Rasmus.Villemoes@decode.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The syntax .UR http://example.com paired with .UE will create
links which one can interact, if the pager allows that. One
way to see the effect is ask the man(1) command to use browser
display, e.g.:
man -H man7/uri.7
("\:" is optional groff syntax to permit hyphenless line breaks.)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I didn't like ithe "SIGKILL operates similarly, with exceptions"
phrase (if it's different, then it's not "similar", right?),
and now I got around to changing it. Now it says simply:
"SIGKILL does not generate signal-delivery-stop and therefore
the tracer can't suppress it."
Replaced "why WNOHANG is not reliable" example with a more
realistic one (the one which actually inspired to add this
information to man page in the first place): we got
ESRCH - process is gone! - but waitpid(WNOHANG) can still
confusingly return 0 "no processes to wait for".
Replaced "This means that unneeded trailing arguments may
be omitted" part with a much better recommendation
to never do that and to supply zero arguments instead.
(The part about "undocumentedness" of gcc behavior was bogus,
btw - deleted).
Expanded BUGS section with the explanation and an example
of visible strace behavior on the buggy syscalls which
exit with EINTR on ptrace attach. I hope this will lead
to people submitting better bug reports to lkml about
such syscalls.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For IOPRIO_WHO_PROCESS, who==0 means operate on the caller.
For IOPRIO_WHO_PGRP, who==0 means operate on the caller's
process group.
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
Reported-by: Марк Коренберг <socketpair@gmail.com>
Reported-by: Kalle Olavi Niemitalo <kon@iki.fi>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Mainly rewording things like "is delivered" to "becomes pending",
which is more accurate terminology.
Reported-by: Daniel Zingaro <daniel.zingaro@utoronto.ca>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This system call was never visible to user space, so it makes
sense to move it out of the main table of system calls into
the notes below the table.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reduce the chance that the reader may be misled into thinking
that there is a wrapper function for this system call by noting
explicitly in the SYNOPSIS that there is no glibc wrapper and
pointing the reader to NOTES for further details.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
And add another example of using syscall() to the program example.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
syscall.2: fix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove links >= 5 years old that were created after historical
moves of pages to new sections.
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add text to NOTES to say that the <sys/types.h> and <sys/ipc.h>
header files aren't required by Linux or the standards, but may
be needed for portability to old systems.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There's no need to mention that the 'ipc_perm' structure
is defined in <sys/ipc.h>. That's an implementation detail,
and furthermore <sys/ipc.h> is itself included by the other
System V IPC header files. The current text might lead the
reader to conclude that they must include <sys/ipc.h>, which
is not the case (it is required neither on Linux, nor by the
standards).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rework 04cd7f64, which didn't capture the details correctly.
See the April/May 2012 linux-man@ mail thread "[PATCH]
Describe race of direct read and fork for unaligned buffers"
http://thread.gmane.org/gmane.linux.kernel.mm/77571
Acked-by: KOSAKI Motohiro <kosaki.motohiro@jp.fujitsu.com>
Cowritten-by: Jan Kara <jack@suse.cz>
Cowritten-by: Hugh Dickins <hughd@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From "groff -ww ..." (or "man --warnings=w ..."):
warning: around line 157: table wider than line width
Have to use text blocks. Move some text to its correct column.
Split text to two columns to avoid hyphenation.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
From "groff -ww" (or "man --warnings=w ..."):
warning: around line 442: table wider than line width
GNU man uses line length of 78.
Use text blocks. Two spaces between sentences or better: start
each sentence in a new line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Clarify that glibc (as well as old libc) provides emulation
using select(2) on older kernels that don't have a poll()
system call.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' interval will be rounded up to the
system clock granularity, and may overrun because of kernel
scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' interval will be rounded up to the
system clock granularity, and may overrun because of kernel
scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' is a minimum interval; the actual
interval will be rounded up to the system clock granularity,
and may overrun because of kernel scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' is a minimum interval; the actual
interval will be rounded up to the system clock granularity,
and may overrun because of kernel scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' is a minimum interval; the actual
interval will be rounded up to the system clock granularity,
and may overrun because of kernel scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that 'timeout' is a minimum interval; the actual
interval will be rounded up to the system clock granularity,
and may overrun because of kernel scheduling delays.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it clear that this clock may be discontinuous, and is
affected my incremental NTP and clock-adjtime(2) adjustments.
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=540872
Reported-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Note interactions of these two clocks with discontinuous
adjustments to the system time and NTP/adjtime(2).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add some basic documentation of these operations, with a pointer to
tools/perf/design.txt for more information.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
SPARC reverses the use of 'addr' and 'data' for
PTRACE_GETREGS, PTRACE_GETFPREGS, PTRACE_SETREGS,
and PTRACE_SETFPREGS.
Reported-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The corresponding kernel change from Marchel Holtmann was
The attached patch fixes a flaw in the "parent process
death signal" when executing SUID binaries. An
unprivileged user may send arbitrary signal to a child
process even if it is running with higher privileges.
The idea to fix this issue is to reset pdeath_signal not
only on fork, but also on the execution of a SUID binary.
Reported-by: Marcel Holtmann <marcel@holtmann.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported in https://bugzilla.redhat.com/show_bug.cgi?id=680214
the descriptions of ENOSYS and EOPNOTSUP are not corrected
Reported-by: John Sullivan <jsrhbz@kanargh.force9.co.uk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
It seems sendto() can return EACCES for UDP as well; the current
man page in git only says it can return EACCES for Unix sockets.
I was able to make sendto() return EACCES if I try to send from
192.168.1.1/24 to 192.168.1.0. I think the relevant code (in
kernel 2.6.38, but also present in 2.6.7 and 2.6.32, the 2 kernels
we use) is this (net/ipv4/udp.c, udp_sendmsg()):
910 err = -EACCES;
911 if ((rt->rt_flags & RTCF_BROADCAST) &&
912 !sock_flag(sk, SOCK_BROADCAST))
913 goto out;
So I guess if the kernel finds a route to the destination and
it's a broadcast route (and the socket doesn't have the broadcast
flag), then it returns EACCES.
I can verify the behavior with a very simple program (attached).
I've run it on my Ubuntu 10.10 (2.6.35 kernel) and got this:
stefan@spuiu-vml2:~/src/test/broadcast$ ./broadcast_test 10.205.20.94
10.205.20.1
sendto() returned 4
stefan@spuiu-vml2:~/src/test/broadcast$ ./broadcast_test 10.205.20.94
10.205.20.0
sendto() returned negative, errno: 13/Permission denied
(10.205.20.94 is my local IP, of course).
=====
#include <stdio.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <errno.h>
#include <stdlib.h>
int main(int argc, char **argv)
{
int sock;
if (argc < 2) {
printf("Usage: %s local_address destination_address\n", argv[0]);
exit(1);
}
sock = socket(AF_INET, SOCK_DGRAM, 0);
if (sock < 0) {
perror("socket");
return -1;
}
struct sockaddr_in local_addr;
local_addr.sin_family = AF_INET;
local_addr.sin_port = htons(1234);
local_addr.sin_addr.s_addr = inet_addr(argv[1]);
int ret = bind(sock, (struct sockaddr *) &local_addr, sizeof(local_addr));
if (ret < 0) {
perror("bind");
return -1;
}
struct sockaddr_in remote_addr;
remote_addr.sin_family = AF_INET;
remote_addr.sin_port = htons(1234);
remote_addr.sin_addr.s_addr = inet_addr(argv[2]);
ret = sendto(sock, "blah", 4, 0, (struct sockaddr *)&remote_addr, sizeof(remote_addr));
if (ret < 0) {
printf("sendto() returned negative, errno: %d/%m\n", errno);
}
else {
printf("sendto() returned %d\n", ret);
}
return 0;
}
=====
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For a long time now, glibc's raise(3) didn't yield SI_USER
for the signal receiver, so remove mention of raise(3)
here. The user can deduce the details, if needed, by looking
at the recently updated raise(3) page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove some FIXMEs and comment out pieces of text that describe
features not yet merged mainline kernel.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
* Wording improvements
* Addition of some FIXMEs for suspicious points
* Addition of various EINVAL cases
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As Simone notes, RETURN VALUE says:
On error, (clock_t) -1 is returned, and errno is set appropriately
but no value for errno is specified. The only error case is
EFAULT, so let's add that.
Reported-by: Simone Piccardi <piccardi@truelite.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The wrapper function has a 'flags' argument (which currently
serves no purpose), while the underlying system call does not.
Reported-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Here's a patch to the fcntl.2 manpage that explains
the working of F_GETLEASE in a bit more detail during
lease breaks. Basically, what happens is this: When a
lease break is initiated by a lease breaker, subsequent
F_GETLEASE calls return the target lease type after
the lease break and not the existing lease type. This
behavior persists until the lease holder downgrades/unlocks
the lease or the kernel forcibly does it after the lease
break timeout expires.
The implicit assumption is that F_GETLEASE should
return the existing lock type until the downgrade/unlock
has actually taken place, which is not true. I've verified
that the kernel indeed returns the target lease type. It
is also simple enough to verify this behavior in a small
program, where you can observe that the lease type
returned by F_GETLEASE in the signal handler for a
lease break is different from the existing lease type.
Signed-off-by: Abhijith Das <adas@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Various fcntl(2) commands require an integral 'arg'.
The man page said it must be "long" in all such cases.
However, for the cases covered by POSIX, there is an
explicit requirement that these arguments be "int".
Update the man page to reflect. Probably, all of the
other "long" cases (not specified in POSIX) should
be "int", and this patch makes them so. Based on a
note fromEric Blake, relating to F_DUPFD_CLOEXEC.
Reported-by: Eric Blake <ebb9@byu.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For some reason, the PTRACE_TRACEME paragraph talks about some
general aspects of ptraced process behavior. It repeats the
"tracee stops on every signal" information even though that was
already explained just a few paragraphs before. Then it describes
legacy SIGTRAP on execve().
This patch deletes the first part, and moves the second part up,
into the general ptrace description. It also adds
"If PTRACE_O_TRACEEXEC option is not in effect" to the description
of the legacy SIGTRAP on execve().
The patch also amends the part which says "For requests other
than PTRACE_KILL, the tracee must be stopped." - PTRACE_ATTACH
also doesn't require that.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The unimplemented system calls are in any case noted lower down
in the page. Also: rearrange the text describing the unimplemented
system calls.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
syscalls.2: fix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk