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