Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" 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 6.4 (Berkeley) 4/19/91 | |
33 | .\" | |
34 | .Dd April 19, 1991 | |
35 | .Dt EXEC 3 | |
36 | .Os | |
37 | .Sh NAME | |
38 | .Nm execl , | |
39 | .Nm execlp , | |
40 | .Nm execle , | |
41 | .Nm exect , | |
42 | .Nm execv , | |
43 | .Nm execvp | |
44 | .Nd execute a file | |
45 | .Sh SYNOPSIS | |
46 | .Fd #include <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 execle "const char *path" "const char *arg" ... "char *const envp[]" | |
54 | .Ft int | |
55 | .Fn exect "const char *path" "char *const argv[]" | |
56 | .Ft int | |
57 | .Fn execv "const char *path" "char *const argv[]" | |
58 | .Ft int | |
59 | .Fn execvp "const char *file" "char *const argv[]" | |
60 | .Sh DESCRIPTION | |
61 | The | |
62 | .Nm exec | |
63 | family of functions replaces the current process image with a | |
64 | new process image. | |
65 | The functions described in this manual page are front-ends for the function | |
66 | .Xr execve 2 . | |
67 | (See the manual page for | |
68 | .Xr execve | |
69 | for detailed information about the replacement of the current process.) | |
70 | .Pp | |
71 | The initial argument for these functions is the pathname of a file which | |
72 | is to be executed. | |
73 | .Pp | |
74 | The | |
75 | .Fa "const char *arg" | |
76 | and subsequent ellipses in the | |
77 | .Fn execl , | |
78 | .Fn execlp , | |
79 | and | |
80 | .Fn execle | |
81 | functions can be thought of as | |
82 | .Em arg0 , | |
83 | .Em arg1 , | |
84 | \&..., | |
85 | .Em argn . | |
86 | Together they describe a list of one or more pointers to null-terminated | |
87 | strings that represent the argument list available to the executed program. | |
88 | The first argument, by convention, should point to the file name associated | |
89 | with the file being executed. | |
90 | The list of arguments | |
91 | .Em must | |
92 | be terminated by a | |
93 | .Dv NULL | |
94 | pointer. | |
95 | .Pp | |
96 | The | |
97 | .Fn exect , | |
98 | .Fn execv , | |
99 | and | |
100 | .Fn execvp | |
101 | functions provide an array of pointers to null-terminated strings that | |
102 | represent the argument list available to the new program. | |
103 | The first argument, by convention, should point to the file name associated | |
104 | with the file begin executed. | |
105 | The array of pointers | |
106 | .Sy must | |
107 | be terminated by a | |
108 | .Dv NULL | |
109 | pointer. | |
110 | .Pp | |
111 | The | |
112 | .Fn execle | |
113 | and | |
114 | .Fn exect | |
115 | functions also specify the environment of the executed process by following | |
116 | the | |
117 | .Dv NULL | |
118 | pointer that terminates the list of arguments in the parameter list | |
119 | or the pointer to the argv array with an additional parameter. | |
120 | This additional parameter is an array of pointers to null-terminated strings | |
121 | and | |
122 | .Em must | |
123 | be terminated by a | |
124 | .Dv NULL | |
125 | pointer. | |
126 | The other functions take the environment for the new process image from the | |
127 | external variable | |
128 | .Va environ | |
129 | in the current process. | |
130 | .Pp | |
131 | Some of these functions have special semantics. | |
132 | .Pp | |
133 | The functions | |
134 | .Fn execlp | |
135 | and | |
136 | .Fn execvp | |
137 | will duplicate the actions of the shell in searching for an executable file | |
138 | if the specified file name does not contain a slash | |
139 | .Dq Li / | |
140 | character. | |
141 | The search path is the path specified in the environment by | |
142 | .Dq Ev PATH | |
143 | variable. | |
144 | If this variable isn't specified, the default path | |
145 | .Dq Ev /bin:/usr/bin: | |
146 | is | |
147 | used. | |
148 | In addtion, certain errors are treated specially. | |
149 | .Pp | |
150 | If permission is denied for a file (the attempted | |
151 | .Xr execve | |
152 | returned | |
153 | .Er EACCES ) , | |
154 | these functions will continue searching the rest of | |
155 | the search path. | |
156 | If no other file is found, however, they will return with the global variable | |
157 | .Va errno | |
158 | set to | |
159 | .Er EACCES . | |
160 | .Pp | |
161 | If the header of a file isn't recognized (the attempted | |
162 | .Xr execve | |
163 | returned | |
164 | .Er ENOEXEC ) , | |
165 | these functions will execute the shell with the path of | |
166 | the file as its first argument. | |
167 | (If this attempt fails, no further searching is done.) | |
168 | .Pp | |
169 | If the file is currently busy (the attempted | |
170 | .Xr execve | |
171 | returned | |
172 | .Er ETXTBUSY ) , | |
173 | these functions will sleep for several seconds, | |
174 | periodically re-attempting to execute the file. | |
175 | .Pp | |
176 | The function | |
177 | .Fn exect | |
178 | executes a file with the program tracing facilities enabled (see | |
179 | .Xr ptrace 2 ) . | |
180 | .Sh RETURN VALUES | |
181 | If any of the | |
182 | .Xr exec | |
183 | functions returns, an error will have occurred. | |
184 | The return value is \-1, and the global variable | |
185 | .Va errno | |
186 | will be set to indicate the error. | |
187 | .Sh FILES | |
188 | .Bl -tag -width /bin/sh - compact | |
189 | .It Pa /bin/sh | |
190 | The shell. | |
191 | .El | |
192 | .Sh ERRORS | |
193 | .Fn Execl , | |
194 | .Fn execle , | |
195 | .Fn execlp | |
196 | and | |
197 | .Fn execvp | |
198 | may fail and set | |
199 | .Va errno | |
200 | for any of the errors specified for the library functions | |
201 | .Xr execve 2 | |
202 | and | |
203 | .Xr malloc 3 . | |
204 | .Pp | |
205 | .Fn Exect | |
206 | and | |
207 | .Fn execv | |
208 | may fail and set | |
209 | .Va errno | |
210 | for any of the errors specified for the library function | |
211 | .Xr execve 2 . | |
212 | .Sh SEE ALSO | |
213 | .Xr sh 1 , | |
214 | .Xr execve 2 , | |
215 | .Xr fork 2 , | |
216 | .Xr trace 2 , | |
217 | .Xr environ 7 , | |
218 | .Xr ptrace 2 , | |
219 | .Xr environ 7 , | |
220 | .Sh COMPATIBILITY | |
221 | Historically, the default path for the | |
222 | .Fn execlp | |
223 | and | |
224 | .Fn execvp | |
225 | functions was | |
226 | .Dq Pa :/bin:/usr/bin . | |
227 | This was changed to place the current directory last to enhance system | |
228 | security. | |
229 | .Pp | |
230 | The behavior of | |
231 | .Fn execlp | |
232 | and | |
233 | .Fn execvp | |
234 | when errors occur while attempting to execute the file is historic | |
235 | practice, but has not traditionally been documented and is not specified | |
236 | by the | |
237 | .Tn POSIX | |
238 | standard. | |
239 | .Pp | |
240 | Traditionally, the functions | |
241 | .Fn execlp | |
242 | and | |
243 | .Fn execvp | |
244 | ignored all errors except for the ones described above and | |
245 | .Er ENOMEM | |
246 | and | |
247 | .Er E2BIG , | |
248 | upon which they returned. | |
249 | They now return if any error other than the ones described above occurs. | |
250 | .Sh STANDARDS | |
251 | .Fn Execl , | |
252 | .Fn execv , | |
253 | .Fn execle , | |
254 | .Fn execlp | |
255 | and | |
256 | .Fn execvp | |
257 | conform to | |
258 | .St -p1003.1-88 . |