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