For a non-blocking socket, POSIX.1-2001/2008 allow either
EAGAIN or EWOULDBLOCK to be returned in cases where a call
would have blocked. Although these constants are defined
with the same value on most Linux architectures (PA-RISC
is the exception), POSIX.1 does not require them to have
the same value. Therefore, a portable application using
the sockets API should test for both errors when checking
this case.
(NB POSIX.1 only mentions EWOULDBLOCK in the context of
the sockets interfaces.)
Change made after a note cross-posted on linux-arch@vger,
http://thread.gmane.org/gmane.linux.debian.ports.hppa/5615
and a suggestion for write(2) from Carlos O'Donell
Reported-by: Carlos O'Donell <carlos@systemhalted.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In the kernel, the error on encountering a mandatory lock is
EAGAIN. Although EAGAIN and EWOULDBLOCK are the same on
most Linux architectures, on some they are not, so don't
mention EWOULDBLOCK as it is misleading. (Mea culpa.)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Target file cannot be opened in append (O_APPEND) mode
In kernels prior to v2.6.27 splice() to a file in append mode is broken,
and since that version it is disallowed. It is possible this behaviour
may change in the future; see the kernel commit message
(efc968d450e013049a662d22727cf132618dcb2f) for more information.
Signed-off-by: Mark Hills <mark@pogo.org.uk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In SEE ALSO, when a few man pages are referenced, those are divided by commas.
Every reference is on a separate line, and all lines but the last one should
end with comma. I spotted one place where there is no comma in between
references, and mocked up an awk script to find similar places:
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 | fgrep 'Missing comma'
This patch fixes all the places found by the above script.
Also, there is an extra dot at the end of uri.7 "SEE ALSO" section.
Removed as per man-pages(7) recommendation.
Signed-off-by: Kir Kolyshkin <kir@openvz.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The POSIX timers API is implemented (mostly) within the kernel,
so thse interfaces are system calls. Although there are as yet
no man pages, when they are added they should be in Section 2,
not 3. Therefore fix those pages that currently refer to these
interfaces as being in Section 3.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
While writing a little program using capset
I found the capset manpage quite light on crucial
details and I had to resort to RTFS.
This patch improves the points I found unclear
and also moves one misplaced paragraph around.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Sebastien pointed out that the first example program
wrongly thinks it can count signals.
Also, some further rewrites by mtk.
Reported-by: Sebastian Kienzl <seb@riot.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since d_type will always just return DT_UNKNOWN before
kernel 2.6.4, we don't need to use a conditional for
determining whether we use this flag.
Reported-by: Bastien ROUCARIES <roucaries.bastien@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This error is encountered when the limit imposed by
/proc/sys/fs/epoll/max_user_instances is encountered.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This error results when the limit imposed by
/proc/sys/fs/epoll/max_user_watches is encountered.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Introduce notion of epoll instance as distinct from epoll file descriptor.
Plus other wording clean-ups.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reword so that the notion of an epoll instance is made clear,
and made distinct from the notion of an epoll file descriptor.
Some other minor rewordings also.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The page text described the semantics of the initial
implementation of signalfd(). These were changed early on,
but the man page wasn't updated.
Reported-by: Vegard Nossum <vegard.nossum@gmail.com>
Reviewed-by: Davide Libenzi <davidel@xmailserver.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The interfaces documented in this page are purely glibc.
Reported-by: Colin Watson <cjwatson@ubuntu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
When a 32-bit app opens a file whose size is too big to be
represented in 31-bits, POSIX.1 specifies the error EOVERFLOW.
Linux used to give EFBIG for this case, but 2.6.24 fixed this.
Also, add some text to describe the error scenario in
more detail.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Some errors were listed under a separate "may" heading.
There's probably no real need to do this; integrate
those errors into the main list.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Most other sockets pages are using the names 'addr'
and 'addrlen'; make these pages do the same.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
If the recvfrom() returned address is truncated, the 'fromlen'
argument indicates the actual size of the address, rather than
a count of the number of bytes in the truncated buffer.
Also clarify that the 'from' argument can be NULL, in which
case 'fromlen' should is unused, and should also be NULL.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
If the returned address is truncated, the 'addrlen' argument
indicates the actual size of the address, rather than a count
of the number of bytes in the truncated buffer.
Also clarify that if 'addr' argument is NULL, then 'addrlen'
should is unused, and should also be NULL.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Many sockets man pages use the name 'sockfd' already.
For consistency, changes the others to do so as well.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Mel Gorman reported that in Linux 2.6.27, 'addr' is rounded
down to a page boundary.
Before kernel 2.6.26, if 'addr' was taken as a hint, it was
rounded up to the next page boundary. Since Linux 2.6.24,
it is rounded down. Therefore, loosen the description of
this point to say that the address is rounded to "a nearby
page boundary".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Mel Gorman <mel@csn.ul.ie>
Internet datagram (since Linux 2.4.27/2.6.8),
and netlink (since Linux 2.6.22) sockets support
the MSG_TRUNC flag for recv(2).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Expand description of setdomainname() and getdomainname().
Note that getdomainname() is implemented as a library function
in glibc.
Note limits on size of domain name.
Reorganize ERRORS list.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Write a paragraph describing sethostname().
Clarify differences between glibc's gethostbyname() and
the kernel gethostbyname() system calls.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
If CLONE_NEWUTS is specified, the IDs are initialized
by duplicating from calling process.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reviewed-by: Serge E. Hallyn <serge@hallyn.com>
Many pages still mention use of the obsolete sysctl(2) system
call, or used the term "sysctls"; rewrite these mentions to
instead be in terms of /proc interfaces.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This was already stated under NOTES, but make it even more
prominent by adding a sentence at the start of the DESCRIPTION.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
When the last process in an IPC namespace is destroyed, the
IPC objects in that namespace are automatically destroyed.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Cedric Le Goater <clg@fr.ibm.com>
This is more consistent with the term "mounts namespace"
used in the 2008 ACM SIGOPS paper, "Virtual servers
and and checkpoint/restart in mainstream Linux".
(I avoided the "s", because using the plural strikes me
as klunky English, and anyway we don't talk about
the "PIDs namespace" or the "networks namespace", etc..)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
In recent times, a number of other namespace flags have been
added to clone(2). As such, it is no longer clear to use
the generic term "namespace" to refer to the particular
namespace controlled by CLONE_NEWNS; instead, use the
term "mount-point namespace".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I submitted a patch to fix this. See the LKML thread
"[patch] Fix type errors in inotify interfaces", 18 Nov 2008
If/when these patches are accepted, the pages need to be updated.
After Loic Domaigne's suggestion for pthread_setaffinity_np(3), add
similar text to this page noting that the system silently
limits the set of CPUs on which the process actually runs to
the set of CPUs physically present and the limits imposed by
cpuset(7).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Loic Domaigne <tech@domaigne.com>
Acked-by: Bert Wesarg <bert.wesarg@googlemail.com>
pthread_setaffinity_np() is preferable for setting
thread CPU affinity if using the POSIX threads API.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Many older pages use a handle_error() macro to do simple
error handling from system and library function calls.
Switch these pages to do similar.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
s/2.6.20/2.6.30/ to fix an earlier typo in the description
of the likely kernel version that will have fully fledged
real-time features.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
s/\.R " "/\\\&/ as a way of getting a blank line after a .SS heading.
(Suggested by Sam Varshavchik <mrsam@courier-mta.com>)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
For sched_setaffinity(), the EINVAL error that occurs
if 'cpusetsize' is smaller than the kernel CPU set size only
occurs with kernels before 2.6.9.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
So on a direct syscall, the EINVAL could also occur for bufsiz < 0.
But at the moment, the error text is sufficiently vague
("bufsiz is not positive") that a change to the man page text
is probably not needed.
The page was phrased in a few places to describe the child as
holding the parent's memory until the child does an execve(2)
or an _exit(2). The latter case should really be the more
general process termimation (i.e., either _exit(2) or abnormal
termination).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Valdis.Kletnieks@vt.edu
Some file systems provide partial support for 'dt_type',
returning DT_UNKNOWN for cases they don't support.
Update the discussion of 'd_type' and DT_UNKNOWN to
support this.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The man page was not explicit about how the memory used by
the child is released back to the parent.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Halesh S <halesh.s@india.com>
In some cases, EINVAL can occur if 'optval' is invalid.
Note this, and point reader to an example in ip(7).
In response to:
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=216092
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Christian Grigis <glove@earthling.net>
Add ".SS Program source" to clearly distinguish shell session and
descriptive text from actual program code.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>