*** UNIX MANUAL PAGE BROWSER ***

exec(2) System Calls Manual exec(2) NAME environ, execl, execv, execle, execve, execlp, execvp - Executes a file LIBRARY Standard C Library (libc.a, libc.so) SYNOPSIS #include <unistd.h> 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[ ] ); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: execl(), execv(), execv(), execle(), execve(), execlp(), ex- ecvp(): POSIX.1, XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Points to a pathname identifying the new process image file. Specifies a pointer to a null-terminated string, which is one argument available to the new process image. The first of these parameters points to the filename that is associated with the process being started by execl(), execle(), or execlp(). The last element in the list of arg parameters must be a null pointer. Specifies an array of character pointers to null-terminated strings, which are the arguments available to the new process image. The value in the argv[0] parameter points to the file- name of the process being started by execv(), execve(), or execvp(). The last member of this array must be a null pointer. Specifies an ar- ray of character pointers to null-terminated strings, constituting the environment for the new process. This array must be terminated by a null pointer. Identifies the new process image file. If this parame- ter points to a string containing a slash character, its contents are used as the absolute or relative pathname to the process image file. Otherwise, the system searches the directories specified in the PATH environment variable definition associated with the new process image to obtain a path prefix for the file. DESCRIPTION The exec functions replace the current process image with a new process image. The system constructs the new image from an executable file, called a new process image file. Successful calls to the exec functions do not return because the system overlays the calling process with the new process. To run an executable file using one of the exec functions, applications include a function call such as the following: int main ( int argc, char *argv[ ] ); Here, the argc parameter contains the number of arguments being passed to the new main function. The argv[ ] parameter is a null-terminated array of character pointers that point to the arguments themselves. (The null pointer is not included in the count specified in the argc parameter.) The value in argv[0] should point to the filename that is associated with the process being started by one of the exec functions. The system passes the arguments to the new process image in the corre- sponding arguments to main(). For forms of the exec functions that do not include the envp parameter, applications also define the environ variable to be a pointer to an ar- ray of character strings. The character strings define the environment in which the new process image runs. For example, the following shows how an application defines the environment variable: extern char **environ; The environ array is terminated by a null pointer. The format of the new process image file must be one that is recognized by the exec function being used. The exec functions recognize exe- cutable text files and binary files. An executable text file is one that contains 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 inter- preter_name string. When executing an executable text file, the system modifies the arguments passed to the exec function being used as fol- lows: argv[0] is set to the name of the interpreter. For example, the ksh shell might be 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. A binary file can be loaded either directly by an exec function or in- directly by the program loader. The exec functions choose to use di- rect or indirect loading based on the contents of the new process image file. For example, the functions use indirect loading if the new process image file contains unresolved symbols, requiring use of a shared library. When an exec function loads a binary file indirectly, it constructs the new process image from the default program loader, /sbin/loader, in the same manner as the exec_with_loader() function (see exec_with_loader(2)). 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 exe- clp() 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 number of bytes available for the combined argument and environment lists of the new process image 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 fcntl(2) for more information). For those file descriptors that remain open, all attributes of the open file descrip- tion, including file locks, remain unchanged. Directory streams open in the calling process image are closed in the new process image. The state of directory streams and message catalog descriptors in the new process image is undefined. For the new process, the equivalent of the following command is executed at startup: setlocale(LC_ALL, "C") Each mapped file and shared memory region created with the mmap() func- tion is unmapped by a successful call to any of the exec functions, ex- cept 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 im- age 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 ig- nored by the new process image. Signals set to be caught by the call- ing process image are set to the default action in the new process im- age. [XPG4-UNIX] After a successful call to any of the exec functions, al- ternate signal stacks are not preserved and the SA_ONSTACK flag is cleared for all signals. After a successful call to any of the exec functions, any functions previously registered by atexit() are no longer registered. [XPG4-UNIX] If the ST_NOSUID bit is set for the file system containing the new process image file, the effective user ID, effective group ID, saved set user ID, and saved set group ID are unchanged in the new process. Otherwise, if the set user ID mode bit of the new process image file is set (see chmod(2) for more information), 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. Any shared memory segments attached to the calling process image are not attached to the new process image. [XPG4-UNIX] Any mappings established through mmap() are not preserved across an exec. The following attributes of the calling process image are unchanged af- ter successful completion of any of the exec functions: Process ID Par- ent process ID Process group ID Session membership Real user ID Real group ID Supplementary group IDs Time left until an alarm clock signal (see alarm(3) for more information) Current working directory Root di- rectory File mode creation mask (see umask(2) for more information) Process signal mask (see sigprocmask(2) for more information) Pending signals (see sigpending(2) for more information) 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 nice(3) for more information) Adjust-on-exit values (see semop(2) for more information) [XPG4-UNIX] Resource limits [XPG4-UNIX] Controlling terminal [XPG4-UNIX] Interval timers Upon successful completion, the exec functions mark for update the st_atime field of the file. NOTES If a multithreaded process calls one of the exec functions, all threads except the calling thread are terminated and the calling thread begins execution within the new process image. RETURN VALUES If one of the exec functions returns to the calling process image, an error has occurred; the return value is -1, and the function sets errno to indicate the error. ERRORS The exec functions set errno to the specified values for the following conditions: The number of bytes used by the new process image's argu- ment list and environment list is greater than ARG_MAX bytes. 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 per- mission, or the new process image file is not an executable file type. [Digital] The security attributes of the program file do not allow ex- ecute permission. [Digital] The calling process is using a kernel subsystem that prevents executing the new image. The call to one of the exec functions will not succeed until the process has detached it- self from the subsystem. [Digital] The path argument is an invalid address. [XPG4-UNIX] Too many symbolic links were encountered in pathname resolution. One of the following conditions occurred: The length of the path argument, the file argument, or an element of the environment variable PATH prefixed to a file exceeds PATH_MAX. A path- name component is longer than NAME_MAX, and _POSIX_NO_TRUNC is in ef- fect for that file. 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. Insufficient memory is available. A component of the new process image file's path prefix is not a directory. The execl(), execv(), execle(), and execve() functions also set errno as follows: The new process image file has the appropriate access permission but is not in the proper format. The execlp() and execvp() functions also set errno as follows: [Digital] Indicates that another thread in the process is already per- forming an execlp() or execvp() operation. RELATED INFORMATION Functions: exit(2), fcntl(2), fork(2), sigaction(2), umask(2), mmap(2), exec_with_loader(2) Routines: alarm(3), getenv(3), nice(3), putenv(3), system(3), times(3), ulimit(3) Standards: standards(5) delim off exec(2)