OSF

NAME

environ, execl, execv, execle, execve, execlp, execvp − Executes a file

LIBRARY

Standard C Library (libc.a): execlp(), execvp()

SYNOPSIS

extern char ∗∗environ;
int execl (
const char ∗path,
const char ∗arg,
...  ); int execv (
const char ∗path,
char ∗ const argv[ ] ); int execle (
const char ∗path,
const char ∗arg,
...
char ∗ const envp[ ] ); int execve (
const char ∗path,
char ∗ const argv[ ],
char ∗ const envp[ ] ); int execlp (
const char ∗file,
const char ∗arg,
... ); int execvp (
const char ∗file,
char ∗ const argv[ ] );

PARAMETERS

pathPoints to a pathname identifying the new process image file. 

argSpecifies a character pointer to null-terminated strings. 

argvSpecifies an array of character pointers to null-terminated strings. 

envpSpecifies an array of character pointers to null-terminated strings, constituting the environment for the new process. 

fileIdentifies the new process image file. 

DESCRIPTION

The exec functions replace the current process image with a new process image.  The new image is constructed from a regular executable file, called a new process image file.  A successful exec does not return, because the calling process image is overlaid by the new process image. 

When a program is executed as a result of an exec call, it is entered as a function call as follows: int main (
int argc,
char ∗argv[ ] ); Here, argc is the argument count and argv[ ] is an array of character pointers to the arguments themselves.  In addition, the following variable is initialized as a pointer to an array of character pointers to the environment strings: extern char ∗∗environ; The argv and environ arrays are each terminated by a null pointer.  The null pointer terminating the argv array is not counted in argc. 

The arguments specified by a program with one of the exec functions are passed on to the new process image in the corresponding arguments to main(). 

The path argument points to a pathname that identifies the new process image file. 

The file argument is used to construct a pathname that identifies the new process image file.  If the file argument contains a slash character, the file argument is used as the pathname for this file.  Otherwise, the path prefix for this file is obtained by a search of the directories passed as the PATH environment variable. 

The new process image file is formatted as an executable text or binary file, in one of the formats recognized by the exec functions.  An executable text file is identified by a header line with the following syntax:

#! interpreter_name [ optional_string ]

The #! identifies the file as an executable text file.  The new process image is constructed from the process image file named by the interpreter_name string.  The arguments are modified as follows:

       •argv[0] is set to the name of the interpreter. 

       •If the optional_string is present, argv[1] is set to the optional_string. 

       •The next element of argv[] is set to the original value of path. 

       •The remaining elements of argv[] are set to the original elements of argv[], starting at argv[1].  The original argv[0] is discarded. 

An executable binary file can be loaded either directly by the exec function, or indirectly by the program loader.  The exec function chooses to use direct or indirect loading based on the contents of the new process image file.  For example, indirect loading might be used if the new process image file has unresolved symbols, requiring use of a shared library. 

When indirect loading is used, the new process image is constructed from the default program loader, /sbin/loader, in the same manner as described for the exec_with_loader() function.  The default program loader is then responsible for completing the new program image by loading the new process image file and any shared libraries on which it depends. 

If the process image file is not a valid executable object, the execlp() and execvp() functions use the contents of that file as standard input to a command interpreter conforming to the system() function.  In this case, the command interpreter becomes the new process image. 

The argv argument is an array of character pointers to null-terminated strings.  The last member of this array is a null pointer.  These strings constitute the argument list available to the new process image.  The value in argv[0] should point to a filename that is associated with the process being started by one of the exec functions. 

The const char ∗arg and subsequent ellipses in the execl(), execlp(), and execle() functions can be thought of as arg0, arg1, ..., argn.  Together they describe a list of one or more pointers to null-terminated character strings that represent the argument list available to the new program.  The first argument must point to a filename that is associated with the process being started by one of the exec functions, and the last argument must be a null pointer.  For the execle() function, the environment is provided by following the null pointer that will terminate the list of arguments in the parameter list to execle() with an additional parameter as if it were declared as:

