]> git.ipfire.org Git - thirdparty/man-pages.git/log
thirdparty/man-pages.git
5 years agosocket.2: Remove notes concerning AF_ALG and AF_XDP
Nikola Forró [Fri, 22 Feb 2019 16:14:14 +0000 (17:14 +0100)] 
socket.2: Remove notes concerning AF_ALG and AF_XDP

All address families are now documented in address_families.7,
which is already present in SEE ALSO section. Also, the AF_ALG
note contains dead link to kernel HTML documentation.

Signed-off-by: Nikola Forró <nforro@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Minor wording fixes
Michael Kerrisk [Mon, 25 Feb 2019 10:22:43 +0000 (11:22 +0100)] 
filesystems.5: Minor wording fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Minor tweaks to Eugene Syromyatnikov's patch
Michael Kerrisk [Mon, 25 Feb 2019 10:21:52 +0000 (11:21 +0100)] 
filesystems.5: Minor tweaks to Eugene Syromyatnikov's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofilesystems.5: Mention sysfs(2)
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:23 +0000 (17:26 +0100)] 
filesystems.5: Mention sysfs(2)

* man5/filesystems.5 (.SH DESCRIPTION): Add a note that the
  information about available file systems can be obtained
  via sysfs() syscall.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoaddress_families.7: tfix
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:21 +0000 (17:26 +0100)] 
address_families.7: tfix

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2: Reinstate AF_VSOCK mention
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:16 +0000 (17:26 +0100)] 
socket.2: Reinstate AF_VSOCK mention

It has its own man page, so it probably makes sense to mention
it here.

* man2/socket.2 (.SH DESCRIPTION): Add mention of AF_VSOCK back.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2: tfix
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:13 +0000 (17:26 +0100)] 
socket.2: tfix

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosocket.2, address_families.7: Mention that address family names are Linux-specific
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:11 +0000 (17:26 +0100)] 
socket.2, address_families.7: Mention that address family names are Linux-specific

* man2/socket.2 (.SH DESCRIPTION): Mention that the list of
  address families is Linux-specific.
* man7/address_families.7 (.SH DESCRIPTION): Likewise.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosigaction.2: Minot tweaks to Eugene Syromyatnikov's patch
Michael Kerrisk [Mon, 25 Feb 2019 10:05:50 +0000 (11:05 +0100)] 
sigaction.2: Minot tweaks to Eugene Syromyatnikov's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosigaction.2: Describe obsolete usage of struct sigcontext as signal handler argument
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:08 +0000 (17:26 +0100)] 
sigaction.2: Describe obsolete usage of struct sigcontext as signal handler argument

* man2/sigaction.2 (.SS Undocumented): Provide information about
  relation between the second argument of sa_handler and
  uc_mcontext field of the struct ucontext structure.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofcntl.2: Briefly explain the meaning of the 'l_sysid' field in 'struct flock'
Michael Kerrisk [Mon, 25 Feb 2019 09:41:45 +0000 (10:41 +0100)] 
fcntl.2: Briefly explain the meaning of the 'l_sysid' field in 'struct flock'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofcntl.2: Mention that l_sysid is not used even if present
Eugene Syromyatnikov [Fri, 22 Feb 2019 16:26:05 +0000 (17:26 +0100)] 
fcntl.2: Mention that l_sysid is not used even if present

Some architectures do provide an 'l_sysid' declaration in
struct flock; however, it is not used anyway.

* man2/fcntl.2 (.SH NOTES): Note that l_sysid field is not used on
Linux even if present on some architectures.

Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoip.7: IP_RECVTTL error fixed
bert hubert [Sun, 24 Feb 2019 10:18:11 +0000 (11:18 +0100)] 
ip.7: IP_RECVTTL error fixed

I need to get the TTL of UDP datagrams from userspace, so I set
the IP_RECVTTL socket option.  And as promised by ip.7, I then get
IP_TTL messages from recvfrom.  However, unlike what the manpage
promises, the TTL field gets passed as a 32 bit integer.

The following userspace code works:

  uint32_t ttl32;
  for (cmsg = CMSG_FIRSTHDR(msgh); cmsg != NULL; cmsg = CMSG_NXTHDR(msgh,cmsg)) {
    if ((cmsg->cmsg_level == IPPROTO_IP) && (cmsg->cmsg_type == IP_TTL) &&
        CMSG_LEN(sizeof(ttl32)) == cmsg->cmsg_len) {

      memcpy(&ttl32, CMSG_DATA(cmsg), sizeof(ttl32));
      *ttl=ttl32;
      return true;
    }
    else
      cerr<<"Saw something else "<<(cmsg->cmsg_type == IP_TTL) <<
", "<<(int)cmsg->cmsg_level<<", "<<cmsg->cmsg_len<<", "<<
CMSG_LEN(1)<<endl;
  }

The 'else' field was used to figure out I go the length wrong.

Note from mtk:

Reading the source code also seems to confirm this, from
net/ipv4/ip_sockglue.c:

[[
static void ip_cmsg_recv_ttl(struct msghdr *msg, struct sk_buff *skb)
{
        int ttl = ip_hdr(skb)->ttl;
        put_cmsg(msg, SOL_IP, IP_TTL, sizeof(int), &ttl);
}
]]

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Remove first paragraph, which repeats details from capabilities(7)
Michael Kerrisk [Sat, 23 Feb 2019 20:20:39 +0000 (21:20 +0100)] 
capget.2: Remove first paragraph, which repeats details from capabilities(7)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Relocate a misplaced sentence
Michael Kerrisk [Sat, 23 Feb 2019 20:19:08 +0000 (21:19 +0100)] 
capget.2: Relocate a misplaced sentence

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: tfix
Michael Kerrisk [Sat, 23 Feb 2019 20:14:00 +0000 (21:14 +0100)] 
capabilities.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogettid.2: Glibc provides a wrapper since version 2.30
Michael Kerrisk [Thu, 21 Feb 2019 13:00:32 +0000 (14:00 +0100)] 
gettid.2: Glibc provides a wrapper since version 2.30

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosetns.2: When joining a user namespace, it must be a descendant user namespace
Michael Kerrisk [Thu, 21 Feb 2019 09:41:19 +0000 (10:41 +0100)] 
setns.2: When joining a user namespace, it must be a descendant user namespace

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: CAP_SYS_CHROOT allows use of setns() to change the mount namespace
Michael Kerrisk [Fri, 15 Feb 2019 09:16:36 +0000 (10:16 +0100)] 
capabilities.7: CAP_SYS_CHROOT allows use of setns() to change the mount namespace

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: srcfix
Michael Kerrisk [Fri, 15 Feb 2019 09:07:04 +0000 (10:07 +0100)] 
capabilities.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Add a subsection on per-user-namespace "set-user-ID-root" programs
Michael Kerrisk [Thu, 14 Feb 2019 10:09:50 +0000 (11:09 +0100)] 
capabilities.7: Add a subsection on per-user-namespace "set-user-ID-root" programs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Relocate the subsection "Interaction with user namespaces"
Michael Kerrisk [Thu, 14 Feb 2019 09:47:34 +0000 (10:47 +0100)] 
capabilities.7: Relocate the subsection "Interaction with user namespaces"

This best belongs at the end of the page, after the subsections
that already make some mention of user namespaces.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: wfix
Michael Kerrisk [Thu, 14 Feb 2019 07:25:25 +0000 (08:25 +0100)] 
capabilities.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Substantially rework "Capabilities and execution of programs by root"
Michael Kerrisk [Tue, 12 Feb 2019 15:56:13 +0000 (16:56 +0100)] 
capabilities.7: Substantially rework "Capabilities and execution of programs by root"

Rework for improved clarity, and also to include missing details
on the case where (1) the binary that is being executed has
capabilities attached and (2) the real user ID of the process is
not 0 (root) and (3) the effective user ID of the process is 0
(root).

Kernel code analysis and some test code (GPLv3 licensed) below.

======

My analysis of security/commoncaps.c capabilities handling
(from Linux 4.20 source):

execve() eventually calls __do_execve_file():

__do_execve_file()
  |
  +-prepare_bprm_creds(&bprm)
  |  |
  |  +-prepare_exec_creds()
  |  |  |
  |  |  +-prepare_creds()
  |  |     |
  |  |     | // Returns copy of existing creds
  |  |     |
  |  |     +-security_prepare_creds()
  |  |        |
  |  |        +-cred_prepare() [via hook]
  |  |           // Seems to do nothing for commoncaps
  |  |
  |  // Returns creds provided by prepare_creds()
  |
  // Places creds returned by prepare_exec_creds() in bprm->creds
  |
  |
  +-prepare_binprm(&bprm) // bprm from prepare_bprm_creds()
     |
     +-bprm_fill_uid(&bprm)
     |
     |  // Places current credentials into bprm
     |
     |  // Performs set-UID & set-GID transitions if those file bits are set
     |
     +-security_bprm_set_creds(&bprm)
        |
        +-bprm_set_creds(&bprm) [via hook]
           |
           +-cap_bprm_set_creds(&bprm)
              |
              // effective = false
              |
              +-get_file_caps(&bprm, &effective, &has_fcap)
              |  |
              |  +-get_vfs_caps_from_disk(..., &vcaps)
              |  |
              |  |  // Fetches file capabilities from disk and places in vcaps
              |  |
              |  +-bprm_caps_from_vfs_caps(&vcaps, &bprm, &effective, &has_fcap)
              |
              |     // If file effective bit is set: effective = true
              |     //
              |     // If file has capabilities: has_fcap |= true
              |     //
              |     // Perform execve transformation:
              |     //     P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset)
              |
              +-handle_privileged_root(&bprm, has_fcap, &effective, root_uid)
              |
              |  // If has_fcap && (rUID != root && eUID == root) then
              |  //     return without doing anything
              |  //
              |  // If rUID == root || eUID == root then
              |  //    P'(perm) = P(inh) | P(bset)
              |  //
              |  // If eUID == root then
              |  //     effective = true
              |
              // Perform execve() transformation:
              //
              //     P'(Amb) = (privprog) ? 0 : P(Amb)
              //     P'(Perm) |= P'(Amb)
              //     P'(Eff) = effective ? P'(Perm) : P'(Amb)

Summary

1. Perform set-UID/set-GID transformations

2. P'(Amb) = (privprog) ? 0 : P(Amb)

