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.\" $FreeBSD$ 34.\" 35.Dd January 24, 1994 36.Dt EXEC 3 37.Os 38.Sh NAME 39.Nm execl , 40.Nm execlp , 41.Nm execle , 42.Nm exect , 43.Nm execv , 44.Nm execvp , 45.Nm execvP 46.Nd execute a file 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In unistd.h 51.Vt extern char **environ ; 52.Ft int 53.Fn execl "const char *path" "const char *arg" ... /* "(char *)0" */ 54.Ft int 55.Fn execlp "const char *file" "const char *arg" ... /* "(char *)0" */ 56.Ft int 57.Fo execle 58.Fa "const char *path" "const char *arg" ... 59.Fa /* 60.Bk -words 61.Fa "(char *)0" "char *const envp[]" */ 62.Ek 63.Fc 64.Ft int 65.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 66.Ft int 67.Fn execv "const char *path" "char *const argv[]" 68.Ft int 69.Fn execvp "const char *file" "char *const argv[]" 70.Ft int 71.Fn execvP "const char *file" "const char *search_path" "char *const argv[]" 72.Sh DESCRIPTION 73The 74.Nm exec 75family of functions replaces the current process image with a 76new process image. 77The functions described in this manual page are front-ends for the function 78.Xr execve 2 . 79(See the manual page for 80.Xr execve 2 81for detailed information about the replacement of the current process.) 82.Pp 83The initial argument for these functions is the pathname of a file which 84is to be executed. 85.Pp 86The 87.Fa "const char *arg" 88and subsequent ellipses in the 89.Fn execl , 90.Fn execlp , 91and 92.Fn execle 93functions can be thought of as 94.Em arg0 , 95.Em arg1 , 96\&..., 97.Em argn . 98Together they describe a list of one or more pointers to null-terminated 99strings that represent the argument list available to the executed program. 100The first argument, by convention, should point to the file name associated 101with the file being executed. 102The list of arguments 103.Em must 104be terminated by a 105.Dv NULL 106pointer. 107.Pp 108The 109.Fn exect , 110.Fn execv , 111.Fn execvp , 112and 113.Fn execvP 114functions provide an array of pointers to null-terminated strings that 115represent the argument list available to the new program. 116The first argument, by convention, should point to the file name associated 117with the file being executed. 118The array of pointers 119.Sy must 120be terminated by a 121.Dv NULL 122pointer. 123.Pp 124The 125.Fn execle 126and 127.Fn exect 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 , 149and 150.Fn execvP 151will duplicate the actions of the shell in searching for an executable file 152if the specified file name does not contain a slash 153.Dq Li / 154character. 155For 156.Fn execlp 157and 158.Fn execvp , 159search path is the path specified in the environment by 160.Dq Ev PATH 161variable. 162If this variable is not specified, 163the default path is set according to the 164.Dv _PATH_DEFPATH 165definition in 166.In paths.h , 167which is set to 168.Dq Ev /usr/bin:/bin . 169For 170.Fn execvP , 171the search path is specified as an argument to the function. 172In addition, certain errors are treated specially. 173.Pp 174If an error is ambiguous (for simplicity, we shall consider all 175errors except 176.Er ENOEXEC 177as being ambiguous here, although only the critical error 178.Er EACCES 179is really ambiguous), 180then these functions will act as if they stat the file to determine 181whether the file exists and has suitable execute permissions. 182If it does, they will return immediately with the global variable 183.Va errno 184restored to the value set by 185.Fn execve . 186Otherwise, the search will be continued. 187If the search completes without performing a successful 188.Fn execve 189or terminating due to an error, 190these functions will return with the global variable 191.Va errno 192set to 193.Er EACCES 194or 195.Er ENOENT 196according to whether at least one file with suitable execute permissions 197was found. 198.Pp 199If the header of a file is not recognized (the attempted 200.Fn execve 201returned 202.Er ENOEXEC ) , 203these functions will execute the shell with the path of 204the file as its first argument. 205(If this attempt fails, no further searching is done.) 206.Pp 207The function 208.Fn exect 209executes a file with the program tracing facilities enabled (see 210.Xr ptrace 2 ) . 211.Sh RETURN VALUES 212If any of the 213.Fn exec 214functions returns, an error will have occurred. 215The return value is \-1, and the global variable 216.Va errno 217will be set to indicate the error. 218.Sh FILES 219.Bl -tag -width /bin/sh -compact 220.It Pa /bin/sh 221The shell. 222.El 223.Sh COMPATIBILITY 224Historically, the default path for the 225.Fn execlp 226and 227.Fn execvp 228functions was 229.Dq Pa :/bin:/usr/bin . 230This was changed to place the current directory last to enhance system 231security. 232.Pp 233The behavior of 234.Fn execlp 235and 236.Fn execvp 237when errors occur while attempting to execute the file is not quite historic 238practice, and has not traditionally been documented and is not specified 239by the 240.Tn POSIX 241standard. 242.Pp 243Traditionally, the functions 244.Fn execlp 245and 246.Fn execvp 247ignored all errors except for the ones described above and 248.Er ETXTBSY , 249upon which they retried after sleeping for several seconds, and 250.Er ENOMEM 251and 252.Er E2BIG , 253upon which they returned. 254They now return for 255.Er ETXTBSY , 256and determine existence and executability more carefully. 257In particular, 258.Er EACCES 259for inaccessible directories in the path prefix is no longer 260confused with 261.Er EACCES 262for files with unsuitable execute permissions. 263In 264.Bx 4.4 , 265they returned upon all errors except 266.Er EACCES , 267.Er ENOENT , 268.Er ENOEXEC 269and 270.Er ETXTBSY . 271This was inferior to the traditional error handling, 272since it breaks the ignoring of errors for path prefixes 273and only improves the handling of the unusual ambiguous error 274.Er EFAULT 275and the unusual error 276.Er EIO . 277The behaviour was changed to match the behaviour of 278.Xr sh 1 . 279.Sh ERRORS 280The 281.Fn execl , 282.Fn execle , 283.Fn execlp , 284.Fn execvp 285and 286.Fn execvP 287functions 288may fail and set 289.Va errno 290for any of the errors specified for the library functions 291.Xr execve 2 292and 293.Xr malloc 3 . 294.Pp 295The 296.Fn exect 297and 298.Fn execv 299functions 300may fail and set 301.Va errno 302for any of the errors specified for the library function 303.Xr execve 2 . 304.Sh SEE ALSO 305.Xr sh 1 , 306.Xr execve 2 , 307.Xr fork 2 , 308.Xr ktrace 2 , 309.Xr ptrace 2 , 310.Xr environ 7 311.Sh STANDARDS 312The 313.Fn execl , 314.Fn execv , 315.Fn execle , 316.Fn execlp 317and 318.Fn execvp 319functions 320conform to 321.St -p1003.1-88 . 322The 323.Fn execvP 324function first appeared in 325.Fx 5.2 . 326