pivot_root.2: Minor wording tweaks

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

pivot_root.2: Another couple of s/filesystem/mount/

This is consistent with some earlier changes suggested by
Eric Biederman.

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

pivot_root.2: Tweak text of an EINVAL error to correspond to DESCRIPTION

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

pivot_root.2: Relegate text about what pivot_root() may or may not do to NOTES

The text stating that "pivot_root() may or may not change the
current root and the current working directory of any processes
or threads which use the old root directory" was written 19 years
ago, before the system call itself was even finalized in the
kernel. The implementation has never changed, and it won't
change in the future, since that would cause user-space breakage.
The existence of that text in DESCRIPTION, followed by qualifying
text stating what the implementation actually does (and has always
done) makes for confusing reading. Therefore, relegate this text
to a historical note in NOTES (so that readers with long memories
can see why the manual page was changed) and rework the text in
DESCRIPTION accordingly.

Reported-by: Philipp Wendler <ml@philippwendler.de>
Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Reported-by: Reid Priedhorsky <reidpr@lanl.gov>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Add a subsection header for the pivot_root(".", ".") discussion

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

pivot_root.2: Minor change: relocate a paragraph in NOTES

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

pivot_root.2: s/root filesystem/root mount/

As suggested by Eric Biederman.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Reword one of the restrictions on 'new_root'

A suggested by Eric Biederman

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Change "filesystem" to "mount" in various places

Quoting Eric:

    If we are going to be pedantic "filesystem" is really the
    wrong concept here.  The section about bind mount clarifies
    it, but I wonder if there is a better term.

    I think I would say: "new_root and put_old must not be on
    the same mount as the current root."

    I think using "mount" instead of "filesystem" keeps the
    concepts less confusing.

    As I am reading through this email and seeing text that is
    trying to be precise and clear then hitting the term
    "filesystem" is a bit jarring.  pivot_root doesn't care a
    thing for file systems.  pivot_root only cares about mounts.

    And by a "mount" I mean the thing that you get when you
    create a bind mount or you call mount normally.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Simplify discussion of restrictions for 'new_root'

Philipp Wendler noted that the text on the restrictions for
'new_root' was slightly contradictory, and things could be
clarified and simplified by describing the restrictions on
'new_root' in one place.

Reported-by: Philipp Wendler <ml@philippwendler.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Remove an imprecision in description

Remove the text that suggests that pivot_root() changes the root
directory and CWD of process that have directory and CWD on the
old root *filesystem*. Change "filesystem" to "directory".

Reported-by: Philipp Wendler <ml@philippwendler.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

namespaces.7: Include manual page references in the summary table of namespace types

Make the page more compact by removing the stub subsections that
list the manual pages for the namespace types. And while we're
here, add an explanation of the table columns.

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

mount_namespaces.7: tfix

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

mount_namespaces.7: Tweak discussion of "less privileged" mount namespace

Eric Biederman:

    I hate to nitpick, but I am going to say that when I read
    the text above the phrase "mount namespace of the process
    that created the new mount namespace" feels wrong.

    Either you use unshare(2) and the mount namespace of the
    process that created the mount namespace changes.

    Or you use clone(2) and you could argue it is the new child
    that created the mount namespace.

    Having a different mount namespace at the end of the
    creation operation feels like it makes your phrase confusing
    about what the starting mount namespace is.  I hate to use
    references that are ambiguous when things are changing.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mount_namespaces.7: Explain how a namespace's mount point list is initialized

Provide a more detailed explanation of the initialization of
the mount point list in a new mount namespace.

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

pivot_root.2: srcfix: FIXME

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

pivot_root.2: Remove the term 'old_root'

Reid noted a confusion between 'old_root' (my attempt at a
shorthand for the old root point) and 'put_old. Eliminate the
confusion by replacing the shorthand with "old root mount point".

Reported-by: Reid Priedhorsky <reidpr@lanl.gov>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mount.2: Describe the concept of "parent mounts"

Reported-by: Reid Priedhorsky <reidpr@lanl.gov>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mount.2: tfix

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

mount.2: Rework the text on mount namespaces a little

Eliminate the term "Per-process namespaces" and add a reference
to mount_namespaces(7).

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

