diff options
Diffstat (limited to 'lib/libc/sys/fork.2')
| -rw-r--r-- | lib/libc/sys/fork.2 | 270 |
1 files changed, 0 insertions, 270 deletions
diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 deleted file mode 100644 index eb9cfcd6130c..000000000000 --- a/lib/libc/sys/fork.2 +++ /dev/null @@ -1,270 +0,0 @@ -.\" Copyright (c) 1980, 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)fork.2 8.1 (Berkeley) 6/4/93 -.\" -.Dd August 5, 2021 -.Dt FORK 2 -.Os -.Sh NAME -.Nm fork -.Nd create a new process -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In unistd.h -.Ft pid_t -.Fn fork void -.Ft pid_t -.Fn _Fork void -.Sh DESCRIPTION -The -.Fn fork -function causes creation of a new process. -The new process (child process) is an exact copy of the -calling process (parent process) except for the following: -.Bl -bullet -offset indent -.It -The child process has a unique process ID. -.It -The child process has a different parent -process ID (i.e., the process ID of the parent process). -.It -The child process has its own copy of the parent's descriptors, -except for descriptors returned by -.Xr kqueue 2 , -which are not inherited from the parent process. -These descriptors reference the same underlying objects, so that, -for instance, file pointers in file objects are shared between -the child and the parent, so that an -.Xr lseek 2 -on a descriptor in the child process can affect a subsequent -.Xr read 2 -or -.Xr write 2 -by the parent. -This descriptor copying is also used by the shell to -establish standard input and output for newly created processes -as well as to set up pipes. -.It -The child process' resource utilizations -are set to 0; see -.Xr setrlimit 2 . -.It -All interval timers are cleared; see -.Xr setitimer 2 . -.It -The robust mutexes list (see -.Xr pthread_mutexattr_setrobust 3 ) -is cleared for the child. -.It -The atfork handlers established with the -.Xr pthread_atfork 3 -function are called as appropriate before fork in the parent process, -and after the child is created, in parent and child. -.It -The child process has only one thread, -corresponding to the calling thread in the parent process. -If the process has more than one thread, -locks and other resources held by the other threads are not released -and therefore only async-signal-safe functions -(see -.Xr sigaction 2 ) -are guaranteed to work in the child process until a call to -.Xr execve 2 -or a similar function. -The -.Fx -implementation of -.Fn fork -provides a usable -.Xr malloc 3 , -and -.Xr rtld 1 -services in the child process. -.El -.Pp -The -.Fn fork -function is not async-signal safe and creates a cancellation point -in the parent process. -It cannot be safely used from signal handlers, and the atfork handlers -established by -.Xr pthread_atfork 3 -do not need to be async-signal safe either. -.Pp -The -.Fn _Fork -function creates a new process, similarly to -.Fn fork , -but it is async-signal safe. -.Fn _Fork -does not call atfork handlers, and does not create a cancellation point. -It can be used safely from signal handlers, but then no userspace -services ( -.Xr malloc 3 -or -.Xr rtld 1 ) -are available in the child if forked from multi-threaded parent. -In particular, if using dynamic linking, all dynamic symbols used by the -child after -.Fn _Fork -must be pre-resolved. -Note: resolving can be done globally by specifying the -.Ev LD_BIND_NOW -environment variable to the dynamic linker, or per-binary by passing the -.Fl z Ar now -option to the static linker -.Xr ld 1 , -or by using each symbol before the -.Fn _Fork -call to force the binding. -.Sh RETURN VALUES -Upon successful completion, -.Fn fork -and -.Fn _Fork -return a value -of 0 to the child process and return the process ID of the child -process to the parent process. -Otherwise, a value of -1 is returned -to the parent process, no child process is created, and the global -variable -.Va errno -is set to indicate the error. -.Sh EXAMPLES -The following example shows a common pattern of how -.Fn fork -is used in practice. -.Bd -literal -offset indent -#include <err.h> -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> - -int -main(void) -{ - pid_t pid; - - /* - * If child is expected to use stdio(3), state of - * the reused io streams must be synchronized between - * parent and child, to avoid double output and other - * possible issues. - */ - fflush(stdout); - - switch (pid = fork()) { - case -1: - err(1, "Failed to fork"); - case 0: - printf("Hello from child process!\en"); - - /* - * Since we wrote into stdout, child needs to use - * exit(3) and not _exit(2). This causes handlers - * registered with atexit(3) to be called twice, - * once in parent, and once in the child. If such - * behavior is undesirable, consider - * terminating child with _exit(2) or _Exit(3). - */ - exit(0); - default: - break; - } - - printf("Hello from parent process (child's PID: %d)!\en", pid); - - return (0); -} -.Ed -.Pp -The output of such a program is along the lines of: -.Bd -literal -offset indent -Hello from parent process (child's PID: 27804)! -Hello from child process! -.Ed -.Sh ERRORS -The -.Fn fork -system call will fail and no child process will be created if: -.Bl -tag -width Er -.It Bq Er EAGAIN -The system-imposed limit on the total -number of processes under execution would be exceeded. -The limit is given by the -.Xr sysctl 3 -MIB variable -.Dv KERN_MAXPROC . -(The limit is actually ten less than this -except for the super user). -.It Bq Er EAGAIN -The user is not the super user, and -the system-imposed limit -on the total number of -processes under execution by a single user would be exceeded. -The limit is given by the -.Xr sysctl 3 -MIB variable -.Dv KERN_MAXPROCPERUID . -.It Bq Er EAGAIN -The user is not the super user, and -the soft resource limit corresponding to the -.Fa resource -argument -.Dv RLIMIT_NPROC -would be exceeded (see -.Xr getrlimit 2 ) . -.It Bq Er ENOMEM -There is insufficient swap space for the new process. -.El -.Sh SEE ALSO -.Xr execve 2 , -.Xr rfork 2 , -.Xr setitimer 2 , -.Xr setrlimit 2 , -.Xr sigaction 2 , -.Xr vfork 2 , -.Xr wait 2 , -.Xr pthread_atfork 3 -.Sh HISTORY -The -.Fn fork -function appeared in -.At v1 . -.Pp -The -.Fn _Fork -function was defined by Austin Group together with the removal -of a requirement that the -.Fn fork -implementation must be async-signal safe. -The -.Fn _Fork -function appeared in -.Fx 14.0 . |