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