Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

 ◄Summary► ◄Example►                         ◄Up► ◄Contents► ◄Index► ◄Back►
─────Run-Time Library───────────────────────────────────────────────────────
 
     The _spawn functions create and execute a new child process.
     Enough memory must be available for loading and executing the
     child process. The <mode> argument determines the action taken by
     the parent process before and during _spawn. The following values
     for <mode> are defined in PROCESS.H:
 
     _P_OVERLAY     _P_WAIT
 
     All of the functions in the _spawn family use the same _spawn
     function. The letter(s) at the end of the function name determine
     the specific variation, as listed below:
 
     Letter     Variation
 
     l          Arguments given as null-terminated list
     v          Arguments given as array of pointers
     p          Searches for child program in PATH
     e          New environment specified for child
 
     The <cmdname> argument specifies the file to be executed as the
     child process. The <cmdname> argument can specify a full path
     (from the root), a partial path (from the current working
     directory), or just a filename. If <cmdname> does not have a
     filename extension or does not end with a period (.), the _spawn
     function first tries the .COM extension, then the .EXE extension,
     and finally the .BAT extension. This ability to spawn batch files
     is new beginning with Microsoft C version 6.0.
 
     If <cmdname> has an extension, only that extension is used. If
     <cmdname> ends with a period, the _spawn calls search for
     <cmdname> with no extension. The _spawnlp, _spawnlpe, _spawnvp,
     and _spawnvpe routines search for <cmdname> (using the same
     procedures) in the directories specified by the PATH environment
     variable.
 
     If <cmdname> contains a drive specifier or any slashes (i.e., it
     is a relative path name), the spawn call searches only for the
     specified file and no path searching is done.
 
     Arguments for the Child Process
 
     Arguments are passed to the child process by giving one or more
     pointers to character strings as arguments in the _spawn call.
     These character strings form the argument list for the child
     process. The combined length of the strings forming the argument
     list for the child process must not exceed 128 bytes in real mode.
     The terminating null character (\0) for each string is not
     included in the count, but space characters (automatically
     inserted to separate arguments) are included.
 
     The argument pointers may be passed as separate arguments (_spawnl,
     _spawnle, _spawnlp, and _spawnlpe) or as an array 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 argument is the name of the program as it might
     be typed on the command line by the user. (A different value will
     not produce an error.) In real mode, the <argv[0]> value is
     supplied by DOS and is the fully qualified path name of the
     executing program. In protected mode, it is usually the program
     name as it would be typed on the command line.
 
     The _spawnl, _spawnle, _spawnlp, and _spawnlpe calls are typically
     used for cases in which the number of arguments is known in
     advance. The <arg0> argument is usually a pointer to <cmdname>.
     The arguments <arg1> through <argn> are pointers to the character
     strings forming the new argument list. Following <argn> there must
     be a NULL pointer to mark the end of the argument list.
 
     The _spawnv, _spawnve, _spawnvp, and _spawnvpe calls are useful
     when the number of arguments to the child process is variable.
     Pointers to the arguments are passed as an array, <argv>. The
     argument <argv[0]> is usually a pointer to a path name in real
     mode or the program name in protected mode, and <argv[1]> through
     <argv[n]> are pointers to the character strings forming the new
     argument list. The argument <argv[n+1]> must be a NULL pointer to
     mark the end of the argument list.
 
     Environment of the Child Process
 
     Files that are open when a _spawn call is made remain open in the
     child process. In the _spawnl, _spawnlp, _spawnv, and _spawnvp
     calls, the child process inherits the environment of the parent.
     The _spawnle, _spawnlpe, _spawnve, and _spawnvpe calls allow the
     user to alter the environment for the child process by passing a
     list of environment settings through the <envp> argument. The
     argument <envp> is an array of character pointers, each element of
     which (except for the final element) points to a null-terminated
     string defining an environment variable. Such a string usually has
     the form
 
          NAME=value
 
     where NAME is the name of an environment variable and value is the
     string value to which that variable is set. The final element of
     the <envp> array should be NULL. When <envp> itself is NULL, the
     child process inherits the environment settings of the parent
     process.
 
     The _spawn functions pass the child process information about open
     files, including the translation mode, through the C_FILE_INFO
     entry in the environment that is passed in real mode.
 
     The startup code usually processes this entry and then deletes it
     from the environment. However, if a _spawn function spawns a non-C
     process, this entry remains in the environment. Printing the
     environment shows graphics characters in the definition string for
     this entry, since the environment information is passed in binary
     form in real mode. It should not have any other effect on normal
     operations.
 
     You must explicitly flush (using fflush or _flushall) or close any
     stream prior to the _spawn function call.
 
     You can control whether a process's open file information will be
     passed to child processes, using the variable _fileinfo.
     See: _fileinfo
 
     NOTE: For _P_OVERLAY, to ensure proper overlay initialization and
           termination, do not use the setjmp or longjmp function to
           enter or leave an overlay routine.
 
     Return Value
 
     The return value from a synchronous spawn (_P_WAIT specified for
     <mode>) is the exit status of the child process.
 
     The exit status is 0 if the process terminated normally. The exit
     status can be set to a nonzero value if the child process
     specifically calls the exit routine with a nonzero argument. If
     the child process did not set a positive exit status, the positive
     exit status indicates an abnormal exit with an abort or an
     interrupt.
 
     A return value of -1 indicates an error (the child process is not
     started). In this case, errno is set to E2BIG, EINVAL, ENOENT,
     ENOEXEC, or ENOMEN.
                                    -♦-