Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <process.h>
    int spawnl(   mode, path, arg0, arg1..., argn, NULL );
    int spawnle(  mode, path, arg0, arg1..., argn, NULL, envp);
    int spawnlp(  mode, file, arg0, arg1..., argn, NULL );
    int spawnlpe( mode, file, arg0, arg1..., argn, NULL, envp);
    int spawnv(   mode, path, argv );
    int spawnve(  mode, path, argv, envp );
    int spawnvp(  mode, file, argv );
    int spawnvpe( mode, file, argv, envp );
      int         mode;             /* mode for parent      */
      const char *path;             /* file name incl. path */
      const char *file;             /* file name            */
      const char *arg0, ..., *argn; /* arguments            */
      char *const argv[];           /* array of arguments   */
      char *const envp[];           /* environment strings  */

Description:
    The spawn functions create and execute a new child process, named by
    pgm.  The value of mode determines how the program is loaded and how the
    invoking program will behave after the invoked program is initiated:

    P_WAIT
        The invoked program is loaded into available memory, is executed,
        and then the original program resumes execution.

    P_NOWAIT
        Causes the current program to execute concurrently with the new
        child process.

    P_NOWAITO
        Causes the current program to execute concurrently with the new
        child process.  The functions  wait and  cwait are ignored.

    P_OVERLAY
        The invoked program replaces the original program in memory and is
        executed.  No return is made to the original program.  This is
        equivalent to calling the appropriate  exec function.   P_OVERLAY is
        only supported on those systems that also support the  exec function
        (see the description of the  exec function for more information).

    The program is located by using the following logic in sequence:

     1. An attempt is made to locate the program in the current working
        directory if no directory specification precedes the program name;
        otherwise, an attempt is made in the specified directory.

     2. If no file extension is given, an attempt is made to find the
        program name, in the directory indicated in the first point, with
        .COM concatenated to the end of the program name.

     3. If no file extension is given, an attempt is made to find the
        program name, in the directory indicated in the first point, with
        .EXE concatenated to the end of the program name.

     4. When no directory specification is given as part of the program
        name, the  spawnlp,  spawnlpe,  spawnvp, and  spawnvpe functions
        will repeat the preceding three steps for each of the directories
        specified by the  PATH environment variable.  The command


             path c:\myapps;d:\lib\applns

        indicates that the two directories


             c:\myapps
             d:\lib\applns

        are to be searched.  The DOS PATH command (without any directory
        specification) will cause the current path definition to be
        displayed.

    An error is detected when the program cannot be found.

    Arguments are passed to the child process by supplying one or more
    pointers to character strings as arguments in the spawn call.  These
    character strings are concatenated with spaces inserted to separate the
    arguments to form one argument string for the child process.  The length
    of this concatenated string must not exceed 128 bytes for DOS systems.

    The arguments may be passed as a list of arguments ( spawnl,  spawnle,
     spawnlp and  spawnlpe) or as a vector of pointers ( spawnv,  spawnve,
     spawnvp, and  spawnvpe).  At least one argument, arg0 or argv[0], must
    be passed to the child process.  By convention, this first argument is a
    pointer to the name of the program.

    If the arguments are passed as a list, there must be a NULL pointer to
    mark the end of the argument list.  Similarly, if a pointer to an
    argument vector is passed, the argument vector must be terminated by a
    NULL pointer.

    The environment for the invoked program is inherited from the parent
    process when you use the  spawnl,  spawnlp,  spawnv and  spawnvp
    functions.  The  spawnle,  spawnlpe,  spawnve and  spawnvpe functions
    allow a different environment to be passed to the child process through
    the envp argument.  The argument envp is a pointer to an array of
    character pointers, each of which points to a string defining an
    environment variable.  The array is terminated with a NULL pointer.
     Each pointer locates a character string of the form


             variable=value

    that is used to define an environment variable.  If the value of envp is
    NULL, then the child process inherits the environment of the parent
    process.

    The environment is the collection of environment variables whose values
    that have been defined with the DOS SET command or by the successful
    execution of the  putenv function.  A program may read these values with
    the  getenv function.

Returns:
    When the value of mode is  P_WAIT, then the return value from spawn is
    the exit status of the child process.

    When the value of mode is  P_NOWAIT or  P_NOWAITO, then the return value
    from spawn is the process id of the child process.  To obtain the exit
    code for a process spawned with  P_NOWAIT, you must call the  wait or
     cwait function specifying the process id.  The exit code cannot be
    obtained for a process spawned with  P_NOWAITO.

    When an error is detected while invoking the indicated program, spawn
    returns -1 and  errno is set to indicate the error.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    E2BIG
        The argument list exceeds 128 bytes, or the space required for the
        environment information exceeds 32K.

    EINVAL
        The mode argument is invalid.

    ENOENT
        Path or file not found

    ENOMEM
        Not enough memory is available to execute the child process.


See Also:
    abort, atexit, cwait, exec Functions Functions, exit, _exit, getcmd, getenv, main,
    putenv, system, wait

Example:
    #include <stddef.h>
    #include <process.h>

    spawnl( P_WAIT, "myprog",
            "myprog", "ARG1", "ARG2", NULL );

    The preceding invokes "myprog" as if

        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe

    is found in the current working directory.

    #include <stddef.h>
    #include <process.h>

    char *env_list[] = { "SOURCE=MYDATA",
                         "TARGET=OUTPUT",
                         "lines=65",
                         NULL
                        };

    spawnle( P_WAIT, "myprog",
            "myprog", "ARG1", "ARG2", NULL,
             env_list );

    The preceding invokes "myprog" as if

        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe

    is found in the current working directory.  The DOS environment for the
    invoked program will consist of the three environment variables SOURCE,
    TARGET and lines.

    #include <stddef.h>
    #include <process.h>

    char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL };

    spawnv( P_WAIT, "myprog", arg_list );

    The preceding invokes "myprog" as if

        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe
    is found in the current working directory.

Classification:
    WATCOM

Systems:
     spawnl - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT

    spawnle - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnlp - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnlpe - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnv - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnve - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnvp - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
    spawnvpe - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT