| @@ -1,293 +1,292 @@ | | | @@ -1,293 +1,292 @@ |
1 | .\" $NetBSD: exec.3,v 1.30 2019/09/01 19:33:45 sevan Exp $ | | 1 | .\" $NetBSD: exec.3,v 1.31 2019/09/01 19:36:09 wiz Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 1991, 1993 | | 3 | .\" Copyright (c) 1991, 1993 |
4 | .\" The Regents of the University of California. All rights reserved. | | 4 | .\" The Regents of the University of California. All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Redistribution and use in source and binary forms, with or without | | 6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | | 7 | .\" modification, are permitted provided that the following conditions |
8 | .\" are met: | | 8 | .\" are met: |
9 | .\" 1. Redistributions of source code must retain the above copyright | | 9 | .\" 1. Redistributions of source code must retain the above copyright |
10 | .\" notice, this list of conditions and the following disclaimer. | | 10 | .\" notice, this list of conditions and the following disclaimer. |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 11 | .\" 2. Redistributions in binary form must reproduce the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer in the | | 12 | .\" notice, this list of conditions and the following disclaimer in the |
13 | .\" documentation and/or other materials provided with the distribution. | | 13 | .\" documentation and/or other materials provided with the distribution. |
14 | .\" 3. Neither the name of the University nor the names of its contributors | | 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 | | 15 | .\" may be used to endorse or promote products derived from this software |
16 | .\" without specific prior written permission. | | 16 | .\" without specific prior written permission. |
17 | .\" | | 17 | .\" |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 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 | | 19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 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 | | 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 | | 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 | | 27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
28 | .\" SUCH DAMAGE. | | 28 | .\" SUCH DAMAGE. |
29 | .\" | | 29 | .\" |
30 | .\" @(#)exec.3 8.3 (Berkeley) 1/24/94 | | 30 | .\" @(#)exec.3 8.3 (Berkeley) 1/24/94 |
31 | .\" | | 31 | .\" |
32 | .Dd September 1, 2019 | | 32 | .Dd September 1, 2019 |
33 | .Dt EXEC 3 | | 33 | .Dt EXEC 3 |
34 | .Os | | 34 | .Os |
35 | .Sh NAME | | 35 | .Sh NAME |
36 | .Nm execl , | | 36 | .Nm execl , |
37 | .Nm execlp , | | 37 | .Nm execlp , |
38 | .Nm execlpe , | | 38 | .Nm execlpe , |
39 | .Nm execle , | | 39 | .Nm execle , |
40 | .Nm exect , | | 40 | .Nm exect , |
41 | .Nm execv , | | 41 | .Nm execv , |
42 | .Nm execvp , | | 42 | .Nm execvp , |
43 | .Nm execvpe | | 43 | .Nm execvpe |
44 | .Nd execute a file | | 44 | .Nd execute a file |
45 | .Sh LIBRARY | | 45 | .Sh LIBRARY |
46 | .Lb libc | | 46 | .Lb libc |
47 | .Sh SYNOPSIS | | 47 | .Sh SYNOPSIS |
48 | .In unistd.h | | 48 | .In unistd.h |
49 | .Vt extern char **environ; | | 49 | .Vt extern char **environ; |
50 | .Ft int | | 50 | .Ft int |
51 | .Fn execl "const char *path" "const char *arg" ... | | 51 | .Fn execl "const char *path" "const char *arg" ... |
52 | .Ft int | | 52 | .Ft int |
53 | .Fn execlp "const char *file" "const char *arg" ... | | 53 | .Fn execlp "const char *file" "const char *arg" ... |
54 | .Ft int | | 54 | .Ft int |
55 | .Fn execlpe "const char *path" "const char *arg" ... "char *const envp[]" | | 55 | .Fn execlpe "const char *path" "const char *arg" ... "char *const envp[]" |
56 | .Ft int | | 56 | .Ft int |
57 | .Fn execle "const char *path" "const char *arg" ... "char *const envp[]" | | 57 | .Fn execle "const char *path" "const char *arg" ... "char *const envp[]" |
58 | .Ft int | | 58 | .Ft int |
59 | .Fn exect "const char *path" "char *const argv[]" "char *const envp[]" | | 59 | .Fn exect "const char *path" "char *const argv[]" "char *const envp[]" |
60 | .Ft int | | 60 | .Ft int |
61 | .Fn execv "const char *path" "char *const argv[]" | | 61 | .Fn execv "const char *path" "char *const argv[]" |
62 | .Ft int | | 62 | .Ft int |
63 | .Fn execvp "const char *file" "char *const argv[]" | | 63 | .Fn execvp "const char *file" "char *const argv[]" |
64 | .Ft int | | 64 | .Ft int |
65 | .Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" | | 65 | .Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" |
66 | .Sh DESCRIPTION | | 66 | .Sh DESCRIPTION |
67 | The | | 67 | The |
68 | .Fn exec | | 68 | .Fn exec |
69 | family of functions replaces the current process image with a | | 69 | family of functions replaces the current process image with a |
70 | new process image. | | 70 | new process image. |
71 | The functions described in this manual page are front-ends for the function | | 71 | The functions described in this manual page are front-ends for the function |
72 | .Xr execve 2 . | | 72 | .Xr execve 2 . |
73 | (See the manual page for | | 73 | (See the manual page for |
74 | .Xr execve 2 | | 74 | .Xr execve 2 |
75 | for detailed information about the replacement of the current process. | | 75 | for detailed information about the replacement of the current process. |
76 | The | | 76 | The |
77 | .Xr script 7 | | 77 | .Xr script 7 |
78 | manual page provides detailed information about the execution of | | 78 | manual page provides detailed information about the execution of |
79 | interpreter scripts.) | | 79 | interpreter scripts.) |
80 | .Pp | | 80 | .Pp |
81 | The initial argument for these functions is the pathname of a file which | | 81 | The initial argument for these functions is the pathname of a file which |
82 | is to be executed. | | 82 | is to be executed. |
83 | .Pp | | 83 | .Pp |
84 | The | | 84 | The |
85 | .Fa "const char *arg" | | 85 | .Fa "const char *arg" |
86 | and subsequent ellipses in the | | 86 | and subsequent ellipses in the |
87 | .Fn execl , | | 87 | .Fn execl , |
88 | .Fn execlp , | | 88 | .Fn execlp , |
89 | .Fn execlpe , | | 89 | .Fn execlpe , |
90 | and | | 90 | and |
91 | .Fn execle | | 91 | .Fn execle |
92 | functions can be thought of as | | 92 | functions can be thought of as |
93 | .Em arg0 , | | 93 | .Em arg0 , |
94 | .Em arg1 , | | 94 | .Em arg1 , |
95 | \&..., | | 95 | \&..., |
96 | .Em argn . | | 96 | .Em argn . |
97 | Together they describe a list of one or more pointers to NUL-terminated | | 97 | Together they describe a list of one or more pointers to NUL-terminated |
98 | strings that represent the argument list available to the executed program. | | 98 | strings that represent the argument list available to the executed program. |
99 | The first argument, by convention, should point to the file name associated | | 99 | The first argument, by convention, should point to the file name associated |
100 | with the file being executed. | | 100 | with the file being executed. |
101 | The list of arguments | | 101 | The list of arguments |
102 | .Em must | | 102 | .Em must |
103 | be terminated by a | | 103 | be terminated by a |
104 | .Dv NULL | | 104 | .Dv NULL |
105 | pointer. | | 105 | pointer. |
106 | .Pp | | 106 | .Pp |
107 | The | | 107 | The |
108 | .Fn exect , | | 108 | .Fn exect , |
109 | .Fn execv , | | 109 | .Fn execv , |
110 | .Fn execvp , | | 110 | .Fn execvp , |
111 | and | | 111 | and |
112 | .Fn execvpe | | 112 | .Fn execvpe |
113 | functions provide an array of pointers to NUL-terminated strings that | | 113 | functions provide an array of pointers to NUL-terminated strings that |
114 | represent the argument list available to the new program. | | 114 | represent the argument list available to the new program. |
115 | The first argument, by convention, should point to the file name associated | | 115 | The first argument, by convention, should point to the file name associated |
116 | with the file being executed. | | 116 | with the file being executed. |
117 | The array of pointers | | 117 | The array of pointers |
118 | .Sy must | | 118 | .Sy must |
119 | be terminated by a | | 119 | be terminated by a |
120 | .Dv NULL | | 120 | .Dv NULL |
121 | pointer. | | 121 | pointer. |
122 | .Pp | | 122 | .Pp |
123 | The | | 123 | The |
124 | .Fn execle , | | 124 | .Fn execle , |
125 | .Fn execlpe , | | 125 | .Fn execlpe , |
126 | .Fn exect , | | 126 | .Fn exect , |
127 | and | | 127 | and |
128 | .Fn execvpe | | 128 | .Fn execvpe |
129 | functions also specify the environment of the executed process by following | | 129 | functions also specify the environment of the executed process by following |
130 | the | | 130 | the |
131 | .Dv NULL | | 131 | .Dv NULL |
132 | pointer that terminates the list of arguments in the parameter list | | 132 | pointer that terminates the list of arguments in the parameter list |
133 | or the pointer to the argv array with an additional parameter. | | 133 | or the pointer to the argv array with an additional parameter. |
134 | This additional parameter is an array of pointers to NUL-terminated strings | | 134 | This additional parameter is an array of pointers to NUL-terminated strings |
135 | and | | 135 | and |
136 | .Em must | | 136 | .Em must |
137 | be terminated by a | | 137 | be terminated by a |
138 | .Dv NULL | | 138 | .Dv NULL |
139 | pointer. | | 139 | pointer. |
140 | The other functions take the environment for the new process image from the | | 140 | The other functions take the environment for the new process image from the |
141 | external variable | | 141 | external variable |
142 | .Va environ | | 142 | .Va environ |
143 | in the current process. | | 143 | in the current process. |
144 | .Pp | | 144 | .Pp |
145 | Some of these functions have special semantics. | | 145 | Some of these functions have special semantics. |
146 | .Pp | | 146 | .Pp |
147 | The functions | | 147 | The functions |
148 | .Fn execlp , | | 148 | .Fn execlp , |
149 | .Fn execlpe , | | 149 | .Fn execlpe , |
150 | .Fn execvp , | | 150 | .Fn execvp , |
151 | and | | 151 | and |
152 | .Fn execvpe | | 152 | .Fn execvpe |
153 | will duplicate the actions of the shell in searching for an executable file | | 153 | will duplicate the actions of the shell in searching for an executable file |
154 | if the specified file name does not contain a slash | | 154 | if the specified file name does not contain a slash |
155 | .Dq Li \&/ | | 155 | .Dq Li \&/ |
156 | character. | | 156 | character. |
157 | The search path is the path specified in the environment by the | | 157 | The search path is the path specified in the environment by the |
158 | .Ev PATH | | 158 | .Ev PATH |
159 | variable. | | 159 | variable. |
160 | If this variable isn't specified, | | 160 | If this variable isn't specified, |
161 | .Va _PATH_DEFPATH | | 161 | .Va _PATH_DEFPATH |
162 | from | | 162 | from |
163 | .In paths.h | | 163 | .In paths.h |
164 | is used instead, its value being: | | 164 | is used instead, its value being: |
165 | .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . | | 165 | .Pa /usr/bin:/bin:/usr/pkg/bin:/usr/local/bin . |
166 | In addition, certain errors are treated specially. | | 166 | In addition, certain errors are treated specially. |
167 | .Pp | | 167 | .Pp |
168 | If permission is denied for a file (the attempted | | 168 | If permission is denied for a file (the attempted |
169 | .Xr execve 2 | | 169 | .Xr execve 2 |
170 | returned | | 170 | returned |
171 | .Er EACCES ) , | | 171 | .Er EACCES ) , |
172 | these functions will continue searching the rest of | | 172 | these functions will continue searching the rest of |
173 | the search path. | | 173 | the search path. |
174 | If no other file is found, however, they will return with the global variable | | 174 | If no other file is found, however, they will return with the global variable |
175 | .Va errno | | 175 | .Va errno |
176 | set to | | 176 | set to |
177 | .Er EACCES . | | 177 | .Er EACCES . |
178 | .Pp | | 178 | .Pp |
179 | If the header of a file isn't recognized (the attempted | | 179 | If the header of a file isn't recognized (the attempted |
180 | .Xr execve 2 | | 180 | .Xr execve 2 |
181 | returned | | 181 | returned |
182 | .Er ENOEXEC ) , | | 182 | .Er ENOEXEC ) , |
183 | these functions will execute the shell with the path of | | 183 | these functions will execute the shell with the path of |
184 | the file as its first argument. | | 184 | the file as its first argument. |
185 | (If this attempt fails, no further searching is done.) | | 185 | (If this attempt fails, no further searching is done.) |
186 | .Pp | | 186 | .Pp |
187 | If the file is currently busy (the attempted | | 187 | If the file is currently busy (the attempted |
188 | .Xr execve 2 | | 188 | .Xr execve 2 |
189 | returned | | 189 | returned |
190 | .Er ETXTBUSY ) , | | 190 | .Er ETXTBUSY ) , |
191 | these functions will sleep for several seconds, | | 191 | these functions will sleep for several seconds, |
192 | periodically re-attempting to execute the file. | | 192 | periodically re-attempting to execute the file. |
193 | .Pp | | 193 | .Pp |
194 | The function | | 194 | The function |
195 | .Fn exect | | 195 | .Fn exect |
196 | executes a file with the program tracing facilities enabled (see | | 196 | executes a file with the program tracing facilities enabled (see |
197 | .Xr ptrace 2 ) . | | 197 | .Xr ptrace 2 ) . |
198 | .Sh RETURN VALUES | | 198 | .Sh RETURN VALUES |
199 | If any of the | | 199 | If any of the |
200 | .Fn exec | | 200 | .Fn exec |
201 | functions returns, an error will have occurred. | | 201 | functions returns, an error will have occurred. |
202 | The return value is \-1, and the global variable | | 202 | The return value is \-1, and the global variable |
203 | .Va errno | | 203 | .Va errno |
204 | will be set to indicate the error. | | 204 | will be set to indicate the error. |
205 | .Sh FILES | | 205 | .Sh FILES |
206 | .Bl -tag -width /bin/sh -compact | | 206 | .Bl -tag -width /bin/sh -compact |
207 | .It Pa /bin/sh | | 207 | .It Pa /bin/sh |
208 | The shell. | | 208 | The shell. |
209 | .El | | 209 | .El |
210 | .Sh COMPATIBILITY | | 210 | .Sh COMPATIBILITY |
211 | Historically, the default path for the | | 211 | Historically, the default path for the |
212 | .Fn execlp | | 212 | .Fn execlp |
213 | .Fn execlpe , | | 213 | .Fn execlpe , |
214 | .Fn execvp , | | 214 | .Fn execvp , |
215 | and | | 215 | and |
216 | .Fn execvpe | | 216 | .Fn execvpe |
217 | functions was | | 217 | functions was |
218 | .Dq Pa :/bin:/usr/bin . | | 218 | .Dq Pa :/bin:/usr/bin . |
219 | This was changed to improve security and behaviour. | | 219 | This was changed to improve security and behaviour. |
220 | .Pp | | 220 | .Pp |
221 | The behavior of | | 221 | The behavior of |
222 | .Fn execlp , | | 222 | .Fn execlp , |
223 | .Fn execlpe , | | 223 | .Fn execlpe , |
224 | .Fn execvp , | | 224 | .Fn execvp , |
225 | and | | 225 | and |
226 | .Fn execvpe | | 226 | .Fn execvpe |
227 | when errors occur while attempting to execute the file is historic | | 227 | when errors occur while attempting to execute the file is historic |
228 | practice, but has not traditionally been documented and is not specified | | 228 | practice, but has not traditionally been documented and is not specified |
229 | by the POSIX standard. | | 229 | by the POSIX standard. |
230 | .Pp | | 230 | .Pp |
231 | Traditionally, the functions | | 231 | Traditionally, the functions |
232 | .Fn execlp , | | 232 | .Fn execlp , |
233 | .Fn execlpe , | | 233 | .Fn execlpe , |
234 | .Fn execvp , | | 234 | .Fn execvp , |
235 | and | | 235 | and |
236 | .Fn execvpe | | 236 | .Fn execvpe |
237 | ignored all errors except for the ones described above and | | 237 | ignored all errors except for the ones described above and |
238 | .Er ENOMEM | | 238 | .Er ENOMEM |
239 | and | | 239 | and |
240 | .Er E2BIG , | | 240 | .Er E2BIG , |
241 | upon which they returned. | | 241 | upon which they returned. |
242 | They now return if any error other than the ones described above occurs. | | 242 | They now return if any error other than the ones described above occurs. |
243 | .Sh ERRORS | | 243 | .Sh ERRORS |
244 | .Fn execl , | | 244 | .Fn execl , |
245 | .Fn execle , | | 245 | .Fn execle , |
246 | .Fn execlp , | | 246 | .Fn execlp , |
247 | .Fn execlpe , | | 247 | .Fn execlpe , |
248 | .Fn execvp , | | 248 | .Fn execvp , |
249 | and | | 249 | and |
250 | .Fn execvpe | | 250 | .Fn execvpe |
251 | may fail and set | | 251 | may fail and set |
252 | .Va errno | | 252 | .Va errno |
253 | for any of the errors specified for the library functions | | 253 | for any of the errors specified for the library functions |
254 | .Xr execve 2 | | 254 | .Xr execve 2 |
255 | and | | 255 | and |
256 | .Xr malloc 3 . | | 256 | .Xr malloc 3 . |
257 | .Pp | | 257 | .Pp |
258 | .Fn exect | | 258 | .Fn exect |
259 | and | | 259 | and |
260 | .Fn execv | | 260 | .Fn execv |
261 | may fail and set | | 261 | may fail and set |
262 | .Va errno | | 262 | .Va errno |
263 | for any of the errors specified for the library function | | 263 | for any of the errors specified for the library function |
264 | .Xr execve 2 . | | 264 | .Xr execve 2 . |
265 | .Sh SEE ALSO | | 265 | .Sh SEE ALSO |
266 | .Xr sh 1 , | | 266 | .Xr sh 1 , |
267 | .Xr execve 2 , | | 267 | .Xr execve 2 , |
268 | .Xr fork 2 , | | 268 | .Xr fork 2 , |
269 | .Xr ptrace 2 , | | 269 | .Xr ptrace 2 , |
270 | .Xr environ 7 , | | 270 | .Xr environ 7 , |
271 | .Xr script 7 | | 271 | .Xr script 7 |
272 | .Sh STANDARDS | | 272 | .Sh STANDARDS |
273 | .Fn execl , | | 273 | .Fn execl , |
274 | .Fn execv , | | 274 | .Fn execv , |
275 | .Fn execle , | | 275 | .Fn execle , |
276 | .Fn execlp , | | 276 | .Fn execlp , |
277 | and | | 277 | and |
278 | .Fn execvp | | 278 | .Fn execvp |
279 | conform to | | 279 | conform to |
280 | .St -p1003.1-90 . | | 280 | .St -p1003.1-90 . |
281 | .Pp | | | |
282 | .Sh HISTORY | | 281 | .Sh HISTORY |
283 | The | | 282 | The |
284 | .Fn exec | | 283 | .Fn exec |
285 | function appeared in | | 284 | function appeared in |
286 | .At v1 . | | 285 | .At v1 . |
287 | The | | 286 | The |
288 | .Fn execlpe | | 287 | .Fn execlpe |
289 | function appeared first in QNX and the | | 288 | function appeared first in QNX and the |
290 | .Fn execvpe | | 289 | .Fn execvpe |
291 | function exists on both | | 290 | function exists on both |
292 | .Nx | | 291 | .Nx |
293 | and QNX. | | 292 | and QNX. |