Debian Codegraph @

upstream/debian-trixie/man3/exec.3

raw
1 '\" t
2 .\" Copyright (c) 1991 The Regents of the University of California.
3 .\" All rights reserved.
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .\" @(#)exec.3 6.4 (Berkeley) 4/19/91
8 .\"
9 .\" Converted for Linux, Mon Nov 29 11:12:48 1993, [email protected]
10 .\" Updated more for Linux, Tue Jul 15 11:54:18 1997, [email protected]
11 .\" Modified, 24 Jun 2004, Michael Kerrisk <[email protected]>
12 .\" Added note on casting NULL
13 .\"
14 .TH exec 3 2024-06-16 "Linux man-pages 6.9.1"
15 .SH NAME
16 execl, execlp, execle, execv, execvp, execvpe \- execute a file
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <unistd.h>
23 .P
24 .B extern char **environ;
25 .P
26 .BI "int execl(const char *" pathname ", const char *" arg ", ..."
27 .B " /*, (char *) NULL */);"
28 .BI "int execlp(const char *" file ", const char *" arg ", ..."
29 .B " /*, (char *) NULL */);"
30 .BI "int execle(const char *" pathname ", const char *" arg ", ..."
31 .BI " /*, (char *) NULL, char *const " envp "[] */);"
32 .BI "int execv(const char *" pathname ", char *const " argv "[]);"
33 .BI "int execvp(const char *" file ", char *const " argv "[]);"
34 .BI "int execvpe(const char *" file ", char *const " argv \
35 "[], char *const " envp "[]);"
36 .fi
37 .P
38 .RS -4
39 Feature Test Macro Requirements for glibc (see
40 .BR feature_test_macros (7)):
41 .RE
42 .P
43 .BR execvpe ():
44 .nf
45 _GNU_SOURCE
46 .fi
47 .SH DESCRIPTION
48 The
49 .BR exec ()
50 family of functions replaces the current process image with a new process
51 image.
52 The functions described in this manual page are layered on top of
53 .BR execve (2).
54 (See the manual page for
55 .BR execve (2)
56 for further details about the replacement of the current process image.)
57 .P
58 The initial argument for these functions is the name of a file that is
59 to be executed.
60 .P
61 The functions can be grouped based on the letters following the "exec" prefix.
62 .\"
63 .SS l - execl(), execlp(), execle()
64 The
65 .I "const char\ *arg"
66 and subsequent ellipses can be thought of as
67 .IR arg0 ,
68 .IR arg1 ,
69 \&...,
70 .IR argn .
71 Together they describe a list of one or more pointers to null-terminated
72 strings that represent the argument list available to the executed program.
73 The first argument, by convention, should point to the filename associated
74 with the file being executed.
75 The list of arguments
76 .I must
77 be terminated by a null pointer,
78 and, since these are variadic functions, this pointer must be cast
79 .IR "(char\ *) NULL" .
80 .P
81 By contrast with the 'l' functions, the 'v' functions (below) specify the
82 command-line arguments of the executed program as a vector.
83 .\"
84 .SS v - execv(), execvp(), execvpe()
85 The
86 .I "char\ *const argv[]"
87 argument is an array of pointers to null-terminated strings that
88 represent the argument list available to the new program.
89 The first argument, by convention, should point to the filename
90 associated with the file being executed.
91 The array of pointers
92 .I must
93 be terminated by a null pointer.
94 .SS e - execle(), execvpe()
95 The environment of the new process image is specified via the argument
96 .IR envp .
97 The
98 .I envp
99 argument is an array of pointers to null-terminated strings and
100 .I must
101 be terminated by a null pointer.
102 .P
103 All other
104 .BR exec ()
105 functions (which do not include 'e' in the suffix)
106 take the environment for the new process
107 image from the external variable
108 .I environ
109 in the calling process.
110 .SS p - execlp(), execvp(), execvpe()
111 These functions duplicate the actions of the shell in
112 searching for an executable file
113 if the specified filename does not contain a slash (/) character.
114 The file is sought in the colon-separated list of directory pathnames
115 specified in the
116 .B PATH
117 environment variable.
118 If this variable isn't defined, the path list defaults to
119 a list that includes the directories returned by
120 .I confstr(_CS_PATH)
121 (which typically returns the value "/bin:/usr/bin")
122 and possibly also the current working directory;
123 see VERSIONS for further details.
124 .P
125 .BR execvpe ()
126 searches for the program using the value of
127 .B PATH
128 from the caller's environment, not from the
129 .I envp
130 argument.
131 .P
132 If the specified filename includes a slash character, then
133 .B PATH
134 is ignored, and the file at the specified pathname is executed.
135 .P
136 In addition, certain errors are treated specially.
137 .P
138 If permission is denied for a file (the attempted
139 .BR execve (2)
140 failed with the error
141 .BR EACCES ),
142 these functions will continue searching the rest of the search path.
143 If no other file is found, however,
144 they will return with
145 .I errno
146 set to
147 .BR EACCES .
148 .P
149 If the header of a file isn't recognized (the attempted
150 .BR execve (2)
151 failed with the error
152 .BR ENOEXEC ),
153 these functions will execute the shell
154 .RI ( /bin/sh )
155 with the path of the file as its first argument.
156 (If this attempt fails, no further searching is done.)
157 .P
158 All other
159 .BR exec ()
160 functions (which do not include 'p' in the suffix)
161 take as their first argument a (relative or absolute) pathname
162 that identifies the program to be executed.
163 .SH RETURN VALUE
164 The
165 .BR exec ()
166 functions return only if an error has occurred.
167 The return value is \-1, and
168 .I errno
169 is set to indicate the error.
170 .SH ERRORS
171 All of these functions may fail and set
172 .I errno
173 for any of the errors specified for
174 .BR execve (2).
175 .SH ATTRIBUTES
176 For an explanation of the terms used in this section, see
177 .BR attributes (7).
178 .TS
179 allbox;
180 lbx lb lb
181 l l l.
182 Interface Attribute Value
183 T{
184 .na
185 .nh
186 .BR execl (),
187 .BR execle (),
188 .BR execv ()
189 T} Thread safety MT-Safe
190 T{
191 .na
192 .nh
193 .BR execlp (),
194 .BR execvp (),
195 .BR execvpe ()
196 T} Thread safety MT-Safe env
197 .TE
198 .SH VERSIONS
199 The default search path (used when the environment
200 does not contain the variable \fBPATH\fR)
201 shows some variation across systems.
202 It generally includes
203 .I /bin
204 and
205 .I /usr/bin
206 (in that order) and may also include the current working directory.
207 On some other systems, the current working is included after
208 .I /bin
209 and
210 .IR /usr/bin ,
211 as an anti-Trojan-horse measure.
212 The glibc implementation long followed the traditional default where
213 the current working directory is included at the start of the search path.
214 However, some code refactoring during the development of glibc 2.24
215 .\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83
216 caused the current working directory to be dropped altogether
217 from the default search path.
218 This accidental behavior change is considered mildly beneficial,
219 and won't be reverted.
220 .P
221 The behavior of
222 .BR execlp ()
223 and
224 .BR execvp ()
225 when errors occur while attempting to execute the file is historic
226 practice, but has not traditionally been documented and is not specified by
227 the POSIX standard.
228 BSD (and possibly other systems) do an automatic
229 sleep and retry if
230 .B ETXTBSY
231 is encountered.
232 Linux treats it as a hard
233 error and returns immediately.
234 .P
235 Traditionally, the functions
236 .BR execlp ()
237 and
238 .BR execvp ()
239 ignored all errors except for the ones described above and
240 .B ENOMEM
241 and
242 .BR E2BIG ,
243 upon which they returned.
244 They now return if any error other than the ones
245 described above occurs.
246 .SH STANDARDS
247 .TP
248 .B environ
249 .TQ
250 .BR execl ()
251 .TQ
252 .BR execlp ()
253 .TQ
254 .BR execle ()
255 .TQ
256 .BR execv ()
257 .TQ
258 .BR execvp ()
259 POSIX.1-2008.
260 .TP
261 .BR execvpe ()
262 GNU.
263 .SH HISTORY
264 .TP
265 .B environ
266 .TQ
267 .BR execl ()
268 .TQ
269 .BR execlp ()
270 .TQ
271 .BR execle ()
272 .TQ
273 .BR execv ()
274 .TQ
275 .BR execvp ()
276 POSIX.1-2001.
277 .TP
278 .BR execvpe ()
279 glibc 2.11.
280 .SH BUGS
281 Before glibc 2.24,
282 .BR execl ()
283 and
284 .BR execle ()
285 employed
286 .BR realloc (3)
287 internally and were consequently not async-signal-safe,
288 in violation of the requirements of POSIX.1.
289 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534
290 This was fixed in glibc 2.24.
291 .\"
292 .SS Architecture-specific details
293 On sparc and sparc64,
294 .BR execv ()
295 is provided as a system call by the kernel
296 (with the prototype shown above)
297 for compatibility with SunOS.
298 This function is
299 .I not
300 employed by the
301 .BR execv ()
302 wrapper function on those architectures.
303 .SH SEE ALSO
304 .BR sh (1),
305 .BR execve (2),
306 .BR execveat (2),
307 .BR fork (2),
308 .BR ptrace (2),
309 .BR fexecve (3),
310 .BR system (3),
311 .BR environ (7)