1.\" $NetBSD: exec.3,v 1.16 2002/08/10 09:14:59 wiz 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 August 10, 2002 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.Fd #include \*[Lt]unistd.h\*[Gt] 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" ... "char *const envp[]" 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 parameter list 123or the pointer to the argv array with an additional parameter. 124This additional parameter 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 the 146.Ev PATH 147variable. 148If this variable isn't specified, 149.Va _PATH_DEFPATH 150from 151.Pa <paths.h> 152is used instead, its value being: 153.Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . 154In addition, certain errors are treated specially. 155.Pp 156If permission is denied for a file (the attempted 157.Xr execve 2 158returned 159.Er EACCES ) , 160these functions will continue searching the rest of 161the search path. 162If no other file is found, however, they will return with the global variable 163.Va errno 164set to 165.Er EACCES . 166.Pp 167If the header of a file isn't recognized (the attempted 168.Xr execve 2 169returned 170.Er ENOEXEC ) , 171these functions will execute the shell with the path of 172the file as its first argument. 173(If this attempt fails, no further searching is done.) 174.Pp 175If the file is currently busy (the attempted 176.Xr execve 2 177returned 178.Er ETXTBUSY ) , 179these functions will sleep for several seconds, 180periodically re-attempting to execute the file. 181.Pp 182The function 183.Fn exect 184executes a file with the program tracing facilities enabled (see 185.Xr ptrace 2 ) . 186.Sh RETURN VALUES 187If any of the 188.Nm exec 189functions returns, an error will have occurred. 190The return value is \-1, and the global variable 191.Va errno 192will be set to indicate the error. 193.Sh FILES 194.Bl -tag -width /bin/sh -compact 195.It Pa /bin/sh 196The shell. 197.El 198.Sh ERRORS 199.Fn execl , 200.Fn execle , 201.Fn execlp 202and 203.Fn execvp 204may fail and set 205.Va errno 206for any of the errors specified for the library functions 207.Xr execve 2 208and 209.Xr malloc 3 . 210.Pp 211.Fn exect 212and 213.Fn execv 214may fail and set 215.Va errno 216for any of the errors specified for the library function 217.Xr execve 2 . 218.Sh SEE ALSO 219.Xr sh 1 , 220.Xr execve 2 , 221.Xr fork 2 , 222.Xr ptrace 2 , 223.Xr environ 7 224.Sh COMPATIBILITY 225Historically, the default path for the 226.Fn execlp 227and 228.Fn execvp 229functions was 230.Dq Pa :/bin:/usr/bin . 231This was changed to improve security and behaviour. 232.Pp 233The behavior of 234.Fn execlp 235and 236.Fn execvp 237when errors occur while attempting to execute the file is historic 238practice, but has not traditionally been documented and is not specified 239by the 240.Tn POSIX 241standard. 242.Pp 243Traditionally, the functions 244.Fn execlp 245and 246.Fn execvp 247ignored all errors except for the ones described above and 248.Er ENOMEM 249and 250.Er E2BIG , 251upon which they returned. 252They now return if any error other than the ones described above occurs. 253.Sh STANDARDS 254.Fn execl , 255.Fn execv , 256.Fn execle , 257.Fn execlp 258and 259.Fn execvp 260conform to 261.St -p1003.1-90 . 262