1.\" $NetBSD: execve.2,v 1.45 2019/09/18 04:57:53 wiz 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.Pp 79.Bd -ragged -offset indent -compact 80.Sy \&#! 81.Em interpreter 82.Bq Em arg 83.Ed 84.Pp 85When an interpreter file is 86.Sy execve Ar d , 87the system actually 88.Sy execve Ap s 89the specified 90.Em interpreter . 91If the optional 92.Em arg 93is specified, it becomes the first argument to the 94.Em interpreter , 95and the name of the originally 96.Sy execve Ap d 97file becomes the second argument; 98otherwise, the name of the originally 99.Sy execve Ap d 100file becomes the first argument. 101The original arguments are shifted over to become the subsequent arguments. 102The zeroth argument, normally the name of the 103.Fn execve Ns d 104file, is left unchanged. 105The interpreter named by 106.Em interpreter 107must not itself be an interpreter file. 108(See 109.Xr script 7 110for a detailed discussion of interpreter file execution.) 111.Pp 112The argument 113.Fa argv 114is a pointer to a null-terminated array of 115character pointers to null-terminated character strings. 116These strings construct the argument list to be made available to the new 117process. 118At least one argument must be present in 119the array; by custom, the first element should be 120the name of the executed program (for example, the last component of 121.Fa path ) . 122.Pp 123The argument 124.Fa envp 125is also a pointer to a null-terminated array of 126character pointers to null-terminated strings. 127A pointer to this array is normally stored in the global variable 128.Va environ . 129These strings pass information to the 130new process that is not directly an argument to the command (see 131.Xr environ 7 ) . 132.Pp 133File descriptors open in the calling process image remain open in 134the new process image, except for those for which the close-on-exec 135flag is set (see 136.Xr close 2 137and 138.Xr fcntl 2 ) . 139Descriptors that remain open are unaffected by 140.Fn execve . 141.Pp 142In the case of a new setuid or setgid executable being executed, if 143file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr) 144are currently unallocated, these descriptors will be opened to point to 145some system file like 146.Pa /dev/null . 147The intent is to ensure these descriptors are not unallocated, since 148many libraries make assumptions about the use of these 3 file descriptors. 149.Pp 150Signals set to be ignored in the calling process are set to be ignored in 151the new process. 152Signals which are set to be caught in the calling process image 153are set to default action in the new process image. 154Blocked signals remain blocked regardless of changes to the signal action. 155The signal stack is reset to be undefined (see 156.Xr sigaction 2 157for more information). 158.Pp 159If the set-user-ID mode bit of the new process image file is set 160(see 161.Xr chmod 2 ) , 162the effective user ID of the new process image is set to the owner ID 163of the new process image file. 164If the set-group-ID mode bit of the new process image file is set, 165the effective group ID of the new process image is set to the group ID 166of the new process image file. 167(The effective group ID is the first element of the group list.) 168The real user ID, real group ID and 169other group IDs of the new process image remain the same as the calling 170process image. 171After any set-user-ID and set-group-ID processing, 172the effective user ID is recorded as the saved set-user-ID, 173and the effective group ID is recorded as the saved set-group-ID. 174These values may be used in changing the effective IDs later (see 175.Xr setuid 2 ) . 176The set-ID bits are not honored if the respective file system has the 177.Cm nosuid 178option enabled or if the new process file is an interpreter file. 179Syscall 180tracing is disabled if effective IDs are changed. 181.Pp 182The new process also inherits the following attributes from 183the calling process: 184.Pp 185.Bl -column parent_process_ID -offset indent -compact 186.It process ID Ta see Xr getpid 2 187.It parent process ID Ta see Xr getppid 2 188.It process group ID Ta see Xr getpgrp 2 189.It access groups Ta see Xr getgroups 2 190.It working directory Ta see Xr chdir 2 191.It root directory Ta see Xr chroot 2 192.It control terminal Ta see Xr termios 4 193.It resource usages Ta see Xr getrusage 2 194.It interval timers Ta see Xr getitimer 2 195.It resource limits Ta see Xr getrlimit 2 196.It file mode mask Ta see Xr umask 2 197.It signal mask Ta see Xr sigaction 2 , 198.Xr sigprocmask 2 199.El 200.Pp 201When a program is executed as a result of an 202.Fn execve 203system call, it is entered as follows: 204.Bd -literal -offset indent 205main(argc, argv, envp) 206int argc; 207char **argv, **envp; 208.Ed 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.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.Aq Pa 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.Dv ( MNT_NOEXEC 279in 280.Ao Pa sys/mount.h Ac ) . 281.It Bq Er EAGAIN 282A 283.Xr setuid 7 284process has exceeded the current resource limit for the number of 285processes it is allowed to run concurrently. 286.It Bq Er EFAULT 287The new process file is not as long as indicated by 288the size values in its header; or 289the 290.Fa path , 291.Fa argv , 292or 293.Fa envp 294arguments point to an illegal address. 295.It Bq Er EIO 296An I/O error occurred while reading from the file system. 297.It Bq Er ELOOP 298Too many symbolic links were encountered in translating the pathname. 299.It Bq Er ENAMETOOLONG 300A component of a pathname exceeded 301.Brq Dv NAME_MAX 302characters, or an entire path name exceeded 303.Brq Dv PATH_MAX 304characters. 305.It Bq Er ENOENT 306The new process file does not exist, or 307the new process file is a script starting with 308.Li #! 309and the script interpreter does not exist. 310.It Bq Er ENOEXEC 311The new process file has the appropriate access 312permission, but has an invalid magic number in its header. 313.It Bq Er ENOMEM 314The new process requires more virtual memory than 315is allowed by the imposed maximum 316.Pq Xr getrlimit 2 . 317.It Bq Er ENOTDIR 318A component of the path prefix is not a directory. 319.It Bq Er ETXTBSY 320The new process file is a pure procedure (shared text) 321file that is currently open for writing or reading by some process. 322.El 323.Pp 324In addition, the 325.Fn fexecve 326will fail and return to the calling process if: 327.Bl -tag -width Er 328.It Bq Er EBADF 329The 330.Fa fd 331argument is not a valid file descriptor open for executing. 332.El 333.Sh SEE ALSO 334.Xr _exit 2 , 335.Xr fork 2 , 336.Xr open 2 , 337.Xr execl 3 , 338.Xr exit 3 , 339.Xr sysctl 3 , 340.Xr a.out 5 , 341.Xr elf 5 , 342.\" .Xr fdescfs 5 , 343.Xr environ 7 , 344.Xr script 7 , 345.Xr mount 8 346.Sh STANDARDS 347The 348.Fn execve 349system call conforms to 350.St -p1003.1-2001 . 351with the exception of reopening descriptors 0, 1, and/or 2 in certain 352circumstances. 353A future update of the Standard is expected to require this behavior, 354and it may become the default for non-privileged processes as well. 355.\" NB: update this caveat when TC1 is blessed. 356The support for executing interpreted programs is an extension. 357The 358.Fn fexecve 359system call conforms to The Open Group Extended API Set 2 specification. 360.Sh HISTORY 361The 362.Fn execve 363function call first appeared in 364.At v7 . 365The 366.Fn fexecve 367system call appeared in 368.Nx 10.0 . 369.Sh BUGS 370If a program is 371.Em setuid 372to a non-super-user, but is executed when 373the real 374.Em uid 375is 376.Dq root , 377then the program has some of the powers of a super-user as well. 378.\" .Pp 379.\" When executing an interpreted program through 380.\" .Fn fexecve , 381.\" kernel supplies 382.\" .Pa /dev/fd/n 383.\" as a second argument to the interpreter, 384.\" where 385.\" .Ar n 386.\" is the file descriptor passed in the 387.\" .Fa fd 388.\" argument to 389.\" .Fn fexecve . 390.\" For this construction to work correctly, the 391.\" .Xr fdescfs 5 392.\" filesystem shall be mounted on 393.\" .Pa /dev/fd . 394