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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 33.\" $FreeBSD: src/lib/libc/gen/exec.3,v 1.7.2.8 2003/03/15 15:11:05 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/gen/exec.3,v 1.5 2007/12/21 22:14:04 swildner Exp $ 35.\" 36.Dd December 21, 2007 37.Dt EXEC 3 38.Os 39.Sh NAME 40.Nm execl , 41.Nm execlp , 42.Nm execle , 43.Nm exect , 44.Nm execv , 45.Nm execvp 46.Nd execute a file 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In unistd.h 51.Vt extern char **environ ; 52.Ft int 53.Fn execl "const char *path" "const char *arg" ... 54.Ft int 55.Fn execlp "const char *file" "const char *arg" ... 56.Ft int 57.Fn execle "const char *path" "const char *arg" ... 58.Ft int 59.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 60.Ft int 61.Fn execv "const char *path" "char *const argv[]" 62.Ft int 63.Fn execvp "const char *file" "char *const argv[]" 64.Sh DESCRIPTION 65The 66.Nm exec 67family of functions replaces the current process image with a 68new process image. 69The functions described in this manual page are front-ends for the function 70.Xr execve 2 . 71(See the manual page for 72.Xr execve 2 73for detailed information about the replacement of the current process. 74The 75.Xr script 7 76manual page provides detailed information about the execution of 77interpreter scripts.) 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 , 107and 108.Fn execvp 109functions provide an array of pointers to null-terminated strings that 110represent the argument list available to the new program. 111The first argument, by convention, should point to the file name associated 112with the file being executed. 113The array of pointers 114.Sy must 115be terminated by a 116.Dv NULL 117pointer. 118.Pp 119The 120.Fn execle 121and 122.Fn exect 123functions also specify the environment of the executed process by following 124the 125.Dv NULL 126pointer that terminates the list of arguments in the argument list 127or the pointer to the argv array with an additional argument. 128This additional argument is an array of pointers to null-terminated strings 129and 130.Em must 131be terminated by a 132.Dv NULL 133pointer. 134The other functions take the environment for the new process image from the 135external variable 136.Va environ 137in the current process. 138.Pp 139Some of these functions have special semantics. 140.Pp 141The functions 142.Fn execlp 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. 149The search path is the path specified in the environment by 150.Dq Ev PATH 151variable. 152If this variable isn't specified, 153the default path is set according to the 154.Dv _PATH_DEFPATH 155definition in 156.In paths.h , 157which is set to 158.Dq Ev /usr/bin:/bin . 159In addition, certain errors are treated specially. 160.Pp 161If an error is ambiguous (for simplicity, we shall consider all 162errors except 163.Er ENOEXEC 164as being ambiguous here, although only the critical error 165.Er EACCES 166is really ambiguous), 167then these functions will act as if they stat the file to determine 168whether the file exists and has suitable execute permissions. 169If it does, they will return immediately with the global variable 170.Va errno 171restored to the value set by 172.Fn execve . 173Otherwise, the search will be continued. 174If the search completes without performing a successful 175.Fn execve 176or terminating due to an error, 177these functions will return with the global variable 178.Va errno 179set to 180.Er EACCES 181or 182.Er ENOENT 183according to whether at least one file with suitable execute permissions 184was found. 185.Pp 186If the header of a file isn't recognized (the attempted 187.Fn execve 188returned 189.Er ENOEXEC ) , 190these functions will execute the shell with the path of 191the file as its first argument. 192(If this attempt fails, no further searching is done.) 193.Pp 194The function 195.Fn exect 196executes a file with the program tracing facilities enabled (see 197.Xr ptrace 2 ) . 198.Sh RETURN VALUES 199If any of the 200.Fn exec 201functions returns, an error will have occurred. 202The return value is \-1, and the global variable 203.Va errno 204will be set to indicate the error. 205.Sh FILES 206.Bl -tag -width /bin/sh -compact 207.It Pa /bin/sh 208The shell. 209.El 210.Sh COMPATIBILITY 211Historically, the default path for the 212.Fn execlp 213and 214.Fn execvp 215functions was 216.Dq Pa :/bin:/usr/bin . 217This was changed to place the current directory last to enhance system 218security. 219.Pp 220The behavior of 221.Fn execlp 222and 223.Fn execvp 224when errors occur while attempting to execute the file is not quite historic 225practice, and has not traditionally been documented and is not specified 226by the 227.Tn POSIX 228standard. 229.Pp 230Traditionally, the functions 231.Fn execlp 232and 233.Fn execvp 234ignored all errors except for the ones described above and 235.Er ETXTBSY , 236upon which they retried after sleeping for several seconds, and 237.Er ENOMEM 238and 239.Er E2BIG , 240upon which they returned. 241They now return for 242.Er ETXTBSY , 243and determine existence and executability more carefully. 244In particular, 245.Er EACCES 246for inaccessible directories in the path prefix is no longer 247confused with 248.Er EACCES 249for files with unsuitable execute permissions. 250In 251.Bx 4.4 , 252they returned upon all errors except 253.Er EACCES , 254.Er ENOENT , 255.Er ENOEXEC 256and 257.Er ETXTBSY . 258This was inferior to the traditional error handling, 259since it breaks the ignoring of errors for path prefixes 260and only improves the handling of the unusual ambiguous error 261.Er EFAULT 262and the unusual error 263.Er EIO . 264The behaviour was changed to match the behaviour of 265.Xr sh 1 . 266.Sh ERRORS 267The 268.Fn execl , 269.Fn execle , 270.Fn execlp 271and 272.Fn execvp 273functions 274may fail and set 275.Va errno 276for any of the errors specified for the library functions 277.Xr execve 2 278and 279.Xr malloc 3 . 280.Pp 281The 282.Fn exect 283and 284.Fn execv 285functions 286may fail and set 287.Va errno 288for any of the errors specified for the library function 289.Xr execve 2 . 290.Sh SEE ALSO 291.Xr sh 1 , 292.Xr execve 2 , 293.Xr fork 2 , 294.Xr ktrace 2 , 295.Xr ptrace 2 , 296.Xr environ 7 , 297.Xr script 7 298.Sh STANDARDS 299The 300.Fn execl , 301.Fn execv , 302.Fn execle , 303.Fn execlp 304and 305.Fn execvp 306functions 307conform to 308.St -p1003.1-88 . 309