1.\" $OpenBSD: execv.3,v 1.2 2023/05/13 16:36:40 kn 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 $Mdocdate: May 13 2023 $ 31.Dt EXECV 3 32.Os 33.Sh NAME 34.Nm execl , 35.Nm execlp , 36.Nm execle , 37.Nm execv , 38.Nm execvp , 39.Nm execvpe 40.Nd execute a file 41.Sh SYNOPSIS 42.In unistd.h 43.Vt extern char **environ; 44.Ft int 45.Fn execl "const char *path" "const char *arg" ... 46.Ft int 47.Fn execlp "const char *file" "const char *arg" ... 48.Ft int 49.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 50.Ft int 51.Fn execv "const char *path" "char *const argv[]" 52.Ft int 53.Fn execvp "const char *file" "char *const argv[]" 54.Ft int 55.Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" 56.Sh DESCRIPTION 57This family of functions replace the current process image with a 58new process image. 59The functions described in this manual page are front-ends for the 60.Xr execve 2 61system call; see that manual page for detailed information 62about 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 , 90.Fn execvp 91and 92.Fn execvpe 93functions provide an array of pointers to 94NUL-terminated strings that 95represent the argument list available to the new program. 96The first argument, by convention, should point to the file name associated 97with the file being executed. 98The array of pointers 99.Em must 100be terminated by a null pointer itself. 101.Pp 102The 103.Fn execle 104and 105.Fn execvpe 106functions also specify the environment of the executed process by following 107the null 108pointer that terminates the list of arguments in the parameter list 109or the pointer to the 110.Va argv 111array with an additional parameter. 112This additional parameter is an array of pointers to NUL-terminated 113strings and 114.Em must 115be terminated by a null pointer itself. 116The other functions take the environment for the new process image from the 117external variable 118.Va environ 119in the current process. 120.Pp 121Some of these functions have special semantics. 122.Pp 123The functions 124.Fn execlp , 125.Fn execvp 126and 127.Fn execvpe 128will duplicate the actions of the shell in searching for an executable file 129if the specified file name does not contain a slash 130.Pq Sq \&/ 131character. 132The search path is the path specified in the environment by 133.Ev PATH 134variable. 135If this variable isn't specified, 136.Dv _PATH_DEFPATH 137from 138.In paths.h 139is used instead, consisting of 140.Pa /usr/bin , 141.Pa /bin , 142.Pa /usr/sbin , 143.Pa /sbin , 144.Pa /usr/X11R6/bin , 145.Pa /usr/local/bin , 146.Pa /usr/local/sbin . 147.Pp 148In addition, certain errors are treated specially. 149.Pp 150If permission is denied for a file (the attempted 151.Xr execve 2 152returned 153.Er EACCES ) , 154these functions will continue searching the rest of 155the search path. 156If no other file is found, however, they will return with the global variable 157.Va errno 158set to 159.Er EACCES . 160.Pp 161If the header of a file isn't recognized (the attempted 162.Xr execve 2 163returned 164.Er ENOEXEC ) , 165these functions will execute the shell with the path of 166the file as its first argument. 167(If this attempt fails, no further searching is done.) 168.Sh RETURN VALUES 169If any of these functions return, an error has occurred. 170The return value is \-1, and the global variable 171.Va errno 172will be set to indicate the error. 173.Sh FILES 174.Bl -tag -width /bin/sh -compact 175.It Pa /bin/sh 176default shell program 177.El 178.Sh ERRORS 179.Fn execl , 180.Fn execle , 181.Fn execlp , 182.Fn execvp , 183and 184.Fn execvpe 185may fail and set 186.Va errno 187for any of the errors specified for the library functions 188.Xr execve 2 189and 190.Xr malloc 3 . 191.Pp 192.Fn execv 193may fail and set 194.Va errno 195for any of the errors specified for the library function 196.Xr execve 2 . 197.Sh SEE ALSO 198.Xr sh 1 , 199.Xr execve 2 , 200.Xr fork 2 , 201.Xr ktrace 2 , 202.Xr ptrace 2 , 203.Xr environ 7 204.Sh STANDARDS 205Historically, the default path for the 206.Fn execlp 207and 208.Fn execvp 209functions was 210.Pa \&. , 211.Pa /bin , 212.Pa /usr/bin . 213This was changed to improve security and behaviour. 214.Pp 215The behavior of 216.Fn execlp 217and 218.Fn execvp 219when errors occur while attempting to execute the file is historic 220practice, but has not traditionally been documented and is not specified 221by the 222.Tn POSIX 223standard. 224.Pp 225Traditionally, the functions 226.Fn execlp 227and 228.Fn execvp 229ignored all errors except for the ones described above and 230.Er ENOMEM 231and 232.Er E2BIG , 233upon which they returned. 234They now return if any error other than the ones described above occurs. 235.Pp 236.Fn execl , 237.Fn execv , 238.Fn execle , 239.Fn execlp 240and 241.Fn execvp 242conform to 243.St -p1003.1-88 . 244.Fn execvpe 245is a GNU extension. 246.Sh HISTORY 247The functions 248.Fn execl 249and 250.Fn execv 251first appeared in 252.At v2 . 253A predecessor to 254.Fn execvp , 255.Fn pexec , 256first appeared in the Programmer's Workbench (PWB/UNIX). 257The functions 258.Fn execle , 259.Fn execlp , 260.Fn execve , 261and 262.Fn execvp 263first appeared in 264.At v7 . 265