1.\" $NetBSD: exec.3,v 1.8 1997/11/23 04:23:48 enami Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 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 SYNOPSIS 48.Fd #include <unistd.h> 49.Vt extern char **environ; 50.Ft int 51.Fn execl "const char *path" "const char *arg" ... 52.Ft int 53.Fn execlp "const char *file" "const char *arg" ... 54.Ft int 55.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 56.Ft int 57.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 58.Ft int 59.Fn execv "const char *path" "char *const argv[]" 60.Ft int 61.Fn execvp "const char *file" "char *const argv[]" 62.Sh DESCRIPTION 63The 64.Nm exec 65family of functions replaces the current process image with a 66new process image. 67The functions described in this manual page are front-ends for the function 68.Xr execve 2 . 69(See the manual page for 70.Xr execve 71for detailed information about the replacement of the current process.) 72.Pp 73The initial argument for these functions is the pathname of a file which 74is to be executed. 75.Pp 76The 77.Fa "const char *arg" 78and subsequent ellipses in the 79.Fn execl , 80.Fn execlp , 81and 82.Fn execle 83functions can be thought of as 84.Em arg0 , 85.Em arg1 , 86\&..., 87.Em argn . 88Together they describe a list of one or more pointers to null-terminated 89strings that represent the argument list available to the executed program. 90The first argument, by convention, should point to the file name associated 91with the file being executed. 92The list of arguments 93.Em must 94be terminated by a 95.Dv NULL 96pointer. 97.Pp 98The 99.Fn exect , 100.Fn execv , 101and 102.Fn execvp 103functions provide an array of pointers to null-terminated strings that 104represent the argument list available to the new program. 105The first argument, by convention, should point to the file name associated 106with the file begin executed. 107The array of pointers 108.Sy must 109be terminated by a 110.Dv NULL 111pointer. 112.Pp 113The 114.Fn execle 115and 116.Fn exect 117functions also specify the environment of the executed process by following 118the 119.Dv NULL 120pointer that terminates the list of arguments in the parameter list 121or the pointer to the argv array with an additional parameter. 122This additional parameter is an array of pointers to null-terminated strings 123and 124.Em must 125be terminated by a 126.Dv NULL 127pointer. 128The other functions take the environment for the new process image from the 129external variable 130.Va environ 131in the current process. 132.Pp 133Some of these functions have special semantics. 134.Pp 135The functions 136.Fn execlp 137and 138.Fn execvp 139will duplicate the actions of the shell in searching for an executable file 140if the specified file name does not contain a slash 141.Dq Li / 142character. 143The search path is the path specified in the environment by 144.Dq Ev PATH 145variable. 146If this variable isn't specified, the default path 147.Dq Ev /bin:/usr/bin: 148is 149used. 150In addition, certain errors are treated specially. 151.Pp 152If permission is denied for a file (the attempted 153.Xr execve 154returned 155.Er EACCES ) , 156these functions will continue searching the rest of 157the search path. 158If no other file is found, however, they will return with the global variable 159.Va errno 160set to 161.Er EACCES . 162.Pp 163If the header of a file isn't recognized (the attempted 164.Xr execve 165returned 166.Er ENOEXEC ) , 167these functions will execute the shell with the path of 168the file as its first argument. 169(If this attempt fails, no further searching is done.) 170.Pp 171If the file is currently busy (the attempted 172.Xr execve 173returned 174.Er ETXTBUSY ) , 175these functions will sleep for several seconds, 176periodically re-attempting to execute the file. 177.Pp 178The function 179.Fn exect 180executes a file with the program tracing facilities enabled (see 181.Xr ptrace 2 ) . 182.Sh RETURN VALUES 183If any of the 184.Xr exec 185functions returns, an error will have occurred. 186The return value is \-1, and the global variable 187.Va errno 188will be set to indicate the error. 189.Sh FILES 190.Bl -tag -width /bin/sh -compact 191.It Pa /bin/sh 192The shell. 193.El 194.Sh ERRORS 195.Fn execl , 196.Fn execle , 197.Fn execlp 198and 199.Fn execvp 200may fail and set 201.Va errno 202for any of the errors specified for the library functions 203.Xr execve 2 204and 205.Xr malloc 3 . 206.Pp 207.Fn exect 208and 209.Fn execv 210may fail and set 211.Va errno 212for any of the errors specified for the library function 213.Xr execve 2 . 214.Sh SEE ALSO 215.Xr sh 1 , 216.Xr execve 2 , 217.Xr fork 2 , 218.Xr ptrace 2 , 219.Xr environ 7 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 historic 235practice, but 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 ENOMEM 246and 247.Er E2BIG , 248upon which they returned. 249They now return if any error other than the ones described above occurs. 250.Sh STANDARDS 251.Fn execl , 252.Fn execv , 253.Fn execle , 254.Fn execlp 255and 256.Fn execvp 257conform to 258.St -p1003.1-90 . 259