1.\" $NetBSD: execve.2,v 1.47 2024/04/28 23:10:26 uwe Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)execve.2 8.5 (Berkeley) 6/1/94 31.\" 32.Dd September 16, 2019 33.Dt EXECVE 2 34.Os 35.Sh NAME 36.Nm execve , 37.Nm fexecve 38.Nd execute a file 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" 45.Ft int 46.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" 47.Sh DESCRIPTION 48The 49.Fn execve 50system call 51transforms the calling process into a new process. 52The new process is constructed from an ordinary file, 53whose name is pointed to by 54.Fa path , 55called the 56.Em new process file . 57The 58.Fn fexecve 59system call is equivalent to 60.Fn execve 61except that the file to be executed is determined by the file 62descriptor 63.Fa fd 64instead of a 65.Fa path . 66This file is either an executable object file, 67or a file of data for an interpreter. 68An executable object file consists of an identifying header, 69followed by pages of data representing the initial program (text) 70and initialized data pages. 71Additional pages may be specified 72by the header to be initialized with zero data; see 73.Xr elf 5 74and 75.Xr a.out 5 . 76.Pp 77An interpreter file begins with a line of the form: 78.Bd -ragged -offset indent 79.Ic \&#! Ns Ar interpreter Op Ar arg 80.Ed 81.Pp 82When an interpreter file is 83.Nm Ap d , 84the system actually 85.Nm Ap s 86the specified 87.Ar interpreter . 88If the optional 89.Ar arg 90is specified, it becomes the first argument to the 91.Ar interpreter , 92and the name of the originally 93.Nm Ap d 94file becomes the second argument; 95otherwise, the name of the originally 96.Nm Ap d 97file becomes the first argument. 98The original arguments are shifted over to become the subsequent arguments. 99The zeroth argument, normally the name of the 100.Nm Ap d 101file, is left unchanged. 102The interpreter named by 103.Ar interpreter 104must not itself be an interpreter file. 105(See 106.Xr script 7 107for a detailed discussion of interpreter file execution.) 108.Pp 109The argument 110.Fa argv 111is a pointer to a null-terminated array of 112character pointers to null-terminated character strings. 113These strings construct the argument list to be made available to the new 114process. 115At least one argument must be present in 116the array; by custom, the first element should be 117the name of the executed program (for example, the last component of 118.Fa path ) . 119.Pp 120The argument 121.Fa envp 122is also a pointer to a null-terminated array of 123character pointers to null-terminated strings. 124A pointer to this array is normally stored in the global variable 125.Va environ . 126These strings pass information to the 127new process that is not directly an argument to the command 128.Pq see Xr environ 7 . 129.Pp 130File descriptors open in the calling process image remain open in 131the new process image, except for those for which the close-on-exec 132flag is set (see 133.Xr close 2 134and 135.Xr fcntl 2 ) . 136Descriptors that remain open are unaffected by 137.Fn execve . 138.Pp 139In the case of a new setuid or setgid executable being executed, if 140file descriptors 0, 1, or 2 141.Po 142representing 143.Em stdin , stdout , 144and 145.Em stderr 146.Pc 147are currently unallocated, these descriptors will be opened to point to 148some system file like 149.Pa /dev/null . 150The intent is to ensure these descriptors are not unallocated, since 151many libraries make assumptions about the use of these three file descriptors. 152.Pp 153Signals set to be ignored in the calling process are set to be ignored in 154the new process. 155Signals which are set to be caught in the calling process image 156are set to default action in the new process image. 157Blocked signals remain blocked regardless of changes to the signal action. 158The signal stack is reset to be undefined (see 159.Xr sigaction 2 160for more information). 161.Pp 162If the set-user-ID mode bit of the new process image file is set 163.Pq see Xr chmod 2 , 164the effective user ID of the new process image is set to the owner ID 165of the new process image file. 166If the set-group-ID mode bit of the new process image file is set, 167the effective group ID of the new process image is set to the group ID 168of the new process image file. 169(The effective group ID is the first element of the group list.) 170The real user ID, real group ID and 171other group IDs of the new process image remain the same as the calling 172process image. 173After any set-user-ID and set-group-ID processing, 174the effective user ID is recorded as the saved set-user-ID, 175and the effective group ID is recorded as the saved set-group-ID. 176These values may be used in changing the effective IDs later 177.Pq see Xr setuid 2 . 178The set-ID bits are not honored if the respective file system has the 179.Cm nosuid 180option enabled or if the new process file is an interpreter file. 181Syscall 182tracing is disabled if effective IDs are changed. 183.Pp 184The new process also inherits the following attributes from 185the calling process: 186.Pp 187.Bl -column "parent process ID" -offset indent -compact 188.It process ID Ta see Xr getpid 2 189.It parent process ID Ta see Xr getppid 2 190.It process group ID Ta see Xr getpgrp 2 191.It access groups Ta see Xr getgroups 2 192.It working directory Ta see Xr chdir 2 193.It root directory Ta see Xr chroot 2 194.It control terminal Ta see Xr termios 4 195.It resource usages Ta see Xr getrusage 2 196.It interval timers Ta see Xr getitimer 2 197.It resource limits Ta see Xr getrlimit 2 198.It file mode mask Ta see Xr umask 2 199.It signal mask Ta see Xr sigaction 2 , Xr sigprocmask 2 200.El 201.Pp 202When a program is executed as a result of an 203.Fn execve 204system call, it is entered as follows: 205.Bd -literal -offset indent 206main(argc, argv, envp) 207int argc; 208char **argv, **envp; 209.Ed 210.Pp 211where 212.Fa argc 213.Pq the Dq arg count 214is the number of elements in 215.Fa argv , 216and 217.Fa argv 218points to the array of character pointers 219to the arguments themselves. 220.Pp 221The 222.Fn fexecve 223function ignores the file offset of 224.Fa fd . 225Since execute permission is checked by 226.Fn fexecve , 227the file descriptor 228.Fa fd 229need not have been opened with the 230.Dv O_EXEC 231flag. 232However, if the file to be executed denies read permission for the process 233preparing to do the exec, the only way to provide the 234.Fa fd 235to 236.Fn fexecve 237is to use the 238.Dv O_EXEC 239flag when opening 240.Fa fd . 241Note that the file to be executed can not be open for writing. 242.Sh RETURN VALUES 243As the 244.Fn execve 245system call overlays the current process image 246with a new process image the successful call 247has no process to return to. 248If 249.Fn execve 250does return to the calling process an error has occurred; the 251return value will be \-1 and the global variable 252.Va errno 253is set to indicate the error. 254.Sh ERRORS 255The 256.Fn execve 257system call 258will fail and return to the calling process if: 259.Bl -tag -width Er 260.It Bq Er E2BIG 261The number of bytes in the new process' argument list 262is larger than the system-imposed limit. 263The default compile time limit is 262144 bytes and is specified 264in the variable 265.Dv NCARGS 266in 267.In sys/param.h 268and get be read from the 269.Xr sysctl 3 270MIB variable 271.Dv KERN_ARGMAX . 272.It Bq Er EACCES 273Search permission is denied for a component of the path prefix, 274the new process file is not an ordinary file, 275its file mode denies execute permission, or 276it is on a file system mounted with execution 277disabled 278.Po 279.Dv MNT_NOEXEC 280in 281.In sys/mount.h 282.Pc . 283.It Bq Er EAGAIN 284A 285.Xr setuid 7 286process has exceeded the current resource limit for the number of 287processes it is allowed to run concurrently. 288.It Bq Er EFAULT 289The new process file is not as long as indicated by 290the size values in its header; or 291the 292.Fa path , 293.Fa argv , 294or 295.Fa envp 296arguments point to an illegal address. 297.It Bq Er EIO 298An I/O error occurred while reading from the file system. 299.It Bq Er ELOOP 300Too many symbolic links were encountered in translating the pathname. 301.It Bq Er ENAMETOOLONG 302A component of a pathname exceeded 303.Brq Dv NAME_MAX 304characters, or an entire path name exceeded 305.Brq Dv PATH_MAX 306characters. 307.It Bq Er ENOENT 308The new process file does not exist, or 309the new process file is a script starting with 310.Ql #! 311and the script interpreter does not exist. 312.It Bq Er ENOEXEC 313The new process file has the appropriate access 314permission, but has an invalid magic number in its header. 315.It Bq Er ENOMEM 316The new process requires more virtual memory than 317is allowed by the imposed maximum 318.Pq Xr getrlimit 2 . 319.It Bq Er ENOTDIR 320A component of the path prefix is not a directory. 321.It Bq Er ETXTBSY 322The new process file is a pure procedure (shared text) 323file that is currently open for writing or reading by some process. 324.El 325.Pp 326In addition, the 327.Fn fexecve 328will fail and return to the calling process if: 329.Bl -tag -width Er 330.It Bq Er EBADF 331The 332.Fa fd 333argument is not a valid file descriptor open for executing. 334.El 335.Sh SEE ALSO 336.Xr _exit 2 , 337.Xr fork 2 , 338.Xr open 2 , 339.Xr execl 3 , 340.Xr exit 3 , 341.Xr sysctl 3 , 342.Xr a.out 5 , 343.Xr elf 5 , 344.\" .Xr fdescfs 5 , 345.Xr environ 7 , 346.Xr script 7 , 347.Xr mount 8 348.Sh STANDARDS 349The 350.Fn execve 351system call conforms to 352.St -p1003.1-2001 . 353with the exception of reopening descriptors 0, 1, and/or 2 in certain 354circumstances. 355A future update of the Standard is expected to require this behavior, 356and it may become the default for non-privileged processes as well. 357.\" NB: update this caveat when TC1 is blessed. 358The support for executing interpreted programs is an extension. 359The 360.Fn fexecve 361system call conforms to The Open Group Extended API Set 2 specification. 362.Sh HISTORY 363The 364.Fn execve 365function call first appeared in 366.At v7 . 367The 368.Fn fexecve 369system call appeared in 370.Nx 10.0 . 371.Sh BUGS 372If a program is 373.Em setuid 374to a non-super-user, but is executed when 375the real 376.Em uid 377is 378.Dq root , 379then the program has some of the powers of a super-user as well. 380.\" .Pp 381.\" When executing an interpreted program through 382.\" .Fn fexecve , 383.\" kernel supplies 384.\" .Pa /dev/fd/n 385.\" as a second argument to the interpreter, 386.\" where 387.\" .Ar n 388.\" is the file descriptor passed in the 389.\" .Fa fd 390.\" argument to 391.\" .Fn fexecve . 392.\" For this construction to work correctly, the 393.\" .Xr fdescfs 5 394.\" filesystem shall be mounted on 395.\" .Pa /dev/fd . 396