mount.2: wfix

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

mount.2: NOTES: add subsection heading for /proc/[pid]/{mounts,mountinfo}

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

mount_namespaces.7: tfix

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

mount_namespaces.7: Clarify description of "less privileged" mount namespaces

The current text talks about "parent mount namespaces", but there
is no such concept. As confirmed by Eric Biederman, what is mean
here is "the mount namespace this mount namespace started as a
copy of". So, this change writes up Eric's description in a more
detailed way.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Simplify pivot_root(".", ".") example

Eric Biederman notes that the change in commit f646ac88ef83969 was
not strictly necessary for this example, since one of the already
documented requirements is that various mount points must not have
shared propagation, or else pivot_root() will fail. So, simplify
the example.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

mount_namespaces.7: It may be desirable to disable propagation after creating a namespace

After creating a new mount namespace, it may be desirable to
disable mount propagation. Give the reader a more explicit
hint about this.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthreads.7: Minor tweaks to Carlos O'Donell's patch

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

pthread_setcancelstate.3, pthreads.7: srcfix: wrap source lines at sentence boundaries

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

pthread_setcancelstate.3, pthreads.7, signal-safety.7: Describe issues with cancellation points in signal handlers

In a recent conversation with Mathieu Desnoyers I was reminded
that we haven't written up anything about how deferred
cancellation and asynchronous signal handlers interact. Mathieu
ran into some of this behaviour and I promised to improve the
documentation in this area to point out the potential pitfall.

Thoughts?

8< --- 8< --- 8<
In pthread_setcancelstate.3, pthreads.7, and signal-safety.7 we
describe that if you have an asynchronous signal nesting over a
deferred cancellation region that any cancellation point in the
signal handler may trigger a cancellation that will behave
as-if it was an asynchronous cancellation. This asynchronous
cancellation may have unexpected effects on the consistency of
the application. Therefore care should be taken with asynchronous
signals and deferred cancellation.

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

perf_event_open.2: SEE ALSO: add Documentation/admin-guide/perf-security.rst

Reported-by: Alexey Budankov <alexey.budankov@linux.intel.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2: Clarify that PR_MCE_KILL_GET returns value via function result

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

prctl.2: wfix (for consistency)

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

prctl.2: RETURN VALUE: add some missing entries

Note success return for PR_GET_SPECULATION_CTRL and PR_GET_FP_MODE.

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

prctl.2: Clarify that PR_GET_SPECULATION_CTRL returns value as function result

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

prctl.2: grfix

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

prctl.2: wfix (for consistency with usage in rest of this page)

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

prctl.2: Clarify that PR_GET_FP_MODE returns value as function result

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

sched_setparam.2, pthread_mutexattr_init.3, pthread_mutexattr_setrobust.3, pthread_mutex_consistent.3, strtol.3, sched.7, uts_namespaces.7: SEE ALSO: correct list order

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

res_nclose.3: Add NEW link to resolver.3

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

veth.4, persistent-keyring.7, process-keyring.7, session-keyring.7, thread-keyring.7, user-keyring.7, user-session-keyring.7: srcfix

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

close.2, execve.2, io_submit.2, prctl.2, write.2: Remove section number from references to function in its own page

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

getlogin.3: grfix

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

copy_file_range.2, fanotify_mark.2, inotify_add_watch.2, ioctl_fideduperange.2, kcmp.2, prctl.2, get_robust_list.2, tkill.2, ttyname.3: ERRORS: correct alphabetical order

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

copy_file_range.2: Kernel v5.3 updates

Update with all the missing errors the syscall can return, the
behaviour the syscall should have w.r.t. to copies within single
files, etc.

[Amir] updates for final released version.

Signed-off-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

epoll_wait.2: tfix

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

strtok.3: Add portability note for strtok_r() '*saveptr' value

On some implementations, '*saveptr' must be NULL on first call
to strtok_r().

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

strtok.3: The caller should not modify 'saveptr' between strtok_r() calls

Reported-by: eponymous alias <eponymousalias@yahoo.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signalfd.2: tfix

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

pivot_root.2: tfix

Remove duplicated words.

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sched_setaffinity.2: RETURN VALUE: sched_getaffinity() syscall differs from the wrapper

