| blob | 75a8c4cf4462e0c91152e881989a4c5c5346e1be |
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
65 The
66 .Fn exec
67 family of functions replaces the current process image with a
68 new process image.
69 The 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
73 for detailed information about the replacement of the current process.
74 The
75 .Xr script 7
76 manual page provides detailed information about the execution of
77 interpreter scripts.)
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 .Fn execlpe ,
88 and
89 .Fn execle
90 functions can be thought of as
91 .Em arg0 ,
92 .Em arg1 ,
93 \&...,
94 .Em argn .
95 Together they describe a list of one or more pointers to NUL-terminated
96 strings that represent the argument list available to the executed program.
97 The first argument, by convention, should point to the file name associated
98 with the file being executed.
99 The list of arguments
100 .Em must
101 be terminated by a
102 .Dv NULL
103 pointer.
104 .Pp
105 The
106 .Fn exect ,
107 .Fn execv ,
108 .Fn execvp ,
109 and
110 .Fn execvpe
111 functions provide an array of pointers to NUL-terminated strings that
112 represent the argument list available to the new program.
113 The first argument, by convention, should point to the file name associated
114 with the file being executed.
115 The array of pointers
116 .Sy must
117 be terminated by a
118 .Dv NULL
119 pointer.
120 .Pp
121 The
122 .Fn execle ,
123 .Fn execlpe ,
124 .Fn exect ,
125 and
126 .Fn execvpe
127 functions also specify the environment of the executed process by following
128 the
129 .Dv NULL
130 pointer that terminates the list of arguments in the parameter list
131 or the pointer to the argv array with an additional parameter.
132 This additional parameter is an array of pointers to NUL-terminated strings
133 and
134 .Em must
135 be terminated by a
136 .Dv NULL
137 pointer.
138 The other functions take the environment for the new process image from the
139 external variable
140 .Va environ
141 in the current process.
142 .Pp
143 Some of these functions have special semantics.
144 .Pp
145 The functions
146 .Fn execlp ,
147 .Fn execlpe ,
148 .Fn execvp ,
149 and
150 .Fn execvpe
151 will duplicate the actions of the shell in searching for an executable file
152 if the specified file name does not contain a slash
153 .Dq Li \&/
154 character.
155 The search path is the path specified in the environment by the
156 .Ev PATH
157 variable.
158 If this variable isn't specified,
159 .Va _PATH_DEFPATH
160 from
161 .In paths.h
162 is used instead, its value being:
163 .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin .
164 In addition, certain errors are treated specially.
165 .Pp
166 If permission is denied for a file (the attempted
167 .Xr execve 2
168 returned
169 .Er EACCES ) ,
170 these functions will continue searching the rest of
171 the search path.
172 If no other file is found, however, they will return with the global variable
173 .Va errno
174 set to
175 .Er EACCES .
176 .Pp
177 If the header of a file isn't recognized (the attempted
178 .Xr execve 2
179 returned
180 .Er ENOEXEC ) ,
181 these functions will execute the shell with the path of
182 the file as its first argument.
183 (If this attempt fails, no further searching is done.)
184 .Pp
185 If the file is currently busy (the attempted
186 .Xr execve 2
187 returned
188 .Er ETXTBUSY ) ,
189 these functions will sleep for several seconds,
190 periodically re-attempting to execute the file.
191 .Pp
192 The function
193 .Fn exect
194 executes a file with the program tracing facilities enabled (see
195 .Xr ptrace 2 ) .
196 .Sh RETURN VALUES
197 If any of the
198 .Fn exec
199 functions returns, an error will have occurred.
200 The return value is \-1, and the global variable
201 .Va errno
202 will be set to indicate the error.
203 .Sh FILES
204 .Bl -tag -width /bin/sh -compact
205 .It Pa /bin/sh
206 The shell.
207 .El
208 .Sh COMPATIBILITY
209 Historically, the default path for the
210 .Fn execlp
211 .Fn execlpe ,
212 .Fn execvp ,
213 and
214 .Fn execvpe
215 functions was
216 .Dq Pa :/bin:/usr/bin .
217 This was changed to improve security and behaviour.
218 .Pp
219 The behavior of
220 .Fn execlp ,
221 .Fn execlpe ,
222 .Fn execvp ,
223 and
224 .Fn execvpe
225 when errors occur while attempting to execute the file is historic
226 practice, but has not traditionally been documented and is not specified
227 by the
228 .Tn POSIX
229 standard.
230 .Pp
231 Traditionally, the functions
232 .Fn execlp ,
233 .Fn execlpe ,
234 .Fn execvp ,
235 and
236 .Fn execvpe
237 ignored all errors except for the ones described above and
238 .Er ENOMEM
239 and
240 .Er E2BIG ,
241 upon which they returned.
242 They 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 ,
249 and
250 .Fn execvpe
251 may fail and set
252 .Va errno
253 for any of the errors specified for the library functions
254 .Xr execve 2
255 and
256 .Xr malloc 3 .
257 .Pp
258 .Fn exect
259 and
260 .Fn execv
261 may fail and set
262 .Va errno
263 for 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 ,
277 and
278 .Fn execvp
279 conform to
280 .St -p1003.1-90 .
281 .Pp
282 The
283 .Fn execlpe
284 function appeared first in QNX and the
285 .Fn execvpe
286 function exists on both
287 .Lx
288 and QNX.