FORK(2)                          System Calls                          FORK(2)

NAME

       fork, fork2, vfork - start a new process from inside the current appli‐
       cation space

SYNOPSIS

       #include <unistd.h>

       int fork (void *proc);
       int vfork (void *proc);
       int fork2 (void *proc, unsigned short stack, unsigned short prio,  char
       *procname, unsigned short numargs, ...);

DESCRIPTION

       fork causes the creation of a new process.

       fork's argument proc is typically the address of a C function, although
       it can be any valid address inside the IIgs RAM space.  In a successful
       fork  call, the parent process resumes execution by returning from fork
       and, under GNO, the child process resumes execution at the  entry  into
       function  proc.   This  is  different from traditional Unix implementa‐
       tions.

       fork creates a new entry in the process table, and sets up default set‐
       tings 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  mem‐
       ory.   The process is executed in 16-bit full native mode, and the reg‐
       isters upon entry to the routine are set as follows:

              A    the userID assigned to the new process
              X    0
              Y    0

       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.

       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 ex‐
       clusion,  either  the  kernel semaphore(2) routines or custom routines.
       This includes C stdio routines.

       There is no way to pass parameters directly to a child with fork.   Use
       fork2 instead.

       Under  GNO,  vfork  is identical to fork; other than the proc parameter
       (and therefore the point at which the child process resumes execution),
       vfork  is  the same as the BSD implementation in that the two processes
       share an address space.

       fork2 is similar to fork(2), except that it  allows  parameters  to  be
       passed both to proc and the execution environment:

              stack  is  the  number  of  bytes  of  stack  to allocate to the
                     proess. If stack is not a multiple of  256,  then  it  is
                     rounded up to the next highest multiple of 256 bytes.

              prio   is  the priority to assign to the process. Priorities are
                     not currently implemented, and you should pass 0 for this
                     argument.

              procname
                     is a string you can have associated with the process when
                     viewing the process table (See ps(1)).

              numargs
                     is the number of (16-bit) words of arguments  which  fol‐
                     low,  not the number of arguments.  Any arguments follow‐
                     ing numargs are passed as parameters to the child's  pro‐
                     cedure.
       See below for an example of the use of fork2.

RETURN VALUE

       On  success  fork, vfork, and fork2 return to the parent the process ID
       of the new (child) process.  On failure, -1 is returned  and  errno  is
       set.

CAVEATS

       Care  must  be  taken such that the child process does not call exit(3)
       either directly or by function call, since exit will  flush  and  close
       standard  I/O  data structures.  Instead, if the child process does not
       or cannot execve(2), it should call _exit(3).

       ORCA/C's stack checking and stack repair code should be turned off when
       compiling  routines  containing  these  functions.   See  occ(1) or the
       ORCA/C Reference Manual for details.

       Because the fork functions are called from the kernel (which is  imple‐
       mented  as  a  user tool set), the child function proc must restore the
       data bank register if it is going to access global variables.  See  the
       description  of  the databank pragma in the ORCA/C Reference Manual for
       details.

       While Splat!  is an excellent source level debugger, it is (at the time
       of  this  writing)  unable  to  handle the execution of fork, fork2, or
       vfork calls.  If you attempt to do so, your machine  will  almost  cer‐
       tainly crash.  Otherwise, 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 Splat!)

CONFORMANCE

       Most Unix forks 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 fork will have to
       be modified slightly to work under GNO.

       The implementation of fork is therefore not  POSIX conforming,  nor  is
       the  implementation of vfork conforming to traditional Unix implementa‐
       tions.

EXAMPLE

       int main (int argc, char **argv) {
          ...
          pid = fork2(proc1,1024,0,"sub-process",3,argc,argv);
          ...
          return 0;
       }

       void proc1(int argc, char *argv[])
       {
          ...
       }

HISTORY

       fork2 first appeared in XINU.

       vfork first appeared in 3.0BSD.

SEE ALSO

       occ(1), exec(2), execve(2), semaphore(2), wait(2), the GNO Kernel  Ref���
       erence Manual, and the ORCA/C Reference Manual.



16 January 1997                       GNO                              FORK(2)