share/man/man9/fork1.9

   1 .\"     $NetBSD: fork1.9,v 1.13 2008/01/04 23:43:56 mjf Exp $
   2 .\"
   3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
   8 .\" NASA Ames Research Center.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  21 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  23 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29 .\" POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .Dd January 4, 2008
  32 .Dt FORK1 9
  33 .Os
  34 .Sh NAME
  35 .Nm fork1
  36 .Nd create a new process
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/proc.h
  40 .Ft int
  41 .Fn "fork1" "struct lwp *l1" "int flags" "int exitsig" "void *stack" "size_t stacksize" "void (*func)(void *)" "void *arg" "register_t *retval" "struct proc **rnewprocp"
  42 .Sh DESCRIPTION
  43 .Fn fork1
  44 creates a new process out of the process behind
  45 .Ar l1 ,
  46 which is assumed to be the current lwp.
  47 This function is used primarily to implement the
  48 .Xr fork 2
  49 and
  50 .Xr vfork 2
  51 system calls, but is versatile enough to be used as a backend for
  52 e.g. the
  53 .Xr __clone 2
  54 call.
  55 .Pp
  56 The
  57 .Ar flags
  58 argument controls the semantics of the fork operation, and is made up of
  59 the bitwise-OR of the following values:
  60 .Bl -tag -width FORK_SHAREFILES
  61 .It FORK_PPWAIT
  62 The parent process will sleep until the child process successfully calls
  63 .Xr execve 2
  64 or exits (either by a call to
  65 .Xr _exit 2
  66 or abnormally).
  67 .It FORK_SHAREVM
  68 The child process will share the parent's virtual address space.
  69 If this flag is not specified, the child will get a copy-on-write
  70 snapshot of the parent's address space.
  71 .It FORK_SHARECWD
  72 The child process will share the parent's current directory, root directory,
  73 and file creation mask.
  74 .It FORK_SHAREFILES
  75 The child process will share the parent's file descriptors.
  76 .It FORK_SHARESIGS
  77 The child process will share the parent's signal actions.
  78 .It FORK_NOWAIT
  79 The child process will at creation time be inherited by the init process.
  80 .It FORK_CLEANFILES
  81 The child process will not copy or share the parent's descriptors, but
  82 rather will start out with a clean set.
  83 .El
  84 .Pp
  85 A
  86 .Ar flags
  87 value of 0 indicates a standard fork operation.
  88 .Pp
  89 The
  90 .Ar exitsig
  91 argument controls the signal sent to the parent on child death.
  92 If normal operation desired, SIGCHLD should be supplied.
  93 .Pp
  94 It is possible to specify the child userspace stack location and size
  95 by using the
  96 .Ar stack
  97 and
  98 .Ar stacksize
  99 arguments, respectively.
 100 Values
 101 .Dv NULL
 102 and 0, respectively, will give the child the default values
 103 for the machine architecture in question.
 104 .Pp
 105 The arguments
 106 .Ar func
 107 and
 108 .Ar arg
 109 can be used to specify a kernel function to be called when the child process
 110 returns instead of
 111 .Fn child_return .
 112 These are used for example in starting the init process and creating kernel
 113 threads.
 114 .Pp
 115 The
 116 .Ar retval
 117 argument is provided for the use of system call stubs.
 118 If
 119 .Ar retval
 120 is not NULL, it will hold the following values after successful completion
 121 of the fork operation:
 122 .Bl -tag -width retval[0]
 123 .It Ar retval[0]
 124 This will contain the pid of the child process.
 125 .It Ar retval[1]
 126 In the parent process, this will contain the value 0.
 127 In the child process, this will contain 1.
 128 .El
 129 .Pp
 130 User level system call stubs typically subtract 1 from
 131 .Ar retval[1]
 132 and bitwise-AND it with
 133 .Ar retval[0] ,
 134 thus returning the pid to the parent process and 0 to the child.
 135 .Pp
 136 If
 137 .Ar rnewprocp
 138 is not NULL,
 139 .Ar *rnewprocp
 140 will point to the newly created process upon successful completion of
 141 the fork operation.
 142 .Sh RETURN VALUES
 143 Upon successful completion of the fork operation,
 144 .Fn fork1
 145 returns 0.
 146 Otherwise, the following error values are returned:
 147 .Bl -tag -width [EAGAIN]
 148 .It Bq Er EAGAIN
 149 The limit on the total number of system processes would be exceeded.
 150 .It Bq Er EAGAIN
 151 The limit
 152 .Dv RLIMIT_NPROC
 153 on the total number of processes under execution by this
 154 user id would be exceeded.
 155 .El
 156 .Sh SEE ALSO
 157 .Xr execve 2 ,
 158 .Xr fork 2 ,
 159 .Xr vfork 2