1 EXEC(2) System Calls EXEC(2)
2
3
4
5 NAME
6 exec, execl, execle, execlp, execv, execve, execvp - execute a file
7
8 SYNOPSIS
9 #include <unistd.h>
10
11 int execl(const char *path, const char *arg0, ...
12 /* const char *argn, (char *)0 */);
13
14
15 int execv(const char *path, char *const argv[]);
16
17
18 int execle(const char *path, const char *arg0, ...
19 /* const char *argn, (char *)0,char *const envp[]*/);
20
21
22 int execve(const char *path, char *const argv[],
23 char *const envp[]);
24
25
26 int execlp(const char *file, const char *arg0, ...
27 /* const char *argn, (char *)0 */);
28
29
30 int execvp(const char *file, char *const argv[]);
31
32
33 DESCRIPTION
34 Each of the functions in the exec family replaces the current process
35 image with a new process image. The new image is constructed from a
36 regular, executable file called the new process image file. This file
37 is either an executable object file or a file of data for an
38 interpreter. There is no return from a successful call to one of these
39 functions because the calling process image is overlaid by the new
40 process image.
41
42
43 An interpreter file begins with a line of the form
44
45 #! pathname [arg]
46
47
48
49 where pathname is the path of the interpreter, and arg is an optional
50 argument. When an interpreter file is executed, the system invokes the
51 specified interpreter. The pathname specified in the interpreter file
52 is passed as arg0 to the interpreter. If arg was specified in the
53 interpreter file, it is passed as arg1 to the interpreter. The
54 remaining arguments to the interpreter are arg0 through argn of the
55 originally exec'd file. The interpreter named by pathname may also be
56 an interpreter file. There can be up to four nested interpreter files
57 before the final interpreter. The setid bits on nested interpreters
58 are silently ignored.
59
60
61 When a C-language program is executed as a result of this call, it is
62 entered as a C-language function call as follows:
63
64 int main (int argc, char *argv[]);
65
66
67
68 where argc is the argument count and argv is an array of character
69 pointers to the arguments themselves. In addition, the following
70 variable:
71
72 extern char **environ;
73
74
75
76 is initialized as a pointer to an array of character pointers to the
77 environment strings. The argv and environ arrays are each terminated by
78 a null pointer. The null pointer terminating the argv array is not
79 counted in argc.
80
81
82 The value of argc is non-negative, and if greater than 0, argv[0]
83 points to a string containing the name of the file. If argc is 0,
84 argv[0] is a null pointer, in which case there are no arguments.
85 Applications should verify that argc is greater than 0 or that argv[0]
86 is not a null pointer before dereferencing argv[0].
87
88
89 The arguments specified by a program with one of the exec functions are
90 passed on to the new process image in the main() arguments.
91
92
93 The path argument points to a path name that identifies the new process
94 image file.
95
96
97 The file argument is used to construct a pathname that identifies the
98 new process image file. If the file argument contains a slash
99 character, it is used as the pathname for this file. Otherwise, the
100 path prefix for this file is obtained by a search of the directories
101 passed in the PATH environment variable (see environ(5)). The
102 environment is supplied typically by the shell. If the process image
103 file is not a valid executable object file, execlp() and execvp() use
104 the contents of that file as standard input to the shell. In this case,
105 the shell becomes the new process image. The standard to which the
106 caller conforms determines which shell is used. See standards(5).
107
108
109 The arguments represented by arg0... are pointers to null-terminated
110 character strings. These strings constitute the argument list available
111 to the new process image. The list is terminated by a null pointer.
112 The arg0 argument should point to a filename that is associated with
113 the process being started by one of the exec functions.
114
115
116 The argv argument is an array of character pointers to null-terminated
117 strings. The last member of this array must be a null pointer. These
118 strings constitute the argument list available to the new process
119 image. The value in argv[0] should point to a filename that is
120 associated with the process being started by one of the exec functions.
121
122
123 The envp argument is an array of character pointers to null-terminated
124 strings. These strings constitute the environment for the new process
125 image. The envp array is terminated by a null pointer. For execl(),
126 execv(), execvp(), and execlp(), the C-language run-time start-off
127 routine places a pointer to the environment of the calling process in
128 the global object extern char **environ, and it is used to pass the
129 environment of the calling process to the new process image.
130
131
132 The number of bytes available for the new process's combined argument
133 and environment lists is ARG_MAX. It is implementation-dependent
134 whether null terminators, pointers, and/or any alignment bytes are
135 included in this total.
136
137
138 File descriptors open in the calling process image remain open in the
139 new process image, except for those whose close-on-exec flag FD_CLOEXEC
140 is set; see fcntl(2). For those file descriptors that remain open, all
141 attributes of the open file description, including file locks, remain
142 unchanged.
143
144
145 The preferred hardware address translation size (see memcntl(2)) for
146 the stack and heap of the new process image are set to the default
147 system page size.
148
149
150 Directory streams open in the calling process image are closed in the
151 new process image.
152
153
154 The state of conversion descriptors and message catalogue descriptors
155 in the new process image is undefined. For the new process, the
156 equivalent of:
157
158 setlocale(LC_ALL, "C")
159
160
161
162 is executed at startup.
163
164
165 Signals set to the default action (SIG_DFL) in the calling process
166 image are set to the default action in the new process image (see
167 signal(3C)). Signals set to be ignored (SIG_IGN) by the calling
168 process image are set to be ignored by the new process image. Signals
169 set to be caught by the calling process image are set to the default
170 action in the new process image (see signal.h(3HEAD)). After a
171 successful call to any of the exec functions, alternate signal stacks
172 are not preserved and the SA_ONSTACK flag is cleared for all signals.
173
174
175 After a successful call to any of the exec functions, any functions
176 previously registered by atexit(3C) are no longer registered.
177
178
179 The saved resource limits in the new process image are set to be a copy
180 of the process's corresponding hard and soft resource limits.
181
182
183 If the ST_NOSUID bit is set for the file system containing the new
184 process image file, then the effective user ID and effective group ID
185 are unchanged in the new process image. If the set-user-ID mode bit of
186 the new process image file is set (see chmod(2)), the effective user ID
187 of the new process image is set to the owner ID of the new process
188 image file. Similarly, if the set-group-ID mode bit of the new process
189 image file is set, the effective group ID of the new process image is
190 set to the group ID of the new process image file. The real user ID and
191 real group ID of the new process image remain the same as those of the
192 calling process image. The effective user ID and effective group ID of
193 the new process image are saved (as the saved set-user-ID and the saved
194 set-group-ID for use by setuid(2).
195
196
197 The privilege sets are changed according to the following rules:
198
199 1. The inheritable set, I, is intersected with the limit set,
200 L. This mechanism enforces the limit set for processes.
201
202 2. The effective set, E, and the permitted set, P, are made
203 equal to the new inheritable set.
204
205
206 The system attempts to set the privilege-aware state to non-PA both
207 before performing any modifications to the process IDs and privilege
208 sets as well as after completing the transition to new UIDs and
209 privilege sets, following the rules outlined in privileges(5).
210
211
212 If the {PRIV_PROC_OWNER} privilege is asserted in the effective set,
213 the set-user-ID and set-group-ID bits will be honored when the process
214 is being controlled by ptrace(3C). Additional restriction can apply
215 when the traced process has an effective UID of 0. See privileges(5).
216
217
218 Any shared memory segments attached to the calling process image will
219 not be attached to the new process image (see shmop(2)). Any mappings
220 established through mmap() are not preserved across an exec. Memory
221 mappings created in the process are unmapped before the address space
222 is rebuilt for the new process image. See mmap(2).
223
224
225 Memory locks established by the calling process via calls to
226 mlockall(3C) or mlock(3C) are removed. If locked pages in the address
227 space of the calling process are also mapped into the address spaces
228 the locks established by the other processes will be unaffected by the
229 call by this process to the exec function. If the exec function fails,
230 the effect on memory locks is unspecified.
231
232
233 If _XOPEN_REALTIME is defined and has a value other than -1, any named
234 semaphores open in the calling process are closed as if by appropriate
235 calls to sem_close(3C)
236
237
238 Profiling is disabled for the new process; see profil(2).
239
240
241 Timers created by the calling process with timer_create(3C) are deleted
242 before replacing the current process image with the new process image.
243
244
245 For the SCHED_FIFO and SCHED_RR scheduling policies, the policy and
246 priority settings are not changed by a call to an exec function.
247
248
249 All open message queue descriptors in the calling process are closed,
250 as described in mq_close(3C).
251
252
253 Any outstanding asynchronous I/O operations may be cancelled. Those
254 asynchronous I/O operations that are not canceled will complete as if
255 the exec function had not yet occurred, but any associated signal
256 notifications are suppressed. It is unspecified whether the exec
257 function itself blocks awaiting such I/O completion. In no event,
258 however, will the new process image created by the exec function be
259 affected by the presence of outstanding asynchronous I/O operations at
260 the time the exec function is called.
261
262
263 All active contract templates are cleared (see contract(4)).
264
265
266 The new process also inherits the following attributes from the calling
267 process:
268
269 o controlling terminal
270
271 o current working directory
272
273 o file-locks (see fcntl(2) and lockf(3C))
274
275 o file mode creation mask (see umask(2))
276
277 o file size limit (see ulimit(2))
278
279 o limit privilege set
280
281 o nice value (see nice(2))
282
283 o parent process ID
284
285 o pending signals (see sigpending(2))
286
287 o privilege debugging flag (see privileges(5) and
288 getpflags(2))
289
290 o process ID
291
292 o process contract (see contract(4) and process(4))
293
294 o process group ID
295
296 o process signal mask (see sigprocmask(2))
297
298 o processor bindings (see processor_bind(2))
299
300 o processor set bindings (see pset_bind(2))
301
302 o project ID
303
304 o real group ID
305
306 o real user ID
307
308 o resource limits (see getrlimit(2))
309
310 o root directory
311
312 o scheduler class and priority (see priocntl(2))
313
314 o semadj values (see semop(2))
315
316 o session membership (see exit(2) and signal(3C))
317
318 o supplementary group IDs
319
320 o task ID
321
322 o time left until an alarm clock signal (see alarm(2))
323
324 o tms_utime, tms_stime, tms_cutime, and tms_cstime (see
325 times(2))
326
327 o trace flag (see ptrace(3C) request 0)
328
329
330 A call to any exec function from a process with more than one thread
331 results in all threads being terminated and the new executable image
332 being loaded and executed. No destructor functions will be called.
333
334
335 Upon successful completion, each of the functions in the exec family
336 marks for update the st_atime field of the file. If an exec function
337 failed but was able to locate the process image file, whether the
338 st_atime field is marked for update is unspecified. Should the function
339 succeed, the process image file is considered to have been opened with
340 open(2). The corresponding close(2) is considered to occur at a time
341 after this open, but before process termination or successful
342 completion of a subsequent call to one of the exec functions. The
343 argv[] and envp[] arrays of pointers and the strings to which those
344 arrays point will not be modified by a call to one of the exec
345 functions, except as a consequence of replacing the process image.
346
347
348 The saved resource limits in the new process image are set to be a copy
349 of the process's corresponding hard and soft limits.
350
351 RETURN VALUES
352 If a function in the exec family returns to the calling process image,
353 an error has occurred; the return value is -1 and errno is set to
354 indicate the error.
355
356 ERRORS
357 The exec functions will fail if:
358
359 E2BIG
360 The number of bytes in the new process's argument list
361 is greater than the system-imposed limit of {ARG_MAX}
362 bytes. The argument list limit is sum of the size of
363 the argument list plus the size of the environment's
364 exported shell variables.
365
366
367 EACCES
368 Search permission is denied for a directory listed in
369 the new process file's path prefix.
370
371 The new process file is not an ordinary file.
372
373 The new process file mode denies execute permission.
374
375 The {FILE_DAC_SEARCH} privilege overrides the
376 restriction on directory searches.
377
378 The {FILE_DAC_EXECUTE} privilege overrides the lack of
379 execute permission.
380
381
382 EAGAIN
383 Total amount of system memory available when reading
384 using raw I/O is temporarily insufficient.
385
386
387 EFAULT
388 An argument points to an illegal address.
389
390
391 EINVAL
392 The new process image file has the appropriate
393 permission and has a recognized executable binary
394 format, but the system does not support execution of a
395 file with this format.
396
397
398 EINTR
399 A signal was caught during the execution of one of the
400 functions in the exec family.
401
402
403 ELOOP
404 Too many symbolic links were encountered in translating
405 path or file, or too many nested interpreter files.
406
407
408 ENAMETOOLONG
409 The length of the file or path argument exceeds
410 {PATH_MAX}, or the length of a file or path component
411 exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in
412 effect.
413
414
415 ENOENT
416 One or more components of the new process path name of
417 the file do not exist or is a null pathname.
418
419
420 ENOLINK
421 The path argument points to a remote machine and the
422 link to that machine is no longer active.
423
424
425 ENOTDIR
426 A component of the new process path of the file prefix
427 is not a directory.
428
429
430
431 The exec functions, except for execlp() and execvp(), will fail if:
432
433 ENOEXEC
434 The new process image file has the appropriate access
435 permission but is not in the proper format.
436
437
438
439 The exec functions may fail if:
440
441 ENAMETOOLONG
442 Pathname resolution of a symbolic link produced an
443 intermediate result whose length exceeds {PATH_MAX}.
444
445
446 ENOMEM
447 The new process image requires more memory than is
448 allowed by the hardware or system-imposed by memory
449 management constraints. See brk(2).
450
451
452 ETXTBSY
453 The new process image file is a pure procedure (shared
454 text) file that is currently open for writing by some
455 process.
456
457
458 USAGE
459 As the state of conversion descriptors and message catalogue
460 descriptors in the new process image is undefined, portable
461 applications should not rely on their use and should close them prior
462 to calling one of the exec functions.
463
464
465 Applications that require other than the default POSIX locale should
466 call setlocale(3C) with the appropriate parameters to establish the
467 locale of thenew process.
468
469
470 The environ array should not be accessed directly by the application.
471
472 ATTRIBUTES
473 See attributes(5) for descriptions of the following attributes:
474
475
476
477
478 +--------------------+-------------------+
479 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
480 +--------------------+-------------------+
481 |Interface Stability | Committed |
482 +--------------------+-------------------+
483 |MT-Level | See below. |
484 +--------------------+-------------------+
485 |Standard | See standards(5). |
486 +--------------------+-------------------+
487
488
489 The execle() and execve() functions are Async-Signal-Safe.
490
491 SEE ALSO
492 ksh(1), ps(1), sh(1), alarm(2), brk(2), chmod(2), exit(2), fcntl(2),
493 fork(2), getpflags(2), getrlimit(2), memcntl(2), mmap(2), nice(2),
494 priocntl(2), profil(2), semop(2), shmop(2), sigpending(2),
495 sigprocmask(2), times(2), umask(2), lockf(3C), ptrace(3C),
496 setlocale(3C), signal(3C), system(3C), timer_create(3C), a.out(4),
497 contract(4), process(4), attributes(5), environ(5), privileges(5),
498 standards(5)
499
500 WARNINGS
501 If a program is setuid to a user ID other than the superuser, and the
502 program is executed when the real user ID is super-user, then the
503 program has some of the powers of a super-user as well.
504
505
506
507 October 27, 2015 EXEC(2)