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            */
      const char *const argv[];     /* array of arguments   */
      const char *const envp[];     /* environment strings  */
    int _wspawnl(   mode, path, arg0, arg1..., argn, NULL );
    int _wspawnle(  mode, path, arg0, arg1..., argn, NULL, envp);
    int _wspawnlp(  mode, file, arg0, arg1..., argn, NULL );
    int _wspawnlpe( mode, file, arg0, arg1..., argn, NULL, envp);
    int _wspawnv(   mode, path, argv );
    int _wspawnve(  mode, path, argv, envp );
    int _wspawnvp(  mode, file, argv );
    int _wspawnvpe( mode, file, argv, envp );
      int            mode;             /* mode for parent      */
      const wchar_t *path;             /* file name incl. path */
      const wchar_t *file;             /* file name            */
      const wchar_t *arg0, ..., *argn; /* arguments            */
      const wchar_t *const argv[];     /* array of arguments   */
      const wchar_t *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:

    Mode     Meaning

P_WAIT
    The invoked program is loaded into available memory, is executed, and
    then the original program resumes execution.  This option is supported
    under DOS, OS/2, Win32 and QNX.

P_NOWAIT
    Causes the current program to execute concurrently with the new child
    process.  This option is supported under OS/2, Win32 and QNX.

P_NOWAITO
    Causes the current program to execute concurrently with the new child
    process.  This option is supported under OS/2, Win32 and QNX.  The  wait
    and  cwait functions cannot be used to obtain the exit code.

P_OVERLAY
    The invoked program replaces the original program in memory and is
    executed.  No return is made to the original program.  This option is
    supported under DOS (16-bit only), OS/2, Win32, and QNX.  This is
    equivalent to calling the appropriate  exec function.

    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.  The wide-character  _wspawnl,  _wspawnle,
     _wspawnlp,  _wspawnlpe,  _wspawnv,  _wspawnve,  _wspawnvp and
     _wspawnvpe functions are similar to their counterparts but operate on
    wide-character strings.

    The following example invokes "myprog" as if myprog ARG1 ARG2 had been
    entered as a command to DOS.


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

    The program will be found if one of "myprog.", "myprog.com", or
    "myprog.exe" is found in the current working directory.

    The following example includes a new environment for "myprog".


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

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

    The environment for the invoked program will consist of the three
    environment variables SOURCE, TARGET and lines.

    The following example is another variation on the first example.


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

         spawnv( P_WAIT, "myprog", arg_list );


Returns:
    When the value of mode is:

    Mode     Meaning

P_WAIT
    then the return value from spawn is the exit status of the child
    process.

P_NOWAIT
    then the return value from spawn is the process id (or process handle
    under Win32) of the child process.  To obtain the exit code for a
    process spawned with  P_NOWAIT, you must call the  wait (under OS/2 or
    QNX) or  cwait (under OS/2 or Win32) function specifying the process
    id/handle.  If the child process terminated normally, then the low order
    byte of the returned status word will be set to 0, and the high order
    byte will contain the low order byte of the return code that the child
    process passed to the  DOSEXIT function.

P_NOWAITO
    then the return value from spawn is the process id of the child process.
     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.

    Constant     Meaning

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.


Example:
    #include <stdio.h>
    #include <stdlib.h>
    #include <process.h>
    #include <errno.h>
    #include <string.h>

    void main()
      {
        int   process_id, status, rc;

        process_id = spawnl( P_NOWAIT, "child.exe",
                   "child", "5", NULL );
        if( process_id == -1 ) {
          printf( "spawn failed - %s\n", strerror( errno ) );
          exit( EXIT_FAILURE );
        }
        printf( "Process id = %d\n", process_id );

    #if defined(__OS2__) || defined(__NT__)
        rc = cwait( &status, process_id, WAIT_CHILD );
        if( rc == -1 ) {
          printf( "wait failed - %s\n", strerror( errno ) );
        } else {
          printf( "wait succeeded - %x\n", status );
          switch( status & 0xff ) {

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