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