Commit | Line | Data |
---|---|---|
931b8415 CL |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
2fe0358e | 3 | .\" |
af359dea C |
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. | |
2fe0358e | 19 | .\" |
af359dea C |
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. | |
931b8415 | 31 | .\" |
af359dea C |
32 | .\" @(#)execve.2 6.9 (Berkeley) 3/10/91 |
33 | .\" | |
34 | .Dd March 10, 1991 | |
931b8415 CL |
35 | .Dt EXECVE 2 |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm execve | |
39 | .Nd execute a file | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <unistd.h> | |
42 | .Ft int | |
43 | .Fn execve "const char *path" "const * char *argv" "const * char *envp" | |
44 | .Sh DESCRIPTION | |
45 | .Fn Execve | |
34aad5a6 | 46 | transforms the calling process into a new process. |
2d025b69 KB |
47 | The new process is constructed from an ordinary file, |
48 | whose name is pointed to by | |
931b8415 CL |
49 | .Fa path , |
50 | called the | |
51 | .Em new process file . | |
34aad5a6 KM |
52 | This file is either an executable object file, |
53 | or a file of data for an interpreter. | |
54 | An executable object file consists of an identifying header, | |
55 | followed by pages of data representing the initial program (text) | |
56 | and initialized data pages. Additional pages may be specified | |
931b8415 CL |
57 | by the header to be initialized with zero data; see |
58 | .Xr a.out 5 . | |
59 | .Pp | |
60 | An interpreter file begins with a line of the form: | |
61 | .Pp | |
62 | .Bd -filled -offset indent -compact | |
63 | .Sy \&#! | |
64 | .Em interpreter | |
65 | .Bq Em arg | |
66 | .Ed | |
67 | .Pp | |
34aad5a6 | 68 | When an interpreter file is |
931b8415 CL |
69 | .Fn execve Ap d , |
70 | the system | |
71 | .Fn execve Ap s | |
72 | the specified | |
73 | .Em interpreter . | |
2d025b69 | 74 | If the optional |
931b8415 | 75 | .Em arg |
2d025b69 | 76 | is specified, it becomes the first argument to the |
931b8415 | 77 | .Em interpreter , |
2d025b69 | 78 | and the name of the originally |
931b8415 | 79 | .Fn execve Ap d |
2d025b69 KB |
80 | file becomes the second argument; |
81 | otherwise, the name of the originally | |
931b8415 | 82 | .Fn execve Ap d |
2d025b69 KB |
83 | file becomes the first argument. The original arguments are shifted over to |
84 | become the subsequent arguments. The zeroth argument, normally the name of the | |
931b8415 | 85 | .Fn execve Ap d |
2d025b69 | 86 | file, is left unchanged. |
931b8415 CL |
87 | .Pp |
88 | The argument | |
89 | .Fa argv | |
90 | is a pointer to a null-terminated array of | |
2d025b69 | 91 | character pointers to null-terminated character strings. |
931b8415 CL |
92 | These strings construct the argument list to be made available to the new |
93 | process. At least one argument must be present in | |
94 | the array; by custom, the first element should be | |
95 | the name of the executed program (for example, the last component of | |
96 | .Fa path ) . | |
97 | .Pp | |
98 | The argument | |
99 | .Fa envp | |
100 | is also a pointer to a null-terminated array of | |
2d025b69 | 101 | character pointers to null-terminated strings. |
931b8415 CL |
102 | A pointer to this array is normally stored in the global variable |
103 | .Va environ. | |
2d025b69 | 104 | These strings pass information to the |
d4bad45b | 105 | new process that is not directly an argument to the command (see |
931b8415 CL |
106 | .Xr environ 7 ) . |
107 | .Pp | |
108 | File descriptors open in the calling process image remain open in | |
109 | the new process image, except for those for which the close-on-exec | |
d4bad45b | 110 | flag is set (see |
931b8415 | 111 | .Xr close 2 |
2d025b69 | 112 | and |
931b8415 | 113 | .Xr fcntl 2 ) . |
b5f0627a | 114 | Descriptors that remain open are unaffected by |
931b8415 CL |
115 | .Fn execve . |
116 | .Pp | |
117 | Signals set to be ignored in the calling process are set to be ignored in | |
118 | the | |
119 | new process. Signals which are set to be caught in the calling process image | |
120 | are set to default action in the new process image. | |
fa6928f4 | 121 | Blocked signals remain blocked regardless of changes to the signal action. |
d4bad45b | 122 | The signal stack is reset to be undefined (see |
931b8415 | 123 | .Xr sigaction 2 |
d4bad45b | 124 | for more information). |
931b8415 CL |
125 | .Pp |
126 | If the set-user-ID mode bit of the new process image file is set | |
127 | (see | |
128 | .Xr chmod 2 ) , | |
129 | the effective user ID of the new process image is set to the owner ID | |
130 | of the new process image file. | |
131 | If the set-group-ID mode bit of the new process image file is set, | |
132 | the effective group ID of the new process image is set to the group ID | |
133 | of the new process image file. | |
134 | The real user ID, real group ID and | |
135 | supplementary group IDs of the new process image remain the same as the calling | |
136 | process image. | |
137 | .Pp | |
34aad5a6 KM |
138 | The new process also inherits the following attributes from |
139 | the calling process: | |
931b8415 CL |
140 | .Pp |
141 | .Bl -column parent_process_ID -offset indent -compact | |
142 | .It process ID Ta see Xr getpid 2 | |
143 | .It parent process ID Ta see Xr getppid 2 | |
144 | .It process group ID Ta see Xr getpgrp 2 | |
145 | .It access groups Ta see Xr getgroups 2 | |
146 | .It working directory Ta see Xr chdir 2 | |
147 | .It root directory Ta see Xr chroot 2 | |
148 | .It control terminal Ta see Xr termios 4 | |
149 | .It resource usages Ta see Xr getrusage 2 | |
150 | .It interval timers Ta see Xr getitimer 2 | |
151 | .It resource limits Ta see Xr getrlimit 2 | |
152 | .It file mode mask Ta see Xr umask 2 | |
153 | .It signal mask Ta see Xr sigvec 2 , | |
154 | .Xr sigsetmask 2 | |
155 | .El | |
156 | .Pp | |
157 | When a program is executed as a result of an | |
158 | .Fn execve | |
159 | call, it is entered as follows: | |
160 | .Bd -literal -offset indent | |
161 | main(argc, argv, envp) | |
162 | int argc; | |
163 | char **argv, **envp; | |
164 | .Ed | |
165 | .Pp | |
2fe0358e | 166 | where |
931b8415 CL |
167 | .Fa argc |
168 | is the number of elements in | |
169 | .Fa argv | |
34aad5a6 | 170 | (the ``arg count'') |
2fe0358e | 171 | and |
931b8415 | 172 | .Fa argv |
2d025b69 | 173 | points to the array of character pointers |
2fe0358e | 174 | to the arguments themselves. |
931b8415 CL |
175 | .Sh RETURN VALUES |
176 | As the | |
177 | .Fn execve | |
178 | function overlays the current process image | |
179 | with a new process image the successful call | |
180 | has no process to return to. | |
2fe0358e | 181 | If |
931b8415 CL |
182 | .Fn execve |
183 | does return to the calling process an error has occurred; the | |
184 | return value will be -1 and the global variable | |
185 | .Va errno | |
186 | is set to indicate the error. | |
187 | .Sh ERRORS | |
188 | .Fn Execve | |
189 | will fail and return to the calling process if: | |
190 | .Bl -tag -width [ENAMETOOLONG] | |
191 | .It Bq Er ENOTDIR | |
b5984ffe | 192 | A component of the path prefix is not a directory. |
931b8415 | 193 | .It Bq Er EINVAL |
b5984ffe | 194 | The pathname contains a character with the high-order bit set. |
931b8415 | 195 | .It Bq Er ENAMETOOLONG |
b5984ffe KM |
196 | A component of a pathname exceeded 255 characters, |
197 | or an entire path name exceeded 1023 characters. | |
931b8415 | 198 | .It Bq Er ENOENT |
b5984ffe | 199 | The new process file does not exist. |
931b8415 | 200 | .It Bq Er ELOOP |
b5984ffe | 201 | Too many symbolic links were encountered in translating the pathname. |
931b8415 | 202 | .It Bq Er EACCES |
b5984ffe | 203 | Search permission is denied for a component of the path prefix. |
931b8415 | 204 | .It Bq Er EACCES |
34aad5a6 | 205 | The new process file is not an ordinary file. |
931b8415 | 206 | .It Bq Er EACCES |
34aad5a6 | 207 | The new process file mode denies execute permission. |
931b8415 | 208 | .It Bq Er ENOEXEC |
34aad5a6 KM |
209 | The new process file has the appropriate access |
210 | permission, but has an invalid magic number in its header. | |
931b8415 | 211 | .It Bq Er ETXTBSY |
34aad5a6 KM |
212 | The new process file is a pure procedure (shared text) |
213 | file that is currently open for writing or reading by some process. | |
931b8415 | 214 | .It Bq Er ENOMEM |
34aad5a6 KM |
215 | The new process requires more virtual memory than |
216 | is allowed by the imposed maximum | |
931b8415 CL |
217 | .Pq Xr getrlimit 2 . |
218 | .It Bq Er E2BIG | |
34aad5a6 | 219 | The number of bytes in the new process's argument list |
95aab6a2 MK |
220 | is larger than the system-imposed limit. |
221 | The limit in the system as released is 20480 bytes | |
931b8415 CL |
222 | .Pf ( Dv NCARGS |
223 | in | |
224 | .Ao Pa sys/param.h Ac . | |
225 | .It Bq Er EFAULT | |
34aad5a6 KM |
226 | The new process file is not as long as indicated by |
227 | the size values in its header. | |
931b8415 CL |
228 | .It Bq Er EFAULT |
229 | .Fa Path , | |
230 | .Fa argv , | |
231 | or | |
232 | .Fa envp | |
233 | point | |
34aad5a6 | 234 | to an illegal address. |
931b8415 | 235 | .It Bq Er EIO |
fd690c8b | 236 | An I/O error occurred while reading from the file system. |
931b8415 CL |
237 | .El |
238 | .Sh CAVEAT | |
34aad5a6 | 239 | If a program is |
931b8415 | 240 | .Em setuid |
34aad5a6 | 241 | to a non-super-user, but is executed when |
931b8415 CL |
242 | the real |
243 | .Em uid | |
244 | is ``root'', then the program has some of the powers | |
34aad5a6 | 245 | of a super-user as well. |
931b8415 CL |
246 | .Sh SEE ALSO |
247 | .Xr exit 2 , | |
248 | .Xr fork 2 , | |
249 | .Xr execl 3 , | |
250 | .Xr environ 7 | |
251 | .Sh HISTORY | |
252 | The | |
253 | .Nm | |
254 | function call appeared in | |
255 | .Bx 4.2 . |