![[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] / 43BSDTahoe / man / man2|
Return to execve.2 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2 |
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.7 (Berkeley) 5/22/86
6: .\"
7: .TH EXECVE 2 "May 22, 1986"
8: .UC 4
9: .SH NAME
10: execve \- execute a file
11: .SH SYNOPSIS
12: .ft B
13: execve(name, argv, envp)
14: .br
15: char *name, *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: 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 initialized 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 and
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
38: core image is lost.
39: This is the mechanism whereby different process images become active.
40: .PP
41: The argument \fIargv\fP is a null-terminated 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 a null-terminated array of character pointers
49: to null-terminated strings. These strings pass information to the
50: new process that is not directly an argument 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 that 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: Blocked signals remain blocked regardless of changes to the signal action.
64: The signal stack is reset to be undefined (see
65: .IR sigvec (2)
66: for more information).
67: .PP
68: Each process has
69: .I real
70: user and group IDs and an
71: .I effective
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
78: changes the effective user and group ID to
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
82: user ID is not affected.
83: .PP
84: The new process also inherits the following attributes from
85: the calling process:
86: .PP
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)
101: signal mask see \fIsigvec\fP\|(2), \fIsigmask\fP\|(2)
102: .in -5n
103: .fi
104: .PP
105: When the executed program begins, it is called as follows:
106: .PP
107: .DT
108: .nf
109: main(argc, argv, envp)
110: int argc;
111: char **argv, **envp;
112: .fi
113: .PP
114: where
115: .I argc
116: is the number of elements in \fIargv\fP
117: (the ``arg count'')
118: and
119: .I argv
120: is the array of character pointers
121: to the arguments themselves.
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.
128: A pointer to this array is also stored in the global variable ``environ''.
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
136: .IR environ (7)
137: for some conventionally
138: used names.
139: .SH "RETURN VALUE
140: If
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
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
161: [ENOENT]
162: The new process file does not exist.
163: .TP 15
164: [ELOOP]
165: Too many symbolic links were encountered in translating the pathname.
166: .TP 15
167: [EACCES]
168: Search permission is denied for a component of the path prefix.
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
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> .
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.
203: .TP 15
204: [EIO]
205: An I/O error occurred while reading from the file system.
206: .SH CAVEATS
207: If a program is
208: .I setuid
209: to a non-super-user, but is executed when
210: the real \fIuid\fP is ``root'', then the program has some of the powers
211: of a super-user as well.
212: .SH "SEE ALSO"
213: 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.