_exec, _wexec Functions

Each of the functions in this family loads and executes a new process.

_execl, _wexecl _execv, _wexecv
_execle, _wexecle _execve, _wexecve
_execlp, _wexeclp _execvp, _wexecvp
_execlpe, _wexeclpe _execvpe, _wexecvpe

The letter(s) at the end of the function name determine the variation.

_exec Function Suffix
Description
e envp, array of pointers to environment settings, is passed to new process.
l Command-line arguments are passed individually to _exec function. Typically used when number of parameters to new process is known in advance.
p PATH environment variable is used to find file to execute.
v argv, array of pointers to command-line arguments, is passed to _exec. Typically used when number of parameters to new process is variable.

Remarks

Each of the _exec functions loads and execute a new process. All _exec functions use the same operating-system function. The _exec functions automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The _wexec functions are wide-character versions of the _exec functions. The _wexec functions behave identically to their _exec family counterparts except that they do not handle multibyte-character strings.

Generic-Text Routine Mappings:

TCHAR.H Routine _UNICODE & _MBCS Not Defined _MBCS Defined _UNICODE Defined
_texecl _execl _execl _wexecl
_texecle _execle _execle _wexecle
_texeclp _execlp _execlp _wexeclp
_texeclpe _execlpe _execlpe _wexeclpe
_texecv _execv _execv _wexecv
_texecve _execve _execve _wexecve
_texecvp _execvp _execvp _wexecvp
_texecvpe _execvpe _execvpe _wexecvpe

When a call to an _exec function is successful, the new process is placed in the memory previously occupied by the calling process. Sufficient memory must be available for loading and executing the new process.

The cmdname parameter specifies the file to be executed as the new process. It can specify a full path (from the root), a partial path (from the current working directory), or a filename. If cmdname does not have a filename extension or does not end with a period (.), the _exec function searches for the named file. If the search is unsuccessful, it tries the same base name with the .COM extension and then with the .EXE, .BAT, and .CMD extensions. If cmdname has an extension, only that extension is used in the search. If cmdname ends with a period, the _exec function searches for cmdname with no extension. _execlp, _execlpe, _execvp, and _execvpe 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 (that is, if it is a relative path), the _exec call searches only for the specified file; the path is not searched.

Parameters are passed to the new process by giving one or more pointers to character strings as parameters in the _exec call. These character strings form the parameter list for the new process. The combined length of the inherited environment settings and the strings forming the parameter list for the new process must not exceed 32K bytes. The terminating null character ('\0') for each string is not included in the count, but space characters (inserted automatically to separate the parameters) are counted.

The argument pointers can be passed as separate parameters (in _execl, _execle, _execlp, and _execlpe) or as an array of pointers (in _execv, _execve, _execvp, and _execvpe). At least one parameter, arg0, must be passed to the new process; this parameter is argv[0] of the new process. Usually, this parameter is a copy of cmdname. (A different value does not produce an error.)

The _execl, _execle, _execlp, and _execlpe calls are typically used when the number of parameters is known in advance. The parameter arg0 is usually a pointer to cmdname. The parameters arg1 through argn point to the character strings forming the new parameter list. A null pointer must follow argn to mark the end of the parameter list.

The _execv, _execve, _execvp, and _execvpe calls are useful when the number of parameters to the new process is variable. Pointers to the parameters are passed as an array, argv. The parameter argv[0] is usually a pointer to cmdname. The parameters argv[1] through argv[n] point to the character strings forming the new parameter list. The parameter argv[n+1] must be a NULL pointer to mark the end of the parameter list.

Files that are open when an _exec call is made remain open in the new process. In _execl, _execlp, _execv, and _execvp calls, the new process inherits the environment of the calling process. _execle, _execlpe, _execve, and _execvpe calls alter the environment for the new process by passing a list of environment settings through the envp parameter. 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. (Note that value is not enclosed in double quotation marks.) The final element of the envp array should be NULL. When envp itself is NULL, the new process inherits the environment settings of the calling process.

A program executed with one of the _exec functions is always loaded into memory as if the “maximum allocation” field in the program’s .EXE file header were set to the default value of 0xFFFFH. You can use the EXEHDR utility to change the maximum allocation field of a program; however, such a program invoked with one of the _exec functions may behave differently from a program invoked directly from the operating-system command line or with one of the _spawn functions.

The _exec calls do not preserve the translation modes of open files. If the new process must use files inherited from the calling process, use the _setmode routine to set the translation mode of these files to the desired mode. You must explicitly flush (using fflush or _flushall) or close any stream before the _exec function call. Signal settings are not preserved in new processes that are created by calls to _exec routines. The signal settings are reset to the default in the new process.

Example

/* EXEC.C illustrates the different versions of exec including:
 *      _execl          _execle          _execlp          _execlpe
 *      _execv          _execve          _execvp          _execvpe
 *
 * Although EXEC.C can exec any program, you can verify how 
 * different versions handle arguments and environment by 
 * compiling and specifying the sample program ARGS.C. See 
 * SPAWN.C for examples of the similar spawn functions.
 */

#include <stdio.h>
#include <conio.h>
#include <process.h>

char *my_env[] =                /* Environment for exec?e */
{
   "THIS=environment will be",
   "PASSED=to new process by",
   "the EXEC=functions",
   NULL
};

void main()
{
   char *args[4], prog[80];
   int ch;

   printf( "Enter name of program to exec: " );
   gets( prog );
   printf( " 1. _execl  2. _execle  3. _execlp  4. _execlpe\n" );
   printf( " 5. _execv  6. _execve  7. _execvp  8. _execvpe\n" );
   printf( "Type a number from 1 to 8 (or 0 to quit): " );
   ch = _getche();
   if( (ch < '1') || (ch > '8') )
       exit( 1 );
   printf( "\n\n" );

   /* Arguments for _execv? */
   args[0] = prog;
   args[1] = "exec??";
   args[2] = "two";
   args[3] = NULL;

   switch( ch )
   {
   case '1':
      _execl( prog, prog, "_execl", "two", NULL );
      break;
   case '2':
      _execle( prog, prog, "_execle", "two", NULL, my_env );
      break;
   case '3':
      _execlp( prog, prog, "_execlp", "two", NULL );
      break;
   case '4':
      _execlpe( prog, prog, "_execlpe", "two", NULL, my_env );
      break;
   case '5':
      _execv( prog, args );
      break;
   case '6':
      _execve( prog, args, my_env );
      break;
   case '7':
      _execvp( prog, args );
      break;
   case '8':
      _execvpe( prog, args, my_env );
      break;
   default:
      break;
   }

   /* This point is reached only if exec fails. */
   printf( "\nProcess was not execed." );
   exit( 0 );
}
 

Process and Environment Control Routines

See Also   abort, atexit, exit, _onexit, _spawn Function Overview, system