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