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