1.\" Copyright (c) 1991 The Regents of the University of California. 2.\" 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.\" from: @(#)exec.3 6.4 (Berkeley) 4/19/91 33.\" $Id: exec.3,v 1.3 1993/11/29 21:40:55 jtc Exp $ 34.\" 35.Dd April 19, 1991 36.Dt EXEC 3 37.Os 38.Sh NAME 39.Nm execl , 40.Nm execlp , 41.Nm execle , 42.Nm exect , 43.Nm execv , 44.Nm execvp 45.Nd execute a file 46.Sh SYNOPSIS 47.Fd #include <unistd.h> 48.Vt extern char **environ; 49.Ft int 50.Fn execl "const char *path" "const char *arg" ... 51.Ft int 52.Fn execlp "const char *file" "const char *arg" ... 53.Ft int 54.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 55.Ft int 56.Fn exect "const char *path" "char *const argv[]" 57.Ft int 58.Fn execv "const char *path" "char *const argv[]" 59.Ft int 60.Fn execvp "const char *file" "char *const argv[]" 61.Sh DESCRIPTION 62The 63.Nm exec 64family of functions replaces the current process image with a 65new process image. 66The functions described in this manual page are front-ends for the function 67.Xr execve 2 . 68(See the manual page for 69.Xr execve 70for detailed information about the replacement of the current process.) 71.Pp 72The initial argument for these functions is the pathname of a file which 73is to be executed. 74.Pp 75The 76.Fa "const char *arg" 77and subsequent ellipses in the 78.Fn execl , 79.Fn execlp , 80and 81.Fn execle 82functions can be thought of as 83.Em arg0 , 84.Em arg1 , 85\&..., 86.Em argn . 87Together they describe a list of one or more pointers to null-terminated 88strings that represent the argument list available to the executed program. 89The first argument, by convention, should point to the file name associated 90with the file being executed. 91The list of arguments 92.Em must 93be terminated by a 94.Dv NULL 95pointer. 96.Pp 97The 98.Fn exect , 99.Fn execv , 100and 101.Fn execvp 102functions provide an array of pointers to null-terminated strings that 103represent the argument list available to the new program. 104The first argument, by convention, should point to the file name associated 105with the file begin executed. 106The array of pointers 107.Sy must 108be terminated by a 109.Dv NULL 110pointer. 111.Pp 112The 113.Fn execle 114and 115.Fn exect 116functions also specify the environment of the executed process by following 117the 118.Dv NULL 119pointer that terminates the list of arguments in the parameter list 120or the pointer to the argv array with an additional parameter. 121This additional parameter is an array of pointers to null-terminated strings 122and 123.Em must 124be terminated by a 125.Dv NULL 126pointer. 127The other functions take the environment for the new process image from the 128external variable 129.Va environ 130in the current process. 131.Pp 132Some of these functions have special semantics. 133.Pp 134The functions 135.Fn execlp 136and 137.Fn execvp 138will duplicate the actions of the shell in searching for an executable file 139if the specified file name does not contain a slash 140.Dq Li / 141character. 142The search path is the path specified in the environment by 143.Dq Ev PATH 144variable. 145If this variable isn't specified, the default path 146.Dq Ev /bin:/usr/bin: 147is 148used. 149In addtion, certain errors are treated specially. 150.Pp 151If permission is denied for a file (the attempted 152.Xr execve 153returned 154.Er EACCES ) , 155these functions will continue searching the rest of 156the search path. 157If no other file is found, however, they will return with the global variable 158.Va errno 159set to 160.Er EACCES . 161.Pp 162If the header of a file isn't recognized (the attempted 163.Xr execve 164returned 165.Er ENOEXEC ) , 166these functions will execute the shell with the path of 167the file as its first argument. 168(If this attempt fails, no further searching is done.) 169.Pp 170If the file is currently busy (the attempted 171.Xr execve 172returned 173.Er ETXTBUSY ) , 174these functions will sleep for several seconds, 175periodically re-attempting to execute the file. 176.Pp 177The function 178.Fn exect 179executes a file with the program tracing facilities enabled (see 180.Xr ptrace 2 ) . 181.Sh RETURN VALUES 182If any of the 183.Xr exec 184functions returns, an error will have occurred. 185The return value is \-1, and the global variable 186.Va errno 187will be set to indicate the error. 188.Sh FILES 189.Bl -tag -width /bin/sh -compact 190.It Pa /bin/sh 191The shell. 192.El 193.Sh ERRORS 194.Fn Execl , 195.Fn execle , 196.Fn execlp 197and 198.Fn execvp 199may fail and set 200.Va errno 201for any of the errors specified for the library functions 202.Xr execve 2 203and 204.Xr malloc 3 . 205.Pp 206.Fn Exect 207and 208.Fn execv 209may fail and set 210.Va errno 211for any of the errors specified for the library function 212.Xr execve 2 . 213.Sh SEE ALSO 214.Xr sh 1 , 215.Xr execve 2 , 216.Xr fork 2 , 217.Xr trace 2 , 218.Xr environ 7 , 219.Xr ptrace 2 , 220.Xr environ 7 , 221.Sh COMPATIBILITY 222Historically, the default path for the 223.Fn execlp 224and 225.Fn execvp 226functions was 227.Dq Pa :/bin:/usr/bin . 228This was changed to place the current directory last to enhance system 229security. 230.Pp 231The behavior of 232.Fn execlp 233and 234.Fn execvp 235when errors occur while attempting to execute the file is historic 236practice, but has not traditionally been documented and is not specified 237by the 238.Tn POSIX 239standard. 240.Pp 241Traditionally, the functions 242.Fn execlp 243and 244.Fn execvp 245ignored all errors except for the ones described above and 246.Er ENOMEM 247and 248.Er E2BIG , 249upon which they returned. 250They now return if any error other than the ones described above occurs. 251.Sh STANDARDS 252.Fn Execl , 253.Fn execv , 254.Fn execle , 255.Fn execlp 256and 257.Fn execvp 258conform to 259.St -p1003.1-88 . 260