sock_diag.7: ffix: white space tweaks in example program

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

sock_diag.7: srcfix: rewrap long lines

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

netlink.7: Rework position of NETLINK_SOCK_DIAG in list

Essentially to fix a formatting issue, where the list head
item wrapped past the 80-column limit when rendered.

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

netlink.7: Add references to sock_diag(7)

Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

netlink.7: Document NETLINK_INET_DIAG rename to NETLINK_SOCK_DIAG

Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface

Co-authored-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Pavel Emelyanov <xemul@virtuozzo.com>
Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

netlink.7: ffix

Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

close.2: Note that future POSIX plans to require that the FD is closed on error

See http://austingroupbugs.net/view.php?id=529#c1200.

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

close.2: Further reworking of discussion of error return from close()

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

close.2: srcfix: FIXME

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

close.2: Further clarify how to treat an error return

Further clarify that an error return should be used only
for diagnostic or remedial purposes.

Lifting Linus's words freely from
http://lkml.iu.edu/hypermail/linux/kernel/0207.2/0409.html
Re: close return value (was Re: [ANNOUNCE] Ext3 vs Reiserfs benchmarks)
Date: Wed Jul 17 2002 - 12:43:57 EST

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

close.2: Other UNIX implementations also close the FD, even if reporting an error

Looking at some historical source code (mostly from [1]) suggests
that the "close() always closes regardless of error return"
behavior has a long history, predating even POSIX.1-1990.

For example, in SVR4 for x86 (from the file sysvr4.tar.bz2 at
[1]), we see the following:

        int
        close(uap, rvp)
                register struct closea *uap;
                rval_t *rvp;
        {
                file_t *fp;
                register int error;

                if (error = getf(uap->fdes, &fp))
                        return error;
                error = closef(fp);
                setf(uap->fdes, NULLFP);
                return error;
        }

In the above, getf() can return EBADF. The other errors are
returned by closef(), but the file descriptor is deallocated
regardless of errors by setf().

A similar pattern seems to have been preserved into at least late
OpenSolaris days (verified from looking at the initial commit of
the illumos source code). There we find the following in
closeandsetf() (called by close()):

        error = closef(fp);

        setf(fd, newfp);

        return (error);

Looking at the code of closef() in AIX 4.1.3 suggests that, as on
on Linux and FreeBSD, the open file is always released, regardless
of errors.

For Irix, 6.5.5, I'm not sure (the code is not so easy to quickly
read); it may be that it does return errors while leaving the FD
open.

[1] https://archive.org/download/various_operating_system_source_code

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

close.2: Minor text reworking

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

close.2: ffix

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

close.2: Minor text relocation

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

close.2: Clarify the variation in EINTR behavior per POSIX and other systems

See also https://news.ycombinator.com/item?id=3363819
and http://www.daemonology.net/blog/2011-12-17-POSIX-close-is-broken.html

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

close.2: wfix

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

close.2: Rework initial paragraph in NOTES on checking close() errors

As Daniel Wagner noted, saying on the one hand that failing
to check the return value of close() is a "serious error"
seems contradicted by the next paragraph that notes that
the return value should be used for "just diagnostics".
Rework the text to resolve the apparent contradiction.

Reported-by: Daniel Wagner <wagi@monom.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

close.2: wfix

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

resolv.conf.5: Timeout does not map to resolver API calls

I'm posting this patch to clarify the timeout behaviour because
there have been developers who expect this timeout to mean
something it is not.

The timeout (and by proxy attempts) does not map to resolver API
calls.  For example a single call to getent might involve multiple
resolution requests to the resolvers listed in resolv.conf and
each request will use TIMEOUT and be attempted at least ATTEMPT
times. A developer using the resolver API cannot easily compute
any given timeout because the implementation may change e.g. A and
AAAA queries made in parallel.  A system administrator uses this
setting to ensure there is a desirable timeout on any request to
any of the nameservers listed in resolv.conf, but no guarantees
exist beyond that.

Reviewed-by: Florian Weimer <fweimer@redhat.com>
Signed-off-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mmap.2: srcfix: FIXME

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

strerror.3: srcfix: FIXME

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

open.2: srcfix: FIXME

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

ptsname.3: Note that ptsname_r() is proposed for future inclusion in POSIX.1

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

ptsname.3: CONFORMING TO:: clarify that only ptsname() is standardized (so far)

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

close.2: Further clarify that close() should not be retried after an error

See Linus ancient comments re EINTR in
    https://lkml.org/lkml/headers/2005/9/10/129
    Date Sat, 10 Sep 2005 12:00:01 -0700 (PDT)
    From Linus Torvalds <>
    Subject Re: [patch 7/7] uml: retry host close() on EINTR

The FreeBSD 11.0 close() man page says similar:

    In case of any error except EBADF, the supplied file
    descriptor is deallocated and therefore is no longer valid.

For AIX:
http://publib16.boulder.ibm.com/doc_link/en_US/a_doc_lib/libs/basetrf1/close.htm

    If the FileDescriptor parameter refers to a device and the
    close subroutine actually results in a device close, and the
    device close routine returns an error, the error is returned
    to the application. However, the FileDescriptor parameter is
    considered closed and it may not be used in any subsequent
    calls.

See also:
http://austingroupbugs.net/view.php?id=529
and in particular:
http://austingroupbugs.net/view.php?id=529#c1200

Reported-by: Daniel Wagner <wagi@monom.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

symlink.7: SEE ALSO: add namei(1)

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

credentials.7: SEE ALSO: add shadow(5)

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

nice.2: Move discussion of handling the -1 success return to RETURN VALUE

This detail was rather hidden in NOTES. Also, rework the text
a little.

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

