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