exec, execl, execle, execlp, execv, execve, execvp, exect, or fexecve Subroutine

Purpose

Executes a file.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

extern 
char **environ;

int execl (
 Path, 
 Argument0 [, Argument1, ...], 0)
const char *Path, *Argument0, *Argument
1, ...;

int execle (
 Path, 
 Argument0 [, Argument1, ...], 0,
        
 EnvironmentPointer)
const 
char *Path, *Argument0, *Argum
ent
1, ...;
char *const EnvironmentPointer[ ];

int execlp (
 File, 
 Argument0 [, Argument1
, ...], 0)
const char *File, *Argument0, *Argument
1, ...;

int execv (
 Path, 
 ArgumentV)
const char *Path;
char *const ArgumentV[ ];

int execve (
 Path, 
 ArgumentV,
        
 EnvironmentPointer)
const char *Path;
char 
*const ArgumentV[ ], *EnvironmentPointer
[ ];

int execvp (
 File, 
 ArgumentV)
const char *File;
char *const ArgumentV[ ];

int exect (
 Path,
 ArgumentV,
 EnvironmentPointer)
char *Path, *ArgumentV, *EnvironmentPointer [ ];

int fexecve (FileDescriptor, ArgumentV, EnvironmentPointer)
int FileDescriptor;
char *const ArgumentV[ ], *EnvironmentPointer[ ];

Description

The exec subroutine, in all its forms, executes a new program in the calling process. The exec subroutine does not create a new process, 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:

• An executable binary file in XCOFF file format.
• An executable text file that contains a shell procedure (only the execlp and execvp subroutines allow this type of new-process image file).
• A file that names an executable binary file or shell procedure to be run.

The fexecve subroutine is equivalent to the execve subroutine, except that the fexecve subroutine takes the file descriptor of an open file to be executed as a first parameter, instead of a pathname. However, the following apply:

The new-process image inherits the following attributes from the calling process image: session membership, supplementary group IDs, process signal mask, and pending signals.

The last of the types mentioned is recognized by a header with the following syntax:

#! Path [String]

The #! is the file magic number, which identifies the file type. The path name of the file to be executed is specified by the Path parameter. The String parameter 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 terminated with a new-line character. When called, the new process passes the Path parameter as ArgumentV[0]. If a String parameter is specified in the new process image file, the exec subroutine sets ArgumentV[0] to the String and Path parameter values concatenated together. The rest of the arguments passed are the same as those passed to the exec subroutine.

The exec subroutine attempts to cancel outstanding asynchronous I/O requests by this process. If the asynchronous I/O requests cannot be canceled, the application is blocked until the requests have completed.

The exec subroutine is similar to the load (load and loadAndInit Subroutines) subroutine, except that the exec subroutine does not have an explicit library path parameter. Instead, the exec subroutine uses either the LIBPATH or LD_LIBRARY_PATH environment variable. The LIBPATH variable, when set, is used in favor of LD_LIBRARY_PATH; otherwise, LD_LIBRARY_PATH is used. These library path variables are ignored when the program that the exec subroutine is run on has more privilege than the calling program (for example, an suid program).

The exect subroutine is included for compatibility with older programs being traced with the ptrace command. The program being executed is forced into hardware single-step mode.

Parameters

When a C program is run, it receives the following parameters:

main (ArgumentCount, ArgumentV, EnvironmentPointer)
int ArgumentCount;
char *ArgumentV[ ], *EnvironmentPointer[ 
];

In this example, the ArgumentCount parameter is the argument count, and the ArgumentV parameter is an array of character pointers to the arguments themselves. By convention, the value of the ArgumentCount parameter is at least 1, and the ArgumentV[0] parameter 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 runtime start-off routine. This routine sets the environ global variable so that it points to the environment array passed to the program in EnvironmentPointer. You can access this global variable by including the following declaration in your program:

extern char **environ;

