Debian Codegraph @

upstream/debian-unstable/man3/exec.3

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