1.\" $NetBSD: exec.3,v 1.26 2014/09/27 16:42:07 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. 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 26, 2014 33.Dt EXEC 3 34.Os 35.Sh NAME 36.Nm execl , 37.Nm execlp , 38.Nm execle , 39.Nm exect , 40.Nm execv , 41.Nm execvp 42.Nd execute a file 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In unistd.h 47.Vt extern char **environ; 48.Ft int 49.Fn execl "const char *path" "const char *arg" ... 50.Ft int 51.Fn execlp "const char *file" "const char *arg" ... 52.Ft int 53.Fn execlpe "const char *path" "const char *arg" ... "char *const envp[]" 54.Ft int 55.Fn execle "const char *path" "const char *arg" ... "char *const envp[]" 56.Ft int 57.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" 58.Ft int 59.Fn execv "const char *path" "char *const argv[]" 60.Ft int 61.Fn execvp "const char *file" "char *const argv[]" 62.Ft int 63.Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" 64.Sh DESCRIPTION 65The 66.Fn 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. 74The 75.Xr script 7 76manual page provides detailed information about the execution of 77interpreter scripts.) 78.Pp 79The initial argument for these functions is the pathname of a file which 80is to be executed. 81.Pp 82The 83.Fa "const char *arg" 84and subsequent ellipses in the 85.Fn execl , 86.Fn execlp , 87.Fn execlpe , 88and 89.Fn execle 90functions can be thought of as 91.Em arg0 , 92.Em arg1 , 93\&..., 94.Em argn . 95Together they describe a list of one or more pointers to NUL-terminated 96strings that represent the argument list available to the executed program. 97The first argument, by convention, should point to the file name associated 98with the file being executed. 99The list of arguments 100.Em must 101be terminated by a 102.Dv NULL 103pointer. 104.Pp 105The 106.Fn exect , 107.Fn execv , 108.Fn execvp , 109and 110.Fn execvpe 111functions provide an array of pointers to NUL-terminated strings that 112represent the argument list available to the new program. 113The first argument, by convention, should point to the file name associated 114with the file being executed. 115The array of pointers 116.Sy must 117be terminated by a 118.Dv NULL 119pointer. 120.Pp 121The 122.Fn execle , 123.Fn execlpe , 124.Fn exect , 125and 126.Fn execvpe 127functions also specify the environment of the executed process by following 128the 129.Dv NULL 130pointer that terminates the list of arguments in the parameter list 131or the pointer to the argv array with an additional parameter. 132This additional parameter is an array of pointers to NUL-terminated strings 133and 134.Em must 135be terminated by a 136.Dv NULL 137pointer. 138The other functions take the environment for the new process image from the 139external variable 140.Va environ 141in the current process. 142.Pp 143Some of these functions have special semantics. 144.Pp 145The functions 146.Fn execlp , 147.Fn execlpe , 148.Fn execvp , 149and 150.Fn execvpe 151will duplicate the actions of the shell in searching for an executable file 152if the specified file name does not contain a slash 153.Dq Li \&/ 154character. 155The search path is the path specified in the environment by the 156.Ev PATH 157variable. 158If this variable isn't specified, 159.Va _PATH_DEFPATH 160from 161.In paths.h 162is used instead, its value being: 163.Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . 164In addition, certain errors are treated specially. 165.Pp 166If permission is denied for a file (the attempted 167.Xr execve 2 168returned 169.Er EACCES ) , 170these functions will continue searching the rest of 171the search path. 172If no other file is found, however, they will return with the global variable 173.Va errno 174set to 175.Er EACCES . 176.Pp 177If the header of a file isn't recognized (the attempted 178.Xr execve 2 179returned 180.Er ENOEXEC ) , 181these functions will execute the shell with the path of 182the file as its first argument. 183(If this attempt fails, no further searching is done.) 184.Pp 185If the file is currently busy (the attempted 186.Xr execve 2 187returned 188.Er ETXTBUSY ) , 189these functions will sleep for several seconds, 190periodically re-attempting to execute the file. 191.Pp 192The function 193.Fn exect 194executes a file with the program tracing facilities enabled (see 195.Xr ptrace 2 ) . 196.Sh RETURN VALUES 197If any of the 198.Fn exec 199functions returns, an error will have occurred. 200The return value is \-1, and the global variable 201.Va errno 202will be set to indicate the error. 203.Sh FILES 204.Bl -tag -width /bin/sh -compact 205.It Pa /bin/sh 206The shell. 207.El 208.Sh COMPATIBILITY 209Historically, the default path for the 210.Fn execlp 211.Fn execlpe , 212.Fn execvp , 213and 214.Fn execvpe 215functions was 216.Dq Pa :/bin:/usr/bin . 217This was changed to improve security and behaviour. 218.Pp 219The behavior of 220.Fn execlp , 221.Fn execlpe , 222.Fn execvp , 223and 224.Fn execvpe 225when errors occur while attempting to execute the file is historic 226practice, but has not traditionally been documented and is not specified 227by the 228.Tn POSIX 229standard. 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.Pp 282The 283.Fn execlpe 284function appeared first in QNX and the 285.Fn execvpe 286function exists on both 287.Lx 288and QNX. 289