diff options
Diffstat (limited to 'man2/fork.2')
| -rw-r--r-- | man2/fork.2 | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/man2/fork.2 b/man2/fork.2 new file mode 100644 index 0000000..607a86b --- /dev/null +++ b/man2/fork.2 @@ -0,0 +1,348 @@ +.\" 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 2023-05-03 "Linux man-pages 6.05.01" +.SH NAME +fork \- create a child process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.PP +.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. +.PP +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. +.PP +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)). +.PP +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). +.PP +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. +.PP +.\" SRC BEGIN (fork.c) +.EX +#include <signal.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.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) |