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►
────────────────────────────────────────────────────────────────────────────
 
     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_DETACH      P_OVERLAY
     P_NOWAIT      P_WAIT
     P_NOWAITO
 
     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 file name. If <cmdname> does not have a
     file-name 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 (or, in OS/2 protected mode, the
     .CMD extension). This ability to spawn batch files is a new feature
     in version 2.5.
 
     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 (_C_FILE_INFO
     in protected mode).
 
     The C start-up code normally processes this entry and then deletes
     it from the environment. However, if a spawn function spawns a
     non-C process (such as CMD.EXE), 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. In protected mode, the
     environment information is passed in text form and therefore
     contains no graphics characters.
 
     You must explicitly flush (using fflush or flushall) or close any
     stream prior to the spawn function call.
 
     Starting with Microsoft C, version 6.0 (or QuickC version 2.5),
     you can control whether or not a process's open file information
     will be passed to child processes, using the variable _fileinfo.
     See _fileinfo for more information.
 
     P_OVERLAY Mode Note
 
     The spawn functions with P_OVERLAY mode will not work in OS/2 DOS-
     compatibility mode in programs that are bound with FAPI for dual-
     mode execution.
 
     Programs linked as DOS mode .EXE files do work, as do protected-
     mode programs. The restriction applies only to bound programs in
     real mode.
 
     In order to ensure proper overlay initialization and termination,
     do not use the setjmp or longjmp functions 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 return value from an asynchronous spawn (P_NOWAIT or P_NOWAITO
     specified for <mode>) is the process ID. To obtain the exit code
     for a process spawned with P_NOWAIT, you must call the wait or
     cwait function and specify the process ID. The exit code cannot be
     obtained for a process spawned with P_NOWAITO.
 
     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.
                                    -♦-