The execl, execv, execlp, and execvp subroutines use the environ global variable to pass the calling process current environment to the new process.

File descriptors open in the calling process remain open, 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 the fcntl.h file.)

The state-of-conversion descriptors and message-catalog descriptors in the new process image are undefined. For the new process, an equivalent of the setlocale subroutine, specifying the LC_ALL value for its category and the "C" value for its locale, is run at startup.

If the new program requires shared libraries, the exec subroutine finds, opens, and loads each of them into the new-process address space. The referenced counts for shared libraries in use by the issuer of the exec are decremented. 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 subroutines reset all caught signals to the default action. Signals that cause the default action continue to do so after the exec subroutines. Ignored signals remain ignored, the signal mask remains the same, and the signal stack state is reset. (For information about signals, see the sigaction subroutine.)

If the SetUserID mode bit of the new-process image file is set, the exec subroutine sets the effective user ID of the new process to the owner ID of the new-process image file. Similarly, if the SetGroupID 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 SetID modes, see the chmod subroutine.)

At the end of the exec operation the saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process.

When one or both of the set ID mode bits is set and the file to be executed is a remote file, the file 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.

Profiling is disabled for the new process.

The new process inherits the following attributes from the calling process:

• Nice value (see the getpriority subroutine, setpriority subroutine, nice subroutine)
• Process ID
• Parent process ID
• Process group ID
• semadj values (see the semop subroutine)
• tty group ID (see the exit, atexit, or _exit subroutine, sigaction subroutine)
• trace flag (see request 0 of the ptrace subroutine)
• Time left until an alarm clock signal (see the incinterval subroutine, setitimer subroutine, and alarm subroutine)
• Current directory
• Root directory
• File-mode creation mask (see the umask subroutine)
• File size limit (see the ulimit subroutine)
• Resource limits (see the getrlimit subroutine, setrlimit subroutine, and vlimit subroutine)
• tms_utime, tms_stime, tms_cutime, and tms_ctime fields of the tms structure (see the times subroutine)
• Login user ID

Upon successful completion, the exec subroutines mark for update the st_atime field of the file.

Examples

1. To run a command and pass it a parameter, enter:

   execlp("ls", "ls", "-al", 0);

   The execlp subroutine searches each of the directories listed in the PATH environment variable for the ls command, and then it overlays the current process image with this command. The execlp subroutine is not returned, unless the ls command cannot be executed.
   Note: 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, enter:

   execl("/usr/bin/sh", "sh", "-c", "ls -l *.c", 
   0);

   This runs the sh command with the -c flag, which indicates that the following parameter is the command to be interpreted. This example uses the execl subroutine instead of the execlp subroutine because the full path name /usr/bin/sh is specified, making a path search unnecessary.

   Running a shell command in a child process is generally more useful than simply using the exec subroutine, as shown in this example. The simplest way to do this is to use the system 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, entering the following command on the command line:

   reverse chapter1 chapter2

   This command runs the following command:

   /usr/bin/awk -f reverse chapter1 chapter2

   Note: The exec subroutines use only the first line of the new-process image file and ignore the rest of it. Also, the awk command interprets the text that follows a # (pound sign) as a comment.

Return Values

Upon successful completion, the exec subroutines do not return because the calling process image is overlaid by the new-process image. If the exec subroutines return to the calling process, the value of -1 is returned and the errno global variable is set to identify the error.

Error Codes

If the exec subroutine is unsuccessful, it returns one or more of the following error codes:

If the exec subroutine is unsuccessful because of a condition requiring path name resolution, it returns one or more of the following error codes:

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.

If an error occurred while mapping a shared library, an error message describing the reason for error is written to standard error before the signal SIGKILL is sent to the process. If a shared library cannot be mapped, the subroutine returns one of the following error codes:

If the fexecve subroutine is unsuccessful, it might also return one of the following error codes:

If NFS is installed on the system, the exec subroutine can also fail if the following is true: