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