]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)exec.3 6.4 (Berkeley) 4/19/91 | |
35 | .\" | |
36 | .\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu | |
37 | .\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com | |
c11b1abf | 38 | .\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
39 | .\" Added note on casting NULL |
40 | .\" | |
8392a3b3 | 41 | .TH EXEC 3 2015-01-22 "GNU" "Linux Programmer's Manual" |
fea681da | 42 | .SH NAME |
c6361950 | 43 | execl, execlp, execle, execv, execvp, execvpe \- execute a file |
fea681da MK |
44 | .SH SYNOPSIS |
45 | .B #include <unistd.h> | |
46 | .sp | |
47 | .B extern char **environ; | |
48 | .sp | |
49 | .BI "int execl(const char *" path ", const char *" arg ", ...);" | |
50 | .br | |
51 | .BI "int execlp(const char *" file ", const char *" arg ", ...);" | |
52 | .br | |
c7da82ff MK |
53 | .BI "int execle(const char *" path ", const char *" arg , |
54 | .br | |
55 | .BI " ..., char * const " envp "[]);" | |
fea681da MK |
56 | .br |
57 | .BI "int execv(const char *" path ", char *const " argv "[]);" | |
58 | .br | |
59 | .BI "int execvp(const char *" file ", char *const " argv "[]);" | |
c6361950 MK |
60 | .br |
61 | .BI "int execvpe(const char *" file ", char *const " argv "[]," | |
62 | .br | |
784a11da | 63 | .BI " char *const " envp "[]);" |
3e3f098f MK |
64 | .sp |
65 | .in -4n | |
66 | Feature Test Macro Requirements for glibc (see | |
67 | .BR feature_test_macros (7)): | |
68 | .in | |
69 | .sp | |
70 | .BR execvpe (): | |
71 | _GNU_SOURCE | |
fea681da MK |
72 | .SH DESCRIPTION |
73 | The | |
e1d6264d | 74 | .BR exec () |
fea681da | 75 | family of functions replaces the current process image with a new process |
c13182ef | 76 | image. |
b5502dfc | 77 | The functions described in this manual page are front-ends for |
fea681da MK |
78 | .BR execve (2). |
79 | (See the manual page for | |
fb186734 | 80 | .BR execve (2) |
b5502dfc | 81 | for further details about the replacement of the current process image.) |
fea681da | 82 | .PP |
c6361950 | 83 | The initial argument for these functions is the name of a file that is |
fea681da MK |
84 | to be executed. |
85 | .PP | |
86 | The | |
5049da5b | 87 | .I "const char\ *arg" |
fea681da | 88 | and subsequent ellipses in the |
e511ffb6 MK |
89 | .BR execl (), |
90 | .BR execlp (), | |
fea681da | 91 | and |
e511ffb6 | 92 | .BR execle () |
fea681da MK |
93 | functions can be thought of as |
94 | .IR arg0 , | |
95 | .IR arg1 , | |
96 | \&..., | |
97 | .IR argn . | |
98 | Together they describe a list of one or more pointers to null-terminated | |
99 | strings that represent the argument list available to the executed program. | |
2c5f1089 | 100 | The first argument, by convention, should point to the filename associated |
c13182ef MK |
101 | with the file being executed. |
102 | The list of arguments | |
fea681da | 103 | .I must |
b437fdd9 | 104 | be terminated by a null pointer, |
efb12489 | 105 | and, since these are variadic functions, this pointer must be cast |
5049da5b | 106 | .IR "(char\ *) NULL" . |
fea681da MK |
107 | .PP |
108 | The | |
c6361950 MK |
109 | .BR execv (), |
110 | .BR execvp (), | |
fea681da | 111 | and |
c6361950 | 112 | .BR execvpe () |
fea681da | 113 | functions provide an array of pointers to null-terminated strings that |
c13182ef MK |
114 | represent the argument list available to the new program. |
115 | The first argument, by convention, should point to the filename | |
116 | associated with the file being executed. | |
117 | The array of pointers | |
fea681da | 118 | .I must |
b437fdd9 | 119 | be terminated by a null pointer. |
fea681da MK |
120 | .PP |
121 | The | |
e511ffb6 | 122 | .BR execle () |
c6361950 MK |
123 | and |
124 | .BR execvpe () | |
125 | functions allow the caller to specify the environment of the | |
126 | executed program via the argument | |
127 | .IR envp . | |
128 | The | |
129 | .I envp | |
c4bb193f | 130 | argument is an array of pointers to null-terminated strings and |
fea681da | 131 | .I must |
b437fdd9 | 132 | be terminated by a null pointer. |
8478ee02 | 133 | The other functions take the environment for the new process |
fea681da MK |
134 | image from the external variable |
135 | .I environ | |
c6361950 | 136 | in the calling process. |
acffc0bc | 137 | .SS Special semantics for execlp() and execvp() |
fea681da | 138 | .PP |
76e2566b | 139 | The |
c6361950 MK |
140 | .BR execlp (), |
141 | .BR execvp (), | |
fea681da | 142 | and |
c6361950 | 143 | .BR execvpe () |
76e2566b MK |
144 | functions duplicate the actions of the shell in |
145 | searching for an executable file | |
c13182ef | 146 | if the specified filename does not contain a slash (/) character. |
76e2566b MK |
147 | The file is sought in the colon-separated list of directory pathnames |
148 | specified in the | |
fea681da | 149 | .B PATH |
76e2566b MK |
150 | environment variable. |
151 | If this variable isn't defined, the path list defaults to | |
152 | the current directory followed by the list of directories returned by | |
153 | .IR confstr(_CS_PATH) . | |
154 | (This | |
155 | .BR confstr (3) | |
156 | call typically returns the value "/bin:/usr/bin".) | |
157 | ||
c6361950 | 158 | If the specified filename includes a slash character, then |
8891f712 | 159 | .B PATH |
c6361950 | 160 | is ignored, and the file at the specified pathname is executed. |
8891f712 MK |
161 | |
162 | In addition, certain errors are treated specially. | |
6517af00 | 163 | |
fea681da | 164 | If permission is denied for a file (the attempted |
a51a49df | 165 | .BR execve (2) |
84af7ae7 | 166 | failed with the error |
fea681da | 167 | .BR EACCES ), |
c13182ef MK |
168 | these functions will continue searching the rest of the search path. |
169 | If no other file is found, however, | |
28d03ce9 | 170 | they will return with |
fea681da MK |
171 | .I errno |
172 | set to | |
173 | .BR EACCES . | |
6517af00 | 174 | |
fea681da | 175 | If the header of a file isn't recognized (the attempted |
a51a49df | 176 | .BR execve (2) |
84af7ae7 | 177 | failed with the error |
fea681da | 178 | .BR ENOEXEC ), |
988db661 | 179 | these functions will execute the shell |
acffc0bc MK |
180 | .RI ( /bin/sh ) |
181 | with the path of the file as its first argument. | |
c13182ef | 182 | (If this attempt fails, no further searching is done.) |
47297adb | 183 | .SH RETURN VALUE |
c6361950 | 184 | The |
e1d6264d | 185 | .BR exec () |
33a0ccb2 | 186 | functions return only if an error has occurred. |
28d03ce9 | 187 | The return value is \-1, and |
fea681da | 188 | .I errno |
c6361950 | 189 | is set to indicate the error. |
fea681da MK |
190 | .SH ERRORS |
191 | All of these functions may fail and set | |
192 | .I errno | |
c6361950 | 193 | for any of the errors specified for |
fea681da | 194 | .BR execve (2). |
c5e56482 | 195 | .SH VERSIONS |
c6361950 MK |
196 | The |
197 | .BR execvpe () | |
198 | function first appeared in glibc 2.11. | |
47297adb | 199 | .SH CONFORMING TO |
c6361950 MK |
200 | POSIX.1-2001, POSIX.1-2008. |
201 | ||
202 | The | |
203 | .BR execvpe () | |
204 | function is a GNU extension. | |
8af1ba10 | 205 | .SH NOTES |
c6361950 | 206 | On some other systems, the default path (used when the environment |
fea681da MK |
207 | does not contain the variable \fBPATH\fR) has the current working |
208 | directory listed after | |
209 | .I /bin | |
210 | and | |
211 | .IR /usr/bin , | |
c13182ef MK |
212 | as an anti-Trojan-horse measure. |
213 | Linux uses here the | |
fea681da MK |
214 | traditional "current directory first" default path. |
215 | .PP | |
216 | The behavior of | |
e511ffb6 | 217 | .BR execlp () |
fea681da | 218 | and |
e511ffb6 | 219 | .BR execvp () |
fea681da MK |
220 | when errors occur while attempting to execute the file is historic |
221 | practice, but has not traditionally been documented and is not specified by | |
c13182ef MK |
222 | the POSIX standard. |
223 | BSD (and possibly other systems) do an automatic | |
2f0af33b MK |
224 | sleep and retry if |
225 | .B ETXTBSY | |
226 | is encountered. | |
c13182ef | 227 | Linux treats it as a hard |
fea681da MK |
228 | error and returns immediately. |
229 | .PP | |
230 | Traditionally, the functions | |
e511ffb6 | 231 | .BR execlp () |
fea681da | 232 | and |
e511ffb6 | 233 | .BR execvp () |
fea681da MK |
234 | ignored all errors except for the ones described above and |
235 | .B ENOMEM | |
236 | and | |
237 | .BR E2BIG , | |
c13182ef MK |
238 | upon which they returned. |
239 | They now return if any error other than the ones | |
fea681da | 240 | described above occurs. |
47297adb | 241 | .SH SEE ALSO |
e37e3282 MK |
242 | .BR sh (1), |
243 | .BR execve (2), | |
6251424c | 244 | .BR execveat (2), |
e37e3282 MK |
245 | .BR fork (2), |
246 | .BR ptrace (2), | |
247 | .BR fexecve (3), | |
248 | .BR environ (7) |