doc/man3/forker.3

.\"
.\" $Id: forker.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\" 
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\" 
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\" 
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc., 59
.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
.\" 
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\" 
.\" http://www.sgi.com 
.\" 
.\" For further information regarding this notice, see: 
.\" 
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH FORKER 3 07/25/2000 "Linux Test Project"
.SH NAME
forker \- fork desired number of copies of the current process
.br
background \- fork a process and return control to caller

.SH SYNOPSIS
int 
.br
\fBbackground\fR(\fIprefix\fR)
.br
char *\fIprefix\fR;

int
.br
\fBforker\fR(\fIncopies, mode, prefix\fR)
.br
int \fIncopies\fR;
.br
int \fImode\fR;
.br
char *\fIprefix\fR;

extern int \fBForker_pids\fR[];
.br
extern int \fBForker_npids\fR;

.SH DESCRIPTION
The \fBbackground\fR function will do a fork of the current process.
The parent process will then exit, thus orphaning the
child process.  Doing this will not nice the child process
like executing a cmd in the background using "&" from the shell.
If the fork fails and prefix is not NULL, a error message is printed
to stderr and the process will exit with a value of errno.

The \fBforker\fR function will fork \fIncopies\fR minus one copies
of the current process.  There are two modes in how the forks
will be done.  Mode 0 (default) will have all new processes
be children of the parent process.    Using Mode 1,
the parent process will have one child and that child will
fork the next process, if necessary, and on and on.
The \fBforker\fR function will return the number of successful
forks.  This value will be different for the parent and each child.
Using mode 0, the parent will get the total number of successful
forks.  Using mode 1, the newest child will get the total number
of forks.  The parent will get a return value of 1.

The \fBforker \fRfunction also updates the global variables
\fIForker_pids[\fR] and Forker_npids.  The \fIForker_pids\fR array will
be updated to contain the pid of each new process.  The
\fIForker_npids\fR variable contains the number of entries
in \fIForker_pids.\fR  Note, not all processes will have
access to all pids via \fIForker_pids.\fR  If using mode 0, only the
parent process will have all information.  If using mode 1,
only the last child process will have all information.

If the \fIprefix\fR parameter is not NULL and the fork system call fails,
a error message will be printed to stderr.  The error message
will be preceded with \fIprefix\fR string.  If \fIprefix\fR is NULL,
no error message is printed.

.SH EXAMPLES

.nf
.in +3
/*
 * The following is a unit test main for the background and forker
 * functions.
 */

#include <stdio.h>

main(argc, argv)
int argc;
char **argv;
{
    int ncopies=1;
    int mode=0;
    int ret;

    if ( argc == 1 ) {
        printf("Usage: %s ncopies [mode]\n", argv[0]);
        exit(1);
    }

    if ( sscanf(argv[1], "%i", &ncopies) != 1 ) {
        printf("%s: ncopies argument must be integer\n", argv[0]);
        exit(1);
    }

    if ( argc == 3 )
        if ( sscanf(argv[2], "%i", &mode) != 1 ) {
        printf("%s: mode argument must be integer\n", argv[0]);
        exit(1);
    }

    printf("Starting Pid = %d\n", getpid());
    ret=background(argv[0]);
    printf("After background() ret:%d, pid = %d\n", ret, getpid());

    ret=forker(ncopies, mode, argv[0]);

    printf("forker(%d, %d, %s) ret:%d, pid = %d, sleeping 30 seconds.\n",
        ncopies, mode, argv[0], ret, getpid());
    sleep(30);
    exit(0);
}
.in -3
.fi

.SH "SEE ALSO"
fork(2).

.SH BUGS
The child pids are stored in the fixed array, \fIForker_pids\fR.
The array only has space for 4098 pids.  Only the first
4098 pids will be stored in the array.