1EXEC(3)                    Linux Programmer's Manual                   EXEC(3)
2
3
4

NAME

6       execl, execlp, execle, execv, execvp, execvpe - execute a file
7

SYNOPSIS

9       #include <unistd.h>
10
11       extern char **environ;
12
13       int execl(const char *path, const char *arg, ...);
14       int execlp(const char *file, const char *arg, ...);
15       int execle(const char *path, const char *arg,
16                  ..., char * const envp[]);
17       int execv(const char *path, char *const argv[]);
18       int execvp(const char *file, char *const argv[]);
19       int execvpe(const char *file, char *const argv[],
20                   char *const envp[]);
21
22   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23
24       execvpe(): _GNU_SOURCE
25

DESCRIPTION

27       The  exec() family of functions replaces the current process image with
28       a new process image.  The functions described in this manual  page  are
29       front-ends  for execve(2).  (See the manual page for execve(2) for fur‐
30       ther details about the replacement of the current process image.)
31
32       The initial argument for these functions is the name of a file that  is
33       to be executed.
34
35       The  const  char *arg and subsequent ellipses in the execl(), execlp(),
36       and execle() functions can be thought of  as  arg0,  arg1,  ...,  argn.
37       Together  they  describe  a list of one or more pointers to null-termi‐
38       nated strings that represent the argument list available  to  the  exe‐
39       cuted  program.  The first argument, by convention, should point to the
40       filename associated with the file being executed.  The  list  of  argu‐
41       ments  must be terminated by a NULL pointer, and, since these are vari‐
42       adic functions, this pointer must be cast (char *) NULL.
43
44       The execv(), execvp(), and execvpe()  functions  provide  an  array  of
45       pointers  to  null-terminated  strings that represent the argument list
46       available to the new  program.   The  first  argument,  by  convention,
47       should  point  to the filename associated with the file being executed.
48       The array of pointers must be terminated by a NULL pointer.
49
50       The execle() and execvpe() functions allow the caller  to  specify  the
51       environment  of  the  executed program via the argument envp.  The envp
52       argument is an array of pointers to null-terminated strings and must be
53       terminated by a NULL pointer.  The other functions take the environment
54       for the new process image from the external  variable  environ  in  the
55       calling process.
56
57   Special semantics for execlp() and execvp()
58       The  execlp(),  execvp(), and execvpe() functions duplicate the actions
59       of the shell in searching for an executable file if the specified file‐
60       name does not contain a slash (/) character.  The file is sought in the
61       colon-separated list of directory pathnames specified in the PATH envi‐
62       ronment  variable.   If  this  variable  isn't  defined,  the path list
63       defaults to the current directory followed by the list  of  directories
64       returned by confstr(_CS_PATH).  (This confstr(3) call typically returns
65       the value "/bin:/usr/bin".)
66
67       If the specified filename includes a  slash  character,  then  PATH  is
68       ignored, and the file at the specified pathname is executed.
69
70       In addition, certain errors are treated specially.
71
72       If permission is denied for a file (the attempted execve(2) failed with
73       the error EACCES), these functions will continue searching the rest  of
74       the  search path.  If no other file is found, however, they will return
75       with errno set to EACCES.
76
77       If the header of a  file  isn't  recognized  (the  attempted  execve(2)
78       failed  with the error ENOEXEC), these functions will execute the shell
79       (/bin/sh) with the path of the file as its first  argument.   (If  this
80       attempt fails, no further searching is done.)
81

RETURN VALUE

83       The  exec() functions return only if an error has occurred.  The return
84       value is -1, and errno is set to indicate the error.
85

ERRORS

87       All of these functions may fail and set errno for  any  of  the  errors
88       specified for execve(2).
89

VERSIONS

91       The execvpe() function first appeared in glibc 2.11.
92

CONFORMING TO

94       POSIX.1-2001, POSIX.1-2008.
95
96       The execvpe() function is a GNU extension.
97

NOTES

99       On some other systems, the default path (used when the environment does
100       not contain the variable PATH) has the current working directory listed
101       after  /bin  and /usr/bin, as an anti-Trojan-horse measure.  Linux uses
102       here the traditional "current directory first" default path.
103
104       The behavior of execlp() and execvp() when errors occur while  attempt‐
105       ing to execute the file is historic practice, but has not traditionally
106       been documented and is not specified by the POSIX standard.   BSD  (and
107       possibly  other  systems) do an automatic sleep and retry if ETXTBSY is
108       encountered.  Linux treats it as a hard error and returns immediately.
109
110       Traditionally, the functions execlp() and execvp() ignored  all  errors
111       except  for  the  ones described above and ENOMEM and E2BIG, upon which
112       they returned.  They now return  if  any  error  other  than  the  ones
113       described above occurs.
114

SEE ALSO

116       sh(1), execve(2), fork(2), ptrace(2), fexecve(3), environ(7)
117

COLOPHON

119       This  page  is  part of release 3.53 of the Linux man-pages project.  A
120       description of the project, and information about reporting  bugs,  can
121       be found at http://www.kernel.org/doc/man-pages/.
122
123
124
125GNU                               2010-09-25                           EXEC(3)
Impressum