1.\" $NetBSD: exec.3,v 1.18 2003/08/07 16:42:47 agc 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)exec.3 8.3 (Berkeley) 1/24/94 31.\" 32.Dd August 10, 2002 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.Nd execute a file 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In unistd.h 47.Vt extern char **environ; 48.Ft int 49.Fn execl "const char *path" "const char *arg" ... 50.Ft int 51.Fn execlp "const char *file" "const char *arg" ... 52.Ft int 53.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 54.Ft int 55.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 56.Ft int 57.Fn execv "const char *path" "char *const argv[]" 58.Ft int 59.Fn execvp "const char *file" "char *const argv[]" 60.Sh DESCRIPTION 61The 62.Nm exec 63family of functions replaces the current process image with a 64new process image. 65The functions described in this manual page are front-ends for the function 66.Xr execve 2 . 67(See the manual page for 68.Xr execve 2 69for detailed information about the replacement of the current process.) 70.Pp 71The initial argument for these functions is the pathname of a file which 72is to be executed. 73.Pp 74The 75.Fa "const char *arg" 76and subsequent ellipses in the 77.Fn execl , 78.Fn execlp , 79and 80.Fn execle 81functions can be thought of as 82.Em arg0 , 83.Em arg1 , 84\&..., 85.Em argn . 86Together they describe a list of one or more pointers to null-terminated 87strings that represent the argument list available to the executed program. 88The first argument, by convention, should point to the file name associated 89with the file being executed. 90The list of arguments 91.Em must 92be terminated by a 93.Dv NULL 94pointer. 95.Pp 96The 97.Fn exect , 98.Fn execv , 99and 100.Fn execvp 101functions provide an array of pointers to null-terminated strings that 102represent the argument list available to the new program. 103The first argument, by convention, should point to the file name associated 104with the file being executed. 105The array of pointers 106.Sy must 107be terminated by a 108.Dv NULL 109pointer. 110.Pp 111The 112.Fn execle 113and 114.Fn exect 115functions also specify the environment of the executed process by following 116the 117.Dv NULL 118pointer that terminates the list of arguments in the parameter list 119or the pointer to the argv array with an additional parameter. 120This additional parameter is an array of pointers to null-terminated strings 121and 122.Em must 123be terminated by a 124.Dv NULL 125pointer. 126The other functions take the environment for the new process image from the 127external variable 128.Va environ 129in the current process. 130.Pp 131Some of these functions have special semantics. 132.Pp 133The functions 134.Fn execlp 135and 136.Fn execvp 137will duplicate the actions of the shell in searching for an executable file 138if the specified file name does not contain a slash 139.Dq Li \&/ 140character. 141The search path is the path specified in the environment by the 142.Ev PATH 143variable. 144If this variable isn't specified, 145.Va _PATH_DEFPATH 146from 147.Pa <paths.h> 148is used instead, its value being: 149.Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . 150In addition, certain errors are treated specially. 151.Pp 152If permission is denied for a file (the attempted 153.Xr execve 2 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 2 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 2 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.Nm 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 improve security and behaviour. 228.Pp 229The behavior of 230.Fn execlp 231and 232.Fn execvp 233when errors occur while attempting to execute the file is historic 234practice, but has not traditionally been documented and is not specified 235by the 236.Tn POSIX 237standard. 238.Pp 239Traditionally, the functions 240.Fn execlp 241and 242.Fn execvp 243ignored all errors except for the ones described above and 244.Er ENOMEM 245and 246.Er E2BIG , 247upon which they returned. 248They now return if any error other than the ones described above occurs. 249.Sh STANDARDS 250.Fn execl , 251.Fn execv , 252.Fn execle , 253.Fn execlp 254and 255.Fn execvp 256conform to 257.St -p1003.1-90 . 258