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.3 2006/02/17 19:35:06 swildner Exp $ 35.\" 36.Dd January 24, 1994 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.) 74.Pp 75The initial argument for these functions is the pathname of a file which 76is to be executed. 77.Pp 78The 79.Fa "const char *arg" 80and subsequent ellipses in the 81.Fn execl , 82.Fn execlp , 83and 84.Fn execle 85functions can be thought of as 86.Em arg0 , 87.Em arg1 , 88\&..., 89.Em argn . 90Together they describe a list of one or more pointers to null-terminated 91strings that represent the argument list available to the executed program. 92The first argument, by convention, should point to the file name associated 93with the file being executed. 94The list of arguments 95.Em must 96be terminated by a 97.Dv NULL 98pointer. 99.Pp 100The 101.Fn exect , 102.Fn execv , 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 139and 140.Fn execvp 141will duplicate the actions of the shell in searching for an executable file 142if the specified file name does not contain a slash 143.Dq Li / 144character. 145The search path is the path specified in the environment by 146.Dq Ev PATH 147variable. 148If this variable isn't specified, 149the default path is set according to the 150.Dv _PATH_DEFPATH 151definition in 152.Aq paths.h , 153which is set to 154.Dq Ev /usr/bin:/bin . 155In addition, certain errors are treated specially. 156.Pp 157If an error is ambiguous (for simplicity, we shall consider all 158errors except 159.Er ENOEXEC 160as being ambiguous here, although only the critical error 161.Er EACCES 162is really ambiguous), 163then these functions will act as if they stat the file to determine 164whether the file exists and has suitable execute permissions. 165If it does, they will return immediately with the global variable 166.Va errno 167restored to the value set by 168.Fn execve . 169Otherwise, the search will be continued. 170If the search completes without performing a successful 171.Fn execve 172or terminating due to an error, 173these functions will return with the global variable 174.Va errno 175set to 176.Er EACCES 177or 178.Er ENOENT 179according to whether at least one file with suitable execute permissions 180was found. 181.Pp 182If the header of a file isn't recognized (the attempted 183.Fn execve 184returned 185.Er ENOEXEC ) , 186these functions will execute the shell with the path of 187the file as its first argument. 188(If this attempt fails, no further searching is done.) 189.Pp 190The function 191.Fn exect 192executes a file with the program tracing facilities enabled (see 193.Xr ptrace 2 ) . 194.Sh RETURN VALUES 195If any of the 196.Fn exec 197functions returns, an error will have occurred. 198The return value is \-1, and the global variable 199.Va errno 200will be set to indicate the error. 201.Sh FILES 202.Bl -tag -width /bin/sh -compact 203.It Pa /bin/sh 204The shell. 205.El 206.Sh COMPATIBILITY 207Historically, the default path for the 208.Fn execlp 209and 210.Fn execvp 211functions was 212.Dq Pa :/bin:/usr/bin . 213This was changed to place the current directory last to enhance system 214security. 215.Pp 216The behavior of 217.Fn execlp 218and 219.Fn execvp 220when errors occur while attempting to execute the file is not quite historic 221practice, and has not traditionally been documented and is not specified 222by the 223.Tn POSIX 224standard. 225.Pp 226Traditionally, the functions 227.Fn execlp 228and 229.Fn execvp 230ignored all errors except for the ones described above and 231.Er ETXTBSY , 232upon which they retried after sleeping for several seconds, and 233.Er ENOMEM 234and 235.Er E2BIG , 236upon which they returned. 237They now return for 238.Er ETXTBSY , 239and determine existence and executability more carefully. 240In particular, 241.Er EACCES 242for inaccessible directories in the path prefix is no longer 243confused with 244.Er EACCES 245for files with unsuitable execute permissions. 246In 247.Bx 4.4 , 248they returned upon all errors except 249.Er EACCES , 250.Er ENOENT , 251.Er ENOEXEC 252and 253.Er ETXTBSY . 254This was inferior to the traditional error handling, 255since it breaks the ignoring of errors for path prefixes 256and only improves the handling of the unusual ambiguous error 257.Er EFAULT 258and the unusual error 259.Er EIO . 260The behaviour was changed to match the behaviour of 261.Xr sh 1 . 262.Sh ERRORS 263The 264.Fn execl , 265.Fn execle , 266.Fn execlp 267and 268.Fn execvp 269functions 270may fail and set 271.Va errno 272for any of the errors specified for the library functions 273.Xr execve 2 274and 275.Xr malloc 3 . 276.Pp 277The 278.Fn exect 279and 280.Fn execv 281functions 282may fail and set 283.Va errno 284for any of the errors specified for the library function 285.Xr execve 2 . 286.Sh SEE ALSO 287.Xr sh 1 , 288.Xr execve 2 , 289.Xr fork 2 , 290.Xr ktrace 2 , 291.Xr ptrace 2 , 292.Xr environ 7 293.Sh STANDARDS 294The 295.Fn execl , 296.Fn execv , 297.Fn execle , 298.Fn execlp 299and 300.Fn execvp 301functions 302conform to 303.St -p1003.1-88 . 304