exec: execl, execv, execle, execve, execlp, execvp
Purpose
Executes a file.
Syntax
int execl (path, arg0 [, arg1, . . . |, 0)int execv (path, argv)
char *path, *arg0, *arg1, . . . ; char *path, *argv[ ];
int execle (path, arg0 [, arg1, . . . |, 0intnexecve (path, argv, envp)
char *path, *arg0, *arg1, . . . , *envp[ ]char *path, *argv[ ], *envp[ ];
int execlp (file, arg0 [, arg1, . . . |, 0int execvp (file, argv)
char *file, *arg0, *arg1, . . . ; char *file, *argv[ ];
Description
The exec system call, in all its forms, executes a new
program in the calling process. exec does not create a
new program, but overlays the current program with a new
one, which is called the new process image. The new
process image file can be one of three file types:
o An executable binary file in a.out format (see
"a.out")
o An executable text file that contains a shell proce-
dure (only execlp and execvp allow this type of new
process image file)
o A file that names an executable binary file or shell
procedure to be run.
The last of the types mentioned is recognized by a header
with the syntax:
"#!" path [string|
The "#!" is the file's magic number, which identifies the
file type. path is the path name of the file to be exe-
cuted. If Distributed Services is installed on your
system, this path can cross into another node. string is
an optional character string that contains no tab or
space characters. If specified, this string is passed to
the new process as an argument in front of the name of
the new process image file. The header must be termi-
nated with a new-line character. When invoked, the new
process is passed path as argv[0]. If a string is speci-
fied in the new process image file, then the exec system
call sets argv[0] to string and path concatenated
together. The rest of the arguments passed are the same
as those passed to the exec system call.
The parameters for the exec system calls are defined as
follows:
path This parameter points to the path name of the new
process image file. If Distributed Services is
installed on your system, this path can cross into
another node. Data is copied into local virtual
memory before proceeding.
file This parameter points to the name of the new
process image file. Unless file is a full path
name, the path prefix for the file is obtained by
searching the directories named in the PATH envi-
ronment variable. The initial environment is sup-
plied by the shell.
Note that execlp and execvp take file parameters,
but the rest of the exec system calls take path
parameters. (For information about the environ-
ment, see "environment" and the sh command in AIX
Operating System Commands Reference.)
arg0 [, arg1, . . . |
These parameters point to null-terminated char-
acter strings. The strings constitute the argu-
ment list available to the new process. By
convention, at least arg0 must be present, and it
must point to a string that is the same as path or
its last component.
argv This parameter is an array of pointers to null-
terminated character strings. These strings con-
stitute the argument list available to the new
process. By convention, argv must have at least
one element, and it must point to a string that is
the same as path or its last component. The last
element of argv is a NULL pointer.
envp This parameter is an array of pointers to null-
terminated character strings. These strings con-
stitute the environment for the new process. The
last element of envp is a NULL pointer.
When a C program is executed, it receives the following
parameters:
main (argc, argv, envp)
int argc;
char *argv[ ], *envp[ ];
Here argc is the argument count, and argv is an array of
character pointers to the arguments themselves. By con-
vention, the value of argc is at least one, and argv[0|
points to a string containing the name of the new process
image file.
The main routine of a C language program automatically
begins with a run-time start-off routine. This routine
sets a global variable named environ so that it points to
the environment array passed to the program in envp. You
can access this global variable by including the fol-
lowing declaration in your program:
extern char **environ;
The execl, execv, execlp, and execvp system calls use
environ to pass the calling process's current environment
to the new process.
File descriptors open in the calling process remain open
in the new process, except for those whose close-on-exec
flag is set. For those file descriptors that remain
open, the file pointer is unchanged. (For information
about file control, see "fcntl.")
If the new process requires shared libraries, exec will
find, open, and map each shared library image to the new
process address space. (See AIX Operating System Pro-
gramming Tools and Interfaces.) Shared libraries are
searched for in the directories listed in the LIBPATH
environment variable. If any of these files is remote,
the data is copied into local virtual memory.
The exec system calls reset all caught signals to the
default action. Signals that cause the default action
continue to do so after exec. Ignored signals remain
ignored, the signal mask remains the same, and the signal
stack state is reset. (For information about signals,
see "signal" and "sigvec.")
If the set-user-ID mode bit of the new process image file
is set, then exec sets the effective user ID of the new
process to the owner ID of the new process image file.
Similarly, if the set-group-ID mode bit of the new
process image file is set, then the effective group ID of
the new process is set to the group ID of the new process
image file. The real user ID and real group ID of the
new process remain the same as those of the calling
process. (For information about the set-ID modes, see
"chmod.")
When one or both of the set-ID mode bits is set and the
file to be executed is a remote file, the file's user and
group IDs go through outbound translation at the server.
Then they are transmitted to the client node where they
are translated according to the inbound translation
table. These translated IDs become the user and group
IDs of the new process. See Managing the AIX Operating
System for a discussion of UID and GID translation.
The shared libraries attached to the calling process are
not attached to the new process. (For information about
shared memory segments, see "shmat," "shmdt," and
"shmget.")
Profiling is disabled for the new process. (For informa-
tion about profiling, see "profil.")
The new process inherits the following attributes from
the calling process:
o Nice value (see "nice")
o Process ID
o Parent process ID
o Process group ID
o semadj values (see "semop")
o TTY group ID (see "exit, _exit" and "signal")
o Trace flag (see request 0 of "ptrace")
o Time left until an alarm clock signal (see "alarm")
o Current directory
o Root directory
o File mode creation mask (see "umask")
o File size limit (see "ulimit") &c2del.
o utime, stime, cutime, and cstime (see "times").
&c2off. &c2ins.
o utime, stime, cutime, and cstime (see "times")
o Login user ID
o Suspend/resume process audit flag (see "auditproc")
o General/special user audit flag (see "auditsys").
&c2off.
Return Value
Upon successful completion, exec does not return because
the calling process image is overlaid by the new process
image. If exec returns to the calling process, then it
returns the value -1 and sets errno to indicate the
error.
Diagnostics
The exec system call fails and returns to the calling
process if one or more of the following are true:
ENOENT One or more components of the new process
image file's path name do not exist.
ENOTDIR A component of the path prefix of the new
process image file is not a directory.
EACCES Search permission is denied for a directory
listed in the path prefix of the new process
image file.
EACCES The new process image file is not an ordinary
file.
EACCES The mode of the new process image file denies
execution permission.
ENOEXEC The exec is not an execlp or execvp, and the
new process image file has the appropriate
access permission but has an invalid magic
number in its header.
EINVAL The new process image file has a valid magic
number in its header, but the header is
damaged or is incorrect for the machine on
which the file is to be run.
ETXTBSY The new process image file is a pure procedure
(shared text) file that is currently open for
writing by some process.
ENOMEM The new process requires more memory than is
allowed by the system-imposed maximum MAXMEM.
E2BIG The number of bytes in the new process's argu-
ment list is greater than the system-imposed
limit. This limit is defined as NCARGS in the
sys/param.h header file.
EFAULT The path, argv, or envp parameter &pointsout..
In addition, some errors can occur when using the new
process file after the old process image has been over-
written. These errors include problems in setting up new
data and stack registers, problems in mapping a shared
library, or problems in reading the new process file.
Because returning to the calling process is not possible,
the system sends the SIGKILL signal to the process when
one of these errors occurs.
If an error occurred while mapping a shared library, an
error message describing the reason for failure will be
written to standard error before the signal SIGKILL is
sent to the process. (See AIX Operating System Program-
ming Tools and Interfaces.) If a shared library cannot
be mapped, one or more of the following is true:
ENOENT One or more components of the path name of the
shared library file do not exist.
ENOTDIR A component of the path prefix of the shared
library file is not a directory.
EACCES Search permission is denied for a directory
listed in the path prefix of the shared
library file.
EACCES The shared library file mode denies execution
permission.
ENOEXEC The shared library file has the appropriate
access permission but an invalid magic number
in its header.
ETXTBSY The shared library file is currently open for
writing by some other process.
ENOMEM The shared library requires more memory than
is allowed by the system-imposed maximum.
ESTALE The process's root or current directory is
located in a virtual file system that has been
unmounted.
If Distributed Services is installed on your system, exec
can also fail if one or more of the following are true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
ESTALE The file descriptor for a remote file has
become obsolete.
EPERM The set-user-ID or set-group-ID bit is set
on the process image file, and the trans-
lation tables at the server or client do
not allow translation of this user or group
ID.
ENODEV The named file is a remote file located on
a device that has been unmounted at the
server.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Examples
1. To run a command and pass it a parameter:
execlp("li", "li", "-al", 0);
The execlp system call searches each of the directo-
ries listed in the PATH environment variable for the
li command, and then it overlays the current process
image with this command. execlp does not return,
unless the li command cannot be executed. Note that
this example does not run the shell command
processor, so operations interpreted by the shell,
such as using wildcard characters in file names, are
not valid.
2. To run the shell to interpret a command:
execl("/bin/sh", "sh", "-c", "li -l *.c", 0);
This runs the sh (shell) command with the -c param-
eter, which indicates that the following parameter is
the command to be interpreted. (See the discussion
of sh in AIX Operating System Commands Reference for
details about this command.) This example uses execl
instead of execlp because the full path name /bin/sh
is specified, making a PATH search unnecessary.
Running a shell command in a child process is gener-
ally more useful than simply using exec, as shown
here. The simplest way to do this is to use the
system subroutine. See "system" for information
about this subroutine.
3. The following is an example of a new process file
that names a program to be run:
#! /usr/bin/awk -f
{ for (i = NF; i > 0; --i) print i }
If this file is named "reverse", then typing the fol-
lowing command on the command line:
reverse chapter1 chapter2
causes the following command to be run:
/usr/bin/awk -f reverse chapter1 chapter2
Note that the exec system calls use only the first
line of the new process image file and ignore the
rest of it. Also, awk interprets the text that
follows a "#" (number sign) as a comment. (See the
awk command in AIX Operating System Commands Refer-
ence for more information.)
Related Information
In this book: "alarm," "chmod," "exit, _exit,"
"fcntl," "fork," "nice," "profil," "ptrace," "semop,"
"shmat," "signal," "sigvec," "times," "ulimit," "umask,"
"system," "varargs," "a.out," and "environment."
The sh and shlib commands in AIX Operating System Com-
mands Reference.