.\" SCCSID: @(#)execl.3	2.1	3/10/87.TH execl 3 VAX.SH Nameexecl, execv, execle, execlp, execvp, exect, environ \- execute a file.SH Syntax.nf.B "execl(\fIname, arg0, arg1, ..., argn, (char *)0\fP)".B char *\fIname, *arg0, *arg1, ..., *argn\fP;.PP.B execv(\fIname, argv\fP).B char *\fIname, *argv[]\fP;.PP.B "execle(\fIname, arg0, arg1, ..., argn, (char *)0, envp\fP)".B "char *\fIname, *arg0, *arg1, ..., *argn, *envp[]\fP;".PP.B "execlp(\fIfile, arg0, arg1, ..., argn, (char *)0\fP)".B "char *\fIfile, *arg0, *arg1, ..., *argn\fP;".PP.B "execvp(\fIfile,argv\fP)".B "char *\fIfile, *argv[]\fP;".PP.B "exect(\fIname, argv, envp\fP).B "char *\fIname, *argv[], *envp[]\fP;.PP.B extern \fIchar **environ\fP;.fi.SH Description.NXR "execl subroutine".NXR "execv subroutine".NXR "execle subroutine".NXR "execlp subroutine".NXR "execvp subroutine".NXR "exect subroutine".NXR "environ subroutine".NXA "ptrace system call" "exect subroutine".NXA "execve system call" "execl subroutine".NXR "file" "executing"These routines provide various interfaces to the.PN execve system call.  Refer to .MS execve 2for a description of their properties; onlybrief descriptions are provided here..PPIn all their forms, these callsoverlay the calling process with the named file, thentransfer to theentry point of the core image of the file.There can be no return from a successful exec.  The calling core image is lost.  .PP The.I nameargumentis a pointer to the name of the fileto be executed.The pointers.IR arg [ 0 ],.IR arg [ 1 "] ..."address null-terminated strings.Conventionally.IR arg [ 0 ]is the name of thefile..PPTwo interfaces are available..PN execlis useful when a known file with known arguments isbeing called;the arguments to .PN execlare the character stringsconstituting the file and the arguments;the first argument is conventionallythe same as the file name (or its last component).A 0 argument must end the argument list..PPThe.PN execvversion is useful when the number of arguments is unknownin advance.The arguments to.PN execvare the name of the file to beexecuted and a vector of strings containingthe arguments.The last argument string must be followedby a 0 pointer..PPThe.PN exectversion is used when the executed file is to bemanipulated with .MS ptrace 2 .The program is forced to single step a singleinstruction giving the parent an opportunity tomanipulate its state.  On the VAX-11 this is doneby setting the trace bit in the process statuslongword..PPWhen a C program is executed,it is called as follows:.EX	main(argc, argv, envp)	int argc;	char **argv, **envp;.EEwhere.I argcis the argument countand.I argv is an array of character pointersto the arguments themselves.As indicated,.I argcis conventionally at least oneand the first member of the array points to astring containing the name of the file..PPThe.I argvis directly usable in another.PN execvbecause.IR argv [ argc ]is 0..PPThe.I envpis a pointer to an array of strings that constitutethe.I environmentof the process.Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.The array of pointers is terminated by a null pointer.The shell .MS sh 1passes an environment entry for each global shell variabledefined when the program is called.See .MS environ 7for some conventionally used names.The C run-time start-off routine places a copy of.I envpin the global cell.PN environ ,which is usedby.PN execvand.PN execlto pass the environment to any subprograms executed by thecurrent program..PPThe.PN execlpand.PN execvproutinesare called with the same arguments as.PN execland.PN execv ,but duplicate the shell's actions in searching for an executablefile in a list of directories.The directory list is obtained from the environment..SH Restrictions.NXR "execvp subroutine" "restrictions"If.PN execvpis called to execute a file that turns out to be a shellcommand file,and if it is impossible to execute the shell,the values of.I argv[0]and.I argv[\-1]will be modified before return..SH Diagnostics.NXR "execvp subroutine" "diagnostics"If the file cannot be found,if it is not executable,if it does not start with a valid magic number,if maximum memory is exceeded,or if the arguments require too much space,a returnconstitutes the diagnostic;the return value is \-1.For further information, see .MS a.out 5 .Even for the super-user,at least one of the execute-permission bits must be set fora file to be executed..SH Files.IP /bin/sh 1iShell, invoked if command file foundby execlp or execvp.SH See Alsocsh(1), execve(2), fork(2), environ(7)