1.\" $OpenBSD: execve.2,v 1.58 2022/10/13 21:37:05 jmc Exp $ 2.\" $NetBSD: execve.2,v 1.9 1995/02/27 12:32:25 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)execve.2 8.3 (Berkeley) 1/24/94 32.\" 33.Dd $Mdocdate: October 13 2022 $ 34.Dt EXECVE 2 35.Os 36.Sh NAME 37.Nm execve 38.Nd execute a file 39.Sh SYNOPSIS 40.In unistd.h 41.Ft int 42.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" 43.Sh DESCRIPTION 44.Fn execve 45transforms the calling process into a new process. 46The new process is constructed from an ordinary file, 47whose name is pointed to by 48.Fa path , 49called the 50.Em new process file . 51This file is either an executable object file, 52or a file of data for an interpreter. 53An executable object file consists of an identifying header, 54followed by pages of data representing the initial program (text) 55and initialized data pages. 56Additional pages may be specified by the header to be initialized 57with zero data; see 58.Xr elf 5 . 59.Pp 60An interpreter file begins with a line of the form: 61.Pp 62.D1 #! Ar interpreter Op Ar arg 63.Pp 64When an interpreter file is passed to 65.Fn execve , 66the system instead calls 67.Fn execve 68with the specified 69.Ar interpreter . 70If the optional 71.Ar arg 72is specified, it becomes the first argument to the 73.Ar interpreter , 74and the original 75.Fa path 76becomes the second argument; 77otherwise, 78.Fa path 79becomes the first argument. 80The original arguments are shifted over to become the subsequent arguments. 81The zeroth argument, normally the name of the file being executed, is left 82unchanged. 83.Pp 84The argument 85.Fa argv 86is a pointer to a null-terminated array of 87character pointers to NUL-terminated character strings. 88These strings construct the argument list to be made available to the new 89process. 90At least one non-null argument must be present in the array; 91by custom, the first element should be 92the name of the executed program (for example, the last component of 93.Fa path ) . 94.Pp 95The argument 96.Fa envp 97is also a pointer to a null-terminated array of 98character pointers to NUL-terminated strings. 99A pointer to this array is normally stored in the global variable 100.Va environ . 101These strings pass information to the 102new process that is not directly an argument to the command (see 103.Xr environ 7 ) . 104.Pp 105File descriptors open in the calling process image remain open in 106the new process image, except for those for which the close-on-exec 107flag is set (see 108.Xr close 2 109and 110.Xr fcntl 2 ) . 111Descriptors that remain open are unaffected by 112.Fn execve . 113In the case of a new setuid or setgid executable being executed, if 114file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr) 115are currently unallocated, these descriptors will be opened to point to 116some system file like 117.Pa /dev/null . 118The intent is to ensure these descriptors are not unallocated, since 119many libraries make assumptions about the use of these 3 file descriptors. 120.Pp 121Signals set to be ignored in the calling process, 122with the exception of 123.Dv SIGCHLD , 124are set to be ignored in 125the 126new process. 127Other signals 128are set to default action in the new process image. 129Blocked signals remain blocked regardless of changes to the signal action. 130The signal stack is reset to be undefined (see 131.Xr sigaction 2 132for more information). 133.Pp 134If the set-user-ID mode bit of the new process image file is set 135(see 136.Xr chmod 2 ) , 137the effective user ID of the new process image is set to the owner ID 138of the new process image file. 139If the set-group-ID mode bit of the new process image file is set, 140the effective group ID of the new process image is set to the group ID 141of the new process image file. 142(The effective group ID is the first element of the group list.) 143The real user ID, real group ID and 144other group IDs of the new process image remain the same as the calling 145process image. 146After any set-user-ID and set-group-ID processing, 147the effective user ID is recorded as the saved set-user-ID, 148and the effective group ID is recorded as the saved set-group-ID. 149These values may be used in changing the effective IDs later (see 150.Xr setuid 2 ) . 151The set-user-ID and set-group-ID bits have no effect if the 152new process image file is located on a file system mounted with 153the nosuid flag. 154The process will be started without the new permissions. 155.Pp 156The new process also inherits the following attributes from 157the calling process: 158.Pp 159.Bl -tag -width controlling_terminal -offset indent -compact 160.It process ID 161see 162.Xr getpid 2 163.It parent process ID 164see 165.Xr getppid 2 166.It process group ID 167see 168.Xr getpgrp 2 169.It session ID 170see 171.Xr getsid 2 172.It access groups 173see 174.Xr getgroups 2 175.It working directory 176see 177.Xr chdir 2 178.It root directory 179see 180.Xr chroot 2 181.It controlling terminal 182see 183.Xr termios 4 184.It resource usages 185see 186.Xr getrusage 2 187.It interval timers 188see 189.Xr getitimer 2 190(unless process image file is setuid or setgid, 191in which case all timers are disabled) 192.It resource limits 193see 194.Xr getrlimit 2 195.It file mode mask 196see 197.Xr umask 2 198.It signal mask 199see 200.Xr sigaction 2 , 201.Xr sigprocmask 2 202.El 203.Pp 204When a program is executed as a result of an 205.Fn execve 206call, it is entered as follows: 207.Pp 208.Dl main(int argc, char **argv, char **envp) 209.Pp 210where 211.Fa argc 212is the number of elements in 213.Fa argv 214(the 215.Dq arg count ) 216and 217.Fa argv 218points to the array of character pointers 219to the arguments themselves. 220.Sh RETURN VALUES 221As the 222.Fn execve 223function overlays the current process image 224with a new process image, the successful call 225has no process to return to. 226If 227.Fn execve 228does return to the calling process, an error has occurred; the 229return value will be \-1 and the global variable 230.Va errno 231is set to indicate the error. 232.Sh ERRORS 233.Fn execve 234will fail and return to the calling process if: 235.Bl -tag -width Er 236.It Bq Er ENOTDIR 237A component of the path prefix is not a directory. 238.It Bq Er ENAMETOOLONG 239A component of a pathname exceeded 240.Dv NAME_MAX 241characters, or an entire pathname (including the terminating NUL) 242exceeded 243.Dv PATH_MAX 244bytes. 245.It Bq Er ENOENT 246The new process file does not exist. 247.It Bq Er ELOOP 248Too many symbolic links were encountered in translating the pathname. 249.It Bq Er EACCES 250Search permission is denied for a component of the path prefix. 251.It Bq Er EACCES 252The new process file is not an ordinary file. 253.It Bq Er EACCES 254The new process file mode denies execute permission. 255.It Bq Er EACCES 256The new process file is on a filesystem mounted with execution 257disabled 258.Pf ( Dv MNT_NOEXEC 259in 260.In sys/mount.h ) . 261.It Bq Er EACCES 262The new process file is marked with 263.Xr ld 1 264.Fl z Cm wxneeded 265to perform W^X violating operations, but it is located on a file 266system not allowing such operations, being mounted without the 267.Xr mount 8 268.Fl o Cm wxallowed 269flag. 270.It Bq Er EACCES 271The parent used 272.Xr pledge 2 273to declare an 274.Va execpromise , 275and that is not permitted for setuid or setgid images. 276.It Bq Er ENOEXEC 277The new process file has the appropriate access 278permission, but has an invalid magic number in its header. 279.It Bq Er ETXTBSY 280The new process file is a pure procedure (shared text) 281file that is currently open for writing by some process. 282.It Bq Er ENOMEM 283The new process requires more virtual memory than 284is allowed by the imposed maximum 285.Pq Xr getrlimit 2 . 286.It Bq Er E2BIG 287The number of bytes in the new process's argument list 288is larger than the system-imposed limit. 289The limit in the system as released is 524288 bytes 290.Pq Dv ARG_MAX . 291.It Bq Er EFAULT 292The new process file is not as long as indicated by 293the size values in its header. 294.It Bq Er EFAULT 295.Fa path , 296.Fa argv , 297or 298.Fa envp 299point 300to an illegal address. 301.It Bq Er EINVAL 302.Fa argv 303did not contain at least one element. 304.It Bq Er EIO 305An I/O error occurred while reading from the file system. 306.It Bq Er ENFILE 307During startup of an 308.Ar interpreter , 309the system file table was found to be full. 310.El 311.Sh SEE ALSO 312.Xr _exit 2 , 313.Xr fork 2 , 314.Xr execl 3 , 315.Xr exit 3 , 316.Xr elf 5 , 317.Xr environ 7 318.Sh STANDARDS 319The 320.Fn execve 321function is expected to conform to 322.St -p1003.1-2008 . 323.Sh HISTORY 324The predecessor of these functions, the former 325.Fn exec 326system call, first appeared in 327.At v1 . 328The 329.Fn execve 330function first appeared in 331.At v7 . 332.Sh CAVEATS 333If a program is 334.Em setuid 335to a non-superuser, but is executed when the real 336.Em uid 337is 338.Dq root , 339then the process has some of the powers of a superuser as well. 340.Pp 341.St -p1003.1-2008 342permits 343.Nm 344to leave 345.Dv SIGCHLD 346as ignored in the new process; portable programs cannot rely on 347.Nm 348resetting it to the default disposition. 349