1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .Dd Sep 19, 2014
13 .Dt EXEC 2
14 .Os
15 .Sh NAME
16 .Nm exec ,
17 .Nm execl ,
18 .Nm execle ,
19 .Nm execlp ,
20 .Nm execv ,
21 .Nm execve ,
22 .Nm execvp ,
23 .Nm fexecve
24 .Nd execute a file
25 .Sh SYNOPSIS
26 .In unistd.h
27 .
28 .Ft int
29 .Fo execl
30 .Fa "const char *path"
31 .Fa "const char *arg0"
32 .Fa "... /* const char *argn, (char *)0 */"
33 .Fc
34 .
35 .Ft int
36 .Fo execv
37 .Fa "const char *path"
38 .Fa "char *const argv[]"
39 .Fc
40 .
41 .Ft int
42 .Fo execle
43 .Fa "const char *path"
44 .Fa "const char *arg0"
45 .Fa "... /* const char *argn, (char *)0, char *const envp[] */"
46 .Fc
47 .
48 .Ft int
49 .Fo execve
50 .Fa "const char *path"
51 .Fa "char *const argv[]"
52 .Fa "char *const envp[]"
53 .Fc
54 .
55 .Ft int
56 .Fo execlp
57 .Fa "const char *file"
58 .Fa "const char *arg0"
59 .Fa "... /* const char *argn, (char *)0 */"
60 .Fc
61 .
62 .Ft int
63 .Fo execvp
64 .Fa "const char *file"
65 .Fa "char *const argv[]"
66 .Fc
67 .
68 .Ft int
69 .Fo fexecve
70 .Fa "int fd"
71 .Fa "char *const argv[]"
72 .Fa "char *const envp[]"
73 .Fc
74 .Sh DESCRIPTION
75 Each of the functions in the
76 .Nm exec
77 family replaces the current process image with a new process image.
78 The new image is constructed from a regular, executable file called the
79 .Em new process image file .
80 This file is either an
81 executable object file or a file of data for an interpreter. There is no return
82 from a successful call to one of these functions because the calling process
83 image is overlaid by the new process image.
84 .Lp
85 An interpreter file begins with a line of the form
86 .Lp
87 .Dl #! pathname Op Ar arg
88 .Lp
89 where
90 .Ar pathname
91 is the path of the interpreter, and
92 .Ar arg
93 is an optional argument.
94 When an interpreter file is executed, the system invokes the
95 specified interpreter.
96 The pathname specified in the interpreter file is passed as
97 .Fa arg0
98 to the interpreter.
99 If
100 .Ar arg
101 was specified in the interpreter file, it is passed as
102 .Fa arg1
103 to the interpreter.
104 The remaining arguments to
105 the interpreter are
106 .Fa arg0
107 through
108 .Fa argn
109 of the originally exec'd file.
110 The interpreter named by
111 .Ar pathname
112 must not be an interpreter file.
113 .Lp
114 When a C-language program is executed as a result of this call, it is entered
115 as a C-language function call as follows:
116 .Lp
117 .Dl Ft int Fn main "int argc" "char *argv[]"
118 .Lp
119 where
120 .Fa argc
121 is the argument count and
122 .Fa argv
123 is an array of character pointers to the arguments themselves.
124 In addition, the following variable:
125 .Lp
126 .Dl Vt "extern char **" Ns Va environ ;
127 .Lp
128 is initialized as a pointer to an array of character pointers to the
129 environment strings.
130 The
131 .Fa argv
132 and
133 .Va environ
134 arrays are each terminated by a null pointer.
135 The null pointer terminating the
136 .Fa argv
137 array is not counted in
138 .Fa argc .
139 .Lp
140 The value of
141 .Fa argc
142 is non-negative, and if greater than 0,
143 .Fa argv Ns [0]
144 points to a string containing the name of the file.
145 If
146 .Fa argc
147 is 0,
148 .Fa argv Ns [0]
149 is a null pointer, in which case there are no arguments.
150 Applications should verify that
151 .Fa argc
152 is greater than 0 or that
153 .Fa argv Ns [0]
154 is not a null pointer before dereferencing
155 .Fa argv Ns [0] .
156 .Lp
157 The arguments specified by a program with one of the
158 .Nm exec
159 functions are passed on to the new process image in the
160 Fn main
161 arguments.
162 .Lp
163 The
164 .Fa path
165 argument points to a path name that identifies the new process image file.
166 .Lp
167 The
168 .Fa file
169 argument is used to construct a pathname that identifies the new
170 process image file.
171 If the
172 .Fa file
173 argument contains a slash character, it is used as the pathname for this file.
174 Otherwise, the path prefix for this file is obtained by a search of the
175 directories passed in the
176 .Ev PATH
177 environment variable.
178 See
179 .Xr environ 5 .
180 The environment is supplied typically by the shell.
181 If the process image file is not a valid executable object file,
182 .Fn execlp
183 and
184 .Fn execvp
185 use the contents of that file as standard input to the shell.
186 In this case, the shell becomes the new process image.
187 The standard to which the caller conforms determines which shell is used.
188 See
189 .Xr standards 5 .
190 .Lp
191 The
192 .Fn fexecve
193 function is equivalent to
194 .Fn execve ,
195 except that instead of using a named file, the file referenced by
196 the file descriptor
197 .Fa fd
198 is used. Note that this file descriptor must reference a regular
199 file and must have been opened for execute
200 .Po with
201 Dv O_EXEC ,
202 defined in
203 .In fcntl.h .
204 .Pc
205 The image is loaded from offset zero of the file, regardless of
206 the offset of
207 .Fa fd .
208 .Lp
209 The arguments represented by
210 .Fa arg0 Ns "..."
211 are pointers to null-terminated character strings.
212 These strings constitute the argument list available to the new process image.
213 The list is terminated by a null pointer.
214 The
215 .Fa arg0
216 argument should point to a filename that is associated with the
217 process being started by one of the
218 .Nm exec
219 functions.
220 .Lp
221 The
222 .Fa argv
223 argument is an array of character pointers to null-terminated strings.
224 The last member of this array must be a null pointer.
225 These strings constitute the argument list available to the new process image.
226 The value in
227 .Fa argv Ns [0]
228 should point to a filename that is associated with the process
229 being started by one of the
230 .Nm exec
231 functions.
232 .Lp
233 The
234 .Fa envp
235 argument is an array of character pointers to null-terminated strings.
236 These strings constitute the environment for the new process image.
237 The
238 .Fa envp
239 array is terminated by a null pointer.
240 For
241 .Fn execl , execv , execvp ,
242 and
243 .Fn execlp ,
244 the C-language run-time
245 start-off routine places a pointer to the environment of the calling process in
246 the global object
247 .Va environ ,
248 and it is used to pass the
249 environment of the calling process to the new process image.
250 .Lp
251 The number of bytes available for the new process's combined argument and
252 environment lists is
253 .Dv ARG_MAX .
254 It is implementation-dependent whether null
255 terminators, pointers, and/or any alignment bytes are included in this total.
256 .Lp
257 File descriptors open in the calling process image remain open in the new
258 process image, except for those whose close-on-exec flag
259 .Dv FD_CLOEXEC
260 is set; see
261 .Xr fcntl 2 .
262 For those file descriptors that remain open, all
263 attributes of the open file description, including file locks, remain
264 unchanged.
265 .Lp
266 The preferred hardware address translation size
267 .Pq see Xr memcntl 2
268 for the
269 stack and heap of the new process image are set to the default system page
270 size.
271 .Lp
272 Directory streams open in the calling process image are closed in the new
273 process image.
274 .Lp
275 The state of conversion descriptors and message catalogue descriptors in the
276 new process image is undefined. For the new process, the equivalent of:
277 .Lp
278 .Dl Fn setlocale LC_ALL \("C" ;
279 .Lp
280 is executed at startup.
281 .Lp
282 Signals set to the default action
283 .Pq Dv BSIG_DFL
284 in the calling process image
285 are set to the default action in the new process image
286 .Pq see Xr signal 3C .
287 Signals set to be ignored
288 .Pq Dv SIG_IGN
289 by the calling process image are set to be ignored by the new process image.
290 Signals set to be caught by the calling
291 process image are set to the default action in the new process image
292 .Pq see Xr signal.h 3HEAD .
293 After a successful call to any of the
294 .Nm exec
295 functions, alternate signal stacks are not preserved and the
296 .Dv SA_ONSTACK
297 flag is cleared for all signals.
298 .Lp
299 After a successful call to any of the
300 .Nm exec
301 functions, any functions
302 previously registered by
303 .Xr atexit 3C
304 are no longer registered.
305 .Lp
306 The saved resource limits in the new process image are set to be a copy of the
307 process's corresponding hard and soft resource limits.
308 .Lp
309 If the
310 .Dv ST_NOSUID
311 bit is set for the file system containing the new
312 process image file, then the effective user ID and effective group
313 ID are unchanged in the new process image.
314 If the set-user-ID mode bit of the new process image file is set
315 .Pq see Xr chmod 2 ,
316 the effective
317 user ID of the new process image is set to the owner ID of the new
318 process image file.
319 Similarly, if the set-group-ID mode bit of the new
320 process image file is set, the effective group ID of the new process
321 image is set to the group ID of the new process image file.
322 The real user ID and real group ID of the new process image remain the same as
323 those of the calling process image.
324 The effective user ID and effective group
325 ID of the new process image are saved
326 .Po
327 as the saved set-user-ID and the saved set-group-ID for use by
328 .Xr setuid 2 Pc .
329 .Lp
330 The privilege sets are changed according to the following rules:
331 .Bl -enum
332 .It
333 The inheritable set, I, is intersected with the limit set, L. This
334 mechanism enforces the limit set for processes.
335 .It
336 The effective set, E, and the permitted set, P, are made equal to the new
337 inheritable set.
338 .El
339 .Lp
340 The system attempts to set the privilege-aware state to non-PA both before
341 performing any modifications to the process IDs and privilege sets as well as
342 after completing the transition to new UIDs and privilege sets, following the
343 rules outlined in
344 .Xr privileges 5 .
345 .Lp
346 If the
347 .Brq Dv PRIV_PROC_OWNER
348 privilege is asserted in the effective set, the
349 set-user-ID and set-group-ID bits will be honored when the process is being
350 controlled by
351 .Xr ptrace 3C .
352 Additional restrictions can apply when the
353 traced process has an effective UID of 0.
354 See
355 .Xr privileges 5 .
356 .Lp
357 Any shared memory segments attached to the calling process image will not be
358 attached to the new process image
359 .Pq see Xr shmop 2 .
360 Any mappings
361 established through
362 .Xr mmap 2
363 are not preserved across an
364 .Nm exec .
365 Memory
366 mappings created in the process are unmapped before the address space is
367 rebuilt for the new process image.
368 See
369 .Xr mmap 2 .
370 .Lp
371 Memory locks established by the calling process via calls to
372 .Xr mlockall 3C
373 or
374 .Xr mlock 3C
375 are removed.
376 If locked pages in the address space of the
377 calling process are also mapped into the address spaces the locks established
378 by the other processes will be unaffected by the call by this process to the
379 .Nm exec
380 function.
381 If the
382 .Nm exec
383 function fails, the effect on memory locks is unspecified.
384 .Lp
385 If
386 .Dv _XOPEN_REALTIME
387 is defined and has a value other than \(mi1, any named
388 semaphores open in the calling process are closed as if by appropriate calls to
389 .Xr sem_close 3C .
390 .Lp
391 Profiling is disabled for the new process; see
392 .Xr profil 2 .
393 .Lp
394 Timers created by the calling process with
395 .Xr timer_create 3C
396 are deleted
397 before replacing the current process image with the new process image.
398 .Lp
399 For the
400 .Dv SCHED_FIFO
401 and
402 .Dv SCHED_RR
403 scheduling policies, the policy and
404 priority settings are not changed by a call to an
405 .Nm exec
406 function.
407 .Lp
408 All open message queue descriptors in the calling process are closed, as
409 described in
410 .Xr mq_close 3C .
411 .Lp
412 Any outstanding asynchronous I/O operations may be cancelled. Those
413 asynchronous I/O operations that are not canceled will complete as if the
414 .Nm exec
415 function had not yet occurred, but any associated signal
416 notifications are suppressed.
417 It is unspecified whether the
418 .Nm exec
419 function itself blocks awaiting such I/O completion.
420 In no event, however, will the new process image created by the
421 .Nm exec
422 function be affected by the presence of
423 outstanding asynchronous I/O operations at the time the
424 .Nm exec
425 function is called.
426 .Lp
427 All active contract templates are cleared
428 .Pq see Xr contract 4 .
429 .Lp
430 The new process also inherits the following attributes from the calling
431 process:
432 .Bl -bullet -offset indent
433 .It
434 controlling terminal
435 .It
436 current working directory
437 .It
438 file-locks
439 .Po see
440 .Xr fcntl 2
441 and
442 .Xr lockf 3C
443 .Pc
444 .It
445 file mode creation mask
446 .Pq see Xr umask 2
447 .It
448 file size limit
449 .Pq see Xr ulimit 2
450 .It
451 limit privilege set
452 .It
453 nice value
454 .Pq see Xr nice 2
455 .It
456 parent process ID
457 .It
458 pending signals
459 .Pq see Xr sigpending 2
460 .It
461 privilege debugging flag
462 .Po see Xr privileges 5
463 and
464 .Xr getpflags 2
465 .Pc
466 .It
467 process ID
468 .It
469 process contract
470 .Po see Xr contract 4
471 and
472 .Xr process 4
473 .Pc
474 .It
475 process group ID
476 .It
477 process signal mask
478 .Pq see Xr sigprocmask 2
479 .It
480 processor bindings
481 .Pq see Xr processor_bind 2
482 .It
483 processor set bindings
484 .Pq see Xr pset_bind 2
485 .It
486 project ID
487 .It
488 real group ID
489 .It
490 real user ID
491 .It
492 resource limits
493 .Pq see Xr getrlimit 2
494 .It
495 root directory
496 .It
497 scheduler class and priority
498 .Pq see Xr priocntl 2
499 .It
500 .Sy semadj
501 values
502 .Pq see Xr semop 2
503 .It
504 session membership
505 .Po see
506 .Xr exit 2
507 and
508 .Xr signal 3C
509 .Pc
510 .It
511 supplementary group IDs
512 .It
513 task ID
514 .It
515 time left until an alarm clock signal
516 .Pq see Xr alarm 2
517 .It
518 .Sy tms_utime , tms_stime , tms_cutime ,
519 and
520 .Sy tms_cstime
521 .Pq see Xr times 2
522 .It
523 trace flag
524 .Po see Xr ptrace 3C
525 request 0
526 .Pc
527 .El
528 .Lp
529 A call to any
530 .Nm exec
531 function from a process with more than one thread
532 results in all threads being terminated and the new executable image being
533 loaded and executed.
534 No destructor functions will be called.
535 .Lp
536 Upon successful completion, each of the functions in the
537 .Nm exec
538 family marks for update the
539 .Va st_atime
540 field of the file.
541 If an
542 .Nm exec
543 function failed but was able to locate the
544 .Em process image file ,
545 whether
546 the
547 .Va st_atime
548 field is marked for update is unspecified.
549 Should the function succeed, the process image file is considered to have
550 been opened with
551 .Xr open 2 .
552 The corresponding
553 .Xr close 2
554 is considered to occur at a
555 time after this open, but before process termination or successful completion
556 of a subsequent call to one of the
557 .Nm exec
558 functions.
559 The
560 .Fa argv
561 and
562 .Fa envp
563 arrays of pointers and the strings to which those arrays point
564 will not be modified by a call to one of the
565 .Nm exec
566 functions, except as a consequence of replacing the process image.
567 .Lp
568 The saved resource limits in the new process image are set to be a copy of the
569 process's corresponding hard and soft limits.
570 .
571 .Sh RETURN VALUES
572 .
573 If a function in the
574 .Nm exec
575 family returns to the calling process image, an
576 error has occurred; the return value is \fB\(mi1\fR and
577 .Va errno
578 is set to indicate the error.
579 .
580 .Sh ERRORS
581 .
582 The
583 .Nm exec
584 functions will fail if:
585 .Bl -tag -width Er
586 .It Bq Er E2BIG
587 The number of bytes in the new process's argument list is greater than the
588 system-imposed limit of
589 .Brq Dv ARG_MAX
590 bytes.
591 The argument list limit is sum
592 of the size of the argument list plus the size of the environment's exported
593 shell variables.
594 .
595 .It Bq Er EACCES
596 Search permission is denied for a directory listed in the new process file's
597 path prefix.
598 .sp
599 The new process file is not an ordinary file.
600 .sp
601 The new process file mode denies execute permission.
602 .sp
603 The
604 .Brq Dv FILE_DAC_SEARCH
605 privilege overrides the restriction on directory searches.
606 .sp
607 The
608 .Brq Dv FILE_DAC_EXECUTE
609 privilege overrides the lack of execute
610 permission.
611 .
612 .It Bq Er EAGAIN
613 Total amount of system memory available when reading using raw I/O is
614 temporarily insufficient.
615 .
616 .It Bq Er EFAULT
617 An argument points to an illegal address.
618 .
619 .It Bq Er EINVAL
620 The new process image file has the appropriate permission and has a recognized
621 executable binary format, but the system does not support execution of a file
622 with this format.
623 .
624 .It Bq Er EINTR
625 A signal was caught during the execution of one of the functions in the
626 .Nm exec
627 family.
628 .El
629 .
630 .Lp
631 The
632 .Nm exec
633 functions except
634 .Fn fexecve
635 will fail if:
636 .
637 .Bl -tag -width Er
638 .It Bq Er ELOOP
639 Too many symbolic links were encountered in translating
640 .Fa path
641 or
642 .Fa file .
643 .
644 .It Bq Er ENAMETOOLONG
645 The length of the
646 .Fa file
647 or
648 .Fa path
649 argument exceeds
650 .Brq PATH_MAX ,
651 or the length of a
652 .Fa file
653 or
654 .Fa path
655 component exceeds
656 .Brq Dv NAME_MAX
657 while
658 .Brq Dv _POSIX_NO_TRUNC
659 is in effect.
660 .
661 .It Bq Er ENOENT
662 One or more components of the new process path name of the file do not exist or
663 is a null pathname.
664 .
665 .It Bq Er ENOLINK
666 The
667 .Fa path
668 argument points to a remote machine and the link to that machine
669 is no longer active.
670 .
671 .It Bq Er ENOTDIR
672 A component of the new process path of the file prefix is not a directory.
673 .El
674 .Lp
675 The
676 .Nm exec
677 functions, except for
678 .Fn execlp
679 and
680 .Fn execvp ,
681 will fail if:
682 .Bl -tag -width Er
683 .It Bq Er ENOEXEC
684 The new process image file has the appropriate access permission but is not in
685 the proper format.
686 .El
687 .Lp
688 The
689 .Fn fexecve
690 function will fail if:
691 .Bl -tag -width Er
692 .It Bq Er EBADF
693 The
694 .Fa fd
695 argument is not a valid file descriptor opened for execute.
696 .El
697 .sp
698 .Lp
699 The
700 .Nm exec
701 functions except for
702 .Fn fexecve
703 may fail if:
704 .
705 .Bl -tag -width Er
706 .It Bq Er ENAMETOOLONG
707 Pathname resolution of a symbolic link produced an intermediate result whose
708 length exceeds
709 .Brq Dv PATH_MAX .
710 .
711 .It Bq Er ENOMEM
712 The new process image requires more memory than is allowed by the hardware or
713 system-imposed by memory management constraints.
714 See
715 .Xr brk 2 .
716 .
717 .It Bq Er ETXTBSY
718 The new process image file is a pure procedure (shared text) file that is
719 currently open for writing by some process.
720 .El
721 .
722 .Sh USAGE
723 .
724 As the state of conversion descriptors and message catalogue descriptors in the
725 new process image is undefined, portable applications should not rely on their
726 use and should close them prior to calling one of the
727 .Nm exec
728 functions.
729 .Lp
730 Applications that require other than the default POSIX locale should call
731 .Xr setlocale 3C
732 with the appropriate parameters to establish the locale of the new process.
733 .Lp
734 The
735 .Va environ
736 array should not be accessed directly by the application.
737 Instead,
738 .Xr getenv 3C
739 should be used.
740 .
741 .Sh SEE ALSO
742 .Xr ps 1 ,
743 .Xr sh 1 ,
744 .Xr alarm 2 ,
745 .Xr brk 2 ,
746 .Xr chmod 2 ,
747 .Xr exit 2 ,
748 .Xr fcntl 2 ,
749 .Xr fork 2 ,
750 .Xr getpflags 2 ,
751 .Xr getrlimit 2 ,
752 .Xr memcntl 2 ,
753 .Xr mmap 2 ,
754 .Xr nice 2 ,
755 .Xr open 2 ,
756 .Xr priocntl 2 ,
757 .Xr profil 2 ,
758 .Xr semop 2 ,
759 .Xr shmop 2 ,
760 .Xr sigpending 2 ,
761 .Xr sigprocmask 2 ,
762 .Xr times 2 ,
763 .Xr umask 2 ,
764 .Xr lockf 3C ,
765 .Xr ptrace 3C ,
766 .Xr setlocale 3C ,
767 .Xr signal 3C ,
768 .Xr system 3C ,
769 .Xr timer_create 3C ,
770 .Xr fcntl.h 3HEAD ,
771 .Xr signal.h 3HEAD ,
772 .Xr unistd.h 3HEAD ,
773 .Xr a.out 4 ,
774 .Xr contract 4 ,
775 .Xr process 4 ,
776 .Xr environ 5 ,
777 .Xr privileges 5 ,
778 .Xr standards 5
779 .
780 .Sh INTERFACE STABILITY
781 .
782 .Sy Standard .
783 .
784 .Sh MT-LEVEL
785 .
786 The
787 .Fn execle , execve , fexecve
788 functions are
789 .Sy Async-Signal-Safe .
790 .
791 .Sh STANDARDS
792 .
793 These functions are available in the following compilation environments.
794 See
795 .Xr standards 5 .
796 .Ss Fn execl , execle , execlp , execv , execve , execvp
797 .Bl -bullet -compact
798 .It
799 .St -p1003.1-90
800 .It
801 .St -xpg3
802 .It
803 .St -xpg4
804 .It
805 .St -xpg4.2
806 .It
807 .St -susv2
808 .It
809 .St -susv3
810 .It
811 .St -p1003.1-2008
812 .El
813 .Ss Fn fexecve
814 .Bl -bullet -compact
815 .It
816 .St -p1003.1-2008
817 .El
818 .
819 .Sh WARNINGS
820 If a program is
821 .Em setuid
822 to a user ID other than the superuser, and
823 the program is executed when the real user ID is super-user, then the
824 program has some of the powers of a super-user as well.