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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 29.\" $FreeBSD$ 30.\" 31.Dd January 24, 1994 32.Dt EXEC 3 33.Os 34.Sh NAME 35.Nm execl , 36.Nm execlp , 37.Nm execle , 38.Nm exect , 39.Nm execv , 40.Nm execvp , 41.Nm execvpe , 42.Nm execvP 43.Nd execute a file 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In unistd.h 48.Vt extern char **environ ; 49.Ft int 50.Fn execl "const char *path" "const char *arg" ... /* "(char *)0" */ 51.Ft int 52.Fn execlp "const char *file" "const char *arg" ... /* "(char *)0" */ 53.Ft int 54.Fo execle 55.Fa "const char *path" "const char *arg" ... 56.Fa /* 57.Bk -words 58.Fa "(char *)0" "char *const envp[]" */ 59.Ek 60.Fc 61.Ft int 62.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 63.Ft int 64.Fn execv "const char *path" "char *const argv[]" 65.Ft int 66.Fn execvp "const char *file" "char *const argv[]" 67.Ft int 68.Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" 69.Ft int 70.Fn execvP "const char *file" "const char *search_path" "char *const argv[]" 71.Sh DESCRIPTION 72The 73.Nm exec 74family of functions replaces the current process image with a 75new process image. 76The functions described in this manual page are front-ends for the function 77.Xr execve 2 . 78(See the manual page for 79.Xr execve 2 80for detailed information about the replacement of the current process.) 81.Pp 82The initial argument for these functions is the pathname of a file which 83is to be executed. 84.Pp 85The 86.Fa "const char *arg" 87and subsequent ellipses in the 88.Fn execl , 89.Fn execlp , 90and 91.Fn execle 92functions can be thought of as 93.Em arg0 , 94.Em arg1 , 95\&..., 96.Em argn . 97Together they describe a list of one or more pointers to null-terminated 98strings that represent the argument list available to the executed program. 99The first argument, by convention, should point to the file name associated 100with the file being executed. 101The list of arguments 102.Em must 103be terminated by a 104.Dv NULL 105pointer. 106.Pp 107The 108.Fn exect , 109.Fn execv , 110.Fn execvp , 111and 112.Fn execvP 113functions provide an array of pointers to null-terminated strings that 114represent the argument list available to the new program. 115The first argument, by convention, should point to the file name associated 116with the file being executed. 117The array of pointers 118.Sy must 119be terminated by a 120.Dv NULL 121pointer. 122.Pp 123The 124.Fn execle , 125.Fn exect 126and 127.Fn execvpe 128functions also specify the environment of the executed process by following 129the 130.Dv NULL 131pointer that terminates the list of arguments in the argument list 132or the pointer to the argv array with an additional argument. 133This additional argument is an array of pointers to null-terminated strings 134and 135.Em must 136be terminated by a 137.Dv NULL 138pointer. 139The other functions take the environment for the new process image from the 140external variable 141.Va environ 142in the current process. 143.Pp 144Some of these functions have special semantics. 145.Pp 146The functions 147.Fn execlp , 148.Fn execvp , 149.Fn execvpe , 150and 151.Fn execvP 152will duplicate the actions of the shell in searching for an executable file 153if the specified file name does not contain a slash 154.Dq Li / 155character. 156For 157.Fn execlp 158and 159.Fn execvp , 160.Fn execvpe , 161search path is the path specified in the environment by 162.Dq Ev PATH 163variable. 164If this variable is not specified, 165the default path is set according to the 166.Dv _PATH_DEFPATH 167definition in 168.In paths.h , 169which is set to 170.Dq Ev /usr/bin:/bin . 171For 172.Fn execvP , 173the search path is specified as an argument to the function. 174In addition, certain errors are treated specially. 175.Pp 176If an error is ambiguous (for simplicity, we shall consider all 177errors except 178.Er ENOEXEC 179as being ambiguous here, although only the critical error 180.Er EACCES 181is really ambiguous), 182then these functions will act as if they stat the file to determine 183whether the file exists and has suitable execute permissions. 184If it does, they will return immediately with the global variable 185.Va errno 186restored to the value set by 187.Fn execve . 188Otherwise, the search will be continued. 189If the search completes without performing a successful 190.Fn execve 191or terminating due to an error, 192these functions will return with the global variable 193.Va errno 194set to 195.Er EACCES 196or 197.Er ENOENT 198according to whether at least one file with suitable execute permissions 199was found. 200.Pp 201If the header of a file is not recognized (the attempted 202.Fn execve 203returned 204.Er ENOEXEC ) , 205these functions will execute the shell with the path of 206the file as its first argument. 207(If this attempt fails, no further searching is done.) 208.Pp 209The function 210.Fn exect 211executes a file with the program tracing facilities enabled (see 212.Xr ptrace 2 ) . 213.Sh RETURN VALUES 214If any of the 215.Fn exec 216functions returns, an error will have occurred. 217The return value is \-1, and the global variable 218.Va errno 219will be set to indicate the error. 220.Sh FILES 221.Bl -tag -width /bin/sh -compact 222.It Pa /bin/sh 223The shell. 224.El 225.Sh COMPATIBILITY 226Historically, the default path for the 227.Fn execlp 228and 229.Fn execvp 230functions was 231.Dq Pa :/bin:/usr/bin . 232This was changed to place the current directory last to enhance system 233security. 234.Pp 235The behavior of 236.Fn execlp 237and 238.Fn execvp 239when errors occur while attempting to execute the file is not quite historic 240practice, and has not traditionally been documented and is not specified 241by the 242.Tn POSIX 243standard. 244.Pp 245Traditionally, the functions 246.Fn execlp 247and 248.Fn execvp 249ignored all errors except for the ones described above and 250.Er ETXTBSY , 251upon which they retried after sleeping for several seconds, and 252.Er ENOMEM 253and 254.Er E2BIG , 255upon which they returned. 256They now return for 257.Er ETXTBSY , 258and determine existence and executability more carefully. 259In particular, 260.Er EACCES 261for inaccessible directories in the path prefix is no longer 262confused with 263.Er EACCES 264for files with unsuitable execute permissions. 265In 266.Bx 4.4 , 267they returned upon all errors except 268.Er EACCES , 269.Er ENOENT , 270.Er ENOEXEC 271and 272.Er ETXTBSY . 273This was inferior to the traditional error handling, 274since it breaks the ignoring of errors for path prefixes 275and only improves the handling of the unusual ambiguous error 276.Er EFAULT 277and the unusual error 278.Er EIO . 279The behaviour was changed to match the behaviour of 280.Xr sh 1 . 281.Sh ERRORS 282The 283.Fn execl , 284.Fn execle , 285.Fn execlp , 286.Fn execvp , 287.Fn execvpe 288and 289.Fn execvP 290functions 291may fail and set 292.Va errno 293for any of the errors specified for the library functions 294.Xr execve 2 295and 296.Xr malloc 3 . 297.Pp 298The 299.Fn exect 300and 301.Fn execv 302functions 303may fail and set 304.Va errno 305for any of the errors specified for the library function 306.Xr execve 2 . 307.Sh SEE ALSO 308.Xr sh 1 , 309.Xr execve 2 , 310.Xr fork 2 , 311.Xr ktrace 2 , 312.Xr ptrace 2 , 313.Xr environ 7 314.Sh STANDARDS 315The 316.Fn execl , 317.Fn execv , 318.Fn execle , 319.Fn execlp 320and 321.Fn execvp 322functions 323conform to 324.St -p1003.1-88 . 325The 326.Fn execvP 327function first appeared in 328.Fx 5.2 . 329The 330.Fn execvpe 331function first appeared in 332.Fx 8.0 . 333