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.Dd December 11, 2023 29.Dt EXEC 3 30.Os 31.Sh NAME 32.Nm execl , 33.Nm execlp , 34.Nm execle , 35.Nm exect , 36.Nm execv , 37.Nm execvp , 38.Nm execvpe , 39.Nm execvP 40.Nd execute a file 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In unistd.h 45.Vt extern char **environ ; 46.Ft int 47.Fn execl "const char *path" "const char *arg" ... NULL 48.Ft int 49.Fn execlp "const char *file" "const char *arg" ... NULL 50.Ft int 51.Fn execle "const char *path" "const char *arg" ... NULL "char *const envp[]" 52.Fc 53.Ft int 54.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 55.Ft int 56.Fn execv "const char *path" "char *const argv[]" 57.Ft int 58.Fn execvp "const char *file" "char *const argv[]" 59.Ft int 60.Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" 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 , 103.Fn execvpe , 104and 105.Fn execvP 106functions provide an array of pointers to null-terminated strings that 107represent the argument list available to the new program. 108The first argument, by convention, should point to the file name associated 109with the file being executed. 110The array of pointers 111.Sy must 112be terminated by a 113.Dv NULL 114pointer. 115.Pp 116The 117.Fn execle , 118.Fn exect , 119and 120.Fn execvpe 121functions also specify the environment of the executed process by following 122the 123.Dv NULL 124pointer that terminates the list of arguments in the argument list 125or the pointer to the argv array with an additional argument. 126This additional argument is an array of pointers to null-terminated strings 127and 128.Em must 129be terminated by a 130.Dv NULL 131pointer. 132The other functions take the environment for the new process image from the 133external variable 134.Va environ 135in the current process. 136.Pp 137Some of these functions have special semantics. 138.Pp 139The functions 140.Fn execlp , 141.Fn execvp , 142.Fn execvpe , 143and 144.Fn execvP 145will duplicate the actions of the shell in searching for an executable file 146if the specified file name does not contain a slash 147.Dq Li / 148character. 149For 150.Fn execlp 151and 152.Fn execvp , 153.Fn execvpe , 154search path is the path specified in the environment by 155.Dq Ev PATH 156variable. 157If this variable is not specified, 158the default path is set according to the 159.Dv _PATH_DEFPATH 160definition in 161.In paths.h , 162which is set to 163.Dq Ev /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin . 164For 165.Fn execvP , 166the search path is specified as an argument to the function. 167In addition, certain errors are treated specially. 168.Pp 169If an error is ambiguous (for simplicity, we shall consider all 170errors except 171.Er ENOEXEC 172as being ambiguous here, although only the critical error 173.Er EACCES 174is really ambiguous), 175then these functions will act as if they stat the file to determine 176whether the file exists and has suitable execute permissions. 177If it does, they will return immediately with the global variable 178.Va errno 179restored to the value set by 180.Fn execve . 181Otherwise, the search will be continued. 182If the search completes without performing a successful 183.Fn execve 184or terminating due to an error, 185these functions will return with the global variable 186.Va errno 187set to 188.Er EACCES 189or 190.Er ENOENT 191according to whether at least one file with suitable execute permissions 192was found. 193.Pp 194If the header of a file is not recognized (the attempted 195.Fn execve 196returned 197.Er ENOEXEC ) , 198these functions will execute the shell with the path of 199the file as its first argument. 200(If this attempt fails, no further searching is done.) 201.Pp 202The function 203.Fn exect 204executes a file with the program tracing facilities enabled (see 205.Xr ptrace 2 ) . 206.Sh RETURN VALUES 207If any of the 208.Fn exec 209functions returns, an error will have occurred. 210The return value is \-1, and the global variable 211.Va errno 212will be set to indicate the error. 213.Sh FILES 214.Bl -tag -width /bin/sh -compact 215.It Pa /bin/sh 216The shell. 217.El 218.Sh COMPATIBILITY 219Historically, the default path for the 220.Fn execlp 221and 222.Fn execvp 223functions was 224.Dq Pa :/bin:/usr/bin . 225This was changed to remove the current directory to enhance system 226security. 227.Pp 228The behavior of 229.Fn execlp 230and 231.Fn execvp 232when errors occur while attempting to execute the file is not quite historic 233practice, and has not traditionally been documented and is not specified 234by the 235.Tn POSIX 236standard. 237.Pp 238Traditionally, the functions 239.Fn execlp 240and 241.Fn execvp 242ignored all errors except for the ones described above and 243.Er ETXTBSY , 244upon which they retried after sleeping for several seconds, and 245.Er ENOMEM 246and 247.Er E2BIG , 248upon which they returned. 249They now return for 250.Er ETXTBSY , 251and determine existence and executability more carefully. 252In particular, 253.Er EACCES 254for inaccessible directories in the path prefix is no longer 255confused with 256.Er EACCES 257for files with unsuitable execute permissions. 258In 259.Bx 4.4 , 260they returned upon all errors except 261.Er EACCES , 262.Er ENOENT , 263.Er ENOEXEC 264and 265.Er ETXTBSY . 266This was inferior to the traditional error handling, 267since it breaks the ignoring of errors for path prefixes 268and only improves the handling of the unusual ambiguous error 269.Er EFAULT 270and the unusual error 271.Er EIO . 272The behaviour was changed to match the behaviour of 273.Xr sh 1 . 274.Sh ERRORS 275The 276.Fn execl , 277.Fn execle , 278.Fn execlp , 279.Fn execvp , 280.Fn execvpe , 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 execvpe 320function is a GNU extension. 321.Sh HISTORY 322The 323.Fn exec 324function appeared in 325.At v1 . 326The 327.Fn execl 328and 329.Fn execv 330functions appeared in 331.At v2 . 332The 333.Fn execlp , 334.Fn execle , 335.Fn execve , 336and 337.Fn execvp 338functions appeared in 339.At v7 . 340The 341.Fn execvP 342function first appeared in 343.Fx 5.2 . 344The 345.Fn execvpe 346function first appeared in 347.Fx 15.0 . 348.Sh BUGS 349The type of the 350.Fa argv 351and 352.Fa envp 353parameters to 354.Fn execle , 355.Fn exect , 356.Fn execv , 357.Fn execvp , 358.Fn execvpe , 359and 360.Fn execvP 361is a historical accident and no sane implementation should modify the provided 362strings. 363The bogus parameter types trigger false positives from 364.Li const 365correctness analyzers. 366On 367.Fx , 368the 369.Fn __DECONST 370macro may be used to work around this limitation. 371.Pp 372Due to a fluke of the C standard, on platforms other than 373.Fx 374the definition of 375.Dv NULL 376may be the untyped number zero, rather than a 377.Ad (void *)0 378expression. 379To distinguish the concepts, they are referred to as a 380.Dq null pointer constant 381and a 382.Dq null pointer , 383respectively. 384On exotic computer architectures that 385.Fx 386does not support, the null pointer constant and null pointer may have a 387different representation. 388In general, where this document and others reference a 389.Dv NULL 390value, they actually imply a null pointer. 391E.g., for portability to non-FreeBSD operating systems on exotic computer 392architectures, one may use 393.Li (char *)NULL 394in place of 395.Dv NULL 396when invoking 397.Fn execl , 398.Fn execle , 399and 400.Fn execlp . 401