1exec(2)                          System Calls                          exec(2)
2
3
4

NAME

6       exec, execl, execle, execlp, execv, execve, execvp - execute a file
7

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

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  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
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 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
58
59       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
62         int main (int argc, char *argv[]);
63
64
65
66       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
70         extern char **environ;
71
72
73
74       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
79
80       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
86
87       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
90
91       The path argument points to a path name that identifies the new process
92       image file.
93
94
95       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
106
107       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
113
114       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
120
121       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
129
130       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
135
136       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
142
143       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
147
148       Directory streams open in the calling process image are closed  in  the
149       new process image.
150
151
152       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
156         setlocale(LC_ALL, "C")
157
158
159
160       is executed at startup.
161
162
163       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
172
173       After a successful call to any of the  exec  functions,  any  functions
174       previously registered by atexit(3C) are no longer registered.
175
176
177       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
180
181       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
194
195       The privilege sets are changed according to the following rules:
196
197           1.     The  inheritable  set, I, is intersected with the limit set,
198                  L.  This mechanism enforces the limit set for processes.
199
200           2.     The effective set, E, and the permitted  set,  P,  are  made
201                  equal to the new inheritable set.
202
203
204       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
209
210       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
215
216       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
222
223       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
230
231       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
235
236       Profiling is disabled for the new process; see profil(2).
237
238
239       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
242
243       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
246
247       All open message queue descriptors in the calling process  are  closed,
248       as described in mq_close(3C).
249
250
251       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
260
261       All active contract templates are cleared (see contract(4)).
262
263
264       The new process also inherits the following attributes from the calling
265       process:
266
267           o      controlling terminal
268
269           o      current working directory
270
271           o      file-locks (see fcntl(2) and lockf(3C))
272
273           o      file mode creation mask (see umask(2))
274
275           o      file size limit (see ulimit(2))
276
277           o      limit privilege set
278
279           o      nice value (see nice(2))
280
281           o      parent process ID
282
283           o      pending signals (see sigpending(2))
284
285           o      privilege    debugging    flag    (see   privileges(5)   and
286                  getpflags(2))
287
288           o      process ID
289
290           o      process contract (see contract(4) and process(4))
291
292           o      process group ID
293
294           o      process signal mask (see sigprocmask(2))
295
296           o      processor bindings (see processor_bind(2))
297
298           o      processor set bindings (see pset_bind(2))
299
300           o      project ID
301
302           o      real group ID
303
304           o      real user ID
305
306           o      resource limits (see getrlimit(2))
307
308           o      root directory
309
310           o      scheduler class and priority (see priocntl(2))
311
312           o      semadj values (see semop(2))
313
314           o      session membership (see exit(2) and signal(3C))
315
316           o      supplementary group IDs
317
318           o      task ID
319
320           o      time left until an alarm clock signal (see alarm(2))
321
322           o      tms_utime,  tms_stime,  tms_cutime,  and   tms_cstime   (see
323                  times(2))
324
325           o      trace flag (see ptrace(3C) request 0)
326
327
328       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
332
333       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
345
346       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

RETURN VALUES

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

ERRORS

355       The exec functions will fail if:
356
357       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
363
364       EACCES          Search permission is denied for a directory  listed  in
365                       the new process file's path prefix.
366
367                       The new process file is not an ordinary file.
368
369                       The new process file mode denies execute permission.
370
371                       The  {FILE_DAC_SEARCH} privilege overrides the restric‐
372                       tion on directory searches.
373
374                       The {FILE_DAC_EXECUTE} privilege overrides the lack  of
375                       execute permission.
376
377
378       EAGAIN          Total  amount  of  system memory available when reading
379                       using raw I/O is temporarily insufficient.
380
381
382       EFAULT          An argument points to an illegal address.
383
384
385       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
390
391       EINTR           A  signal was caught during the execution of one of the
392                       functions in the exec family.
393
394
395       ELOOP           Too many symbolic links were encountered in translating
396                       path or file.
397
398
399       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
404
405       ENOENT          One or more components of the new process path name  of
406                       the file do not exist or is a null pathname.
407
408
409       ENOLINK         The  path  argument  points to a remote machine and the
410                       link to that machine is no longer active.
411
412
413       ENOTDIR         A component of the new process path of the file  prefix
414                       is not a directory.
415
416
417
418       The exec functions, except for execlp() and execvp(), will fail if:
419
420       ENOEXEC    The  new  process image file has the appropriate access per‐
421                  mission but is not in the proper format.
422
423
424
425       The exec functions may fail if:
426
427       ENAMETOOLONG    Pathname resolution of  a  symbolic  link  produced  an
428                       intermediate result whose length exceeds {PATH_MAX}.
429
430
431       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
435
436       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
440

USAGE

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
447
448       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
452
453       The environ array should not be accessed directly by the application.
454

ATTRIBUTES

456       See attributes(5) for descriptions of the following attributes:
457
458
459
460
461       ┌─────────────────────────────┬─────────────────────────────┐
462       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
463       ├─────────────────────────────┼─────────────────────────────┤
464       │Interface Stability          │Committed                    │
465       ├─────────────────────────────┼─────────────────────────────┤
466       │MT-Level                     │See below.                   │
467       ├─────────────────────────────┼─────────────────────────────┤
468       │Standard                     │See standards(5).            │
469       └─────────────────────────────┴─────────────────────────────┘
470
471
472       The execle() and execve() fucntions are Async-Signal-Safe.
473

SEE ALSO

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

WARNINGS

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.
486
487
488
489SunOS 5.11                        16 Jun 2008                          exec(2)
Impressum