char ∗ const envp[]

The envp argument to execve(), and the final argument to execle(), name an array of character pointers to null-terminated strings.  These strings constitute the environment for the new process image.  The environment array is terminated with a null pointer. 

For those forms not containing an envp pointer (execl(), execv(), execlp() and execvp()) the environment for the new process image is taken from the external variable environ in the calling process. 

The number of bytes available for the new process’ combined argument and environment lists is ARG_MAX.  ARG_MAX includes the null terminators on the strings;  it does not include the pointers. 

File descriptors open in the calling process image remain open in the new process image, except for those whose close-on-exec flag FD_CLOEXEC is set (see the fcntl() function).  For those file descriptors that remain open, all attributes of the open file description, including file locks, remain unchanged. 

The state of directory streams and message catalog descriptors in the new process image is undefined. 

Each mapped file and shared memory region created with the mmap() function is unmapped by a successful call to any of the exec functions, except those regions mapped with the MAP_INHERIT option.  Regions mapped with the MAP_INHERIT option remain mapped in the new process image. 

Signals set to the default action (SIG_DFL) in the calling process image are set to the default action in the new process image. Signals set to be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image.  Signals set to be caught by the calling process image are set to the default action in the new process image (see the signal.h header file). 

If the set user ID mode bit of the new process image file is set (see the chmod() function), the effective user ID of the new process image is set 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 image is set to the group ID of the new process image file.  The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the calling process image.  The effective user ID and effective group ID of the new process image are saved (as the saved set user ID and the saved set group ID) for use by the setuid() function. 

The following attributes of the calling process image are unchanged after successful completion of any of the exec functions:

       •Process ID

       •Parent process ID

       •Process group ID

       •Session membership

       •Real user ID

       •Real group ID

       •Supplementary group IDs

       •Time left until an alarm clock signal (see the alarm() function)

       •Current working directory

       •Root directory

       •File mode creation mask (see the umask() function)

       •Process signal mask (see the sigprocmask() function)

       •Pending signals (see the sigpending() function)

       •The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms structure. 

       •File size limit (see the ulimit() function)

       •Nice value (see the nice() function)

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

NOTES

AES Support Level:
Full use

RETURN VALUE

If one of the exec functions returns to the calling process image, an error has occurred; the return value is −1, and errno is set to indicate the error. 

ERRORS

If the exec functions fail, errno may be set to one of the following values:

[E2BIG]The number of bytes used by the new process image’s argument list and environment list is greater than the system-imposed limit of ARG_MAX bytes. 

[EACCES]Search permission is denied for a directory listed in the new process image file’s path prefix, or the new process image file denies execution permission, or the new process image file is not a regular file and the implementation does not support execution of files of its type. 

[ENAMETOOLONG]
The length of the path or file arguments, or an element of the environment variable PATH prefixed to a file, exceeds PATH_MAX, or a pathname component is longer than NAME_MAX and _POSIX_NO_TRUNC is in effect for that file. 

[ENOENT]One or more components of the new process image file’s pathname do not exist, or the path or file argument points to an empty string. 

[ENOTDIR]A component of the new process image file’s path prefix is not a directory. 

[EFAULT]The path argument is an invalid address. 

[ELOOP]Too many symbolic links were encountered in pathname resolution. 

[ENOMEM]Insufficient memory is available. 

[ETXTBSY]The new process image file is currently open for writing by some process. 

If the execl(), execv(), execle(), or execve() function fails, errno may be set to the following value:

[ENOEXEC]The new process image file has the appropriate access permission but is not in the proper format. 

RELATED INFORMATION

Functions: alarm(3), exit(2), fcntl(2), fork(2), getenv(3), nice(3), putenv(3), sigaction(2), system(3), times(3), ulimit(3), umask(2), mmap(2), exec_with_loader(2)