3. If [process has nonzero UIDs] OR
   ([file has caps] && [rUID != root && eUID == root]), then

        P'(perm) = F(inh) & P(Inh) | F(Perm) & P(bset) | P'(Amb)

   else // ~ [process has rUID == root || eUID == root]

        P'(perm) = P(inh) | P(bset) | P'(Amb)

4. P'(Eff) = (F(eff) || eUID == root) ? P'(Perm) : P'(Amb)

======

$ cat show_creds_and_caps_long.c

int
main(int argc, char *argv[])
{
    uid_t ruid, euid, suid;
    gid_t rgid, egid, sgid;
    cap_t caps;
    char *s;

    if (getresuid(&ruid, &euid, &suid) == -1) {
        perror("getresuid");
        exit(EXIT_FAILURE);
    }

    if (getresgid(&rgid, &egid, &sgid) == -1) {
        perror("getresgid");
        exit(EXIT_FAILURE);
    }

    printf("UID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) ruid, (long) euid, (long) suid);
    printf("GID: %5ld (real), %5ld (effective), %5ld (saved)\n",
            (long) rgid, (long) egid, (long) sgid);

    caps = cap_get_proc();
    if (caps == NULL) {
        perror("cap_get_proc");
        exit(EXIT_FAILURE);
    }
    s = cap_to_text(caps, NULL);
    if (s == NULL) {
        perror("cap_to_text");
        exit(EXIT_FAILURE);
    }
    printf("Capabilities: %s\n", s);

    cap_free(caps);
    cap_free(s);

    exit(EXIT_SUCCESS);
}

$ cat cred_launcher.c

                        } while (0)

                        do { fprintf(stderr, "Usage: "); \
                             fprintf(stderr, msg, progName); \
                             exit(EXIT_FAILURE); } while (0)

int
main(int argc, char *argv[])
{
    uid_t r, e, s;

    if (argc != 5 || strcmp(argv[1], "--help") == 0)
        usageErr("%s rUID eUID sUID <prog>\n", argv[0]);

    r = atoi(argv[1]);
    e = atoi(argv[2]);
    s = atoi(argv[3]);

    if (setresuid(r, e, s) == -1)
        errExit("setresuid");

    if (getresuid(&r, &e, &s) == -1)
        errExit("getresuid");

    execv(argv[4], &argv[4]);
    errExit("execve");
}

$ cc -o cred_launcher cred_launcher.c
$ cc -o show_creds_and_caps_long show_creds_and_caps_long.c -lcap

$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: =ep

$ sudo setcap cap_kill=pe show_creds_and_caps_long
$ sudo ./cred_launcher 1000 0 1000 ./show_creds_and_caps_long
UID:  1000 (real),     0 (effective),     0 (saved)
GID:     0 (real),     0 (effective),     0 (saved)
Capabilities: = cap_kill+ep

The final program execution above shows the special casing
that occurs in handle_privileged_root() for the case where:

    rUID != root && eUID == root && [file has capabilities]

======

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: tfix
Michael Kerrisk [Tue, 12 Feb 2019 13:36:32 +0000 (14:36 +0100)] 
capabilities.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Improve the discussion of when file capabilities are ignored
Michael Kerrisk [Tue, 12 Feb 2019 09:29:21 +0000 (10:29 +0100)] 
capabilities.7: Improve the discussion of when file capabilities are ignored

The text stated that the execve() capability transitions are not
performed for the same reasons that setuid and setgid mode bits
may be ignored (as described in execve(2)). But, that's not quite
correct: rather, the file capability sets are treated as empty
for the purpose of the capability transition calculations.

Also merge the new 'no_file_caps' kernel option text into the
same paragraph.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Document the 'no_file_caps' kernel command-line option
Michael Kerrisk [Tue, 12 Feb 2019 09:15:35 +0000 (10:15 +0100)] 
capabilities.7: Document the 'no_file_caps' kernel command-line option

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapget.2: Remove crufty sentence suggesting use of deprecated functions
Michael Kerrisk [Sat, 23 Feb 2019 20:58:23 +0000 (21:58 +0100)] 
capget.2: Remove crufty sentence suggesting use of deprecated functions

Remove crufty sentence suggesting use of deprecated capsetp(3) and
capgetp(3); the manual page for those functions has long (at least
as far back as 2007) noted that they are deprecated.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosetfsgid.2, setfsuid.2: wfix
Michael Kerrisk [Sat, 16 Feb 2019 06:52:30 +0000 (07:52 +0100)] 
setfsgid.2, setfsuid.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: Rework discussion of exec and UID 0, correcting a couple of details
Michael Kerrisk [Sun, 10 Feb 2019 02:40:15 +0000 (03:40 +0100)] 
capabilities.7: Rework discussion of exec and UID 0, correcting a couple of details

Clarify the "Capabilities and execution of programs by root"
section, and correct a couple of details:

* If a process with rUID == 0 && eUID != 0 does an exec,
  the process will nevertheless gain effective capabilities
  if the file effective bit is set.
* Set-UID-root programs only confer a full set of capabilities
  if the binary does not also have attached capabilities.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocapabilities.7: srcfix
