1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 33.\" 34.Dd January 24, 1994 35.Dt EXEC 3 36.Os 37.Sh NAME 38.Nm execl , 39.Nm execlp , 40.Nm execle , 41.Nm exect , 42.Nm execv , 43.Nm execvp 44.Nd execute a file 45.Sh SYNOPSIS 46.Fd #include <unistd.h> 47.Vt extern char **environ; 48.Ft int 49.Fn execl "const char *path" "const char *arg" ... 50.Ft int 51.Fn execlp "const char *file" "const char *arg" ... 52.Ft int 53.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 54.Ft int 55.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 56.Ft int 57.Fn execv "const char *path" "char *const argv[]" 58.Ft int 59.Fn execvp "const char *file" "char *const argv[]" 60.Sh DESCRIPTION 61The 62.Nm exec 63family of functions replaces the current process image with a 64new process image. 65The functions described in this manual page are front-ends for the function 66.Xr execve 2 . 67(See the manual page for 68.Xr execve 69for detailed information about the replacement of the current process.) 70.Pp 71The initial argument for these functions is the pathname of a file which 72is to be executed. 73.Pp 74The 75.Fa "const char *arg" 76and subsequent ellipses in the 77.Fn execl , 78.Fn execlp , 79and 80.Fn execle 81functions can be thought of as 82.Em arg0 , 83.Em arg1 , 84\&..., 85.Em argn . 86Together they describe a list of one or more pointers to null-terminated 87strings that represent the argument list available to the executed program. 88The first argument, by convention, should point to the file name associated 89with the file being executed. 90The list of arguments 91.Em must 92be terminated by a 93.Dv NULL 94pointer. 95.Pp 96The 97.Fn exect , 98.Fn execv , 99and 100.Fn execvp 101functions provide an array of pointers to null-terminated strings that 102represent the argument list available to the new program. 103The first argument, by convention, should point to the file name associated 104with the file begin executed. 105The array of pointers 106.Sy must 107be terminated by a 108.Dv NULL 109pointer. 110.Pp 111The 112.Fn execle 113and 114.Fn exect 115functions also specify the environment of the executed process by following 116the 117.Dv NULL 118pointer that terminates the list of arguments in the parameter list 119or the pointer to the argv array with an additional parameter. 120This additional parameter is an array of pointers to null-terminated strings 121and 122.Em must 123be terminated by a 124.Dv NULL 125pointer. 126The other functions take the environment for the new process image from the 127external variable 128.Va environ 129in the current process. 130.Pp 131Some of these functions have special semantics. 132.Pp 133The functions 134.Fn execlp 135and 136.Fn execvp 137will duplicate the actions of the shell in searching for an executable file 138if the specified file name does not contain a slash 139.Dq Li / 140character. 141The search path is the path specified in the environment by 142.Dq Ev PATH 143variable. 144If this variable isn't specified, the default path 145.Dq Ev /bin:/usr/bin: 146is 147used. 148In addition, certain errors are treated specially. 149.Pp 150If permission is denied for a file (the attempted 151.Xr execve 152returned 153.Er EACCES ) , 154these functions will continue searching the rest of 155the search path. 156If no other file is found, however, they will return with the global variable 157.Va errno 158set to 159.Er EACCES . 160.Pp 161If the header of a file isn't recognized (the attempted 162.Xr execve 163returned 164.Er ENOEXEC ) , 165these functions will execute the shell with the path of 166the file as its first argument. 167(If this attempt fails, no further searching is done.) 168.Pp 169If the file is currently busy (the attempted 170.Xr execve 171returned 172.Er ETXTBUSY ) , 173these functions will sleep for several seconds, 174periodically re-attempting to execute the file. 175.Pp 176The function 177.Fn exect 178executes a file with the program tracing facilities enabled (see 179.Xr ptrace 2 ) . 180.Sh RETURN VALUES 181If any of the 182.Xr exec 183functions returns, an error will have occurred. 184The return value is \-1, and the global variable 185.Va errno 186will be set to indicate the error. 187.Sh FILES 188.Bl -tag -width /bin/sh - compact 189.It Pa /bin/sh 190The shell. 191.El 192.Sh ERRORS 193.Fn Execl , 194.Fn execle , 195.Fn execlp 196and 197.Fn execvp 198may fail and set 199.Va errno 200for any of the errors specified for the library functions 201.Xr execve 2 202and 203.Xr malloc 3 . 204.Pp 205.Fn Exect 206and 207.Fn execv 208may fail and set 209.Va errno 210for any of the errors specified for the library function 211.Xr execve 2 . 212.Sh SEE ALSO 213.Xr sh 1 , 214.Xr execve 2 , 215.Xr fork 2 , 216.Xr trace 2 , 217.Xr environ 7 , 218.Xr ptrace 2 , 219.Xr environ 7 , 220.Sh COMPATIBILITY 221Historically, the default path for the 222.Fn execlp 223and 224.Fn execvp 225functions was 226.Dq Pa :/bin:/usr/bin . 227This was changed to place the current directory last to enhance system 228security. 229.Pp 230The behavior of 231.Fn execlp 232and 233.Fn execvp 234when errors occur while attempting to execute the file is historic 235practice, but has not traditionally been documented and is not specified 236by the 237.Tn POSIX 238standard. 239.Pp 240Traditionally, the functions 241.Fn execlp 242and 243.Fn execvp 244ignored all errors except for the ones described above and 245.Er ENOMEM 246and 247.Er E2BIG , 248upon which they returned. 249They now return if any error other than the ones described above occurs. 250.Sh STANDARDS 251.Fn Execl , 252.Fn execv , 253.Fn execle , 254.Fn execlp 255and 256.Fn execvp 257conform to 258.St -p1003.1-88 . 259