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