Michael Kerrisk [Thu, 7 Feb 2019 10:40:25 +0000 (11:40 +0100)] 
capabilities.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agonamespaces.7: srcfix
Michael Kerrisk [Thu, 7 Feb 2019 01:07:28 +0000 (02:07 +0100)] 
namespaces.7: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Sat, 2 Feb 2019 18:48:15 +0000 (19:48 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: SEE ALSO: add htop(1) and pstree(1)
Michael Kerrisk [Thu, 31 Jan 2019 04:36:00 +0000 (05:36 +0100)] 
proc.5: SEE ALSO: add htop(1) and pstree(1)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: Since Linux 4.5, "stack:" is no longer shown in /proc/PID/maps
Michael Kerrisk [Thu, 24 Jan 2019 20:08:57 +0000 (09:08 +1300)] 
proc.5: Since Linux 4.5, "stack:" is no longer shown in /proc/PID/maps

Reported-by: Nick Gregory <ghost@capsule8.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofsync.2: tfix
Ignat Loskutov [Thu, 17 Jan 2019 17:46:33 +0000 (20:46 +0300)] 
fsync.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoio_submit.2: ffix
Michael Kerrisk [Thu, 24 Jan 2019 19:59:54 +0000 (08:59 +1300)] 
io_submit.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoio_submit.2: Fix the description of aio_data
Jeff Moyer [Thu, 17 Jan 2019 20:32:44 +0000 (15:32 -0500)] 
io_submit.2: Fix the description of aio_data

aio_data is not a kernel-internal field.

Signed-off-by: Jeff Moyer <jmoyer@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: Mention /proc/uptime includes time spent in suspend
Stephan Knauss [Tue, 22 Jan 2019 15:24:17 +0000 (16:24 +0100)] 
proc.5: Mention /proc/uptime includes time spent in suspend

fs/proc/uptime.c:uptime_proc_show() fetches time using
ktime_get_boottime which includes the time spent in suspend.

Signed-off-by: Stephan Knauss <linux@stephans-server.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: Reframe the text on delegation to include more details about cgroups v1
Michael Kerrisk [Wed, 23 Jan 2019 21:11:25 +0000 (22:11 +0100)] 
cgroups.7: Reframe the text on delegation to include more details about cgroups v1

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 21:04:31 +0000 (22:04 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 20:41:48 +0000 (21:41 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: Soften the discussion about delegation in cgroups v1
Michael Kerrisk [Wed, 23 Jan 2019 20:24:06 +0000 (21:24 +0100)] 
cgroups.7: Soften the discussion about delegation in cgroups v1

Balbir pointed out that v1 delegation was not an accidental
feature.

Reported-by: Balbir Singh <bsingharora@gmail.com>
Reported-by: Marcus Gelderie <redmnic@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agocgroups.7: wfix
Michael Kerrisk [Wed, 23 Jan 2019 20:16:52 +0000 (21:16 +0100)] 
cgroups.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agotime.1: Update bug reporting address
Jakub Wilk [Tue, 15 Jan 2019 22:14:45 +0000 (23:14 +0100)] 
time.1: Update bug reporting address

Update the bug reporting email address to that shown by

     /bin/time --help

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoman.7: tfix
Jakub Wilk [Tue, 15 Jan 2019 22:07:30 +0000 (23:07 +0100)] 
man.7: tfix

Use \(aq for ASCII apostrophes and \(ga for backtick,
as recommended by groff_man(7).

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoclose.2: ffix
Lucas Werkmeister [Sun, 13 Jan 2019 17:49:00 +0000 (18:49 +0100)] 
close.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agotime.1: Document the -q/--quiet option
Michael Kerrisk [Sat, 12 Jan 2019 20:50:00 +0000 (21:50 +0100)] 
time.1: Document the -q/--quiet option

Reported-by: Johannes Altmanninger <aclopte@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agolocaledef.1: Minor tweaks to Howard Johnson's patch
Michael Kerrisk [Thu, 10 Jan 2019 04:04:35 +0000 (17:04 +1300)] 
localedef.1: Minor tweaks to Howard Johnson's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agolocaledef.1: Note that -f and -c, are reversed from what you might expect
Howard Johnson [Thu, 10 Jan 2019 04:01:46 +0000 (17:01 +1300)] 
localedef.1: Note that -f and -c, are reversed from what you might expect

I was reading the local-gen bash script, looking for why I'm
getting locale errors, when I noticed that localdef's -f and -c
options were named, in what I think, is a very confusing way.

   -c is the same as --force, and

   -f charmapfile is the same as --charmap=charmapfile.

Yes, it would have been better if they're names had been reversed,
like this:

   -f is the same as --force, and

   -c charmapfile is the same as --charmap=charmapfile.

But given what they are, I thought it would be helpful to give a
heads up to watch for their irregular naming.  I hope I've worded
it appropriately.

I'm not ccing this to anyone else, (i.e. developers, etc), as
these features work as described in the man page.  They're just
confusing.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agobstring.3: Correct argument list for memmem() prototype
Michael Kerrisk [Thu, 10 Jan 2019 00:32:05 +0000 (13:32 +1300)] 
bstring.3: Correct argument list for memmem() prototype

Reported-by: Emil Fihlman <emil.fihlman@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoChanges.old: tfix
Jakub Wilk [Mon, 31 Dec 2018 16:20:45 +0000 (17:20 +0100)] 
Changes.old: tfix

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agobsd_signal.3: Fix the wrong version of _POSIX_C_SOURCE
Xiao Yang [Fri, 21 Dec 2018 03:01:58 +0000 (11:01 +0800)] 
bsd_signal.3: Fix the wrong version of _POSIX_C_SOURCE

According to the latest glibc, the bsd_signal() function is just
declared when POSIX.1-2008 (or newer) instead of POSIX.1-2001 is
not set since glibc v2.26.

Please see the following code from signal/signal.h:
-----------------------------------------------------------------
/* The X/Open definition of `signal' conflicts with the BSD version.
   So they defined another function `bsd_signal'.  */
extern __sighandler_t bsd_signal (int __sig, __sighandler_t __handler)
     __THROW;
-----------------------------------------------------------------

Signed-off-by: Xiao Yang <yangx.jy@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agofeature_test_macros.7: Add more detail on why FTMs must be defined before including...
Michael Kerrisk [Thu, 10 Jan 2019 00:01:03 +0000 (13:01 +1300)] 
feature_test_macros.7: Add more detail on why FTMs must be defined before including any header

Reported-by: Andreas Westfeld <andreas.westfeld@htw-dresden.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoMerge branch 'master' of ra.kernel.org:/pub/scm/docs/man-pages/man-pages
Michael Kerrisk [Wed, 9 Jan 2019 18:01:44 +0000 (07:01 +1300)] 
Merge branch 'master' of ra.kernel.org:/pub/scm/docs/man-pages/man-pages

5 years agoerrno.3: Mention that errno(1) is part of the 'moreutils' package
Michael Kerrisk [Sat, 5 Jan 2019 20:21:02 +0000 (21:21 +0100)] 
errno.3: Mention that errno(1) is part of the 'moreutils' package

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Minor fixes to Eugene's patch
Michael Kerrisk [Wed, 9 Jan 2019 17:38:52 +0000 (06:38 +1300)] 
open.2: Minor fixes to Eugene's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Mention presence of unused O_RSYNC definition
Eugene Syromiatnikov [Fri, 4 Jan 2019 17:24:33 +0000 (18:24 +0100)] 
open.2: Mention presence of unused O_RSYNC definition

O_RSYNC is defined in <asm/fcntl.h> on HP PA-RISC, but is not
used anyway.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:34:38 +0000 (06:34 +1300)] 
open.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Minor fixes to Eugene's patch
Michael Kerrisk [Wed, 9 Jan 2019 17:32:39 +0000 (06:32 +1300)] 
open.2: Minor fixes to Eugene's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoopen.2: Document FASYNC usage in Linux UAPI headers
Eugene Syromiatnikov [Fri, 4 Jan 2019 17:24:29 +0000 (18:24 +0100)] 
open.2: Document FASYNC usage in Linux UAPI headers

Linux's <asm/fcntl.h> defines FASYNC instead of O_ASYNC; document
this peculiarity.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agorename.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:25:18 +0000 (06:25 +1300)] 
rename.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agorename.2: Some additional notes regarding RENAME_WHITEOUT
Eugene Syromiatnikov [Fri, 4 Jan 2019 15:35:45 +0000 (16:35 +0100)] 
rename.2: Some additional notes regarding RENAME_WHITEOUT

Add a note regarding other implementations of whiteout inodes
and update filesystem support information.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetgid.2, getpid.2, getuid.2, pipe.2: Remove mention of other syscalls that use secon...
Michael Kerrisk [Wed, 9 Jan 2019 17:21:17 +0000 (06:21 +1300)] 
getgid.2, getpid.2, getuid.2, pipe.2: Remove mention of other syscalls that use second retval register

This information is already summarized in syscall(2), so there's
no need to repeat it in each page.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:16:24 +0000 (06:16 +1300)] 
syscall.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: tfix
Michael Kerrisk [Wed, 9 Jan 2019 17:09:01 +0000 (06:09 +1300)] 
syscall.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: ffix
Michael Kerrisk [Wed, 9 Jan 2019 17:08:08 +0000 (06:08 +1300)] 
syscall.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: Rework table to render within 80 columns
Michael Kerrisk [Wed, 9 Jan 2019 17:06:20 +0000 (06:06 +1300)] 
syscall.2: Rework table to render within 80 columns

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetgid.2, getpid.2, getuid.2, pipe.2, syscall.2: Minor tweaks to Eugene's patch
Michael Kerrisk [Wed, 9 Jan 2019 06:10:30 +0000 (19:10 +1300)] 
getgid.2, getpid.2, getuid.2, pipe.2, syscall.2: Minor tweaks to Eugene's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetgid.2, getpid.2, getuid.2, pipe.2, syscall.2: Describe 2nd return value peculiarity
Eugene Syromiatnikov [Fri, 4 Jan 2019 15:08:06 +0000 (16:08 +0100)] 
getgid.2, getpid.2, getuid.2, pipe.2, syscall.2: Describe 2nd return value peculiarity

Some architectures (ab)use second return value register for additional
return value in some system calls. Let's describe this.

Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: ffix
Eugene Syromiatnikov [Fri, 4 Jan 2019 15:10:11 +0000 (16:10 +0100)] 
syscall.2: ffix

Add missing .RE.

Fixes: 2ad7b4c46c0a92ae ("syscall.2: Elaborate x32 ABI specifics")
Signed-off-by: Eugene Syromiatnikov <esyr@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoerrno.3: Mention that errno(1) is part of the 'moreutils' package
Michael Kerrisk [Sat, 5 Jan 2019 20:21:02 +0000 (21:21 +0100)] 
errno.3: Mention that errno(1) is part of the 'moreutils' package

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: wfix
Michael Kerrisk [Sun, 23 Dec 2018 18:02:41 +0000 (19:02 +0100)] 
unix.7: wfix

Reported-by: Felipe Gasper <felipe@felipegasper.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: Clarify that SO_PASSCRED behavior
Michael Kerrisk [Sun, 23 Dec 2018 17:55:33 +0000 (18:55 +0100)] 
unix.7: Clarify that SO_PASSCRED behavior

Clarify that SO_PASSCRED results in SCM_CREDENTIALS data in each
subsequently received message.

See https://bugzilla.kernel.org/show_bug.cgi?id=201805

Reported-by: Felipe Gasper <felipe@felipegasper.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: Rework SO_PEERCRED text for greater clarity
Michael Kerrisk [Sun, 23 Dec 2018 17:24:06 +0000 (18:24 +0100)] 
unix.7: Rework SO_PEERCRED text for greater clarity

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: Explicitly note that SO_PASSCRED provides SCM_CREDENTIALS messages
Michael Kerrisk [Sun, 23 Dec 2018 17:17:06 +0000 (18:17 +0100)] 
unix.7: Explicitly note that SO_PASSCRED provides SCM_CREDENTIALS messages

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: wfix
Michael Kerrisk [Sun, 23 Dec 2018 17:11:54 +0000 (18:11 +0100)] 
unix.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agounix.7: Improve wording describing socket option argument/return values
Michael Kerrisk [Sun, 23 Dec 2018 17:10:25 +0000 (18:10 +0100)] 
unix.7: Improve wording describing socket option argument/return values

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoselect.2: wfix
Michael Kerrisk [Sun, 23 Dec 2018 17:01:19 +0000 (18:01 +0100)] 
select.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agowrite.2: RETURN VALUE: clarify details of partial write and
Michael Kerrisk [Sun, 23 Dec 2018 16:50:02 +0000 (17:50 +0100)] 
write.2: RETURN VALUE: clarify details of partial write and

As reported by Nadav Har'El in
https://bugzilla.kernel.org/show_bug.cgi?id=197961

    The write(2) manual page has this paragraph:

    "On  success,  the  number  of bytes written is returned
    (zero indicates nothing was written).  It is not an error
    if  this  number  is  smaller than the number of bytes
    requested; this may happen for example because the disk
    device was filled.  See also NOTES."

    I find a few problems with this paragraph:

    1. It's not clear what "See also NOTES." refers to (does it
       refer to anything?). What in the NOTES is relevant here?

    2. The paragraph seems to suggest that write(2) of a
       non-empty buffer may sometimes return even 0 in case of an
       error like the device being filled. I think this is wrong
       - if there was an error after already writing some number
       of bytes, this non-zero number is returned. But if there's
       an error before writing any bytes, -1 will be returned
       (and the error reason in errno) - 0 will not be returned
       unless the given count is 0 (that case is explained in the
       following paragraph).

    3. The paragraph doesn't explain what a user should do
       after a short write (i.e., write(2) returning less than
       count). How would the user know why there was an error, or
       if there even was one? I think users should be told what
       to do next because this information is part of how to use
       this API correctly. I think users should be told to retry
       the rest of the write (i.e., write(fd, buf+ret, count-ret)
       and this will either succeed in writing some more data if
       the error reason was solved, or the second write will
       return -1 and the error reason in errno.

Reported-by: Nadav Har'El <nyh@math.technion.ac.il>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agogetxattr.2, removexattr.2, setxattr.2: ERRORS: replace ENOATTR with ENODATA
Michael Kerrisk [Sun, 23 Dec 2018 16:36:18 +0000 (17:36 +0100)] 
getxattr.2, removexattr.2, setxattr.2: ERRORS: replace ENOATTR with ENODATA

ENOATTR is not a standard error code, but rather one that is
defined in 'libattr' as a synonym for ENODATA. The manual pages
should use the error code actually returned by the kernel APIs.

See also https://bugzilla.kernel.org/show_bug.cgi?id=201995

Reported-by: Enrico Scholz <enrico.scholz@sigma-chemnitz.de>
Reviewed-by: Andreas Gruenbacher <agruenba@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agonamespaces.7: tfix
Radostin Stoyanov [Tue, 18 Dec 2018 14:32:10 +0000 (14:32 +0000)] 
namespaces.7: tfix

Signed-off-by: Radostin Stoyanov <rstoyanov1@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agomount.2: wfix (clarify effect of unbindable propagation type)
Michael Kerrisk [Fri, 14 Dec 2018 10:35:40 +0000 (11:35 +0100)] 
mount.2: wfix (clarify effect of unbindable propagation type)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoproc.5: Refer to mount(2) for explanation of mount vs superblock options
Michael Kerrisk [Fri, 14 Dec 2018 08:11:29 +0000 (09:11 +0100)] 
proc.5: Refer to mount(2) for explanation of mount vs superblock options

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agosyscall.2: Fix wrong retval register number in alpha architecture
snyh [Sat, 8 Dec 2018 13:44:15 +0000 (14:44 +0100)] 
syscall.2: Fix wrong retval register number in alpha architecture

alpha use v0 e.g. $0 as the return value register both in
syscall ABI and C ABI.

see also
https://github.com/torvalds/linux/blob/master/arch/alpha/kernel/entry.S#L479

The normal Alpha C ABI use a0~a5 to pass arguments and use v0 as
the return value register. See here
https://www2.cs.arizona.edu/projects/alto/Doc/local/alpha.register.html

The syscall ABI use v0 as the trap number, a0~a5 to pass arguments
and use a3 as a indicator (bool type) whether has a error occurred.

We can also see the libc's syscall wrapper implements at
https://code.woboq.org/userspace/glibc/sysdeps/unix/sysv/linux/alpha/syscall.S.html
The v0 is the normal used as return register, and we can see the
return processing doesn't do anything about a0 which is the wrong
register of currently syscall(2) description.

p.s. I found this wrong description because I'm porting Go gc to
a new CPU architecture which is similar to Alpha, And I use the
wrong register at first, then I have inspect the kernel code and
objdump to ensure the right syscall ABI.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoperf_event_open.2: Fix wording in multiplexing description
Vince Weaver [Mon, 3 Dec 2018 20:23:42 +0000 (15:23 -0500)] 
perf_event_open.2: Fix wording in multiplexing description

Back in 2014 (37bee118ad692e120559c71bc2b2428d31637c5e) the text
describing when multiplexing happens was changed in a confusing way.
This is an attempt to clarify things a bit.

Signed-off-by: Vince Weaver <vincent.weaver@maine.edu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agomadvise.2: Minor tweaks to Michal Hocko's patch
Michael Kerrisk [Sat, 1 Dec 2018 08:53:19 +0000 (09:53 +0100)] 
madvise.2: Minor tweaks to Michal Hocko's patch

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agomadvise.2: MADV_FREE clarify swapless behavior
Michal Hocko [Thu, 29 Nov 2018 18:10:48 +0000 (19:10 +0100)] 
madvise.2: MADV_FREE clarify swapless behavior

Since 93e06c7a6453 ("mm: enable MADV_FREE for swapless system") we
handle MADV_FREE on a swapless system the same way as with the
swap available. Clarify that fact in the man page.

Reported-by: Niklas Hambüchen <mail@nh2.me>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agotcp.7: wfix
Konst Mayer [Fri, 30 Nov 2018 10:05:23 +0000 (17:05 +0700)] 
tcp.7: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoaccept.2, copy_file_range.2, eventfd.2, inotify_init.2, pipe.2, readahead.2, signalfd...
Michael Kerrisk [Sat, 1 Dec 2018 08:42:01 +0000 (09:42 +0100)] 
accept.2, copy_file_range.2, eventfd.2, inotify_init.2, pipe.2, readahead.2, signalfd.2, socket.2, timerfd_create.2: Clarify the distinction between "file descriptor" and "file description"

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoeventfd.2: Move text noting that eventfd() creates a FD earlier in the page
Michael Kerrisk [Sat, 1 Dec 2018 08:30:07 +0000 (09:30 +0100)] 
eventfd.2: Move text noting that eventfd() creates a FD earlier in the page

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoclone.2: srcfix
Michael Kerrisk [Sat, 1 Dec 2018 08:21:05 +0000 (09:21 +0100)] 
clone.2: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoioctl_console.2, ctime.3: tfix
Michael Kerrisk [Tue, 27 Nov 2018 17:26:19 +0000 (18:26 +0100)] 
ioctl_console.2, ctime.3: tfix

Reported-by: Anatoly Borodin <anatoly.borodin@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoptrace.2: Do not say that PTRACE_O_TRACESYSGOOD may not work
Dmitry V. Levin [Mon, 26 Nov 2018 21:18:47 +0000 (00:18 +0300)] 
ptrace.2: Do not say that PTRACE_O_TRACESYSGOOD may not work

Remove the old statement that PTRACE_O_TRACESYSGOOD may not work
on all architectures.  As far as I can tell, all kernel code
properly tests PT_TRACESYSGOOD flag and sets the 7th bit in the
exit code passed to ptrace_notify().

Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: wfix
Michael Kerrisk [Sat, 24 Nov 2018 19:54:48 +0000 (20:54 +0100)] 
prctl.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: Explain the circumstances in which the parent-death signal is sent
Michael Kerrisk [Sat, 24 Nov 2018 11:48:35 +0000 (12:48 +0100)] 
prctl.2: Explain the circumstances in which the parent-death signal is sent

To test the behavior documented by this patch, the following
demos employ the program shown at the foot of this commit message.

First, show that the pdeath signal is sent when the parent
terminates:

$ ./pdeath_signal 0 10 4
Parent (18595) about to sleep for 4 seconds
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18595) terminating
*********** Child (18596) got signal; si_pid = 18595; si_uid = 1000
            Parent PID is now 1403
$ Child about to exit

But the signal is not sent if the parent terminates before the
child uses PR_SET_PDEATHSIG:

$ ./pdeath_signal 2 10  0
Parent (18707) about to sleep for 0 seconds
Parent (18707) terminating
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
$ Child about to set PR_SET_PDEATHSIG
Child about to sleep
Child about to exit

Demonstrate that the pdeath signal is sent on termination of each
ancestor subreaper process:

$ ./pdeath_signal 2 10 3 7 6 5
18786 marked itself as a subreaper
18786 subreaper about to sleep 7 seconds
18787 marked itself as a subreaper
18787 subreaper about to sleep 6 seconds
18788 marked itself as a subreaper
18788 subreaper about to sleep 5 seconds
Parent (18789) about to sleep for 3 seconds
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18789) terminating
*********** Child (18790) got signal; si_pid = 18789; si_uid = 1000
            Parent PID is now 18788
