gen/exec.3

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  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 .\"     @(#)exec.3      8.3 (Berkeley) 1/24/94
  33 .\" $FreeBSD: src/lib/libc/gen/exec.3,v 1.23 2003/09/10 19:24:32 ru Exp $
  34 .\"
  35 .Dd January 24, 1994
  36 .Dt EXEC 3
  37 .Os
  38 .Sh NAME
  39 .Nm execl ,
  40 .Nm execle ,
  41 .Nm execlp ,
  42 .Nm execv ,
  43 .Nm execvp ,
  44 .Nm execvP
  45 .Nd execute a file
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In unistd.h
  50 .Vt extern char **environ ;
  51 .Ft int
  52 .Fo execl
  53 .Fa "const char *path"
  54 .Fa "const char *arg0"
  55 .Fa ... /* "(char *)0" */
  56 .Fc
  57 .Ft int
  58 .Fo execle
  59 .Fa "const char *path"
  60 .Fa "const char *arg0"
  61 .Fa ...
  62 .Fa /*
  63 .Bk -words
  64 .Fa "(char *)0" "char *const envp[]" */
  65 .Ek
  66 .Fc
  67 .Ft int
  68 .Fo execlp
  69 .Fa "const char *file"
  70 .Fa "const char *arg0"
  71 .Fa ... /* "(char *)0" */
  72 .Fc
  73 .Ft int
  74 .Fo execv
  75 .Fa "const char *path"
  76 .Fa "char *const argv[]"
  77 .Fc
  78 .Ft int
  79 .Fo execvp
  80 .Fa "const char *file"
  81 .Fa "char *const argv[]"
  82 .Fc
  83 .Ft int
  84 .Fo execvP
  85 .Fa "const char *file"
  86 .Fa "const char *search_path"
  87 .Fa "char *const argv[]"
  88 .Fc
  89 .Sh DESCRIPTION
  90 The
  91 .Nm exec
  92 family of functions replaces the current process image with a
  93 new process image.
  94 The functions described in this manual page are front-ends for the function
  95 .Xr execve 2 .
  96 (See the manual page for
  97 .Xr execve 2
  98 for detailed information about the replacement of the current process.)
  99 .Pp
 100 The initial argument for these functions is the pathname of a file which
 101 is to be executed.
 102 .Pp
 103 The
 104 .Fa "const char *arg0"
 105 and subsequent ellipses in the
 106 .Fn execl ,
 107 .Fn execlp ,
 108 and
 109 .Fn execle
 110 functions can be thought of as
 111 .Em arg0 ,
 112 .Em arg1 ,
 113 \&...,
 114 .Em argn .
 115 Together they describe a list of one or more pointers to null-terminated
 116 strings that represent the argument list available to the executed program.
 117 The first argument, by convention, should point to the file name associated
 118 with the file being executed.
 119 The list of arguments
 120 .Em must
 121 be terminated by a
 122 .Dv NULL
 123 pointer.
 124 .Pp
 125 The
 126 .Fn execv ,
 127 .Fn execvp ,
 128 and
 129 .Fn execvP
 130 functions provide an array of pointers to null-terminated strings that
 131 represent the argument list available to the new program.
 132 The first argument, by convention, should point to the file name associated
 133 with the file being executed.
 134 The array of pointers
 135 .Sy must
 136 be terminated by a
 137 .Dv NULL
 138 pointer.
 139 .Pp
 140 The
 141 .Fn execle
 142 function also specifies the environment of the executed process
 143 by following the
 144 .Dv NULL
 145 pointer that terminates the list of arguments in the argument list
 146 or the pointer to the argv array with an additional argument.
 147 This additional argument is an array of pointers to null-terminated strings
 148 and
 149 .Em must
 150 be terminated by a
 151 .Dv NULL
 152 pointer.
 153 The other functions take the environment for the new process image from the
 154 external variable
 155 .Va environ
 156 in the current process.
 157 .Pp
 158 Some of these functions have special semantics.
 159 .Pp
 160 The functions
 161 .Fn execlp ,
 162 .Fn execvp ,
 163 and
 164 .Fn execvP
 165 will duplicate the actions of the shell in searching for an executable file
 166 if the specified file name does not contain a slash
 167 .Dq Li /
 168 character.
 169 For
 170 .Fn execlp
 171 and
 172 .Fn execvp ,
 173 search path is the path specified in the environment by
 174 .Dq Ev PATH
 175 variable.
 176 If this variable isn't specified,
 177 the default path is set according to the
 178 .Dv _PATH_DEFPATH
 179 definition in
 180 .In paths.h ,
 181 which is set to
 182 .Dq Ev /usr/bin:/bin .
 183 For
 184 .Fn execvP ,
 185 the search path is specified as an argument to the function.
 186 In addition, certain errors are treated specially.
 187 .Pp
 188 If an error is ambiguous (for simplicity, we shall consider all
 189 errors except
 190 .Er ENOEXEC
 191 as being ambiguous here, although only the critical error
 192 .Er EACCES
 193 is really ambiguous),
 194 then these functions will act as if they stat the file to determine
 195 whether the file exists and has suitable execute permissions.
 196 If it does, they will return immediately with the global variable
 197 .Va errno
 198 restored to the value set by
 199 .Fn execve .
 200 Otherwise, the search will be continued.
 201 If the search completes without performing a successful
 202 .Fn execve
 203 or terminating due to an error,
 204 these functions will return with the global variable
 205 .Va errno
 206 set to
 207 .Er EACCES
 208 or
 209 .Er ENOENT
 210 according to whether at least one file with suitable execute permissions
 211 was found.
 212 .Pp
 213 If the header of a file isn't recognized (the attempted
 214 .Fn execve
 215 returned
 216 .Er ENOEXEC ) ,
 217 these functions will execute the shell with the path of
 218 the file as its first argument.
 219 (If this attempt fails, no further searching is done.)
 220 .Sh RETURN VALUES
 221 If any of the
 222 .Fn exec
 223 functions returns, an error will have occurred.
 224 The return value is \-1, and the global variable
 225 .Va errno
 226 will be set to indicate the error.
 227 .Sh FILES
 228 .Bl -tag -width /bin/sh -compact
 229 .It Pa /bin/sh
 230 The shell.
 231 .El
 232 .Sh ERRORS
 233 The
 234 .Fn execl ,
 235 .Fn execle ,
 236 .Fn execlp ,
 237 .Fn execvp ,
 238 and
 239 .Fn execvP
 240 functions
 241 may fail and set
 242 .Va errno
 243 for any of the errors specified for the library functions
 244 .Xr execve 2
 245 and
 246 .Xr malloc 3 .
 247 .Pp
 248 The
 249 .Fn execv
 250 function may fail and set
 251 .Va errno
 252 for any of the errors specified for the library function
 253 .Xr execve 2 .
 254 .Sh SEE ALSO
 255 .Xr sh 1 ,
 256 .Xr execve 2 ,
 257 .Xr fork 2 ,
 258 .Xr ptrace 2 ,
 259 .Xr environ 7
 260 .Sh COMPATIBILITY
 261 Historically, the default path for the
 262 .Fn execlp
 263 and
 264 .Fn execvp
 265 functions was
 266 .Dq Pa :/bin:/usr/bin .
 267 This was changed to place the current directory last to enhance system
 268 security.
 269 .Pp
 270 The behavior of
 271 .Fn execlp
 272 and
 273 .Fn execvp
 274 when errors occur while attempting to execute the file is not quite historic
 275 practice, and has not traditionally been documented and is not specified
 276 by the
 277 .Tn POSIX
 278 standard.
 279 .Pp
 280 Traditionally, the
 281 .Fn execlp
 282 and
 283 .Fn execvp
 284 functions ignored all errors except for the ones described above and
 285 .Er ETXTBSY ,
 286 upon which they retried after sleeping for several seconds, and
 287 .Er ENOMEM
 288 and
 289 .Er E2BIG ,
 290 upon which they returned.
 291 They now return for
 292 .Er ETXTBSY ,
 293 and determine existence and executability more carefully.
 294 In particular,
 295 .Er EACCES
 296 for inaccessible directories in the path prefix is no longer
 297 confused with
 298 .Er EACCES
 299 for files with unsuitable execute permissions.
 300 In
 301 .Bx 4.4 ,
 302 they returned upon all errors except
 303 .Er EACCES ,
 304 .Er ENOENT ,
 305 .Er ENOEXEC
 306 and
 307 .Er ETXTBSY .
 308 This was inferior to the traditional error handling,
 309 since it breaks the ignoring of errors for path prefixes
 310 and only improves the handling of the unusual ambiguous error
 311 .Er EFAULT
 312 and the unusual error
 313 .Er EIO .
 314 The behaviour was changed to match the behaviour of
 315 .Xr sh 1 .
 316 .Sh STANDARDS
 317 The
 318 .Fn execl ,
 319 .Fn execv ,
 320 .Fn execle ,
 321 .Fn execlp ,
 322 and
 323 .Fn execvp
 324 functions
 325 conform to
 326 .St -p1003.1-88 .
 327 The
 328 .Fn execvP
 329 function first appeared in
 330 .Fx 5.2 .