1exec(2) System Calls exec(2)
2
6 exec, execl, execle, execlp, execv, execve, execvp - execute a file
7
9 #include <unistd.h>
10 int execl(const char *path, const char *arg0, ...
12 /* const char *argn, (char *)0 */);
13 int execv(const char *path, char *const argv[]);
16 int execle(const char *path, const char *arg0, ...
19 /* const char *argn, (char *)0,char *const envp[]*/);
20 int execve(const char *path, char *const argv[],
23 char *const envp[]);
24 int execlp(const char *file, const char *arg0, ...
27 /* const char *argn, (char *)0 */);
28 int execvp(const char *file, char *const argv[]);
31
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 inter‐
38 preter. There is no return from a successful call to one of these func‐
39 tions because the calling process image is overlaid by the new process
40 image.
41 An interpreter file begins with a line of the form
44 #! pathname [arg]
46 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 remain‐
54 ing arguments to the interpreter are arg0 through argn of the origi‐
55 nally exec'd file. The interpreter named by pathname must not be an
56 interpreter file.
57 When a C-language program is executed as a result of this call, it is
60 entered as a C-language function call as follows:
61 int main (int argc, char *argv[]);
63 where argc is the argument count and argv is an array of character
67 pointers to the arguments themselves. In addition, the following vari‐
68 able:
69 extern char **environ;
71 is initialized as a pointer to an array of character pointers to the
75 environment strings. The argv and environ arrays are each terminated by
76 a null pointer. The null pointer terminating the argv array is not
77 counted in argc.
78 The value of argc is non-negative, and if greater than 0, argv[0]
81 points to a string containing the name of the file. If argc is 0,
82 argv[0] is a null pointer, in which case there are no arguments. Appli‐
83 cations should verify that argc is greater than 0 or that argv[0] is
84 not a null pointer before dereferencing argv[0].
85 The arguments specified by a program with one of the exec functions are
88 passed on to the new process image in the main() arguments.
89 The path argument points to a path name that identifies the new process
92 image file.
93 The file argument is used to construct a pathname that identifies the
96 new process image file. If the file argument contains a slash charac‐
97 ter, it is used as the pathname for this file. Otherwise, the path pre‐
98 fix for this file is obtained by a search of the directories passed in
99 the PATH environment variable (see environ(5)). The environment is sup‐
100 plied typically by the shell. If the process image file is not a valid
101 executable object file, execlp() and execvp() use the contents of that
102 file as standard input to the shell. In this case, the shell becomes
103 the new process image. The standard to which the caller conforms deter‐
104 mines which shell is used. See standards(5).
105 The arguments represented by arg0... are pointers to null-terminated
108 character strings. These strings constitute the argument list available
109 to the new process image. The list is terminated by a null pointer. The
110 arg0 argument should point to a filename that is associated with the
111 process being started by one of the exec functions.
112 The argv argument is an array of character pointers to null-terminated
115 strings. The last member of this array must be a null pointer. These
116 strings constitute the argument list available to the new process
117 image. The value in argv[0] should point to a filename that is associ‐
118 ated with the process being started by one of the exec functions.
119 The envp argument is an array of character pointers to null-terminated
122 strings. These strings constitute the environment for the new process
123 image. The envp array is terminated by a null pointer. For execl(),
124 execv(), execvp(), and execlp(), the C-language run-time start-off rou‐
125 tine places a pointer to the environment of the calling process in the
126 global object extern char **environ, and it is used to pass the envi‐
127 ronment of the calling process to the new process image.
128 The number of bytes available for the new process's combined argument
131 and environment lists is ARG_MAX. It is implementation-dependent
132 whether null terminators, pointers, and/or any alignment bytes are
133 included in this total.
134 File descriptors open in the calling process image remain open in the
137 new process image, except for those whose close-on-exec flag FD_CLOEXEC
138 is set; see fcntl(2). For those file descriptors that remain open, all
139 attributes of the open file description, including file locks, remain
140 unchanged.
141 The preferred hardware address translation size (see memcntl(2)) for
144 the stack and heap of the new process image are set to the default sys‐
145 tem page size.
146 Directory streams open in the calling process image are closed in the
149 new process image.
150 The state of conversion descriptors and message catalogue descriptors
153 in the new process image is undefined. For the new process, the equiva‐
154 lent of:
155 setlocale(LC_ALL, "C")
157 is executed at startup.
161 Signals set to the default action (SIG_DFL) in the calling process
164 image are set to the default action in the new process image (see sig‐
165 nal(3C)). Signals set to be ignored (SIG_IGN) by the calling process
166 image are set to be ignored by the new process image. Signals set to be
167 caught by the calling process image are set to the default action in
168 the new process image (see signal.h(3HEAD)). After a successful call to
169 any of the exec functions, alternate signal stacks are not preserved
170 and the SA_ONSTACK flag is cleared for all signals.
171 After a successful call to any of the exec functions, any functions
174 previously registered by atexit(3C) are no longer registered.
175 The saved resource limits in the new process image are set to be a copy
178 of the process's corresponding hard and soft resource limits.
179 If the ST_NOSUID bit is set for the file system containing the new
182 process image file, then the effective user ID and effective group ID
183 are unchanged in the new process image. If the set-user-ID mode bit of
184 the new process image file is set (see chmod(2)), the effective user ID
185 of the new process image is set to the owner ID of the new process
186 image file. Similarly, if the set-group-ID mode bit of the new process
187 image file is set, the effective group ID of the new process image is
188 set to the group ID of the new process image file. The real user ID and
189 real group ID of the new process image remain the same as those of the
190 calling process image. The effective user ID and effective group ID of
191 the new process image are saved (as the saved set-user-ID and the saved
192 set-group-ID for use by setuid(2).
193 The privilege sets are changed according to the following rules:
196 1. The inheritable set, I, is intersected with the limit set,
198 L. This mechanism enforces the limit set for processes.
199 2. The effective set, E, and the permitted set, P, are made
201 equal to the new inheritable set.
202 The system attempts to set the privilege-aware state to non-PA both
205 before performing any modifications to the process IDs and privilege
206 sets as well as after completing the transition to new UIDs and privi‐
207 lege sets, following the rules outlined in privileges(5).
208 If the {PRIV_PROC_OWNER} privilege is asserted in the effective set,
211 the set-user-ID and set-group-ID bits will be honored when the process
212 is being controlled by ptrace(3C). Additional restriction can apply
213 when the traced process has an effective UID of 0. See privileges(5).
214 Any shared memory segments attached to the calling process image will
217 not be attached to the new process image (see shmop(2)). Any mappings
218 established through mmap() are not preserved across an exec. Memory
219 mappings created in the process are unmapped before the address space
220 is rebuilt for the new process image. See mmap(2).
221 Memory locks established by the calling process via calls to mlock‐
224 all(3C) or mlock(3C) are removed. If locked pages in the address space
225 of the calling process are also mapped into the address spaces the
226 locks established by the other processes will be unaffected by the call
227 by this process to the exec function. If the exec function fails, the
228 effect on memory locks is unspecified.
229 If _XOPEN_REALTIME is defined and has a value other than −1, any named
232 semaphores open in the calling process are closed as if by appropriate
233 calls to sem_close(3C)
234 Profiling is disabled for the new process; see profil(2).
237 Timers created by the calling process with timer_create(3C) are deleted
240 before replacing the current process image with the new process image.
241 For the SCHED_FIFO and SCHED_RR scheduling policies, the policy and
244 priority settings are not changed by a call to an exec function.
245 All open message queue descriptors in the calling process are closed,
248 as described in mq_close(3C).
249 Any outstanding asynchronous I/O operations may be cancelled. Those
252 asynchronous I/O operations that are not canceled will complete as if
253 the exec function had not yet occurred, but any associated signal noti‐
254 fications are suppressed. It is unspecified whether the exec function
255 itself blocks awaiting such I/O completion. In no event, however, will
256 the new process image created by the exec function be affected by the
257 presence of outstanding asynchronous I/O operations at the time the
258 exec function is called.
259 All active contract templates are cleared (see contract(4)).
262 The new process also inherits the following attributes from the calling
265 process:
266 o controlling terminal
268 o current working directory
270 o file-locks (see fcntl(2) and lockf(3C))
272 o file mode creation mask (see umask(2))
274 o file size limit (see ulimit(2))
276 o limit privilege set
278 o nice value (see nice(2))
280 o parent process ID
282 o pending signals (see sigpending(2))
284 o privilege debugging flag (see privileges(5) and
286 getpflags(2))
287 o process ID
289 o process contract (see contract(4) and process(4))
291 o process group ID
293 o process signal mask (see sigprocmask(2))
295 o processor bindings (see processor_bind(2))
297 o processor set bindings (see pset_bind(2))
299 o project ID
301 o real group ID
303 o real user ID
305 o resource limits (see getrlimit(2))
307 o root directory
309 o scheduler class and priority (see priocntl(2))
311 o semadj values (see semop(2))
313 o session membership (see exit(2) and signal(3C))
315 o supplementary group IDs
317 o task ID
319 o time left until an alarm clock signal (see alarm(2))
321 o tms_utime, tms_stime, tms_cutime, and tms_cstime (see
323 times(2))
324 o trace flag (see ptrace(3C) request 0)
326 A call to any exec function from a process with more than one thread
329 results in all threads being terminated and the new executable image
330 being loaded and executed. No destructor functions will be called.
331 Upon successful completion, each of the functions in the exec family
334 marks for update the st_atime field of the file. If an exec function
335 failed but was able to locate the process image file, whether the
336 st_atime field is marked for update is unspecified. Should the function
337 succeed, the process image file is considered to have been opened with
338 open(2). The corresponding close(2) is considered to occur at a time
339 after this open, but before process termination or successful comple‐
340 tion of a subsequent call to one of the exec functions. The argv[] and
341 envp[] arrays of pointers and the strings to which those arrays point
342 will not be modified by a call to one of the exec functions, except as
343 a consequence of replacing the process image.
344 The saved resource limits in the new process image are set to be a copy
347 of the process's corresponding hard and soft limits.
348
350 If a function in the exec family returns to the calling process image,
351 an error has occurred; the return value is −1 and errno is set to indi‐
352 cate the error.
353
355 The exec functions will fail if:
356 E2BIG The number of bytes in the new process's argument list
358 is greater than the system-imposed limit of {ARG_MAX}
359 bytes. The argument list limit is sum of the size of
360 the argument list plus the size of the environment's
361 exported shell variables.
362 EACCES Search permission is denied for a directory listed in
365 the new process file's path prefix.
366 The new process file is not an ordinary file.
368 The new process file mode denies execute permission.
370 The {FILE_DAC_SEARCH} privilege overrides the restric‐
372 tion on directory searches.
373 The {FILE_DAC_EXECUTE} privilege overrides the lack of
375 execute permission.
376 EAGAIN Total amount of system memory available when reading
379 using raw I/O is temporarily insufficient.
380 EFAULT An argument points to an illegal address.
383 EINVAL The new process image file has the appropriate permis‐
386 sion and has a recognized executable binary format, but
387 the system does not support execution of a file with
388 this format.
389 EINTR A signal was caught during the execution of one of the
392 functions in the exec family.
393 ELOOP Too many symbolic links were encountered in translating
396 path or file.
397 ENAMETOOLONG The length of the file or path argument exceeds
400 {PATH_MAX}, or the length of a file or path component
401 exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in
402 effect.
403 ENOENT One or more components of the new process path name of
406 the file do not exist or is a null pathname.
407 ENOLINK The path argument points to a remote machine and the
410 link to that machine is no longer active.
411 ENOTDIR A component of the new process path of the file prefix
414 is not a directory.
415 The exec functions, except for execlp() and execvp(), will fail if:
419 ENOEXEC The new process image file has the appropriate access per‐
421 mission but is not in the proper format.
422 The exec functions may fail if:
426 ENAMETOOLONG Pathname resolution of a symbolic link produced an
428 intermediate result whose length exceeds {PATH_MAX}.
429 ENOMEM The new process image requires more memory than is
432 allowed by the hardware or system-imposed by memory
433 management constraints. See brk(2).
434 ETXTBSY The new process image file is a pure procedure (shared
437 text) file that is currently open for writing by some
438 process.
439
442 As the state of conversion descriptors and message catalogue descrip‐
443 tors in the new process image is undefined, portable applications
444 should not rely on their use and should close them prior to calling one
445 of the exec functions.
446 Applications that require other than the default POSIX locale should
449 call setlocale(3C) with the appropriate parameters to establish the
450 locale of thenew process.
451 The environ array should not be accessed directly by the application.
454
456 See attributes(5) for descriptions of the following attributes:
457 ┌─────────────────────────────┬─────────────────────────────┐
462 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
463 ├─────────────────────────────┼─────────────────────────────┤
464 │Interface Stability │Committed │
465 ├─────────────────────────────┼─────────────────────────────┤
466 │MT-Level │See below. │
467 ├─────────────────────────────┼─────────────────────────────┤
468 │Standard │See standards(5). │
469 └─────────────────────────────┴─────────────────────────────┘
470 The execle() and execve() fucntions are Async-Signal-Safe.
473
475 ksh(1), ps(1), sh(1), alarm(2), brk(2), chmod(2), exit(2), fcntl(2),
476 fork(2), getpflags(2), getrlimit(2), memcntl(2), mmap(2), nice(2), pri‐
477 ocntl(2), profil(2), semop(2), shmop(2), sigpending(2), sigprocmask(2),
478 times(2), umask(2), lockf(3C), ptrace(3C), setlocale(3C), signal(3C),
479 system(3C), timer_create(3C), a.out(4), contract(4), process(4),
480 attributes(5), environ(5), privileges(5), standards(5)
481
483 If a program is setuid to a user ID other than the superuser, and the
484 program is executed when the real user ID is super-user, then the pro‐
485 gram has some of the powers of a super-user as well.
486SunOS 5.11 16 Jun 2008 exec(2)