nice.2: CONFORMING TO: Remove an ancient SVr4 detail on errno values

At this stage, vague details (when does EINVAL get returned?) of
ancient implementations are little more than noise in the page.

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

nice.2: Rework discussion of nice() return value and standards conformance

Make the text a little clearer. In particular, clarify that the
raw system call (still) returns 0 on success.

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

nice.2: Add mention of RLIMIT_NICE

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

signal.7: tfix

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

getrlimit.2: Refer to sched(7) in discussion of RLIMIT_RTPRIO and RLIMIT_RTTIME

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

getrlimit.2: SEE ALSO: add credentials(7)

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

getrlimit.2: refer to sched(7) in the discussion of RLIMIT_NICE

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

getrlimit.2: Minor wording fix for RLIMIT_NICE

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

getrlimit.2: Describe the range of the RLIMIT_NICE limit

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

setsid.2: SEE ALSO: add sched(7)

List sched(7), because setsid(2) is part of the machinery
of autogrouping.

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

bpf.2: tfix

Changed to "will" instead of "with".

Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

nice.2: Warn that autogrouping voids the effect of 'nice' in many cases

Refer the reader to sched(7) for the details.

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

getpriority.2: Warn that autogrouping voids the effect of 'nice' in many cases

Refer the reader to sched(7) for the details.

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

sched.7: Clarify that autogroup defaults on in various distros

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

sched.7: Note command that can be used to modify the autogroup nice value

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

sched.7: Improve section on nice value and group scheduling

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

sched.7: Relocate discussion of group scheduling

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

sched.7: Clarify details of autogroup nice value

Also clarify its interactions with the thread nice value.

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

sched.7: srcfix: tfix

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

sched.7: Further clarify scheduling policies for which autogroup applied

Further clarify that autogroup groups only SCHED_OTHER/SCHED_NICE/
SCHED_IDLE processes.

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

sched.7: Add a subsection on group scheduling

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

sched.7: Tweak description of cgroups overriding autogroup

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

sched.7: tfix

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

sched.7: Note error that occurs when writing invalid value to /proc/PID/autogroup

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

sched.7: Further clarify details of group scheduling

After comments by Mike Galbraith.

Reported-by: Mike Galbraith <efault@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched.7: wfix

Reported-by: Afzal Mohammed <afzal.mohd.ma@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched.7: srcfix: add details to FIXME

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

sched.7: Rework discussion of autogroups

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

sched.7: Rework discussion of autogroup nice value

Remove the text saying that setting the autogroup nice value
always lowers the group's priority. That was actually a
bug introduced in Linux 4.7.

Also make it clearer that the autogroup nice value has the same
meaning as the nice value set by setpriority(2).

Reported-by: Mike Galbraith <efault@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

proc.5: Add pointers to sched(7) for autogroup files

sched(7) describes /proc/sys/kernel/sched_autogroup_enabled
and /proc/PID/autogroup.

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

sched.7: Document the autogroup feature

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

getpriority.2: The nice value supplied to setpriority() is clamped

Note that the nice value supplied to setpriority() is clamped
to the permitted range.

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

namespaces.7: srcfix

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

sched.7: Minor wording fix

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

elf.5: Minor fixes

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

elf.5: Minor fixes

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

elf(5): Further details on Notes

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

sched.7: Minor rewording of discussion of nice value

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

sched.7: Add nice(2), getpriority(2), and setpriority(2) to API list

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

nice.2: Clarify that nice() changes the nice value of the calling *thread*

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

getpriority.2: Expand discussion of getpriority() return value

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

getpriority.2: Improve description of setpriority() return value

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

sched.7: Minor text reorganization

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

sched.7: wfix

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

sched.7: Add a new introductory paragraph describing the nice value

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

random.7: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>

ptrace.2: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>

getrlimit.2: ffix

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

sched.7: Mention RLIMIT_NICE in the discussion of the nice value

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

sched_setattr.2: Fix cross reference for further info on the nice value

The information moved from getpriority(2) to sched(7).

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

nice.2: add reference to sched(7) for further details on the nice value

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

sched.7: Add more precise details on CFS's treatment of the nice value

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

getpriority.2, sched.7: Move nice value details from getpriority(2) to sched(7)

Centralizing these details in sched(7) is more logical.

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

getpriority.2: Minor wording change

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

getpriority.2: Minor wording fix

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

nice.2: Add "C library/kernel differences" subsection heading

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

nice.2: Clarify the range of the nice value, and note that it is clamped

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

getpriority.2: The nice value supplied to setpriority() is clamped

Note that the nice value supplied to setpriority() is clamped
to the permitted range.

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

sched.7: ffix

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

sched.7: Make it clearer that SCHED_OTHER is always scheduled below real-time

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

sched.7: Add introductory sentence mentioning CFS scheduler

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

sched.7: Minor wording improvement in text introducing system calls

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

sched.7: Remove mention of individual kernel developer names

It's not the norm to name developers of particular features
in each man page.  No need for an exception here.

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

sched.7: Minor wording fix

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

sched.7: wfix

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

cgroups.7: Add details on 'cpu' CFS bandwidth control

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

elf.5: wfix

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

elf.5: srcfix: rewrap some long source lines

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

elf.5: A few tweaks to Mike Frysinger's text (Mike to check)

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

elf.5: Minor fixes to Mike Frysinger's patch

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

elf(5): document notes

Document the Elf{32,64}_Nhdr structure, the sections/segments that
contain notes, and how to interpret them.  I've been lazy and only
included the GNU extensions here, especially as others are not
defined in the elf.h header file as shipped by glibc.

I've mostly used binutils, glibc, breakpad, and the GABI ELF spec
as sources of data for these fields.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>