18788 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18788; si_uid = 1000
            Parent PID is now 18787
18787 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18787; si_uid = 1000
            Parent PID is now 18786
18786 subreaper about to terminate
*********** Child (18790) got signal; si_pid = 18786; si_uid = 1000
            Parent PID is now 1403
$ Child about to exit

But in the case where some subreapers terminate before they
have a chance to adopt the child, the terminations of those
subreapers do not result in a signal for the child:

$ ./pdeath_signal 2 10 3 5 6 7
18836 marked itself as a subreaper
18836 subreaper about to sleep 5 seconds
18837 marked itself as a subreaper
18837 subreaper about to sleep 6 seconds
18838 marked itself as a subreaper
18838 subreaper about to sleep 7 seconds
Parent (18839) about to sleep for 3 seconds
Child about to sleep 2 seconds before setting PR_SET_PDEATHSIG
Child about to set PR_SET_PDEATHSIG
Child about to sleep
Parent (18839) terminating
*********** Child (18840) got signal; si_pid = 18839; si_uid = 1000
            Parent PID is now 18838
18836 subreaper about to terminate
$ 18837 subreaper about to terminate
18838 subreaper about to terminate
*********** Child (18840) got signal; si_pid = 18838; si_uid = 1000
            Parent PID is now 1403
