147208Scael.\" Copyright (c) 1980, 1991 Regents of the University of California. 247208Scael.\" All rights reserved. 320107Smckusick.\" 447208Scael.\" %sccs.include.redist.man% 520107Smckusick.\" 6*58265Smckusick.\" @(#)execve.2 6.10 (Berkeley) 02/26/93 747208Scael.\" 847208Scael.Dd 947208Scael.Dt EXECVE 2 1047208Scael.Os BSD 4 1147208Scael.Sh NAME 1247208Scael.Nm execve 1347208Scael.Nd execute a file 1447208Scael.Sh SYNOPSIS 1547208Scael.Fd #include <unistd.h> 1647208Scael.Ft int 1747208Scael.Fn execve "const char *path" "const * char *argv" "const * char *envp" 1847208Scael.Sh DESCRIPTION 1947208Scael.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 2347208Scael.Fa path , 2447208Scaelcalled the 2547208Scael.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 3147208Scaelby the header to be initialized with zero data; see 3247208Scael.Xr a.out 5 . 3347208Scael.Pp 3447208ScaelAn interpreter file begins with a line of the form: 3547208Scael.Pp 3647208Scael.Bd -filled -offset indent -compact 3747208Scael.Sy \&#! 3847208Scael.Em interpreter 3947208Scael.Bq Em arg 4047208Scael.Ed 4147208Scael.Pp 4220108SmckusickWhen an interpreter file is 4347208Scael.Fn execve Ap d , 4447208Scaelthe system 4547208Scael.Fn execve Ap s 4647208Scaelthe specified 4747208Scael.Em interpreter . 4836256SbosticIf the optional 4947208Scael.Em arg 5036256Sbosticis specified, it becomes the first argument to the 5147208Scael.Em interpreter , 5236256Sbosticand the name of the originally 5347208Scael.Fn execve Ap d 5436256Sbosticfile becomes the second argument; 5536256Sbosticotherwise, the name of the originally 5647208Scael.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 5947208Scael.Fn execve Ap d 6036256Sbosticfile, is left unchanged. 6147208Scael.Pp 6247208ScaelThe argument 6347208Scael.Fa argv 6447208Scaelis a pointer to a null-terminated array of 6536256Sbosticcharacter pointers to null-terminated character strings. 6647208ScaelThese strings construct the argument list to be made available to the new 6747208Scaelprocess. At least one argument must be present in 6847208Scaelthe array; by custom, the first element should be 6947208Scaelthe name of the executed program (for example, the last component of 7047208Scael.Fa path ) . 7147208Scael.Pp 7247208ScaelThe argument 7347208Scael.Fa envp 7447208Scaelis also a pointer to a null-terminated array of 7536256Sbosticcharacter pointers to null-terminated strings. 7647208ScaelA pointer to this array is normally stored in the global variable 7747208Scael.Va environ. 7836256SbosticThese strings pass information to the 7928364Sannenew process that is not directly an argument to the command (see 8047208Scael.Xr environ 7 ) . 8147208Scael.Pp 8247208ScaelFile descriptors open in the calling process image remain open in 8347208Scaelthe new process image, except for those for which the close-on-exec 8428364Sanneflag is set (see 8547208Scael.Xr close 2 8636256Sbosticand 8747208Scael.Xr fcntl 2 ) . 8823798SsechrestDescriptors that remain open are unaffected by 8947208Scael.Fn execve . 9047208Scael.Pp 9147208ScaelSignals set to be ignored in the calling process are set to be ignored in 9247208Scaelthe 9347208Scaelnew process. Signals which are set to be caught in the calling process image 9447208Scaelare 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 9747208Scael.Xr sigaction 2 9828364Sannefor more information). 9947208Scael.Pp 10047208ScaelIf the set-user-ID mode bit of the new process image file is set 10147208Scael(see 10247208Scael.Xr chmod 2 ) , 10347208Scaelthe effective user ID of the new process image is set to the owner ID 10447208Scaelof the new process image file. 10547208ScaelIf the set-group-ID mode bit of the new process image file is set, 10647208Scaelthe effective group ID of the new process image is set to the group ID 10747208Scaelof the new process image file. 108*58265Smckusick(The effective group ID is the first element of the group list.) 10947208ScaelThe real user ID, real group ID and 110*58265Smckusickother group IDs of the new process image remain the same as the calling 11147208Scaelprocess image. 112*58265SmckusickAfter any set-user-ID and set-group-ID processing, 113*58265Smckusickthe effective user ID is recorded as the saved set-user-ID, 114*58265Smckusickand the effective group ID is recorded as the saved set-group-ID. 115*58265SmckusickThese values may be used in changing the effective IDs later (see 116*58265Smckusick.XR setuid 2 ) . 11747208Scael.Pp 11820108SmckusickThe new process also inherits the following attributes from 11920108Smckusickthe calling process: 12047208Scael.Pp 12147208Scael.Bl -column parent_process_ID -offset indent -compact 12247208Scael.It process ID Ta see Xr getpid 2 12347208Scael.It parent process ID Ta see Xr getppid 2 12447208Scael.It process group ID Ta see Xr getpgrp 2 12547208Scael.It access groups Ta see Xr getgroups 2 12647208Scael.It working directory Ta see Xr chdir 2 12747208Scael.It root directory Ta see Xr chroot 2 12847208Scael.It control terminal Ta see Xr termios 4 12947208Scael.It resource usages Ta see Xr getrusage 2 13047208Scael.It interval timers Ta see Xr getitimer 2 13147208Scael.It resource limits Ta see Xr getrlimit 2 13247208Scael.It file mode mask Ta see Xr umask 2 13347208Scael.It signal mask Ta see Xr sigvec 2 , 13447208Scael.Xr sigsetmask 2 13547208Scael.El 13647208Scael.Pp 13747208ScaelWhen a program is executed as a result of an 13847208Scael.Fn execve 13947208Scaelcall, it is entered as follows: 14047208Scael.Bd -literal -offset indent 14147208Scaelmain(argc, argv, envp) 14247208Scaelint argc; 14347208Scaelchar **argv, **envp; 14447208Scael.Ed 14547208Scael.Pp 14620107Smckusickwhere 14747208Scael.Fa argc 14847208Scaelis the number of elements in 14947208Scael.Fa argv 15020108Smckusick(the ``arg count'') 15120107Smckusickand 15247208Scael.Fa argv 15336256Sbosticpoints to the array of character pointers 15420107Smckusickto the arguments themselves. 15547208Scael.Sh RETURN VALUES 15647208ScaelAs the 15747208Scael.Fn execve 15847208Scaelfunction overlays the current process image 15947208Scaelwith a new process image the successful call 16047208Scaelhas no process to return to. 16120108SmckusickIf 16247208Scael.Fn execve 16347208Scaeldoes return to the calling process an error has occurred; the 16447208Scaelreturn value will be -1 and the global variable 16547208Scael.Va errno 16647208Scaelis set to indicate the error. 16747208Scael.Sh ERRORS 16847208Scael.Fn Execve 16947208Scaelwill fail and return to the calling process if: 17047208Scael.Bl -tag -width [ENAMETOOLONG] 17147208Scael.It Bq Er ENOTDIR 17221003SmckusickA component of the path prefix is not a directory. 17347208Scael.It Bq Er EINVAL 17421003SmckusickThe pathname contains a character with the high-order bit set. 17547208Scael.It Bq Er ENAMETOOLONG 17621003SmckusickA component of a pathname exceeded 255 characters, 17721003Smckusickor an entire path name exceeded 1023 characters. 17847208Scael.It Bq Er ENOENT 17921003SmckusickThe new process file does not exist. 18047208Scael.It Bq Er ELOOP 18121003SmckusickToo many symbolic links were encountered in translating the pathname. 18247208Scael.It Bq Er EACCES 18321003SmckusickSearch permission is denied for a component of the path prefix. 18447208Scael.It Bq Er EACCES 18520108SmckusickThe new process file is not an ordinary file. 18647208Scael.It Bq Er EACCES 18720108SmckusickThe new process file mode denies execute permission. 18847208Scael.It Bq Er ENOEXEC 18920108SmckusickThe new process file has the appropriate access 19020108Smckusickpermission, but has an invalid magic number in its header. 19147208Scael.It Bq Er ETXTBSY 19220108SmckusickThe new process file is a pure procedure (shared text) 19320108Smckusickfile that is currently open for writing or reading by some process. 19447208Scael.It Bq Er ENOMEM 19520108SmckusickThe new process requires more virtual memory than 19620108Smckusickis allowed by the imposed maximum 19747208Scael.Pq Xr getrlimit 2 . 19847208Scael.It Bq Er E2BIG 19920108SmckusickThe number of bytes in the new process's argument list 20028151Skarelsis larger than the system-imposed limit. 20128151SkarelsThe limit in the system as released is 20480 bytes 20247208Scael.Pf ( Dv NCARGS 20347208Scaelin 20447208Scael.Ao Pa sys/param.h Ac . 20547208Scael.It Bq Er EFAULT 20620108SmckusickThe new process file is not as long as indicated by 20720108Smckusickthe size values in its header. 20847208Scael.It Bq Er EFAULT 20947208Scael.Fa Path , 21047208Scael.Fa argv , 21147208Scaelor 21247208Scael.Fa envp 21347208Scaelpoint 21420108Smckusickto an illegal address. 21547208Scael.It Bq Er EIO 21624439SmckusickAn I/O error occurred while reading from the file system. 21747208Scael.El 21847208Scael.Sh CAVEAT 21920108SmckusickIf a program is 22047208Scael.Em setuid 22120108Smckusickto a non-super-user, but is executed when 22247208Scaelthe real 22347208Scael.Em uid 22447208Scaelis ``root'', then the program has some of the powers 22520108Smckusickof a super-user as well. 22647208Scael.Sh SEE ALSO 22747208Scael.Xr exit 2 , 22847208Scael.Xr fork 2 , 22947208Scael.Xr execl 3 , 23047208Scael.Xr environ 7 23147208Scael.Sh HISTORY 23247208ScaelThe 23347208Scael.Nm 23447208Scaelfunction call appeared in 23547208Scael.Bx 4.2 . 236