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 | .\" | |
95f51977 | 5 | .\" @(#)execve.2 6.7 (Berkeley) 5/22/86 |
2fe0358e | 6 | .\" |
95f51977 | 7 | .TH EXECVE 2 "May 22, 1986" |
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 | |
d4bad45b | 27 | by the header to be initialized with zero data. See |
34aad5a6 KM |
28 | .IR a.out (5). |
29 | .PP | |
fa6928f4 | 30 | An interpreter file begins with a line of the form ``#! \fIinterpreter\fP''. |
34aad5a6 KM |
31 | When an interpreter file is |
32 | .IR execve\| 'd, | |
33 | the system \fIexecve\fP\|'s the specified \fIinterpreter\fP, giving | |
fa6928f4 | 34 | it the name of the originally exec'd file as an argument and |
34aad5a6 KM |
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 | |
fa6928f4 | 41 | The argument \fIargv\fP is a null-terminated array of character pointers |
34aad5a6 KM |
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 | |
d4bad45b | 46 | the name of the executed program (i.e., the last component of \fIname\fP). |
34aad5a6 | 47 | .PP |
fa6928f4 | 48 | The argument \fIenvp\fP is also a null-terminated array of character pointers |
34aad5a6 | 49 | to null-terminated strings. These strings pass information to the |
d4bad45b AH |
50 | new process that is not directly an argument to the command (see |
51 | .IR environ (7)). | |
34aad5a6 KM |
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 | |
d4bad45b AH |
55 | flag is set (see |
56 | .IR close (2)). | |
b5f0627a | 57 | Descriptors that remain open are unaffected by |
34aad5a6 KM |
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. | |
fa6928f4 | 63 | Blocked signals remain blocked regardless of changes to the signal action. |
d4bad45b AH |
64 | The signal stack is reset to be undefined (see |
65 | .IR sigvec (2) | |
66 | for more information). | |
34aad5a6 KM |
67 | .PP |
68 | Each process has | |
2fe0358e | 69 | .I real |
d4bad45b | 70 | user and group IDs and an |
2fe0358e | 71 | .I effective |
34aad5a6 KM |
72 | user and group IDs. The |
73 | .I real | |
74 | ID identifies the person using the system; the | |
75 | .I effective | |
76 | ID determines his access privileges. | |
77 | .I Execve | |
2fe0358e | 78 | changes the effective user and group ID to |
34aad5a6 KM |
79 | the owner of the executed file if the file has the \*(lqset-user-ID\*(rq |
80 | or \*(lqset-group-ID\*(rq modes. The | |
81 | .I real | |
2fe0358e KM |
82 | user ID is not affected. |
83 | .PP | |
34aad5a6 KM |
84 | The new process also inherits the following attributes from |
85 | the calling process: | |
2fe0358e | 86 | .PP |
34aad5a6 KM |
87 | .in +5n |
88 | .nf | |
89 | .ta +2i | |
90 | process ID see \fIgetpid\fP\|(2) | |
91 | parent process ID see \fIgetppid\fP\|(2) | |
92 | process group ID see \fIgetpgrp\fP\|(2) | |
93 | access groups see \fIgetgroups\fP\|(2) | |
94 | working directory see \fIchdir\fP\|(2) | |
95 | root directory see \fIchroot\fP\|(2) | |
96 | control terminal see \fItty\fP\|(4) | |
97 | resource usages see \fIgetrusage\fP\|(2) | |
98 | interval timers see \fIgetitimer\fP\|(2) | |
99 | resource limits see \fIgetrlimit\fP\|(2) | |
100 | file mode mask see \fIumask\fP\|(2) | |
fa6928f4 | 101 | signal mask see \fIsigvec\fP\|(2), \fIsigmask\fP\|(2) |
34aad5a6 KM |
102 | .in -5n |
103 | .fi | |
2fe0358e | 104 | .PP |
34aad5a6 | 105 | When the executed program begins, it is called as follows: |
2fe0358e | 106 | .PP |
34aad5a6 | 107 | .DT |
2fe0358e KM |
108 | .nf |
109 | main(argc, argv, envp) | |
110 | int argc; | |
111 | char **argv, **envp; | |
112 | .fi | |
113 | .PP | |
114 | where | |
34aad5a6 KM |
115 | .I argc |
116 | is the number of elements in \fIargv\fP | |
117 | (the ``arg count'') | |
2fe0358e | 118 | and |
34aad5a6 KM |
119 | .I argv |
120 | is the array of character pointers | |
2fe0358e | 121 | to the arguments themselves. |
2fe0358e KM |
122 | .PP |
123 | .I Envp | |
124 | is a pointer to an array of strings that constitute | |
125 | the | |
126 | .I environment | |
127 | of the process. | |
34aad5a6 | 128 | A pointer to this array is also stored in the global variable ``environ''. |
2fe0358e KM |
129 | Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. |
130 | The array of pointers is terminated by a null pointer. | |
131 | The shell | |
132 | .IR sh (1) | |
133 | passes an environment entry for each global shell variable | |
134 | defined when the program is called. | |
135 | See | |
34aad5a6 | 136 | .IR environ (7) |
2fe0358e KM |
137 | for some conventionally |
138 | used names. | |
34aad5a6 | 139 | .SH "RETURN VALUE |
2fe0358e | 140 | If |
34aad5a6 KM |
141 | .I execve |
142 | returns to the calling process an error has occurred; the | |
143 | return value will be \-1 and the global variable | |
144 | .I errno | |
145 | will contain an error code. | |
146 | .SH ERRORS | |
147 | .I Execve | |
148 | will fail and return to the calling process if one or more | |
149 | of the following are true: | |
150 | .TP 15 | |
b5984ffe KM |
151 | [ENOTDIR] |
152 | A component of the path prefix is not a directory. | |
153 | .TP 15 | |
154 | [EINVAL] | |
155 | The pathname contains a character with the high-order bit set. | |
156 | .TP 15 | |
157 | [ENAMETOOLONG] | |
158 | A component of a pathname exceeded 255 characters, | |
159 | or an entire path name exceeded 1023 characters. | |
160 | .TP 15 | |
34aad5a6 | 161 | [ENOENT] |
b5984ffe | 162 | The new process file does not exist. |
34aad5a6 | 163 | .TP 15 |
b5984ffe KM |
164 | [ELOOP] |
165 | Too many symbolic links were encountered in translating the pathname. | |
34aad5a6 KM |
166 | .TP 15 |
167 | [EACCES] | |
b5984ffe | 168 | Search permission is denied for a component of the path prefix. |
34aad5a6 KM |
169 | .TP 15 |
170 | [EACCES] | |
171 | The new process file is not an ordinary file. | |
172 | .TP 15 | |
173 | [EACCES] | |
174 | The new process file mode denies execute permission. | |
175 | .TP 15 | |
176 | [ENOEXEC] | |
177 | The new process file has the appropriate access | |
178 | permission, but has an invalid magic number in its header. | |
179 | .TP 15 | |
180 | [ETXTBSY] | |
181 | The new process file is a pure procedure (shared text) | |
182 | file that is currently open for writing or reading by some process. | |
183 | .TP 15 | |
184 | [ENOMEM] | |
185 | The new process requires more virtual memory than | |
186 | is allowed by the imposed maximum | |
187 | .RI ( getrlimit (2)). | |
188 | .TP 15 | |
189 | [E2BIG] | |
190 | The number of bytes in the new process's argument list | |
95aab6a2 MK |
191 | is larger than the system-imposed limit. |
192 | The limit in the system as released is 20480 bytes | |
193 | (NCARGS in | |
194 | .IR <sys/param.h> . | |
34aad5a6 KM |
195 | .TP 15 |
196 | [EFAULT] | |
197 | The new process file is not as long as indicated by | |
198 | the size values in its header. | |
199 | .TP 15 | |
200 | [EFAULT] | |
201 | \fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point | |
202 | to an illegal address. | |
fd690c8b KM |
203 | .TP 15 |
204 | [EIO] | |
205 | An I/O error occurred while reading from the file system. | |
34aad5a6 KM |
206 | .SH CAVEATS |
207 | If a program is | |
208 | .I setuid | |
209 | to a non-super-user, but is executed when | |
fa6928f4 | 210 | the real \fIuid\fP is ``root'', then the program has some of the powers |
34aad5a6 KM |
211 | of a super-user as well. |
212 | .SH "SEE ALSO" | |
213 | exit(2), fork(2), execl(3), environ(7) |