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