1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)exec.3 8.3 (Berkeley) 01/24/94 7.\" 8.Dd 9.Dt EXEC 3 10.Os 11.Sh NAME 12.Nm execl , 13.Nm execlp , 14.Nm execle , 15.Nm exect , 16.Nm execv , 17.Nm execvp 18.Nd execute a file 19.Sh SYNOPSIS 20.Fd #include <unistd.h> 21.Vt extern char **environ; 22.Ft int 23.Fn execl "const char *path" "const char *arg" ... 24.Ft int 25.Fn execlp "const char *file" "const char *arg" ... 26.Ft int 27.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 28.Ft int 29.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 30.Ft int 31.Fn execv "const char *path" "char *const argv[]" 32.Ft int 33.Fn execvp "const char *file" "char *const argv[]" 34.Sh DESCRIPTION 35The 36.Nm exec 37family of functions replaces the current process image with a 38new process image. 39The functions described in this manual page are front-ends for the function 40.Xr execve 2 . 41(See the manual page for 42.Xr execve 43for detailed information about the replacement of the current process.) 44.Pp 45The initial argument for these functions is the pathname of a file which 46is to be executed. 47.Pp 48The 49.Fa "const char *arg" 50and subsequent ellipses in the 51.Fn execl , 52.Fn execlp , 53and 54.Fn execle 55functions can be thought of as 56.Em arg0 , 57.Em arg1 , 58\&..., 59.Em argn . 60Together they describe a list of one or more pointers to null-terminated 61strings that represent the argument list available to the executed program. 62The first argument, by convention, should point to the file name associated 63with the file being executed. 64The list of arguments 65.Em must 66be terminated by a 67.Dv NULL 68pointer. 69.Pp 70The 71.Fn exect , 72.Fn execv , 73and 74.Fn execvp 75functions provide an array of pointers to null-terminated strings that 76represent the argument list available to the new program. 77The first argument, by convention, should point to the file name associated 78with the file begin executed. 79The array of pointers 80.Sy must 81be terminated by a 82.Dv NULL 83pointer. 84.Pp 85The 86.Fn execle 87and 88.Fn exect 89functions also specify the environment of the executed process by following 90the 91.Dv NULL 92pointer that terminates the list of arguments in the parameter list 93or the pointer to the argv array with an additional parameter. 94This additional parameter is an array of pointers to null-terminated strings 95and 96.Em must 97be terminated by a 98.Dv NULL 99pointer. 100The other functions take the environment for the new process image from the 101external variable 102.Va environ 103in the current process. 104.Pp 105Some of these functions have special semantics. 106.Pp 107The functions 108.Fn execlp 109and 110.Fn execvp 111will duplicate the actions of the shell in searching for an executable file 112if the specified file name does not contain a slash 113.Dq Li / 114character. 115The search path is the path specified in the environment by 116.Dq Ev PATH 117variable. 118If this variable isn't specified, the default path 119.Dq Ev /bin:/usr/bin: 120is 121used. 122In addition, certain errors are treated specially. 123.Pp 124If permission is denied for a file (the attempted 125.Xr execve 126returned 127.Er EACCES ) , 128these functions will continue searching the rest of 129the search path. 130If no other file is found, however, they will return with the global variable 131.Va errno 132set to 133.Er EACCES . 134.Pp 135If the header of a file isn't recognized (the attempted 136.Xr execve 137returned 138.Er ENOEXEC ) , 139these functions will execute the shell with the path of 140the file as its first argument. 141(If this attempt fails, no further searching is done.) 142.Pp 143If the file is currently busy (the attempted 144.Xr execve 145returned 146.Er ETXTBUSY ) , 147these functions will sleep for several seconds, 148periodically re-attempting to execute the file. 149.Pp 150The function 151.Fn exect 152executes a file with the program tracing facilities enabled (see 153.Xr ptrace 2 ) . 154.Sh RETURN VALUES 155If any of the 156.Xr exec 157functions returns, an error will have occurred. 158The return value is \-1, and the global variable 159.Va errno 160will be set to indicate the error. 161.Sh FILES 162.Bl -tag -width /bin/sh - compact 163.It Pa /bin/sh 164The shell. 165.El 166.Sh ERRORS 167.Fn Execl , 168.Fn execle , 169.Fn execlp 170and 171.Fn execvp 172may fail and set 173.Va errno 174for any of the errors specified for the library functions 175.Xr execve 2 176and 177.Xr malloc 3 . 178.Pp 179.Fn Exect 180and 181.Fn execv 182may fail and set 183.Va errno 184for any of the errors specified for the library function 185.Xr execve 2 . 186.Sh SEE ALSO 187.Xr sh 1 , 188.Xr execve 2 , 189.Xr fork 2 , 190.Xr trace 2 , 191.Xr environ 7 , 192.Xr ptrace 2 , 193.Xr environ 7 , 194.Sh COMPATIBILITY 195Historically, the default path for the 196.Fn execlp 197and 198.Fn execvp 199functions was 200.Dq Pa :/bin:/usr/bin . 201This was changed to place the current directory last to enhance system 202security. 203.Pp 204The behavior of 205.Fn execlp 206and 207.Fn execvp 208when errors occur while attempting to execute the file is historic 209practice, but has not traditionally been documented and is not specified 210by the 211.Tn POSIX 212standard. 213.Pp 214Traditionally, the functions 215.Fn execlp 216and 217.Fn execvp 218ignored all errors except for the ones described above and 219.Er ENOMEM 220and 221.Er E2BIG , 222upon which they returned. 223They now return if any error other than the ones described above occurs. 224.Sh STANDARDS 225.Fn Execl , 226.Fn execv , 227.Fn execle , 228.Fn execlp 229and 230.Fn execvp 231conform to 232.St -p1003.1-88 . 233