EXECVE(2) | Linux Programmer's Manual | EXECVE(2) |
NAME
execve - execute programSYNOPSIS
#include <unistd.h>DESCRIPTION
execve() executes the program pointed to by filename. filename must be either a binary executable, or a script starting with a line of the form:#! interpreter [optional-arg]
int main(int argc, char *argv[], char *envp[])
- *
- The dispositions of any signals that are being caught are reset to the default ( signal(7)).
- *
- Any alternate signal stack is not preserved ( sigaltstack(2)).
- *
- Memory mappings are not preserved ( mmap(2)).
- *
- Attached System V shared memory segments are detached ( shmat(2)).
- *
- POSIX shared memory regions are unmapped ( shm_open(3)).
- *
- Open POSIX message queue descriptors are closed ( mq_overview(7)).
- *
- Any open POSIX named semaphores are closed ( sem_overview(7)).
- *
- POSIX timers are not preserved ( timer_create(2)).
- *
- Any open directory streams are closed ( opendir(3)).
- *
- Memory locks are not preserved ( mlock(2), mlockall(2)).
- *
- Exit handlers are not preserved ( atexit(3), on_exit(3)).
- *
- The floating-point environment is reset to the default (see fenv(3)).
The process attributes in the preceding list are all specified in POSIX.1-2001. The following Linux-specific process attributes are also not preserved during an execve():
- *
- The prctl(2) PR_SET_DUMPABLE flag is set, unless a set-user-ID or set-group ID program is being executed, in which case it is cleared.
- *
- The prctl(2) PR_SET_KEEPCAPS flag is cleared.
- *
- (Since Linux 2.4.36 / 2.6.23) If a set-user-ID or set-group-ID program is being executed, then the parent death signal set by prctl(2) PR_SET_PDEATHSIG flag is cleared.
- *
- The process name, as set by prctl(2) PR_SET_NAME (and displayed by ps -o comm), is reset to the name of the new executable file.
- *
- The SECBIT_KEEP_CAPS securebits flag is cleared. See capabilities(7).
- *
- The termination signal is reset to SIGCHLD (see clone(2)).
Note the following further points:
- *
- All threads other than the calling thread are destroyed during an execve(). Mutexes, condition variables, and other pthreads objects are not preserved.
- *
- The equivalent of setlocale(LC_ALL, "C") is executed at program start-up.
- *
- POSIX.1-2001 specifies that the dispositions of any signals that are ignored or set to the default are left unchanged. POSIX.1-2001 specifies one exception: if SIGCHLD is being ignored, then an implementation may leave the disposition unchanged or reset it to the default; Linux does the former.
- *
- Any outstanding asynchronous I/O operations are canceled ( aio_read(3), aio_write(3)).
- *
- For the handling of capabilities during execve(), see capabilities(7).
- *
- By default, file descriptors remain open across an execve(). File descriptors that are marked close-on-exec are closed; see the description of FD_CLOEXEC in fcntl(2). (If a file descriptor is closed, this will cause the release of all record locks obtained on the underlying file by this process. See fcntl(2) for details.) POSIX.1-2001 says that if file descriptors 0, 1, and 2 would otherwise be closed after a successful execve(), and the process would gain privilege because the set-user_ID or set-group_ID permission bit was set on the executed file, then the system may open an unspecified file for each of these file descriptors. As a general principle, no portable program, whether privileged or not, can assume that these three file descriptors will remain closed across an execve().
Interpreter scripts
An interpreter script is a text file that has execute permission enabled and whose first line is of the form:#! interpreter [optional-arg]
interpreter [optional-arg] filename arg...
Limits on size of arguments and environment
Most UNIX implementations impose some limit on the total size of the command-line argument ( argv) and environment ( envp) strings that may be passed to a new program. POSIX.1 allows an implementation to advertise this limit using the ARG_MAX constant (either defined in <limits.h> or available at run time using the call sysconf(_SC_ARG_MAX)).RETURN VALUE
On success, execve() does not return, on error -1 is returned, and errno is set appropriately.ERRORS
- E2BIG
- The total number of bytes in the environment ( envp) and argument list ( argv) is too large.
- EACCES
- Search permission is denied on a component of the path prefix of filename or the name of a script interpreter. (See also path_resolution(7).)
- EACCES
- The file or a script interpreter is not a regular file.
- EACCES
- Execute permission is denied for the file or a script or ELF interpreter.
- EACCES
- The file system is mounted noexec.
- EFAULT
- filename points outside your accessible address space.
- EINVAL
- An ELF executable had more than one PT_INTERP segment (i.e., tried to name more than one interpreter).
- EIO
- An I/O error occurred.
- EISDIR
- An ELF interpreter was a directory.
- ELIBBAD
- An ELF interpreter was not in a recognized format.
- ELOOP
- Too many symbolic links were encountered in resolving filename or the name of a script or ELF interpreter.
- EMFILE
- The process has the maximum number of files open.
- ENAMETOOLONG
- filename is too long.
- ENFILE
- The system limit on the total number of open files has been reached.
- ENOENT
- The file filename or a script or ELF interpreter does not exist, or a shared library needed for file or interpreter cannot be found.
- ENOEXEC
- An executable is not in a recognized format, is for the wrong architecture, or has some other format error that means it cannot be executed.
- ENOMEM
- Insufficient kernel memory was available.
- ENOTDIR
- A component of the path prefix of filename or a script or ELF interpreter is not a directory.
- EPERM
- The file system is mounted nosuid, the user is not the superuser, and the file has the set-user-ID or set-group-ID bit set.
- EPERM
- The process is being traced, the user is not the superuser and the file has the set-user-ID or set-group-ID bit set.
- ETXTBSY
- Executable was open for writing by one or more processes.
CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2001 does not document the #! behavior but is otherwise compatible.NOTES
Set-user-ID and set-group-ID processes can not be ptrace(2)d.Historical
With UNIX V6 the argument list of an exec() call was ended by 0, while the argument list of main was ended by -1. Thus, this argument list was not directly usable in a further exec() call. Since UNIX V7 both are NULL.EXAMPLE
The following program is designed to be execed by the second program below. It just echoes its command-line one per line./* myecho.c */
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
int j;
for (j = 0; j < argc; j++)
printf("argv[%d]: %s\n", j, argv[j]);
exit(EXIT_SUCCESS);
}
This program can be used to exec the program named in its command-line argument:
/* execve.c */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{
char *newargv[] = { NULL, "hello", "world", NULL };
char *newenviron[] = { NULL };
if (argc != 2) {
fprintf(stderr, "Usage: %s <file-to-exec>\n", argv[0]);
exit(EXIT_FAILURE);
}
newargv[0] = argv[1];
execve(argv[1], newargv, newenviron);
perror("execve"); /* execve() only returns on error */
exit(EXIT_FAILURE);
}
We can use the second program to exec the first as follows:
$ cc myecho.c -o myecho
$ cc execve.c -o execve
$ ./execve ./myecho
argv[0]: ./myecho
argv[1]: hello
argv[2]: world
We can also use these programs to demonstrate the use of a script interpreter. To do this we create a script whose "interpreter" is our myecho program:
$ cat > script.sh #!
./myecho
script-arg ^D
$ chmod +x script.sh
We can then use our program to exec the script:
$ ./execve ./script.sh
argv[0]: ./myecho
argv[1]: script-arg
argv[2]: ./script.sh
argv[3]: hello
argv[4]: world
SEE ALSO
chmod(2), fork(2), ptrace(2), execl(3), fexecve(3), getopt(3), credentials(7), environ(7), path_resolution(7), ld.so(8)COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.2013-07-04 | Linux |