lib/libc/sys/fork.2

   1 .\"     $NetBSD: fork.2,v 1.22 2004/06/25 15:29:25 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)fork.2      8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd June 10, 2004
  33 .Dt FORK 2
  34 .Os
  35 .Sh NAME
  36 .Nm fork
  37 .Nd create a new process
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft pid_t
  43 .Fn fork void
  44 .Sh DESCRIPTION
  45 .Fn fork
  46 causes creation of a new process.
  47 The new process (child process) is an exact copy of the
  48 calling process (parent process) except for the following:
  49 .Bl -bullet -offset indent
  50 .It
  51 The child process has a unique process ID.
  52 .It
  53 The child process has a different parent
  54 process ID (i.e., the process ID of the parent process).
  55 .It
  56 The child process has its own copy of the parent's descriptors.
  57 These descriptors reference the same underlying objects, so that,
  58 for instance, file pointers in file objects are shared between
  59 the child and the parent, so that an
  60 .Xr lseek 2
  61 on a descriptor in the child process can affect a subsequent
  62 .Xr read 2
  63 or
  64 .Xr write 2
  65 by the parent.
  66 This descriptor copying is also used by the shell to
  67 establish standard input and output for newly created processes
  68 as well as to set up pipes.
  69 .It
  70 The child process' resource utilizations
  71 are set to 0; see
  72 .Xr setrlimit 2 .
  73 .El
  74 .Pp
  75 In general, the child process should call
  76 .Xr _exit 2
  77 rather than
  78 .Xr exit 3 .
  79 Otherwise, any stdio buffers that exist both in the parent and child
  80 will be flushed twice.
  81 Similarly,
  82 .Xr _exit 2
  83 should be used to prevent
  84 .Xr atexit 3
  85 routines from being called twice (once in the parent and once in the child).
  86 .Pp
  87 In case of a threaded program, only the thread calling
  88 .Fn fork
  89 is still running in the child processes.
  90 .Pp
  91 Child processes of a threaded program have additional restrictions,
  92 a child must only call functions that are async-signal-safe.
  93 Very few functions are asynchronously safe and applications should
  94 make sure they call
  95 .Xr exec 3
  96 as soon as possible.
  97 .Sh RETURN VALUES
  98 Upon successful completion,
  99 .Fn fork
 100 returns a value
 101 of 0 to the child process and returns the process ID of the child
 102 process to the parent process.
 103 Otherwise, a value of \-1 is returned to the parent process, no
 104 child process is created, and the global variable
 105 .Va errno
 106 is set to indicate the error.
 107 .Sh ERRORS
 108 .Fn fork
 109 will fail and no child process will be created if:
 110 .Bl -tag -width [EAGAIN]
 111 .It Bq Er EAGAIN
 112 The system-imposed limit on the total
 113 number of processes under execution would be exceeded.
 114 This limit is configuration-dependent.
 115 .It Bq Er EAGAIN
 116 The limit
 117 .Dv RLIMIT_NPROC
 118 on the total number of
 119 processes under execution by this user id would be exceeded.
 120 .It Bq Er ENOMEM
 121 There is insufficient swap space for the new process.
 122 .El
 123 .Sh SEE ALSO
 124 .Xr execve 2 ,
 125 .Xr setrlimit 2 ,
 126 .Xr vfork 2 ,
 127 .Xr wait 2 ,
 128 .Xr pthread_atfork 3
 129 .Sh STANDARDS
 130 The
 131 .Fn fork
 132 function conforms to
 133 .St -p1003.1-90 .
 134 .Sh HISTORY
 135 A
 136 .Fn fork
 137 system call appeared in
 138 .At v6 .