getdents.2, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, pthread_setaffinity_np.3, pthread_setschedparam.3, pthread_tryjoin_np.3: Use consistent error-handling function names

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>

pthread_tryjoin_np.3: minor: tidy up example code segment

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthreads.7: Tweak text on sigpause() cancellation point

In POSIX.1-2009, this function moves from the "must be"
to the "may be" list.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setinheritsched.3: New page for pthread_attr_setinheritsched(3) and pthread_attr_getinheritsched(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

bindresvport.3: Since glibc 2.8, EPFNOSUPPORT error is now EAFNOSUPPORT

Glibc switched to using a POSIX-specified error code for
this error case.

http://bugs.linuxbase.org/show_bug.cgi?id=2375

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Acked-by: Stew Benedict <stewb@linux-foundation.org>

pthreads.7: Add section on cancellation points

This section includes a list of the functions that must and
may be cancellation points.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

fsync.2: Update feature test macro requirements for fsync()

Since glibc 2.8, the fsync() declaration is also exposed if
_POSIX_C_SOURCE >= 200112L

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

clone.2: srcfix: added comment about CLONE_STOPPED going away in glibc 2.8

makecontext.3: grfix

makecontext.3: Add text on use of pointer arguments to makecontext()

Passing pointer arguments to makecontext() is possible,
but only on some architectures, and with no guarantees
of portability.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504699

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Paul Evans <leonerd@leonerd.org.uk>

getpwnam.3: Add an EXAMPLE program for getpwnam_r()

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getgrnam.3: Rename arguments to getgrnam_r() and getgrgid_r()

s/gbuf/grp/ and s/gbufp/result/, for consistency
with POSIX.1 argument names.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getpwnam.3: Rename arguments to getpwnam_r() and getpwuid_r()

s/pwbuf/pwd/ and s/pwbufp/result/, for consistency
with POSIX.1 argument names.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getgrnam.3: Clarify and add more detail in RETURN VALUE description

The page was a bit fuzzy in describing the return values for
various cases.  In particular, it needed to be more explicit
in describing what happens for the "not found" case.

This is an analogous change to the previous change for
getpwnam.3, made after Andreas Henriksson's report.
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getpwnam.3: Clarify and add more detail in RETURN VALUE description

The page was a bit fuzzy in describing the return values for
various cases.  In particular, it needed to be more explicit
in describing what happens for the "not found" case.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504787

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Andreas Henriksson <andreas@fatal.se>

getgrnam.3: Clarify RETURN VALUE description

The page was a bit fuzzy in describing the return values for
various cases.  In particular, it needed to be more explicit
in describing what happens for the "not found" case.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Andreas Henriksson <andreas@fatal.se>

clock_getres.3: wfix

clock_getres.3: srcfix: Added FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Start of man-pages-3.14: updating Changes and Changes.old

Start of man-pages-3.14: updating .Announce and .lsm files

Start of man-pages-3.14: renaming .Announce and .lsm files

Ready for 3.13

Expanded tabs

pthread_attr_getaffinity_np.3: Fix circular self-link reference

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_getattr_np.3, pthread_tryjoin_np.3: tstamp

Changes: Update changelog for 3.13 release

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setschedparam.3: tfix

pthread_attr_setschedparam.3: tfix

pthread_attr_setschedpolicy.3: minor: s/policy/*policy/ in SYNOPSIS

pthread_attr_setschedpolicy.3: ffix

clock_getres.3: CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID not settable

According to POSIX.1-2001, the CLOCK_PROCESS_CPUTIME_ID and
CLOCK_THREAD_CPUTIME_ID clocks should be settable, but
currently they are not.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setschedprio.3: New page for pthread_setschedprio(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched_setscheduler.2: tfix

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>

pthread_setschedparam.3: Rework text pointing to information on required permissions

Rework the text that refers to sched_setscheduler(2) for
a description of the permissions required to change
the scheduling policy and priority.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setschedparam.3: SEE ALSO: add getrlimit(2)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setschedpolicy.3: Add pointer to EXAMPLE in pthread_setschedparam(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setschedparam.3: Add pointer to EXAMPLE in pthread_setschedparam(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_getschedparam.3: New link to new pthread_setschedparam.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setschedparam.3: New page for pthread_setschedparam(3) and pthread_getschedparam(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_create.3, pthread_getattr_np.3: ffix: s/'/\\(aq/

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setschedpolicy.3: srcfix: Added FIXME

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setaffinity_np.3: SEE ALSO: add pthread_self(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

resolver.3: Fix prototype of dn_expand()

The 4th argument is "char *", not "unsigned char *".
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504708

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Török Edwin <edwintorok@gmail.com>

pthreads.7: spfix

pthreads.7: Add a section describing thread IDs

In particular, note that in each pthreads function that takes
a thread ID argument, that ID by definition refers to a thread
in the same process as the caller.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched_setaffinity.2: SEE ALSO: add sched_getcpu(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setaffinity_np.3: SEE ALSO: add sched_getcpu(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_getschedparam.3: New link to new pthread_attr_setschedparam.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setschedparam.3: New page for pthread_attr_setschedparam(3) and pthread_attr_getschedparam(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_getschedpolicy.3: New link to new pthread_attr_setschedpolicy.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setschedpolicy.3: New page for pthread_attr_setschedpolicy(3) and pthread_attr_getschedpolicy(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setstacksize.3: EINVAL occurs on some systems if stacksize != page-size

On MacOS X at least, pthread_attr_setstacksize(3) can fail
with EINVAL if 'stacksize' is not a multiple of the system
page size.  Best to mention this so as to aid people writing
portable programs.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Karsten Weiss <knweiss@gmail.com>
==
From: Karsten Weiss <knweiss@gmail.com>
Date: Fri, Oct 31, 2008 at 3:46 PM
Subject: pthread_create(3) - example bug + problems

[...]
A look in the pthread_set_stacksize man page on Mac revealed that on
Mac the stack size must not only be at least PTHREAD_STACK_MIN...
[...]
...but the new stack size must also be a multiple of the system page
size!

From pthread_attr_setstacksize(3):

    pthread_attr_setstacksize() will fail if:

    [EINVAL]           Invalid value for attr.
    [EINVAL]           stacksize is less than PTHREAD_STACK_MIN.
!!!  [EINVAL]           stacksize is not a multiple of the system page size.

See for yourself (PTHREAD_STACK_MIN==8192 on Mac OS X):

$ ./pthread_test -s $((8192*10-1)) a
pthread_attr_setstacksize: Invalid argument
$ ./pthread_test -s $((8192*10)) a
Thread 1: top of stack near 0xb0014f6c; argv_string=a
Joined with thread 1; returned value was A
$ ./pthread_test -s $((8192*10+1)) a
pthread_attr_setstacksize: Invalid argument

pthread_create.3: Fix bug in EXAMPLE program

The bug is in this part of the code:

    /* Allocate memory for pthread_create() arguments */

    tinfo = calloc(num_threads, num_threads);
    if (tinfo == NULL)
       errExit("calloc");

The calloc() line should read like this instead:

    tinfo = calloc(num_threads, sizeof(struct thread_info));

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setaffinity_np.3, pthread_getattr_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3: Explain _np suffix

Add text to CONFORMING TO explaining that the "_np"
suffix is because these functions are non-portable.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Karsten Weiss <K.Weiss@science-computing.de>

pthread_attr_setaffinity_np.3: Remove EFAULT, add new EINVAL error

EFAULT can't occur for these functions.  EINVAL can occur
for invalid 'attr' or 'cpuset' arguments.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_getaffinity_np.3: New link to new pthread_attr_setaffinity_np.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_setaffinity_np.3: New page for pthread_attr_setaffinity_np(3) and pthread_attr_getaffinity_np(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setaffinity_np.3: tfix

pthread_setaffinity_np.3: minor: fix function names in EXAMPLE diagnostic messages

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setaffinity_np.3: minor: Clean up SEE ALSO list

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_getaffinity_np.3: New link to new pthread_setaffinity_np.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_setaffinity_np.3: New page for pthread_setaffinity_np(3) and pthread_getaffinity_np(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getaddrinfo.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5: srcfix

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>

sched_setaffinity.3: minor: rework EPERM text

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched_setaffinity.2: Clarify EINVAL error for cpusetsize < kernel mask size

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>

sched_setaffinity.2: SEE ALSO: Add pthread_setaffinity_np(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched_setaffinity.2: wfix

readlink.2: srcfix: Note that bufsiz has a signed type at kernel level

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.

epoll.7: Add error handling for epoll_wait() call in example code

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

epoll.7: Fix error handling after accept() in example code

Simply continuing after an error is in most cases wrong,
and can lead to infinite loops (e.g., for EMFILE).
So handle an error by terminating.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Olaf van der Spek <olafvdspek@gmail.com>

pipe.2: wfix: SYNPOSIS: add missing word "int"

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

eventfd.2, mprotect.2, signalfd.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_tryjoin_np.3: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: tfix: in CONFORMING TO: s/POSIX.1-2001/POSIX.1-2008/

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

epoll.7: Improve example code

Fill in some gaps in example code (variable declarations,
adding listening socket to epoll set).
Give variables more meaningful names.
Other minor changes.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=504202

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Olaf van der Spek <OlafvdSpek@gmail.com>

dup.2: wfix

umount.2: srcfix: remove out-of-date FIXME

iso_8859-7.7: Add characters for Drachma and Greek Ypogegrammeni

Lines for these two characters were added in the previous patch,
but the actual characters were not included in the 4th column
of the table.  This fixes that.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_exit.3: BUGS: thread group with a dead leader and stop signals

Document the bug that can occur when a stop signal
is sent to a thread group whose leader has terminated.
http://thread.gmane.org/gmane.linux.kernel/611611
http://marc.info/?l=linux-kernel&m=122525468300823&w=2

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: Bert Wesarg <bert.wesarg@googlemail.com>

syscalls.2: srcfix: add FIXME

Changes.old: wspfix

Changes.old: Add Contributors to 3.12 Changelog

I forgot to do this before the 3.12 release.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

vfork.2: Child holds parent's memory until execve() or *termination*

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

Changes.old: Reformat 3.11 Changelog entries

To be consistent with format used in 3.12 changelog (and beyond)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Start of man-pages-3.13: updating Changes and Changes.old

Start of man-pages-3.13: updating .Announce and .lsm files

Start of man-pages-3.13: renaming .Announce and .lsm files

Ready for 3.12

Removed trailing white space at end of lines

Expanded tabs

timerfd_create.2, ctime.3, frexp.3, strftime.3, strtok.3, tty_ioctl.4, iso_8859-7.7: tstamp

Changes: Update Changelog for 3.12 release

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: srcfix: add comments re NFS and O_APPEND

readdir.3: Fix text relating to DT_UNKNOWN and 'd_type' support

(This mirrors the previous change to getdents.2)
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>

getdents.2: Fix text relating to DT_UNKNOWN and 'd_type' support

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>

vfork.2: grfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

vfork.2: minor: Clarify that standards text is current (not a draft).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

vfork.2: grfix

vfork.2: Clarify meaning of "child releases the parent's memory"

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>

getaddrinfo.3: Clarify error descriptions with some examples

Clarify the description of some errors by giving examples
that produce the errors.  (Text added for EAI_SERVICE and
EAI_SOCKTYPE.)

Also, add an error case for EAI_BADFLAGS.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Reported-by: J.H.M. Dassen (Ray) <fsmla@xinara.org>