1*47208Scael.\" Copyright (c) 1980, 1991 Regents of the University of California. 2*47208Scael.\" All rights reserved. 320107Smckusick.\" 4*47208Scael.\" %sccs.include.redist.man% 520107Smckusick.\" 6*47208Scael.\" @(#)execve.2 6.9 (Berkeley) 03/10/91 7*47208Scael.\" 8*47208Scael.Dd 9*47208Scael.Dt EXECVE 2 10*47208Scael.Os BSD 4 11*47208Scael.Sh NAME 12*47208Scael.Nm execve 13*47208Scael.Nd execute a file 14*47208Scael.Sh SYNOPSIS 15*47208Scael.Fd #include <unistd.h> 16*47208Scael.Ft int 17*47208Scael.Fn execve "const char *path" "const * char *argv" "const * char *envp" 18*47208Scael.Sh DESCRIPTION 19*47208Scael.Fn Execve 2020108Smckusicktransforms the calling process into a new process. 2136256SbosticThe new process is constructed from an ordinary file, 2236256Sbosticwhose name is pointed to by 23*47208Scael.Fa path , 24*47208Scaelcalled the 25*47208Scael.Em new process file . 2620108SmckusickThis file is either an executable object file, 2720108Smckusickor a file of data for an interpreter. 2820108SmckusickAn executable object file consists of an identifying header, 2920108Smckusickfollowed by pages of data representing the initial program (text) 3020108Smckusickand initialized data pages. Additional pages may be specified 31*47208Scaelby the header to be initialized with zero data; see 32*47208Scael.Xr a.out 5 . 33*47208Scael.Pp 34*47208ScaelAn interpreter file begins with a line of the form: 35*47208Scael.Pp 36*47208Scael.Bd -filled -offset indent -compact 37*47208Scael.Sy \&#! 38*47208Scael.Em interpreter 39*47208Scael.Bq Em arg 40*47208Scael.Ed 41*47208Scael.Pp 4220108SmckusickWhen an interpreter file is 43*47208Scael.Fn execve Ap d , 44*47208Scaelthe system 45*47208Scael.Fn execve Ap s 46*47208Scaelthe specified 47*47208Scael.Em interpreter . 4836256SbosticIf the optional 49*47208Scael.Em arg 5036256Sbosticis specified, it becomes the first argument to the 51*47208Scael.Em interpreter , 5236256Sbosticand the name of the originally 53*47208Scael.Fn execve Ap d 5436256Sbosticfile becomes the second argument; 5536256Sbosticotherwise, the name of the originally 56*47208Scael.Fn execve Ap d 5736256Sbosticfile becomes the first argument. The original arguments are shifted over to 5836256Sbosticbecome the subsequent arguments. The zeroth argument, normally the name of the 59*47208Scael.Fn execve Ap d 6036256Sbosticfile, is left unchanged. 61*47208Scael.Pp 62*47208ScaelThe argument 63*47208Scael.Fa argv 64*47208Scaelis a pointer to a null-terminated array of 6536256Sbosticcharacter pointers to null-terminated character strings. 66*47208ScaelThese strings construct the argument list to be made available to the new 67*47208Scaelprocess. At least one argument must be present in 68*47208Scaelthe array; by custom, the first element should be 69*47208Scaelthe name of the executed program (for example, the last component of 70*47208Scael.Fa path ) . 71*47208Scael.Pp 72*47208ScaelThe argument 73*47208Scael.Fa envp 74*47208Scaelis also a pointer to a null-terminated array of 7536256Sbosticcharacter pointers to null-terminated strings. 76*47208ScaelA pointer to this array is normally stored in the global variable 77*47208Scael.Va environ. 7836256SbosticThese strings pass information to the 7928364Sannenew process that is not directly an argument to the command (see 80*47208Scael.Xr environ 7 ) . 81*47208Scael.Pp 82*47208ScaelFile descriptors open in the calling process image remain open in 83*47208Scaelthe new process image, except for those for which the close-on-exec 8428364Sanneflag is set (see 85*47208Scael.Xr close 2 8636256Sbosticand 87*47208Scael.Xr fcntl 2 ) . 8823798SsechrestDescriptors that remain open are unaffected by 89*47208Scael.Fn execve . 90*47208Scael.Pp 91*47208ScaelSignals set to be ignored in the calling process are set to be ignored in 92*47208Scaelthe 93*47208Scaelnew process. Signals which are set to be caught in the calling process image 94*47208Scaelare set to default action in the new process image. 9528068SkarelsBlocked signals remain blocked regardless of changes to the signal action. 9628364SanneThe signal stack is reset to be undefined (see 97*47208Scael.Xr sigaction 2 9828364Sannefor more information). 99*47208Scael.Pp 100*47208ScaelIf the set-user-ID mode bit of the new process image file is set 101*47208Scael(see 102*47208Scael.Xr chmod 2 ) , 103*47208Scaelthe effective user ID of the new process image is set to the owner ID 104*47208Scaelof the new process image file. 105*47208ScaelIf the set-group-ID mode bit of the new process image file is set, 106*47208Scaelthe effective group ID of the new process image is set to the group ID 107*47208Scaelof the new process image file. 108*47208ScaelThe real user ID, real group ID and 109*47208Scaelsupplementary group IDs of the new process image remain the same as the calling 110*47208Scaelprocess image. 111*47208Scael.Pp 11220108SmckusickThe new process also inherits the following attributes from 11320108Smckusickthe calling process: 114*47208Scael.Pp 115*47208Scael.Bl -column parent_process_ID -offset indent -compact 116*47208Scael.It process ID Ta see Xr getpid 2 117*47208Scael.It parent process ID Ta see Xr getppid 2 118*47208Scael.It process group ID Ta see Xr getpgrp 2 119*47208Scael.It access groups Ta see Xr getgroups 2 120*47208Scael.It working directory Ta see Xr chdir 2 121*47208Scael.It root directory Ta see Xr chroot 2 122*47208Scael.It control terminal Ta see Xr termios 4 123*47208Scael.It resource usages Ta see Xr getrusage 2 124*47208Scael.It interval timers Ta see Xr getitimer 2 125*47208Scael.It resource limits Ta see Xr getrlimit 2 126*47208Scael.It file mode mask Ta see Xr umask 2 127*47208Scael.It signal mask Ta see Xr sigvec 2 , 128*47208Scael.Xr sigsetmask 2 129*47208Scael.El 130*47208Scael.Pp 131*47208ScaelWhen a program is executed as a result of an 132*47208Scael.Fn execve 133*47208Scaelcall, it is entered as follows: 134*47208Scael.Bd -literal -offset indent 135*47208Scaelmain(argc, argv, envp) 136*47208Scaelint argc; 137*47208Scaelchar **argv, **envp; 138*47208Scael.Ed 139*47208Scael.Pp 14020107Smckusickwhere 141*47208Scael.Fa argc 142*47208Scaelis the number of elements in 143*47208Scael.Fa argv 14420108Smckusick(the ``arg count'') 14520107Smckusickand 146*47208Scael.Fa argv 14736256Sbosticpoints to the array of character pointers 14820107Smckusickto the arguments themselves. 149*47208Scael.Sh RETURN VALUES 150*47208ScaelAs the 151*47208Scael.Fn execve 152*47208Scaelfunction overlays the current process image 153*47208Scaelwith a new process image the successful call 154*47208Scaelhas no process to return to. 15520108SmckusickIf 156*47208Scael.Fn execve 157*47208Scaeldoes return to the calling process an error has occurred; the 158*47208Scaelreturn value will be -1 and the global variable 159*47208Scael.Va errno 160*47208Scaelis set to indicate the error. 161*47208Scael.Sh ERRORS 162*47208Scael.Fn Execve 163*47208Scaelwill fail and return to the calling process if: 164*47208Scael.Bl -tag -width [ENAMETOOLONG] 165*47208Scael.It Bq Er ENOTDIR 16621003SmckusickA component of the path prefix is not a directory. 167*47208Scael.It Bq Er EINVAL 16821003SmckusickThe pathname contains a character with the high-order bit set. 169*47208Scael.It Bq Er ENAMETOOLONG 17021003SmckusickA component of a pathname exceeded 255 characters, 17121003Smckusickor an entire path name exceeded 1023 characters. 172*47208Scael.It Bq Er ENOENT 17321003SmckusickThe new process file does not exist. 174*47208Scael.It Bq Er ELOOP 17521003SmckusickToo many symbolic links were encountered in translating the pathname. 176*47208Scael.It Bq Er EACCES 17721003SmckusickSearch permission is denied for a component of the path prefix. 178*47208Scael.It Bq Er EACCES 17920108SmckusickThe new process file is not an ordinary file. 180*47208Scael.It Bq Er EACCES 18120108SmckusickThe new process file mode denies execute permission. 182*47208Scael.It Bq Er ENOEXEC 18320108SmckusickThe new process file has the appropriate access 18420108Smckusickpermission, but has an invalid magic number in its header. 185*47208Scael.It Bq Er ETXTBSY 18620108SmckusickThe new process file is a pure procedure (shared text) 18720108Smckusickfile that is currently open for writing or reading by some process. 188*47208Scael.It Bq Er ENOMEM 18920108SmckusickThe new process requires more virtual memory than 19020108Smckusickis allowed by the imposed maximum 191*47208Scael.Pq Xr getrlimit 2 . 192*47208Scael.It Bq Er E2BIG 19320108SmckusickThe number of bytes in the new process's argument list 19428151Skarelsis larger than the system-imposed limit. 19528151SkarelsThe limit in the system as released is 20480 bytes 196*47208Scael.Pf ( Dv NCARGS 197*47208Scaelin 198*47208Scael.Ao Pa sys/param.h Ac . 199*47208Scael.It Bq Er EFAULT 20020108SmckusickThe new process file is not as long as indicated by 20120108Smckusickthe size values in its header. 202*47208Scael.It Bq Er EFAULT 203*47208Scael.Fa Path , 204*47208Scael.Fa argv , 205*47208Scaelor 206*47208Scael.Fa envp 207*47208Scaelpoint 20820108Smckusickto an illegal address. 209*47208Scael.It Bq Er EIO 21024439SmckusickAn I/O error occurred while reading from the file system. 211*47208Scael.El 212*47208Scael.Sh CAVEAT 21320108SmckusickIf a program is 214*47208Scael.Em setuid 21520108Smckusickto a non-super-user, but is executed when 216*47208Scaelthe real 217*47208Scael.Em uid 218*47208Scaelis ``root'', then the program has some of the powers 21920108Smckusickof a super-user as well. 220*47208Scael.Sh SEE ALSO 221*47208Scael.Xr exit 2 , 222*47208Scael.Xr fork 2 , 223*47208Scael.Xr execl 3 , 224*47208Scael.Xr environ 7 225*47208Scael.Sh HISTORY 226*47208ScaelThe 227*47208Scael.Nm 228*47208Scaelfunction call appeared in 229*47208Scael.Bx 4.2 . 230