1 .\" $NetBSD: exec.3,v 1.22 2012/11/22 16:19:49 abs Exp $
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
30 .\" @(#)exec.3 8.3 (Berkeley) 1/24/94
47 .Vt extern char **environ;
49 .Fn execl "const char *path" "const char *arg" ...
51 .Fn execlp "const char *file" "const char *arg" ...
53 .Fn execle "const char *path" "const char *arg" ... "char *const envp[]"
55 .Fn exect "const char *path" "char *const argv[]" "char *const envp[]"
57 .Fn execv "const char *path" "char *const argv[]"
59 .Fn execvp "const char *file" "char *const argv[]"
63 family of functions replaces the current process image with a
65 The functions described in this manual page are front-ends for the function
67 (See the manual page for
69 for detailed information about the replacement of the current process.
72 manual page provides detailed information about the execution of
75 The initial argument for these functions is the pathname of a file which
80 and subsequent ellipses in the
85 functions can be thought of as
90 Together they describe a list of one or more pointers to null-terminated
91 strings that represent the argument list available to the executed program.
92 The first argument, by convention, should point to the file name associated
93 with the file being executed.
105 functions provide an array of pointers to null-terminated strings that
106 represent the argument list available to the new program.
107 The first argument, by convention, should point to the file name associated
108 with the file being executed.
109 The array of pointers
119 functions also specify the environment of the executed process by following
122 pointer that terminates the list of arguments in the parameter list
123 or the pointer to the argv array with an additional parameter.
124 This additional parameter is an array of pointers to null-terminated strings
130 The other functions take the environment for the new process image from the
133 in the current process.
135 Some of these functions have special semantics.
141 will duplicate the actions of the shell in searching for an executable file
142 if the specified file name does not contain a slash
145 The search path is the path specified in the environment by the
148 If this variable isn't specified,
152 is used instead, its value being:
153 .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin .
154 In addition, certain errors are treated specially.
156 If permission is denied for a file (the attempted
160 these functions will continue searching the rest of
162 If no other file is found, however, they will return with the global variable
167 If the header of a file isn't recognized (the attempted
171 these functions will execute the shell with the path of
172 the file as its first argument.
173 (If this attempt fails, no further searching is done.)
175 If the file is currently busy (the attempted
179 these functions will sleep for several seconds,
180 periodically re-attempting to execute the file.
184 executes a file with the program tracing facilities enabled (see
189 functions returns, an error will have occurred.
190 The return value is \-1, and the global variable
192 will be set to indicate the error.
194 .Bl -tag -width /bin/sh -compact
199 Historically, the default path for the
204 .Dq Pa :/bin:/usr/bin .
205 This was changed to improve security and behaviour.
211 when errors occur while attempting to execute the file is historic
212 practice, but has not traditionally been documented and is not specified
217 Traditionally, the functions
221 ignored all errors except for the ones described above and
225 upon which they returned.
226 They now return if any error other than the ones described above occurs.
235 for any of the errors specified for the library functions
245 for any of the errors specified for the library function