Commit | Line | Data |
---|---|---|
2fe0358e KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
2d025b69 | 5 | .\" @(#)execve.2 6.8 (Berkeley) %G% |
2fe0358e | 6 | .\" |
547837f0 | 7 | .TH EXECVE 2 "" |
2fe0358e KM |
8 | .UC 4 |
9 | .SH NAME | |
34aad5a6 | 10 | execve \- execute a file |
2fe0358e | 11 | .SH SYNOPSIS |
34aad5a6 | 12 | .ft B |
2d025b69 | 13 | execve(path, argv, envp) |
34aad5a6 | 14 | .br |
2d025b69 | 15 | char *path, **argv, **envp; |
2fe0358e KM |
16 | .fi |
17 | .SH DESCRIPTION | |
34aad5a6 KM |
18 | .I Execve |
19 | transforms the calling process into a new process. | |
2d025b69 KB |
20 | The new process is constructed from an ordinary file, |
21 | whose name is pointed to by | |
22 | .IR path , | |
34aad5a6 KM |
23 | called the \fInew process file\fP. |
24 | This file is either an executable object file, | |
25 | or a file of data for an interpreter. | |
26 | An executable object file consists of an identifying header, | |
27 | followed by pages of data representing the initial program (text) | |
28 | and initialized data pages. Additional pages may be specified | |
d4bad45b | 29 | by the header to be initialized with zero data. See |
34aad5a6 KM |
30 | .IR a.out (5). |
31 | .PP | |
2d025b69 KB |
32 | An interpreter file begins with a line of the form |
33 | .RB `` "#! \fIinterpreter\fP [\fIarg\fP]" ''. | |
34aad5a6 KM |
34 | When an interpreter file is |
35 | .IR execve\| 'd, | |
2d025b69 KB |
36 | the system \fIexecve\fP\|'s the specified \fIinterpreter\fP. |
37 | If the optional | |
38 | .I arg | |
39 | is specified, it becomes the first argument to the | |
40 | .IR interpreter , | |
41 | and the name of the originally | |
42 | .BR execve 'd | |
43 | file becomes the second argument; | |
44 | otherwise, the name of the originally | |
45 | .BR execve 'd | |
46 | file becomes the first argument. The original arguments are shifted over to | |
47 | become the subsequent arguments. The zeroth argument, normally the name of the | |
48 | .BR execve 'd | |
49 | file, is left unchanged. | |
34aad5a6 KM |
50 | .PP |
51 | There can be no return from a successful \fIexecve\fP because the calling | |
2fe0358e | 52 | core image is lost. |
34aad5a6 KM |
53 | This is the mechanism whereby different process images become active. |
54 | .PP | |
2d025b69 KB |
55 | The argument \fIargv\fP is a pointer to a null-terminated array of |
56 | character pointers to null-terminated character strings. | |
57 | These strings constitute the argument list to be made available to the new | |
34aad5a6 KM |
58 | process. By convention, at least one argument must be present in |
59 | this array, and the first element of this array should be | |
2d025b69 | 60 | the name of the executed program (i.e., the last component of \fIpath\fP). |
34aad5a6 | 61 | .PP |
2d025b69 KB |
62 | The argument \fIenvp\fP is also a pointer to a null-terminated array of |
63 | character pointers to null-terminated strings. | |
64 | These strings pass information to the | |
d4bad45b AH |
65 | new process that is not directly an argument to the command (see |
66 | .IR environ (7)). | |
34aad5a6 KM |
67 | .PP |
68 | Descriptors open in the calling process remain open in | |
69 | the new process, except for those for which the close-on-exec | |
d4bad45b | 70 | flag is set (see |
2d025b69 KB |
71 | .IR close (2) |
72 | and | |
73 | .IR fcntl (2)). | |
b5f0627a | 74 | Descriptors that remain open are unaffected by |
34aad5a6 KM |
75 | .IR execve . |
76 | .PP | |
77 | Ignored signals remain ignored across an | |
78 | .IR execve , | |
79 | but signals that are caught are reset to their default values. | |
fa6928f4 | 80 | Blocked signals remain blocked regardless of changes to the signal action. |
d4bad45b AH |
81 | The signal stack is reset to be undefined (see |
82 | .IR sigvec (2) | |
83 | for more information). | |
34aad5a6 KM |
84 | .PP |
85 | Each process has | |
2fe0358e | 86 | .I real |
d4bad45b | 87 | user and group IDs and an |
2fe0358e | 88 | .I effective |
34aad5a6 KM |
89 | user and group IDs. The |
90 | .I real | |
91 | ID identifies the person using the system; the | |
92 | .I effective | |
93 | ID determines his access privileges. | |
94 | .I Execve | |
2fe0358e | 95 | changes the effective user and group ID to |
34aad5a6 KM |
96 | the owner of the executed file if the file has the \*(lqset-user-ID\*(rq |
97 | or \*(lqset-group-ID\*(rq modes. The | |
98 | .I real | |
2d025b69 | 99 | user and group IDs are not affected. |
2fe0358e | 100 | .PP |
34aad5a6 KM |
101 | The new process also inherits the following attributes from |
102 | the calling process: | |
2fe0358e | 103 | .PP |
34aad5a6 KM |
104 | .in +5n |
105 | .nf | |
106 | .ta +2i | |
107 | process ID see \fIgetpid\fP\|(2) | |
108 | parent process ID see \fIgetppid\fP\|(2) | |
109 | process group ID see \fIgetpgrp\fP\|(2) | |
110 | access groups see \fIgetgroups\fP\|(2) | |
111 | working directory see \fIchdir\fP\|(2) | |
112 | root directory see \fIchroot\fP\|(2) | |
113 | control terminal see \fItty\fP\|(4) | |
114 | resource usages see \fIgetrusage\fP\|(2) | |
115 | interval timers see \fIgetitimer\fP\|(2) | |
116 | resource limits see \fIgetrlimit\fP\|(2) | |
117 | file mode mask see \fIumask\fP\|(2) | |
2d025b69 | 118 | signal mask see \fIsigvec\fP\|(2), \fIsigsetmask\fP\|(2) |
34aad5a6 KM |
119 | .in -5n |
120 | .fi | |
2fe0358e | 121 | .PP |
34aad5a6 | 122 | When the executed program begins, it is called as follows: |
2fe0358e | 123 | .PP |
34aad5a6 | 124 | .DT |
2fe0358e KM |
125 | .nf |
126 | main(argc, argv, envp) | |
127 | int argc; | |
128 | char **argv, **envp; | |
129 | .fi | |
130 | .PP | |
131 | where | |
34aad5a6 KM |
132 | .I argc |
133 | is the number of elements in \fIargv\fP | |
134 | (the ``arg count'') | |
2fe0358e | 135 | and |
34aad5a6 | 136 | .I argv |
2d025b69 | 137 | points to the array of character pointers |
2fe0358e | 138 | to the arguments themselves. |
2fe0358e KM |
139 | .PP |
140 | .I Envp | |
141 | is a pointer to an array of strings that constitute | |
142 | the | |
143 | .I environment | |
144 | of the process. | |
34aad5a6 | 145 | A pointer to this array is also stored in the global variable ``environ''. |
2fe0358e KM |
146 | Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. |
147 | The array of pointers is terminated by a null pointer. | |
148 | The shell | |
149 | .IR sh (1) | |
150 | passes an environment entry for each global shell variable | |
151 | defined when the program is called. | |
152 | See | |
34aad5a6 | 153 | .IR environ (7) |
2fe0358e KM |
154 | for some conventionally |
155 | used names. | |
34aad5a6 | 156 | .SH "RETURN VALUE |
2fe0358e | 157 | If |
34aad5a6 KM |
158 | .I execve |
159 | returns to the calling process an error has occurred; the | |
160 | return value will be \-1 and the global variable | |
161 | .I errno | |
162 | will contain an error code. | |
163 | .SH ERRORS | |
164 | .I Execve | |
165 | will fail and return to the calling process if one or more | |
166 | of the following are true: | |
167 | .TP 15 | |
b5984ffe KM |
168 | [ENOTDIR] |
169 | A component of the path prefix is not a directory. | |
170 | .TP 15 | |
171 | [EINVAL] | |
172 | The pathname contains a character with the high-order bit set. | |
173 | .TP 15 | |
174 | [ENAMETOOLONG] | |
175 | A component of a pathname exceeded 255 characters, | |
176 | or an entire path name exceeded 1023 characters. | |
177 | .TP 15 | |
34aad5a6 | 178 | [ENOENT] |
b5984ffe | 179 | The new process file does not exist. |
34aad5a6 | 180 | .TP 15 |
b5984ffe KM |
181 | [ELOOP] |
182 | Too many symbolic links were encountered in translating the pathname. | |
34aad5a6 KM |
183 | .TP 15 |
184 | [EACCES] | |
b5984ffe | 185 | Search permission is denied for a component of the path prefix. |
34aad5a6 KM |
186 | .TP 15 |
187 | [EACCES] | |
188 | The new process file is not an ordinary file. | |
189 | .TP 15 | |
190 | [EACCES] | |
191 | The new process file mode denies execute permission. | |
192 | .TP 15 | |
193 | [ENOEXEC] | |
194 | The new process file has the appropriate access | |
195 | permission, but has an invalid magic number in its header. | |
196 | .TP 15 | |
197 | [ETXTBSY] | |
198 | The new process file is a pure procedure (shared text) | |
199 | file that is currently open for writing or reading by some process. | |
200 | .TP 15 | |
201 | [ENOMEM] | |
202 | The new process requires more virtual memory than | |
203 | is allowed by the imposed maximum | |
204 | .RI ( getrlimit (2)). | |
205 | .TP 15 | |
206 | [E2BIG] | |
207 | The number of bytes in the new process's argument list | |
95aab6a2 MK |
208 | is larger than the system-imposed limit. |
209 | The limit in the system as released is 20480 bytes | |
210 | (NCARGS in | |
211 | .IR <sys/param.h> . | |
34aad5a6 KM |
212 | .TP 15 |
213 | [EFAULT] | |
214 | The new process file is not as long as indicated by | |
215 | the size values in its header. | |
216 | .TP 15 | |
217 | [EFAULT] | |
218 | \fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point | |
219 | to an illegal address. | |
fd690c8b KM |
220 | .TP 15 |
221 | [EIO] | |
222 | An I/O error occurred while reading from the file system. | |
34aad5a6 KM |
223 | .SH CAVEATS |
224 | If a program is | |
225 | .I setuid | |
226 | to a non-super-user, but is executed when | |
fa6928f4 | 227 | the real \fIuid\fP is ``root'', then the program has some of the powers |
34aad5a6 KM |
228 | of a super-user as well. |
229 | .SH "SEE ALSO" | |
230 | exit(2), fork(2), execl(3), environ(7) |