EXEC(2,L) AIX Technical Reference EXEC(2,L)
-------------------------------------------------------------------------------
exec: execl, execv, execle, execve, execlp, execvp
PURPOSE
Executes a file.
SYNTAX
int execl (path, arg0 [, arg1,...], 0)
char *path, *arg0, *arg1,...;
int execv (path, argv)
char *path, *argv [ ];
int execle (path, arg0 [, arg1,...], 0, envp)
char *path, *arg0, *arg1,..., *envp [ ];
int execve (path, argv, envp)
char *path, *argv [ ], *envp [ ];
int execlp (file, arg0 [, arg1,...], 0)
char *file, *arg0, *arg1,...;
int execvp (file, argv)
char *file, *argv [ ];
DESCRIPTION
The exec system call, in all its forms, executes a new program in the calling
process. This call 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 procedure (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. The path
parameter is the path name of the file to be executed. The string parameter is
an optional character string that contains no tab or space characters. The
header must be terminated with a new-line character. When invoked, the new
Processed November 7, 1990 EXEC(2,L) 1
EXEC(2,L) AIX Technical Reference EXEC(2,L)
process is passed path as argv[0]. This is followed by the optional parameter
string and the name of the new process image file. 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.
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 environment variable. The
initial environment is supplied 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
environment, see "environment" and the sh and csh commands in AIX
Operating System Commands Reference.)
arg0 [, arg1,...]
These parameters point to null-terminated character strings. The
strings constitute the argument 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 constitute 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 constitute 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 convention, 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 following declaration in your
program:
extern char **environ;
Processed November 7, 1990 EXEC(2,L) 2
EXEC(2,L) AIX Technical Reference EXEC(2,L)
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, flock, lockf.") If the new process requires shared
libraries, exec attaches each shared library image to the new process address
space. (See AIX Programming Tools and Interfaces.) Shared libraries are
searched for in the directories listed in the LIBPATH environment variable.
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 "sigaction, sigvec, signal.")
If the set-user-ID mode bit of the new process image file is set, 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, 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, fchmod.") The effective user ID and the effective
group ID are saved (as the saved set-user-ID and the saved set-group-ID) for
use by the setuid function and for signal delivery permissions.
The shared libraries attached to the calling process are not attached to the
new process.
Profiling is disabled for the new process. (For information about profiling,
see "profil.")
The new process inherits the following attributes from the calling process:
o Nice value (see "getpriority, setpriority, 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 "sigaction, sigvec, 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 <LOCAL> alias pathname (see "getlocal, setlocal")
o File mode creation mask (see "umask")
o File locks (see "fcntl, flock, lockf")
o System resource limits (see "getrlimit, setrlimit, vlimit" and "ulimit")
o utime, stime, cutime, and cstime (see "times")
o xvers string (see "getxvers, setxvers")
o Site path (see "getspath, setspath")
o Execution site permissions (see "getxperm, setxperm").
Processed November 7, 1990 EXEC(2,L) 3
EXEC(2,L) AIX Technical Reference EXEC(2,L)
The name of the new process image file may refer to a hidden directory. Hidden
directories are normally used in a Transparent Computing Facility cluster to
enable execution of the correct process image for a given machine type.
Without TCF, however, hidden directories can be used to allow execution of
different versions of a program without changing the program name (see
"getxvers, setxvers").
If the Transparent Computing Facility is installed, the following information
also applies.
After the exec system call, the calling process executes on a site determined
by the machine type on which the new process image must run and by the site
path.
If the name of the new process image file refers to a hidden directory, exec
first selects the new process image file by following the usual hidden
directory path search rules, determined by prior calls to getspath. The
selected new process image file is examined to determine on what type of site
it may run. Then the site path is searched until the corresponding machine
type or a site of the appropriate type is found. If a specific site is found,
the exec system call executes a new program at that site. If an entry for the
machine type is found, the exec system call executes a new program at a site of
that type, using the local site if possible. The user must have permission to
move processes to the destination site (see "getxperm, setxperm").
The user level code is responsible for maintaining a site path which is
compatible with the user's permissions and the current network partition. If
the contents of the site path cause the system to choose a new process image
file for which there is no permissible site in the current partition, then the
system call exec fails.
The utime, stime, cutime, and cstime (see "times") are preserved by the exec
system call if the process remains on the same site. If it moves to a new
site, they are changed accordingly to the following rules:
cutime += utime;
cstime += stime;
utime = 0;
stime = 0;
Note: Processes may not execute to another site if:
1. They have too many (85 or more) child processes.
2. They have a file open which is marked as being in error (for
instance, the storage site is not on the cluster network).
3. They have made use of semaphores or messages operations.
4. There are any TCP/IP sockets open.
Processed November 7, 1990 EXEC(2,L) 4
EXEC(2,L) AIX Technical Reference EXEC(2,L)
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.
ERROR CONDITIONS
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 system call 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.
ENOEXEC 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 argument 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 points to a location outside of the
process's allocated address space.
In addition, some errors can occur when using the new process file after the
old process image has been overwritten. 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.
Processed November 7, 1990 EXEC(2,L) 5
EXEC(2,L) AIX Technical Reference EXEC(2,L)
ESTALE The process's root or current directory is located in an NFS virtual
file system that has been unmounted.
ENAMETOOLONG
A component of the path parameter exceeded NAME_MAX characters or the
entire path parameter exceeded PATH_MAX characters.
ENOENT A hidden directory was named, but no component inside it matched the
process's current site path list.
ENOENT A symbolic link was named, but the file to which it refers does not
exist.
ELOOP A loop of symbolic links was detected.
EIO A physical I/O error occurred.
If a shared library cannot be attached, one of more of the following is true:
ELIBMAX More than 10 shared libraries are specified by the new process image
file.
ELIBSCN The specification of shared libraries in the .lib section of the new
process image file is not in the correct format (see "a.out").
ELIBACC A shared library specified by the new process image file cannot be
opened.
ELIBBAD A shared library file is not in correct a.out format (see "a.out").
If the Transparent Computing Facility is installed on your system, the exec
system call can also fail if one or more of the following are true:
ESITEDN1 path cannot be accessed because a site went down.
ENOSTORE path is a name relative to the working directory, but no site which
stores this directory is currently up.
EINTR A signal was caught during the system call.
ENOSTORE A component of path is replicated but is not stored on any site
which is currently up.
ESITEDN1 The site chosen for the exec is down.
EPERM Execute permission is not granted for any of the sites chosen by
the site path.
ELDWRG The exec system call tried to execute on a site that is the wrong
machine type for the new process image.
Processed November 7, 1990 EXEC(2,L) 6
EXEC(2,L) AIX Technical Reference EXEC(2,L)
ETABLE On either the new site or the old site, the system's PID-site
table, which is used to keep track of remote processes and process
groups, is full.
ELOCALONLY The calling process may not use exec to execute a new program at
another site because it is using local only resources, such as
semaphores, or it has too many child processes.
ENLDEV The process may not execute on the designated site because one of
its open file descriptors is for a local-only object such as a
socket or a non-tty character special file.
In addition, the process may be killed with a SIGKILL signal if a system error
occurs very late in the process of reading in the new process image. These
system errors include being out of text table space and getting a disk read
error while reading the new process image file.
EXAMPLES
1. To run a command and pass it a parameter:
execlp("li", "li", "-al", 0);
The execlp system call searches each of the directories 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 parameter, 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 generally 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:
#! /bin/awk -f
{ for (i = NF; i > 0; --i) print i }
If this file is named "reverse", then typing the following command on the
command line:
Processed November 7, 1990 EXEC(2,L) 7
EXEC(2,L) AIX Technical Reference EXEC(2,L)
reverse chapter1 chapter2
causes the following command to be run:
/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 Reference for more information.)
RELATED INFORMATION
In this book: "alarm," "chmod, fchmod," "exit, _exit," "fcntl, flock,
lockf," "fork, vfork," "getpriority, setpriority, nice," "profil," "ptrace,"
"semop," "shmat," "sigaction, sigvec, signal," "system," "times," "ulimit,"
"umask," "varargs," "a.out," and "environment."
The csh and shlib2 commands in AIX Operating System Commands Reference.
Processed November 7, 1990 EXEC(2,L) 8