]>
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 | .\" | |
4b8c67d9 | 41 | .TH EXEC 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 42 | .SH NAME |
c6361950 | 43 | execl, execlp, execle, execv, execvp, execvpe \- execute a file |
fea681da | 44 | .SH SYNOPSIS |
8f92fd96 | 45 | .nf |
fea681da | 46 | .B #include <unistd.h> |
68e4db0a | 47 | .PP |
fea681da | 48 | .B extern char **environ; |
68e4db0a | 49 | .PP |
2a3bc44e | 50 | .BI "int execl(const char *" path ", const char *" arg ", ..." |
67de1cc9 | 51 | .B " /* (char *) NULL */);" |
2a3bc44e | 52 | .BI "int execlp(const char *" file ", const char *" arg ", ..." |
67de1cc9 | 53 | .B " /* (char *) NULL */);" |
67de1cc9 | 54 | .BI "int execle(const char *" path ", const char *" arg ", ..." |
67de1cc9 | 55 | .BI " /*, (char *) NULL, char * const " envp "[] */);" |
fea681da | 56 | .BI "int execv(const char *" path ", char *const " argv "[]);" |
fea681da | 57 | .BI "int execvp(const char *" file ", char *const " argv "[]);" |
c6361950 | 58 | .BI "int execvpe(const char *" file ", char *const " argv "[]," |
67de1cc9 | 59 | .BI " char *const " envp "[]);" |
8f92fd96 | 60 | .fi |
68e4db0a | 61 | .PP |
3e3f098f MK |
62 | .in -4n |
63 | Feature Test Macro Requirements for glibc (see | |
64 | .BR feature_test_macros (7)): | |
65 | .in | |
68e4db0a | 66 | .PP |
3e3f098f MK |
67 | .BR execvpe (): |
68 | _GNU_SOURCE | |
fea681da MK |
69 | .SH DESCRIPTION |
70 | The | |
e1d6264d | 71 | .BR exec () |
fea681da | 72 | family of functions replaces the current process image with a new process |
c13182ef | 73 | image. |
b5502dfc | 74 | The functions described in this manual page are front-ends for |
fea681da MK |
75 | .BR execve (2). |
76 | (See the manual page for | |
fb186734 | 77 | .BR execve (2) |
b5502dfc | 78 | for further details about the replacement of the current process image.) |
fea681da | 79 | .PP |
c6361950 | 80 | The initial argument for these functions is the name of a file that is |
fea681da MK |
81 | to be executed. |
82 | .PP | |
83 | The | |
5049da5b | 84 | .I "const char\ *arg" |
fea681da | 85 | and subsequent ellipses in the |
e511ffb6 MK |
86 | .BR execl (), |
87 | .BR execlp (), | |
fea681da | 88 | and |
e511ffb6 | 89 | .BR execle () |
fea681da MK |
90 | functions can be thought of as |
91 | .IR arg0 , | |
92 | .IR arg1 , | |
93 | \&..., | |
94 | .IR argn . | |
95 | Together they describe a list of one or more pointers to null-terminated | |
96 | strings that represent the argument list available to the executed program. | |
2c5f1089 | 97 | The first argument, by convention, should point to the filename associated |
c13182ef MK |
98 | with the file being executed. |
99 | The list of arguments | |
fea681da | 100 | .I must |
b437fdd9 | 101 | be terminated by a null pointer, |
efb12489 | 102 | and, since these are variadic functions, this pointer must be cast |
5049da5b | 103 | .IR "(char\ *) NULL" . |
fea681da MK |
104 | .PP |
105 | The | |
c6361950 MK |
106 | .BR execv (), |
107 | .BR execvp (), | |
fea681da | 108 | and |
c6361950 | 109 | .BR execvpe () |
fea681da | 110 | functions provide an array of pointers to null-terminated strings that |
c13182ef MK |
111 | represent the argument list available to the new program. |
112 | The first argument, by convention, should point to the filename | |
113 | associated with the file being executed. | |
114 | The array of pointers | |
fea681da | 115 | .I must |
b437fdd9 | 116 | be terminated by a null pointer. |
fea681da MK |
117 | .PP |
118 | The | |
e511ffb6 | 119 | .BR execle () |
c6361950 MK |
120 | and |
121 | .BR execvpe () | |
122 | functions allow the caller to specify the environment of the | |
123 | executed program via the argument | |
124 | .IR envp . | |
125 | The | |
126 | .I envp | |
c4bb193f | 127 | argument is an array of pointers to null-terminated strings and |
fea681da | 128 | .I must |
b437fdd9 | 129 | be terminated by a null pointer. |
8478ee02 | 130 | The other functions take the environment for the new process |
fea681da MK |
131 | image from the external variable |
132 | .I environ | |
c6361950 | 133 | in the calling process. |
acffc0bc | 134 | .SS Special semantics for execlp() and execvp() |
fea681da | 135 | .PP |
76e2566b | 136 | The |
c6361950 MK |
137 | .BR execlp (), |
138 | .BR execvp (), | |
fea681da | 139 | and |
c6361950 | 140 | .BR execvpe () |
76e2566b MK |
141 | functions duplicate the actions of the shell in |
142 | searching for an executable file | |
c13182ef | 143 | if the specified filename does not contain a slash (/) character. |
76e2566b MK |
144 | The file is sought in the colon-separated list of directory pathnames |
145 | specified in the | |
fea681da | 146 | .B PATH |
76e2566b MK |
147 | environment variable. |
148 | If this variable isn't defined, the path list defaults to | |
7a951861 MK |
149 | a list that includes the directories returned by |
150 | .IR confstr(_CS_PATH) | |
151 | (which typically returns the value "/bin:/usr/bin") | |
152 | and possibly also the current working directory; | |
153 | see NOTES for further details. | |
847e0d88 | 154 | .PP |
c6361950 | 155 | If the specified filename includes a slash character, then |
8891f712 | 156 | .B PATH |
c6361950 | 157 | is ignored, and the file at the specified pathname is executed. |
847e0d88 | 158 | .PP |
8891f712 | 159 | In addition, certain errors are treated specially. |
847e0d88 | 160 | .PP |
fea681da | 161 | If permission is denied for a file (the attempted |
a51a49df | 162 | .BR execve (2) |
84af7ae7 | 163 | failed with the error |
fea681da | 164 | .BR EACCES ), |
c13182ef MK |
165 | these functions will continue searching the rest of the search path. |
166 | If no other file is found, however, | |
28d03ce9 | 167 | they will return with |
fea681da MK |
168 | .I errno |
169 | set to | |
170 | .BR EACCES . | |
847e0d88 | 171 | .PP |
fea681da | 172 | If the header of a file isn't recognized (the attempted |
a51a49df | 173 | .BR execve (2) |
84af7ae7 | 174 | failed with the error |
fea681da | 175 | .BR ENOEXEC ), |
988db661 | 176 | these functions will execute the shell |
acffc0bc MK |
177 | .RI ( /bin/sh ) |
178 | with the path of the file as its first argument. | |
c13182ef | 179 | (If this attempt fails, no further searching is done.) |
47297adb | 180 | .SH RETURN VALUE |
c6361950 | 181 | The |
e1d6264d | 182 | .BR exec () |
33a0ccb2 | 183 | functions return only if an error has occurred. |
28d03ce9 | 184 | The return value is \-1, and |
fea681da | 185 | .I errno |
c6361950 | 186 | is set to indicate the error. |
fea681da MK |
187 | .SH ERRORS |
188 | All of these functions may fail and set | |
189 | .I errno | |
c6361950 | 190 | for any of the errors specified for |
fea681da | 191 | .BR execve (2). |
c5e56482 | 192 | .SH VERSIONS |
c6361950 MK |
193 | The |
194 | .BR execvpe () | |
195 | function first appeared in glibc 2.11. | |
76474a15 PH |
196 | .SH ATTRIBUTES |
197 | For an explanation of the terms used in this section, see | |
198 | .BR attributes (7). | |
199 | .TS | |
200 | allbox; | |
201 | lbw29 lb lb | |
202 | l l l. | |
203 | Interface Attribute Value | |
204 | T{ | |
205 | .BR execl (), | |
206 | .BR execle (), | |
207 | .BR execv () | |
208 | T} Thread safety MT-Safe | |
209 | T{ | |
210 | .BR execlp (), | |
211 | .BR execvp (), | |
212 | .BR execvpe () | |
213 | T} Thread safety MT-Safe env | |
214 | .TE | |
47297adb | 215 | .SH CONFORMING TO |
c6361950 | 216 | POSIX.1-2001, POSIX.1-2008. |
847e0d88 | 217 | .PP |
c6361950 MK |
218 | The |
219 | .BR execvpe () | |
220 | function is a GNU extension. | |
8af1ba10 | 221 | .SH NOTES |
7a951861 MK |
222 | The default search path (used when the environment |
223 | does not contain the variable \fBPATH\fR) | |
224 | shows some variation across systems. | |
225 | It generally includes | |
226 | .I /bin | |
227 | and | |
228 | .IR /usr/bin | |
229 | (in that order) and may also include the current working directory. | |
230 | On some other systems, the current working is included after | |
fea681da MK |
231 | .I /bin |
232 | and | |
233 | .IR /usr/bin , | |
c13182ef | 234 | as an anti-Trojan-horse measure. |
7a951861 MK |
235 | The glibc implementation long followed the traditional default where |
236 | the current working directory is included at the start of the search path. | |
237 | However, some code refactoring during the development of glibc 2.24 | |
238 | .\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83 | |
239 | caused the current working directory to be dropped altogether | |
240 | from the default search path. | |
241 | This accidental behavior change is considered mildly beneficial, | |
242 | and won't be reverted. | |
fea681da MK |
243 | .PP |
244 | The behavior of | |
e511ffb6 | 245 | .BR execlp () |
fea681da | 246 | and |
e511ffb6 | 247 | .BR execvp () |
fea681da MK |
248 | when errors occur while attempting to execute the file is historic |
249 | practice, but has not traditionally been documented and is not specified by | |
c13182ef MK |
250 | the POSIX standard. |
251 | BSD (and possibly other systems) do an automatic | |
2f0af33b MK |
252 | sleep and retry if |
253 | .B ETXTBSY | |
254 | is encountered. | |
c13182ef | 255 | Linux treats it as a hard |
fea681da MK |
256 | error and returns immediately. |
257 | .PP | |
258 | Traditionally, the functions | |
e511ffb6 | 259 | .BR execlp () |
fea681da | 260 | and |
e511ffb6 | 261 | .BR execvp () |
fea681da MK |
262 | ignored all errors except for the ones described above and |
263 | .B ENOMEM | |
264 | and | |
265 | .BR E2BIG , | |
c13182ef MK |
266 | upon which they returned. |
267 | They now return if any error other than the ones | |
fea681da | 268 | described above occurs. |
ff1203e5 MK |
269 | .SH BUGS |
270 | Before glibc 2.24, | |
c4c97d9f | 271 | .BR execl () |
ff1203e5 | 272 | and |
c4c97d9f | 273 | .BR execle () |
ff1203e5 MK |
274 | employed |
275 | .BR realloc (3) | |
276 | internally and were consequently not async-signal-safe, | |
277 | in violation of the requirements of POSIX.1. | |
278 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 | |
279 | This was fixed in glibc 2.24. | |
47297adb | 280 | .SH SEE ALSO |
e37e3282 MK |
281 | .BR sh (1), |
282 | .BR execve (2), | |
6251424c | 283 | .BR execveat (2), |
e37e3282 MK |
284 | .BR fork (2), |
285 | .BR ptrace (2), | |
286 | .BR fexecve (3), | |
6c15ab2d | 287 | .BR system (3), |
e37e3282 | 288 | .BR environ (7) |