Child about to exit

============================

/* pdeath_signal.c */

                        } while (0)

static void
handler(int sig, siginfo_t *si, void *ucontext)
{
    printf("*********** Child (%ld) got signal; si_pid = %d; si_uid = %d\n",
            (long) getpid(), si->si_pid, si->si_uid);
    printf("            Parent PID is now %ld\n", (long) getppid());
}

int
main(int argc, char *argv[])
{
    struct sigaction sa;
    int childPreSleep, childPostSleep, parentSleep;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s child-pre-sleep "
                "[child-post-sleep [parent-sleep [subreaper-sleep...]]]\n",
                argv[0]);
        exit(EXIT_FAILURE);
    }

    childPreSleep = atoi(argv[1]);
    if (argc > 2)
        childPostSleep = atoi(argv[2]);
    if (argc > 3)
        parentSleep = atoi(argv[3]);

    /* Optionally create a series of subreapers */

    if (argc > 4) {
        for (int sr = 4; sr < argc; sr++) {
            if (prctl(PR_SET_CHILD_SUBREAPER, 1) == -1)
                errExit("prctl");
            printf("%ld marked itself as a subreaper\n", (long) getpid());
            switch (fork()) {
            case -1:
                errExit("fork");
            case 0:
                break;
            default:
                printf("%ld subreaper about to sleep %s seconds\n",
                        (long) getpid(), argv[sr]);
                sleep(atoi(argv[sr]));
                printf("%ld subreaper about to terminate\n", (long) getpid());
                exit(EXIT_SUCCESS);
            }
        }
    }

    switch (fork()) {
    case -1:
        errExit("fork");

    case 0:
        sa.sa_flags = SA_SIGINFO;
        sigemptyset(&sa.sa_mask);
        sa.sa_sigaction = handler;
        if (sigaction(SIGUSR1, &sa, NULL) == -1)
            errExit("sigaction");

        if (childPreSleep > 0) {
            printf("Child about to sleep %d seconds before setting "
                    "PR_SET_PDEATHSIG\n", childPreSleep);
            sleep(childPreSleep);
        }

        printf("Child about to set PR_SET_PDEATHSIG\n");
        if (prctl(PR_SET_PDEATHSIG, SIGUSR1) == -1)
            errExit("prctl");

        printf("Child about to sleep\n");
        for (int j = 0; j < childPostSleep; j++)
            sleep(1);

        printf("Child about to exit\n");
        exit(EXIT_SUCCESS);

    default:
        printf("Parent (%ld) about to sleep for %d seconds\n",
                (long) getpid(), parentSleep);
        sleep(parentSleep);
        printf("Parent (%ld) terminating\n", (long) getpid());
        exit(EXIT_SUCCESS);
    }
}

Reported-by: Jann Horn <jann@thejh.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: tfix
Michael Kerrisk [Sat, 24 Nov 2018 11:44:27 +0000 (12:44 +0100)] 
prctl.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: wfix
Michael Kerrisk [Sat, 24 Nov 2018 10:25:28 +0000 (11:25 +0100)] 
prctl.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: ffix
Michael Kerrisk [Sat, 24 Nov 2018 10:23:51 +0000 (11:23 +0100)] 
prctl.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
5 years agoprctl.2: wfix
Michael Kerrisk [Sat, 24 Nov 2018 10:22:47 +0000 (11:22 +0100)] 
prctl.2: wfix

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