.\" .\" Devin Reade, 1997 .\" .\" $Id: fork.2,v 1.1 1997/02/27 07:32:12 gdr Exp $ .\" .\" .TH FORK2 2 GNO "System Calls" "16 December 1996" .TH FORK 2 GNO "16 January 1997" "System Calls" .SH NAME .BR fork , .BR fork2 , .BR vfork \- start a new process from inside the current application space .SH SYNOPSIS #include .sp 1 int \fBfork\fR (void *\fIproc\fR); .br int \fBvfork\fR (void *\fIproc\fR); .br int \fBfork2\fR (void *\fIproc\fR, unsigned short \fIstack\fR, unsigned short \fIprio\fR, char *\fIprocname\fR, unsigned short \fInumargs\fR, ...); .SH DESCRIPTION .BR fork causes the creation of a new process. .LP .BR fork 's argument .IR proc is typically the address of a C function, although it can be any valid address inside the IIgs RAM space. In a successful .BR fork call, the parent process resumes execution by returning from .BR fork and, under GNO, the child process resumes execution at the entry into function .IR proc . This is different from traditional Unix implementations. .LP .BR fork creates a new entry in the process table, and sets up default settings for the new process. The process is allocated 1k (1024 bytes) of stack space, and the direct page is set to the beginning of this memory. The process is executed in 16-bit full native mode, and the registers upon entry to the routine are set as follows: .RS .nf A the userID assigned to the new process X 0 Y 0 .fi .RE .LP The child inherits the memory shadowing and machine state parameters of the parent, as well as signal blocking information and the ID of the controlling TTY. In addition, the child inherits all the open files of its parent. .LP A forked process may share code with other children or the parent. However, this is only allowed in a forward manner; any forked process that exits by function return will be terminated. Note that any shared global variables will need to be moderated with some type of mutual exclusion, either the kernel .BR semaphore (2) routines or custom routines. This includes C stdio routines. .LP There is no way to pass parameters directly to a child with .BR fork . Use .BR fork2 instead. .LP Under GNO, .BR vfork is identical to .BR fork ; other than the .IR proc parameter (and therefore the point at which the child process resumes execution), .BR vfork is the same as the BSD implementation in that the two processes share an address space. .LP .B fork2 is similar to .BR fork (2), except that it allows parameters to be passed both to .IR proc and the execution environment: .RS .IP \fIstack\fR is the number of bytes of stack to allocate to the proess. If .I stack is not a multiple of 256, then it is rounded up to the next highest multiple of 256 bytes. .IP \fIprio\fR is the priority to assign to the process. Priorities are not currently implemented, and you should pass 0 for this argument. .IP \fIprocname\fR is a string you can have associated with the process when viewing the process table (See .BR ps (1)). .IP \fInumargs\fR is the number of (16-bit) .B words of arguments which follow, not the number of arguments. Any arguments following .I numargs are passed as parameters to the child's procedure. .RE See below for an example of the use of .BR fork2 . .SH "RETURN VALUE" On success .BR fork , .BR vfork , and .BR fork2 return to the parent the process ID of the new (child) process. On failure, -1 is returned and .B errno is set. .SH CAVEATS Care must be taken such that the child process does not call .BR exit (3) either directly or by function call, since .BR exit will flush and close standard I/O data structures. Instead, if the child process does not or cannot .BR execve (2), it should call .BR _exit (3). .LP Orca/C's stack checking and stack repair code should be turned off when compiling routines containing these functions. See .BR occ (1) or the Orca/C Reference Manual for details. .LP Because the .BR fork functions are called from the kernel (which is implemented as a user tool set), the child function .IR proc must restore the data bank register if it is going to access global variables. See the description of the .BR databank pragma in the Orca/C Reference Manual for details. .LP While .BR Splat! is an excellent source level debugger, it is (at the time of this writing) unable to handle the execution of .BR fork , .BR fork2 , or .BR vfork calls. If you attempt to do so, your machine will almost certainly crash. Otherwise, .BR Splat! is strongly recommended as a powerful tool for GNO programmers using C as their source language. (For the record, the author of this manual page receives no renumeration from the sales of .BR Splat! ) .SH CONFORMANCE Most Unix .BR fork s take no parameters; they copy the entire address space of the calling process and return witha different value in the parent and child. Due to hardware limitations, this sort of manipulation isn't possible on the IIgs. Unix programs utilizing .BR fork will have to be modified slightly to work under GNO. .LP The implementation of .BR fork is therefore not POSIX conforming, nor is the implementation of .BR vfork conforming to traditional Unix implementations. .SH EXAMPLE .nf int main (int argc, char **argv) { ... pid = fork2(proc1,1024,0,"sub-process",3,argc,argv); ... return 0; } void proc1(int argc, char *argv[]) { ... } .fi .SH HISTORY .B fork2 first appeared in XINU. .LP .B vfork first appeared in 3.0BSD. .SH "SEE ALSO" .BR occ (1), .BR exec (2), .BR execve (2), .BR semaphore (2), .BR wait (2), the .IR "GNO Kernel Reference Manual" , and the .IR "Orca/C Reference Manual" .