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