![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to execve.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to execve.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 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: .\"
5: .\" @(#)execve.2 6.8 (Berkeley) 11/22/88
6: .\"
7: .TH EXECVE 2 "November 22, 1988"
8: .UC 4
9: .SH NAME
10: execve \- execute a file
11: .SH SYNOPSIS
12: .ft B
13: execve(path, argv, envp)
14: .br
15: char *path, **argv, **envp;
16: .fi
17: .SH DESCRIPTION
18: .I Execve
19: transforms the calling process into a new process.
20: The new process is constructed from an ordinary file,
21: whose name is pointed to by
22: .IR path ,
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
29: by the header to be initialized with zero data. See
30: .IR a.out (5).
31: .PP
32: An interpreter file begins with a line of the form
33: .RB `` "#! \fIinterpreter\fP [\fIarg\fP]" ''.
34: When an interpreter file is
35: .IR execve\| 'd,
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.
50: .PP
51: There can be no return from a successful \fIexecve\fP because the calling
52: core image is lost.
53: This is the mechanism whereby different process images become active.
54: .PP
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
58: process. By convention, at least one argument must be present in
59: this array, and the first element of this array should be
60: the name of the executed program (i.e., the last component of \fIpath\fP).
61: .PP
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
65: new process that is not directly an argument to the command (see
66: .IR environ (7)).
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
70: flag is set (see
71: .IR close (2)
72: and
73: .IR fcntl (2)).
74: Descriptors that remain open are unaffected by
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.
80: Blocked signals remain blocked regardless of changes to the signal action.
81: The signal stack is reset to be undefined (see
82: .IR sigvec (2)
83: for more information).
84: .PP
85: Each process has
86: .I real
87: user and group IDs and an
88: .I effective
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
95: changes the effective user and group ID to
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
99: user and group IDs are not affected.
100: .PP
101: The new process also inherits the following attributes from
102: the calling process:
103: .PP
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)
118: signal mask see \fIsigvec\fP\|(2), \fIsigsetmask\fP\|(2)
119: .in -5n
120: .fi
121: .PP
122: When the executed program begins, it is called as follows:
123: .PP
124: .DT
125: .nf
126: main(argc, argv, envp)
127: int argc;
128: char **argv, **envp;
129: .fi
130: .PP
131: where
132: .I argc
133: is the number of elements in \fIargv\fP
134: (the ``arg count'')
135: and
136: .I argv
137: points to the array of character pointers
138: to the arguments themselves.
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.
145: A pointer to this array is also stored in the global variable ``environ''.
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
153: .IR environ (7)
154: for some conventionally
155: used names.
156: .SH "RETURN VALUE
157: If
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
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
178: [ENOENT]
179: The new process file does not exist.
180: .TP 15
181: [ELOOP]
182: Too many symbolic links were encountered in translating the pathname.
183: .TP 15
184: [EACCES]
185: Search permission is denied for a component of the path prefix.
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
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> .
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.
220: .TP 15
221: [EIO]
222: An I/O error occurred while reading from the file system.
223: .SH CAVEATS
224: If a program is
225: .I setuid
226: to a non-super-user, but is executed when
227: the real \fIuid\fP is ``root'', then the program has some of the powers
228: of a super-user as well.
229: .SH "SEE ALSO"
230: exit(2), fork(2), execl(3), environ(7)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.