In RETURN VALUE, point reader at subsection noting that the return
value of the raw sched_setaffinity() system call differs from the
wrapper function in glibc.

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

getauxval.3: ffix

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

getauxval.3: srcfix: rewrap source lines

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

getauxval.3: Add new cache geometry entries

Add entries for the new cache geometry values of the auxiliary
vector that got included in the kernel.

Signed-off-by: Raphael Moreira Zinsly <rzinsly@linux.vnet.ibm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

open.2: tfix

Reported-by: Дилян Палаузов <dilyan.palauzov@aegee.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signalfd.2: Rewrite the text on epoll semantics

I also verified the behavior reported by Andrew Clayton
with the program below.

$ ./epoll_signalfd
PID of parent: 5661
PID of child:  5662
epoll_wait() returned 0
PID 5662: got signal 10
Successfully read signal, even though epoll_wait() didn't say FD was ready!

8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----
/* epoll_signalfd.c */

#include <sys/signalfd.h>
#include <signal.h>
#include <sys/epoll.h>
#include <sys/wait.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                        } while (0)

static void
signalTest(int sfd, int epfd)
{
    struct signalfd_siginfo fdsi;
    struct epoll_event rev;
    int ready;
    ssize_t s;

    usleep(50000);
    ready = epoll_wait(epfd, &rev, 1, 0);
    if (ready == -1)
        errExit("epoll_wait");

    printf("epoll_wait() returned %d\n", ready);

    s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
    if (s != sizeof(struct signalfd_siginfo))
        errExit("read");

    printf("PID %ld: got signal %d\n", (long) getpid(), fdsi.ssi_signo);

    if (ready == 0 && s > 0)
        printf("Successfully read signal, even though epoll_wait() "
                "didn't say FD was ready!\n");
}

int
main(int argc, char *argv[])
{
    struct epoll_event ev;
    sigset_t mask;
    int sfd, epfd;

    sigfillset(&mask);
    sigdelset(&mask, SIGINT);

    if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)
        errExit("sigprocmask");

    sfd = signalfd(-1, &mask, SFD_NONBLOCK);
    if (sfd == -1)
        errExit("signalfd");

    epfd = epoll_create(5);
    if (epfd == -1)
        errExit("epoll_create");

    ev.data.fd = sfd;
    ev.events = EPOLLIN;
    if (epoll_ctl(epfd, EPOLL_CTL_ADD, sfd, &ev) == -1)
        errExit("epoll_ctl");

    switch (fork()) {
    case -1:
        errExit("fork");
    case 0:
        printf("PID of child:  %ld\n", (long) getpid());
        raise(SIGUSR1);
        signalTest(sfd, epfd);
        break;
    default:
        printf("PID of parent: %ld\n", (long) getpid());
        wait(NULL);
        break;
    }

    exit(EXIT_SUCCESS);
}
8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----8x----

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

signalfd.2: Note about interactions with epoll & fork

Using signalfd(2) with epoll(7) and fork(2) can lead to some head
scratching.

It seems that when a signalfd file descriptor is added to epoll
you will only get notifications for signals sent to the process
that added the file descriptor to epoll.

So if you have a signalfd fd registered with epoll and then call
fork(2), perhaps by way of daemon(3) for example. Then you will
find that you no longer get notifications for signals sent to the
newly forked process.

User kentonv on ycombinator[0] explained it thus

    "One place where the inconsistency gets weird is when you
     use signalfd with epoll. The epoll will flag events on the
     signalfd based on the process where the signalfd was
     registered with epoll, not the process where the epoll is
     being used. One case where this can be surprising is if you
     set up a signalfd and an epoll and then fork() for the
     purpose of daemonizing -- now you will find that your epoll
     mysteriously doesn't deliver any events for the signalfd
     despite the signalfd otherwise appearing to function as
     expected."

And another post from the same person[1].

And then there is this snippet from this kernel commit message[2]

    "If you share epoll fd which contains our sigfd with another
     process you should blame yourself. signalfd is "really
     special"."

So add a note to the man page that points this out where people
will hopefully find it sooner rather than later!

