Merging upstream version 6.8.

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

1 files changed, 349 insertions, 0 deletions

diff --git a/man/man2/fork.2 b/man/man2/fork.2
new file mode 100644
index 0000000..4857165
--- /dev/null
+++ b/man/man2/fork.2
@@ -0,0 +1,349 @@
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" A few fragments remain from an earlier (1992) page by
+.\" Drew Eckhardt (drew@cs.colorado.edu),
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified by Michael Haardt (michael@moria.de)
+.\" Modified Sat Jul 24 13:22:07 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 21 Aug 1994 by Michael Chastain (mec@shell.portal.com):
+.\"   Referenced 'clone(2)'.
+.\" Modified 1995-06-10, 1996-04-18, 1999-11-01, 2000-12-24
+.\"   by Andries Brouwer (aeb@cwi.nl)
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"     Added notes on capability requirements
+.\" 2006-09-04, Michael Kerrisk
+.\"     Greatly expanded, to describe all attributes that differ
+.\"	parent and child.
+.\"
+.TH fork 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+fork \- create a child process
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.B pid_t fork(void);
+.fi
+.SH DESCRIPTION
+.BR fork ()
+creates a new process by duplicating the calling process.
+The new process is referred to as the
+.I child
+process.
+The calling process is referred to as the
+.I parent
+process.
+.P
+The child process and the parent process run in separate memory spaces.
+At the time of
+.BR fork ()
+both memory spaces have the same content.
+Memory writes, file mappings
+.RB ( mmap (2)),
+and unmappings
+.RB ( munmap (2))
+performed by one of the processes do not affect the other.
+.P
+The child process is an exact duplicate of the parent
+process except for the following points:
+.IP \[bu] 3
+The child has its own unique process ID,
+and this PID does not match the ID of any existing process group
+.RB ( setpgid (2))
+or session.
+.IP \[bu]
+The child's parent process ID is the same as the parent's process ID.
+.IP \[bu]
+The child does not inherit its parent's memory locks
+.RB ( mlock (2),
+.BR mlockall (2)).
+.IP \[bu]
+Process resource utilizations
+.RB ( getrusage (2))
+and CPU time counters
+.RB ( times (2))
+are reset to zero in the child.
+.IP \[bu]
+The child's set of pending signals is initially empty
+.RB ( sigpending (2)).
+.IP \[bu]
+The child does not inherit semaphore adjustments from its parent
+.RB ( semop (2)).
+.IP \[bu]
+The child does not inherit process-associated record locks from its parent
+.RB ( fcntl (2)).
+(On the other hand, it does inherit
+.BR fcntl (2)
+open file description locks and
+.BR flock (2)
+locks from its parent.)
+.IP \[bu]
+The child does not inherit timers from its parent
+.RB ( setitimer (2),
+.BR alarm (2),
+.BR timer_create (2)).
+.IP \[bu]
+The child does not inherit outstanding asynchronous I/O operations
+from its parent
+.RB ( aio_read (3),
+.BR aio_write (3)),
+nor does it inherit any asynchronous I/O contexts from its parent (see
+.BR io_setup (2)).
+.P
+The process attributes in the preceding list are all specified
+in POSIX.1.
+The parent and child also differ with respect to the following
+Linux-specific process attributes:
+.IP \[bu] 3
+The child does not inherit directory change notifications (dnotify)
+from its parent
+(see the description of
+.B F_NOTIFY
+in
+.BR fcntl (2)).
+.IP \[bu]
+The
+.BR prctl (2)
+.B PR_SET_PDEATHSIG
+setting is reset so that the child does not receive a signal
+when its parent terminates.
+.IP \[bu]
+The default timer slack value is set to the parent's
+current timer slack value.
+See the description of
+.B PR_SET_TIMERSLACK
+in
+.BR prctl (2).
+.IP \[bu]
+Memory mappings that have been marked with the
+.BR madvise (2)
+.B MADV_DONTFORK
+flag are not inherited across a
+.BR fork ().
+.IP \[bu]
+Memory in address ranges that have been marked with the
+.BR madvise (2)
+.B MADV_WIPEONFORK
+flag is zeroed in the child after a
+.BR fork ().
+(The
+.B MADV_WIPEONFORK
+setting remains in place for those address ranges in the child.)
+.IP \[bu]
+The termination signal of the child is always
+.B SIGCHLD
+(see
+.BR clone (2)).
+.IP \[bu]
+The port access permission bits set by
+.BR ioperm (2)
+are not inherited by the child;
+the child must turn on any bits that it requires using
+.BR ioperm (2).
+.P
+Note the following further points:
+.IP \[bu] 3
+The child process is created with a single thread\[em]the
+one that called
+.BR fork ().
+The entire virtual address space of the parent is replicated in the child,
+including the states of mutexes, condition variables,
+and other pthreads objects; the use of
+.BR pthread_atfork (3)
+may be helpful for dealing with problems that this can cause.
+.IP \[bu]
+After a
+.BR fork ()
+in a multithreaded program,
+the child can safely call only async-signal-safe functions (see
+.BR signal\-safety (7))
+until such time as it calls
+.BR execve (2).
+.IP \[bu]
+The child inherits copies of the parent's set of open file descriptors.
+Each file descriptor in the child refers to the same
+open file description (see
+.BR open (2))
+as the corresponding file descriptor in the parent.
+This means that the two file descriptors share open file status flags,
+file offset,
+and signal-driven I/O attributes (see the description of
+.B F_SETOWN
+and
+.B F_SETSIG
+in
+.BR fcntl (2)).
+.IP \[bu]
+The child inherits copies of the parent's set of open message
+queue descriptors (see
+.BR mq_overview (7)).
+Each file descriptor in the child refers to the same
+open message queue description
+as the corresponding file descriptor in the parent.
+This means that the two file descriptors share the same flags
+.RI ( mq_flags ).
+.IP \[bu]
+The child inherits copies of the parent's set of open directory streams (see
+.BR opendir (3)).
+POSIX.1 says that the corresponding directory streams
+in the parent and child
+.I may
+share the directory stream positioning;
+on Linux/glibc they do not.
+.SH RETURN VALUE
+On success, the PID of the child process is returned in the parent,
+and 0 is returned in the child.
+On failure, \-1 is returned in the parent,
+no child process is created, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+.\" NOTE! The following should match the description in pthread_create(3)
+A system-imposed limit on the number of threads was encountered.
+There are a number of limits that may trigger this error:
+.RS
+.IP \[bu] 3
+the
+.B RLIMIT_NPROC
+soft resource limit (set via
+.BR setrlimit (2)),
+which limits the number of processes and threads for a real user ID,
+was reached;
+.IP \[bu]
+the kernel's system-wide limit on the number of processes and threads,
+.IR /proc/sys/kernel/threads\-max ,
+was reached (see
+.BR proc (5));
+.IP \[bu]
+the maximum number of PIDs,
+.IR /proc/sys/kernel/pid_max ,
+was reached (see
+.BR proc (5));
+or
+.IP \[bu]
+the PID limit
+.RI ( pids.max )
+imposed by the cgroup "process number" (PIDs) controller was reached.
+.RE
+.TP
+.B EAGAIN
+The caller is operating under the
+.B SCHED_DEADLINE
+scheduling policy and does not have the reset-on-fork flag set.
+See
+.BR sched (7).
+.TP
+.B ENOMEM
+.BR fork ()
+failed to allocate the necessary kernel structures because memory is tight.
+.TP
+.B ENOMEM
+An attempt was made to create a child process in a PID namespace
+whose "init" process has terminated.
+See
+.BR pid_namespaces (7).
+.TP
+.B ENOSYS
+.BR fork ()
+is not supported on this platform (for example,
+.\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa
+hardware without a Memory-Management Unit).
+.TP
+.BR ERESTARTNOINTR " (since Linux 2.6.17)"
+.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56
+System call was interrupted by a signal and will be restarted.
+(This can be seen only during a trace.)
+.SH VERSIONS
+.SS C library/kernel differences
+Since glibc 2.3.3,
+.\" nptl/sysdeps/unix/sysv/linux/fork.c
+rather than invoking the kernel's
+.BR fork ()
+system call,
+the glibc
+.BR fork ()
+wrapper that is provided as part of the
+NPTL threading implementation invokes
+.BR clone (2)
+with flags that provide the same effect as the traditional system call.
+(A call to
+.BR fork ()
+is equivalent to a call to
+.BR clone (2)
+specifying
+.I flags
+as just
+.BR SIGCHLD .)
+The glibc wrapper invokes any fork handlers that have been
+established using
+.BR pthread_atfork (3).
+.\" and does some magic to ensure that getpid(2) returns the right value.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4, 4.3BSD.
+.SH NOTES
+Under Linux,
+.BR fork ()
+is implemented using copy-on-write pages, so the only penalty that it incurs
+is the time and memory required to duplicate the parent's page tables,
+and to create a unique task structure for the child.
+.SH EXAMPLES
+See
+.BR pipe (2)
+and
+.BR wait (2)
+for more examples.
+.P
+.\" SRC BEGIN (fork.c)
+.EX
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <unistd.h>
+\&
+int
+main(void)
+{
+    pid_t pid;
+\&
+    if (signal(SIGCHLD, SIG_IGN) == SIG_ERR) {
+        perror("signal");
+        exit(EXIT_FAILURE);
+    }
+    pid = fork();
+    switch (pid) {
+    case \-1:
+        perror("fork");
+        exit(EXIT_FAILURE);
+    case 0:
+        puts("Child exiting.");
+        exit(EXIT_SUCCESS);
+    default:
+        printf("Child is PID %jd\en", (intmax_t) pid);
+        puts("Parent exiting.");
+        exit(EXIT_SUCCESS);
+    }
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR clone (2),
+.BR execve (2),
+.BR exit (2),
+.BR setrlimit (2),
+.BR unshare (2),
+.BR vfork (2),
+.BR wait (2),
+.BR daemon (3),
+.BR pthread_atfork (3),
+.BR capabilities (7),
+.BR credentials (7)