Name
execl, execle, execlp, execlpe, execv, execve, execvp,
execvpe - Load and execute a process.
Syntax
#include <process.h>
int execl(pathname, arg0, arg1,... argn, NULL)
int execle(pathname, arg0, arg1,... argn, NULL, envp)
int execlp(pathname, arg0, arg1,... argn, NULL)
int execlpe(pathname, arg0, arg1,... argn, NULL, envp)
int execv(pathname, argv)
int execve(pathname, argv, envp)
int execvp(pathname, argv)
int execvpe(pathname, argv, envp)
char *pathname;
char *arg0,*arg1,... *argn;
char *argv[ ];
char *envp[ ];
Description
The exec functions load and execute new child processes.
When the call is successful, the child process is placed in
the memory previously occupied by the calling process.
Sufficient memory must be available for loading and
executing the child process.
All of the functions in this family use the same exec
function; the letter(s) at the end determine the specific
variation:
Letter Variation
p Uses the PATH environment variable to
find the file to be executed
l Command-line arguments are passed
individually to the exec function
v Command-line arguments are passed to the
exec function as an array of pointers
e Explicitly passes to the child process
an array of pointers to environment
arguments
The pathname argument specifies the file to be executed as
the child process. It can specify a full path (from the
root), a partial path (from the current working directory),
or just a file name. If pathname has a file-name extension,
the exec function searches for the file exactly as
specified. If pathname does not have a file-name extension
and does not end with a period (.), the exec function
searches for the file with no extension; if unsuccessful, it
searches for the file with the extension .COM, then .EXE. If
pathname ends with a period, the exec function searches for
the file with no extension. The execlp, execlpe, execvp, and
execvpe routines search for pathname (using the same
procedures) in the directories specified by the PATH
environment variable.
Arguments are passed to the new process by giving one or
more pointers to character strings as arguments in the exec
call. These character strings form the argument list for the
child process. The combined length of the strings forming
the argument list for the new process must not exceed 128
bytes (in real mode only). The terminating null character
(\0) for each string is not included in the count, but space
characters (inserted automatically to separate the
arguments) are counted.
The argument pointers can be passed as separate arguments
(execl, execle, execlp, and execlpe) or as an array of
pointers (execv, execve, execvp, and execvpe). At least one
argument, arg0, must be passed to the child process (which
sees it as argv[0]). Usually, this argument is a copy of the
pathname argument. (A different value will not produce an
error.) Under versions of DOS earlier than 3.0, the passed
value of arg0 is not available for use in the child process.
However, under OS/2 and DOS Versions 3.0 and later, the
pathname is available as arg0.
The execl, execle, execlp, and execlpe calls are typically
used when the number of arguments is known in advance. The
argument arg0 is usually a pointer to pathname. The
arguments arg1 through argn point to the character strings
forming the new argument list. A null pointer must follow
argn to mark the end of the argument list.
The execv, execve, execvp, and execvpe calls are useful when
the number of arguments to the new process is variable.
Pointers to the arguments are passed as an array, argv. The
argument argv[0] is usually a pointer to pathname. The
arguments argv[1] through argv[n] point 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.
Files that are open when an exec call is made remain open in
the new process. In the execl, execlp, execv, and execvp
calls, the child process inherits the environment of the
parent. The execle, execlpe, execve, and execvpe 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. (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 child process inherits the environment
settings of the parent process.
A program executed with one of the exec family of C run-time
functions is always loaded into memory as if the ``maximum
allocation field in the program's EXE file header is set to
the default value of 0FFFFH. If you use the EXEMOD utility
to change the maximum allocation field of a program, the
program may behave differently when invoked with one of the
exec functions from the operating system command line or
with one of the spawn run-time functions.
The exec calls do not preserve the translation modes of open
files. If the child process must use files inherited from
the parent, the setmode routine should be used to set the
translation mode of these files to the desired mode.
Signal settings are not preserved in child processes created
by calls to exec routines. The signal settings are reset to
the default in the child process.
Notes
Because of differences in DOS Versions 2.0 and 2.1, child
processes generated by the exec family of functions (or by
the equivalent spawn functions with the P_OVERLAY argument)
may cause fatal system errors when they exit. If you are
running DOS 2.0 or 2.1, you must upgrade to DOS Versions 3.0
or later, to use these functions.
Bound programs cannot use the exec family of functions in
real mode.
Return Value
The exec functions do not normally return to the calling
process. If an exec function returns, an error has occurred
and the return value is -1.
The errno variable is set to one of the following values:
Value Meaning
E2BIG The argument list exceeds 128 bytes,
or the space required for the
environment information exceeds 32K.
EACCES The specified file has a locking or
sharing violation (OS/2 and DOS
Versions 3.0 or later).
EMFILE Too many files are open. (The
specified file must be opened to
determine whether it is executable.)
ENOENT The file or path name not found.
ENOEXEC The specified file is not executable,
or it has an invalid executable-file
format.
ENOMEM Not enough memory is available to
execute the child process; or the
available memory has been corrupted;
or an invalid block exists, indicating
that the parent process was not
allocated properly.
See Also
abort(DOS), atexit(DOS), exit(DOS), spawn(DOS), system(DOS)
Example
#include <stdio.h> #include <process.h>
char *my_env[] = {
"THIS=environment will be",
"PASSED=to child.exe by the",
"EXECLE=and",
"EXECLPE=and",
"EXECVE=and",
"EXECVPE=functions",
NULL
};
main(argc, argv) int argc; char *argv[];
{
char *args[4];
int result;
/* Set up parameters to send */
args[0] = "child";
args[1] = "execv??";
args[2] = "two";
args[3] = NULL;
/* Based on first letter of argument */
switch (argv[1][0])
{
case '1':
execl ("child.exe","child
","execl","two",NULL);
break;
case '2':
execle
("child.exe","child","execle","two",NULL,my_env);
break;
case '3':
execlp
("child.exe","child","execlp","two",NULL);
break;
case '4':
execlpe("child.exe","child","execlpe","two",NULL,my_env);
break;
case '5':
execv ("child.exe",args);
break;
case '6':
execve ("child.exe",args,my_env);
break;
case '7':
execvp ("child.exe",args);
break;
case '8':
execvpe("child.exe",args,my_env);
break;
default:
printf("Enter a number from 1 to 8 as a
");
printf("command line parameter.\n");
exit(1);
}
printf("Process was not spawned.\n");
printf("Program 'child' was not found.\n");
}
This program accepts a number in the range 1 through 8 from
the command line. Based on the number it receives, it
executes one of the eight different procedures that spawn
the process named child. For some of these procedures, the
child.exe file must be in the same directory; for others, it
need only be in the same path.
(printed 6/18/89)