[0]: https://news.ycombinator.com/item?id=9564975
[1]: https://stackoverflow.com/questions/26701159/sending-signalfd-to-another-process/29751604#29751604
[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d80e731ecab420ddcb79ee9d0ac427acbc187b4b

Signed-off-by: Andrew Clayton <andrew@digital-domain.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

strtok.3: Correct description of use of 'saveptr' argument in strtok_r()

Reported-by: eponymous alias <eponymousalias@yahoo.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Explain why various mount points can't have shared propagation

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Correct the list of mount points that can't be MS_SHARED

Eric Biederman noted that my list of directories that could not
have shared propagation was incorrect.  I had written that
new_root could not be shared; rather it should be: the parent of
the current root mount point.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Tweak pivot_root(".", ".") example

Quoting Eric Biederman:

    The concern from our conversation at the container
    mini-summit was that there is a pathology if in your initial
    mount namespace all of the mounts are marked MS_SHARED like
    systemd does (and is almost necessary if you are going to
    use mount propagation), that if new_root itself is MS_SHARED
    then unmounting the old_root could propagate.

    So I believe the desired sequence is:

    >>>            chdir(new_root);
    +++            mount("", ".", MS_SLAVE | MS_REC, NULL);
    >>>            pivot_root(".", ".");
    >>>            umount2(".", MNT_DETACH);

    The change to new new_root could be either MS_SLAVE or
    MS_PRIVATE.  So long as it is not MS_SHARED the mount won't
    propagate back to the parent mount namespace.

Reported-by: Eric W. Biederman <ebiederm@xmission.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: pivot_root(".", ".") really is a thing

LXC uses this [1]. I tested, to double-check, and it works.

The fchdir() dance done by LXC is not needed though:

fchdir(old_root); umount(".", MNT_DETACH); fchdir(new_root);

As far as I can see, just the umount() is sufficient, since,
after pivot_root(), oldi_root is at the top of the stack
of mounts at "/" and thus (so long as CWD is at "/")
the umount will remove the mount at the top of the stack.
Eric Biederman confirmed my understanding by mail, and
Philipp Wendler verified my results by experiment.

[1] See the following commit in LXC:

    commit 2d489f9e87fa0cccd8a1762680a43eeff2fe1b6e
    Author: Serge Hallyn <serge.hallyn@ubuntu.com>
    Date:   Sat Sep 20 03:15:44 2014 +0000

        pivot_root: switch to a new mechanism (v2)

Helped-by: Eric W. Biederman <ebiederm@xmission.com>
Helped-by: Philipp Wendler <ml@philippwendler.de>
Helped-by: Aleksa Sarai <asarai@suse.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: Eliminate text suggesting that behavior may change in the future

After around 19 years, the behavior of pivot_root() has not been
changed, and will almost certainly not change in the future.
So, reword to remove the suggestion that the behavior may change.
Also, more clearly document the effect of pivot_root() on
the calling process's current working directory.

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

pivot_root.2: Rework a "hanging" description into an earlier paragraph

The reference of "Note that this also applies" was vague. So
combine this paragraph with an earlier one to make the linkage
clearer.

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

pivot_root.2: Remove a note about a historical idea/expectation

The idea that there might one day be a mechanism for kernel
threads to explicitly relinquish access to the filesystem never
came to pass (after 20 years), and the presence of text
describing this idea is, IMO, a distraction. So, remove it.

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

pivot_root.2: ffix (break up a paragraph)

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

pivot_root.2: Remove text describing case where current root is not a mount point

One kernel printk() later, my suspicions seem confirmed: the text
describing the situation where the current root is not a mount
point (because of a chroot()) seems to be bogus. (Perhaps it was
true once upon a time.) In my testing, if the current root is not
a mount point, an EINVAL error results.

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

pivot_root.2: srcfix: FIXME

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

pivot_root.2: Fix a technical detail

In this text:

        If the current root is not a mount point (e.g., after an
        earlier chroot(2) or pivot_root())...

mention of pivot_root() makes no sense, since (as noted in an
earlier commit message for this page) 'new_root' in a previous
pivot_root() must (since Linux 2.4.5) have been a mount point.

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

pivot_root.2: Minor change: rewrite the reference to pivot_root(8)

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

pivot_root.2: Remove BUGS section

One of these "bugs" is a philosophical point already covered
elsewhere in the page, while the other is a somewhat obscure joke.
Both pieces are a bit of a distraction, really.

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

pivot_root.2: Minor wording fix

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

pivot_root.2: Relocate details about kernel threads to NOTES

This text is a side point that somewhat distracts from the
flow in DESCRIPTION.

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

pivot_root.2: Add some more detail to the remaining EBUSY error

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

pivot_root.2: Remove bogus a bogus EBUSY error case

The note that EBUSY is given if a filesystem is already mounted
on 'Iput_old' was never really true. That restriction was in
Linux 2.3.14, but removed in Linux 2.3.99-pre6 so it never made
it to mainline.

The relevant diff in pivot_root() was:

        error = -EBUSY;
-       if (d_new_root->d_sb == root->d_sb || d_put_old->d_sb == root->d_sb)
+       if (new_nd.mnt == root_mnt || old_nd.mnt == root_mnt)
                goto out2; /* loop */
-       if (d_put_old != d_put_old->d_covers)
-               goto out2; /* mount point is busy */
        error = -EINVAL;

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

mount_namespaces.7: SEE ALSO: refer to example in pivot_root(2)

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

pivot_root.2: Add an example program

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

pivot_root.2: Minor fix: add a reference to a relevant piece in NOTES

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

pivot_root.2: Relocate text on use cases and add text on purpose of pivot_root(2)

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

pivot_root.2: Rework the text on "future changes" to reflect that 20 years have passed

Some of the text was written long ago, and hinted that things
might change in the future. However, 20 years have passed
and these details have not changed, so rework the text to
hint at that fact.

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

pivot_root.2: Mention containers as a use case for pivot_root()

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

pivot_root.2: srcfix

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

pivot_root.2: There is no restriction against 'put_old' being a mount point

As far as I can see from the source code, the statement that
"No other filesystem may be mounted on 'put_old'" is incorrect.
Even looking at the 2.4.0 source code, there I can't see such
a restriction. In addition, some testing on a 5.0 kernel
(mounting 'put_old' in the new mount namespace just before
pivot_root()) did not result in an error for this case when
calling pivot_root().

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

pivot_root.2: srcfix: add self to copyright

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

pivot_root.2: pivot_root() affects only other processes in the same mount namespace

pivot_root() only affects the current working directory and root
directory of other processes in the same mount namespace as the
caller.

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

pivot_root.2: Introduce mount namespaces in the very first sentence

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

pivot_root.2: Note capability requirements

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

pivot_root.2: Mention mount namespaces

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

pivot_root.2: SEE ALSO: add mount_namespaces(7)

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

pivot_root.2: wfix

"At the time of writing" was ~20 years ago. Things
have not so far changed.

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

pivot_root.2: Reword some text that is currently rather hard to parse

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

pivot_root.2: Minor tweak

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

pivot_root.2: Minor fix: place some text at a more logical location in the page

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

operator.7: Prefix and postfix ++/-- have different precedences

Harbison and Steele also agree on this.

Reported-by: Rick Stanley <rstanley@rsiny.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kill.2: Minor clarification

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

rt_sigqueueinfo.2: Rename 'uinfo' argument to 'info'

This is more consistent with the naming in other pages
that refer to a 'siginfo_t' structure.

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

rt_sigqueueinfo.2: The rules for 'si_code' don't apply when sending a signal to oneself

The restriction on what values may be specified in 'si_code'
apply only when sending a signal to a process other than the
caller itself.

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

rt_sigqueueinfo.2: Note that 'si_code' can't be specified as SI_KERNEL

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

rt_sigqueueinfo.2: Minor restructuring in preparation for next patch

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

setns.2: Fix CLONE_NEWNS restriction info

Threads are allowed to switch mount namespaces if the filesystem
details aren't being shared.  That's the purpose of the check in
the kernel quoted by the comment:

    if (fs->users != 1)
        return -EINVAL;

It's been this way since the code was originally merged in v3.8.

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

ptrace.2: Fix description of 'is_error' field in 'struct ptrace_syscall_info'

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