_spawnvp, _wspawnvp (original) (raw)

Creates a process and executes it.

Syntax

intptr_t _spawnvp(
   int mode,
   const char *cmdname,
   const char *const *argv
);
intptr_t _wspawnvp(
   int mode,
   const wchar_t *cmdname,
   const wchar_t *const *argv
);

Parameters

mode
Execution mode for calling the process.

cmdname
Path of the file to be executed.

argv
Array of pointers to arguments. The argument argv[0] is usually a pointer to a path in real mode or to 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.

Return value

The return value from a synchronous _spawnvp or _wspawnvp (_P_WAIT specified for mode) is the exit status of the new process. The return value from an asynchronous _spawnvp or _wspawnvp (_P_NOWAIT or _P_NOWAITO specified for mode) is the process handle. The exit status is 0 if the process terminated normally. You can set the exit status to a nonzero value if the spawned process specifically uses a nonzero argument to call the exit routine. If the new process didn't explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of -1 indicates an error (the new process isn't started). In this case, errno is set to one of the following values:

Value	Description
E2BIG	Argument list exceeds 1024 bytes.
EINVAL	mode argument is invalid.
ENOENT	File or path isn't found.
ENOEXEC	Specified file isn't executable or has invalid executable-file format.
ENOMEM	Not enough memory is available to execute the new process.

For more information about return codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Each of these functions creates a new process and executes it, and passes an array of pointers to command-line arguments and uses the PATH environment variable to find the file to execute.

These functions validate their parameters. If either cmdname or argv is a null pointer, or if argv points to null pointer, or argv[0] is an empty string, the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, these functions set errno to EINVAL, and return -1. No new process is spawned.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Requirements

Routine	Required header
_spawnvp	<stdio.h> or <process.h>
_wspawnvp	<stdio.h> or <wchar.h>

For more compatibility information, see Compatibility.

Example