Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 150 insertions, 0 deletions

diff --git a/man/man2/getpid.2 b/man/man2/getpid.2
new file mode 100644
index 0000000..fafcb6c
--- /dev/null
+++ b/man/man2/getpid.2
@@ -0,0 +1,150 @@
+.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH getpid 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getpid, getppid \- get process identification
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.B pid_t getpid(void);
+.B pid_t getppid(void);
+.fi
+.SH DESCRIPTION
+.BR getpid ()
+returns the process ID (PID) of the calling process.
+(This is often used by
+routines that generate unique temporary filenames.)
+.P
+.BR getppid ()
+returns the process ID of the parent of the calling process.
+This will be either the ID of the process that created this process using
+.BR fork (),
+or, if that process has already terminated,
+the ID of the process to which this process has been reparented (either
+.BR init (1)
+or a "subreaper" process defined via the
+.BR prctl (2)
+.B PR_SET_CHILD_SUBREAPER
+operation).
+.SH ERRORS
+These functions are always successful.
+.SH VERSIONS
+On Alpha, instead of a pair of
+.BR getpid ()
+and
+.BR getppid ()
+system calls, a single
+.BR getxpid ()
+system call is provided, which returns a pair of PID and parent PID.
+The glibc
+.BR getpid ()
+and
+.BR getppid ()
+wrapper functions transparently deal with this.
+See
+.BR syscall (2)
+for details regarding register mapping.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 4.3BSD, SVr4.
+.SS C library/kernel differences
+From glibc 2.3.4 up to and including glibc 2.24,
+the glibc wrapper function for
+.BR getpid ()
+cached PIDs,
+with the goal of avoiding additional system calls when a process calls
+.BR getpid ()
+repeatedly.
+Normally this caching was invisible,
+but its correct operation relied on support in the wrapper functions for
+.BR fork (2),
+.BR vfork (2),
+and
+.BR clone (2):
+if an application bypassed the glibc wrappers for these system calls by using
+.BR syscall (2),
+then a call to
+.BR getpid ()
+in the child would return the wrong value
+(to be precise: it would return the PID of the parent process).
+.\" The following program demonstrates this "feature":
+.\"
+.\" #define _GNU_SOURCE
+.\" #include <sys/syscall.h>
+.\" #include <sys/wait.h>
+.\" #include <stdint.h>
+.\" #include <stdio.h>
+.\" #include <stdlib.h>
+.\" #include <unistd.h>
+.\"
+.\" int
+.\" main(int argc, char *argv[])
+.\" {
+.\"    /* The following statement fills the getpid() cache */
+.\"
+.\"    printf("parent PID = %ld\n", (intmax_t) getpid());
+.\"
+.\"    if (syscall(SYS_fork) == 0) {
+.\"        if (getpid() != syscall(SYS_getpid))
+.\"            printf("child getpid() mismatch: getpid()=%jd; "
+.\"                    "syscall(SYS_getpid)=%ld\n",
+.\"                    (intmax_t) getpid(), (long) syscall(SYS_getpid));
+.\"        exit(EXIT_SUCCESS);
+.\"    }
+.\"    wait(NULL);
+.\"}
+In addition, there were cases where
+.BR getpid ()
+could return the wrong value even when invoking
+.BR clone (2)
+via the glibc wrapper function.
+(For a discussion of one such case, see BUGS in
+.BR clone (2).)
+Furthermore, the complexity of the caching code had been
+the source of a few bugs within glibc over the years.
+.P
+Because of the aforementioned problems,
+since glibc 2.25, the PID cache is removed:
+.\" commit c579f48edba88380635ab98cb612030e3ed8691e
+.\" https://sourceware.org/glibc/wiki/Release/2.25#pid_cache_removal
+calls to
+.BR getpid ()
+always invoke the actual system call, rather than returning a cached value.
+.\" FIXME .
+.\" Review progress of https://bugzilla.redhat.com/show_bug.cgi?id=1469757
+.SH NOTES
+If the caller's parent is in a different PID namespace (see
+.BR pid_namespaces (7)),
+.BR getppid ()
+returns 0.
+.P
+From a kernel perspective,
+the PID (which is shared by all of the threads in a multithreaded process)
+is sometimes also known as the thread group ID (TGID).
+This contrasts with the kernel thread ID (TID),
+which is unique for each thread.
+For further details, see
+.BR gettid (2)
+and the discussion of the
+.B CLONE_THREAD
+flag in
+.BR clone (2).
+.SH SEE ALSO
+.BR clone (2),
+.BR fork (2),
+.BR gettid (2),
+.BR kill (2),
+.BR exec (3),
+.BR mkstemp (3),
+.BR tempnam (3),
+.BR tmpfile (3),
+.BR tmpnam (3),
+.BR credentials (7),
+.BR pid_namespaces (7)