1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)execve.2 8.5 (Berkeley) 6/1/94
| 1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)execve.2 8.5 (Berkeley) 6/1/94
|
33.\" $FreeBSD: head/lib/libc/sys/execve.2 50476 1999-08-28 00:22:10Z peter $
| 33.\" $FreeBSD: head/lib/libc/sys/execve.2 57686 2000-03-02 09:14:21Z sheldonh $
|
34.\"
35.Dd June 1, 1994
36.Dt EXECVE 2
37.Os BSD 4
38.Sh NAME
39.Nm execve
40.Nd execute a file
41.Sh SYNOPSIS
42.Fd #include <unistd.h>
43.Ft int
44.Fn execve "const char *path" "char *const argv[]" "char *const envp[]"
45.Sh DESCRIPTION
46.Fn Execve
47transforms the calling process into a new process.
48The new process is constructed from an ordinary file,
49whose name is pointed to by
50.Fa path ,
51called the
52.Em new process file .
53This file is either an executable object file,
54or a file of data for an interpreter.
55An executable object file consists of an identifying header,
56followed by pages of data representing the initial program (text)
57and initialized data pages. Additional pages may be specified
58by the header to be initialized with zero data; see
59.Xr a.out 5 .
60.Pp
61An interpreter file begins with a line of the form:
62.Pp
63.Bd -filled -offset indent -compact
64.Sy \&#!
65.Em interpreter
66.Bq Em arg
67.Ed
68.Pp
69When an interpreter file is
70.Sy execve Ap d ,
71the system actually
72.Sy execve Ap s
73the specified
74.Em interpreter .
75If the optional
76.Em arg
77is specified, it becomes the first argument to the
78.Em interpreter ,
79and the name of the originally
80.Sy execve Ap d
81file becomes the second argument;
82otherwise, the name of the originally
83.Sy execve Ap d
84file becomes the first argument. The original arguments are shifted over to
85become the subsequent arguments. The zeroth argument, normally the name of the
86.Sy execve Ap d
87file, is left unchanged.
88.Pp
89The argument
90.Fa argv
91is a pointer to a null-terminated array of
92character pointers to null-terminated character strings.
93These strings construct the argument list to be made available to the new
94process. At least one argument must be present in
95the array; by custom, the first element should be
96the name of the executed program (for example, the last component of
97.Fa path ) .
98.Pp
99The argument
100.Fa envp
101is also a pointer to a null-terminated array of
102character pointers to null-terminated strings.
103A pointer to this array is normally stored in the global variable
104.Va environ.
105These strings pass information to the
106new process that is not directly an argument to the command (see
107.Xr environ 7 ) .
108.Pp
109File descriptors open in the calling process image remain open in
110the new process image, except for those for which the close-on-exec
111flag is set (see
112.Xr close 2
113and
114.Xr fcntl 2 ) .
115Descriptors that remain open are unaffected by
116.Fn execve .
117.Pp
118Signals set to be ignored in the calling process are set to be ignored in
119the
| 34.\"
35.Dd June 1, 1994
36.Dt EXECVE 2
37.Os BSD 4
38.Sh NAME
39.Nm execve
40.Nd execute a file
41.Sh SYNOPSIS
42.Fd #include <unistd.h>
43.Ft int
44.Fn execve "const char *path" "char *const argv[]" "char *const envp[]"
45.Sh DESCRIPTION
46.Fn Execve
47transforms the calling process into a new process.
48The new process is constructed from an ordinary file,
49whose name is pointed to by
50.Fa path ,
51called the
52.Em new process file .
53This file is either an executable object file,
54or a file of data for an interpreter.
55An executable object file consists of an identifying header,
56followed by pages of data representing the initial program (text)
57and initialized data pages. Additional pages may be specified
58by the header to be initialized with zero data; see
59.Xr a.out 5 .
60.Pp
61An interpreter file begins with a line of the form:
62.Pp
63.Bd -filled -offset indent -compact
64.Sy \&#!
65.Em interpreter
66.Bq Em arg
67.Ed
68.Pp
69When an interpreter file is
70.Sy execve Ap d ,
71the system actually
72.Sy execve Ap s
73the specified
74.Em interpreter .
75If the optional
76.Em arg
77is specified, it becomes the first argument to the
78.Em interpreter ,
79and the name of the originally
80.Sy execve Ap d
81file becomes the second argument;
82otherwise, the name of the originally
83.Sy execve Ap d
84file becomes the first argument. The original arguments are shifted over to
85become the subsequent arguments. The zeroth argument, normally the name of the
86.Sy execve Ap d
87file, is left unchanged.
88.Pp
89The argument
90.Fa argv
91is a pointer to a null-terminated array of
92character pointers to null-terminated character strings.
93These strings construct the argument list to be made available to the new
94process. At least one argument must be present in
95the array; by custom, the first element should be
96the name of the executed program (for example, the last component of
97.Fa path ) .
98.Pp
99The argument
100.Fa envp
101is also a pointer to a null-terminated array of
102character pointers to null-terminated strings.
103A pointer to this array is normally stored in the global variable
104.Va environ.
105These strings pass information to the
106new process that is not directly an argument to the command (see
107.Xr environ 7 ) .
108.Pp
109File descriptors open in the calling process image remain open in
110the new process image, except for those for which the close-on-exec
111flag is set (see
112.Xr close 2
113and
114.Xr fcntl 2 ) .
115Descriptors that remain open are unaffected by
116.Fn execve .
117.Pp
118Signals set to be ignored in the calling process are set to be ignored in
119the
|
120new process. Signals which are set to be caught in the calling process image
| 120new process.
121Signals which are set to be caught in the calling process image
|
121are set to default action in the new process image.
122Blocked signals remain blocked regardless of changes to the signal action.
123The signal stack is reset to be undefined (see
124.Xr sigaction 2
125for more information).
126.Pp
127If the set-user-ID mode bit of the new process image file is set
128(see
129.Xr chmod 2 ) ,
130the effective user ID of the new process image is set to the owner ID
131of the new process image file.
132If the set-group-ID mode bit of the new process image file is set,
133the effective group ID of the new process image is set to the group ID
134of the new process image file.
135(The effective group ID is the first element of the group list.)
136The real user ID, real group ID and
137other group IDs of the new process image remain the same as the calling
138process image.
139After any set-user-ID and set-group-ID processing,
140the effective user ID is recorded as the saved set-user-ID,
141and the effective group ID is recorded as the saved set-group-ID.
142These values may be used in changing the effective IDs later (see
143.Xr setuid 2 ) .
144.ne 1i
145.Pp
146The set-ID bits are not honored if the respective file system has the
147.Ar nosuid
148option enabled or if the new process file is an interpreter file. Syscall
149tracing is disabled if effective IDs are changed.
150.Pp
151The new process also inherits the following attributes from
152the calling process:
153.Pp
154.Bl -column parent_process_ID -offset indent -compact
155.It process ID Ta see Xr getpid 2
156.It parent process ID Ta see Xr getppid 2
157.It process group ID Ta see Xr getpgrp 2
158.It access groups Ta see Xr getgroups 2
159.It working directory Ta see Xr chdir 2
160.It root directory Ta see Xr chroot 2
161.It control terminal Ta see Xr termios 4
162.It resource usages Ta see Xr getrusage 2
163.It interval timers Ta see Xr getitimer 2
164.It resource limits Ta see Xr getrlimit 2
165.It file mode mask Ta see Xr umask 2
166.It signal mask Ta see Xr sigvec 2 ,
167.Xr sigsetmask 2
168.El
169.Pp
170When a program is executed as a result of an
171.Fn execve
172call, it is entered as follows:
173.Bd -literal -offset indent
174main(argc, argv, envp)
175int argc;
176char **argv, **envp;
177.Ed
178.Pp
179where
180.Fa argc
181is the number of elements in
182.Fa argv
183(the ``arg count'')
184and
185.Fa argv
186points to the array of character pointers
187to the arguments themselves.
188.Sh IMPLEMENTATION NOTES
189.Pp
190In the non-threaded library
191.Fn execve
192is implemented as the
193.Va execve
194syscall.
195.Pp
196In the threaded library, the
197.Va execve
198syscall is assembled to
199.Fn _thread_sys_execve
200and
201.Fn execve
202is implemented as a function which performs user-thread
203library re-initialization and then calls
204.Fn _thread_sys_execve .
205.Sh RETURN VALUES
206As the
207.Fn execve
208function overlays the current process image
209with a new process image the successful call
210has no process to return to.
211If
212.Fn execve
213does return to the calling process an error has occurred; the
214return value will be -1 and the global variable
215.Va errno
216is set to indicate the error.
217.Sh ERRORS
218.Fn Execve
219will fail and return to the calling process if:
220.Bl -tag -width [ENAMETOOLONG]
221.It Bq Er ENOTDIR
222A component of the path prefix is not a directory.
223.It Bq Er ENAMETOOLONG
224A component of a pathname exceeded 255 characters,
225or an entire path name exceeded 1023 characters.
226.It Bq Er ENOENT
227The new process file does not exist.
228.It Bq Er ELOOP
229Too many symbolic links were encountered in translating the pathname.
230.It Bq Er EACCES
231Search permission is denied for a component of the path prefix.
232.It Bq Er EACCES
233The new process file is not an ordinary file.
234.It Bq Er EACCES
235The new process file mode denies execute permission.
236.It Bq Er ENOEXEC
237The new process file has the appropriate access
238permission, but has an invalid magic number in its header.
239.It Bq Er ETXTBSY
240The new process file is a pure procedure (shared text)
241file that is currently open for writing or reading by some process.
242.ne 1i
243.It Bq Er ENOMEM
244The new process requires more virtual memory than
245is allowed by the imposed maximum
246.Pq Xr getrlimit 2 .
247.It Bq Er E2BIG
248The number of bytes in the new process' argument list
249is larger than the system-imposed limit.
250This limit is specified by the
251.Xr sysctl 3
252MIB variable
253.Dv KERN_ARGMAX .
254.It Bq Er EFAULT
255The new process file is not as long as indicated by
256the size values in its header.
257.It Bq Er EFAULT
258.Fa Path ,
259.Fa argv ,
260or
261.Fa envp
262point
263to an illegal address.
264.It Bq Er EIO
265An I/O error occurred while reading from the file system.
266.El
267.Sh CAVEAT
268If a program is
269.Em setuid
270to a non-super-user, but is executed when
271the real
272.Em uid
273is ``root'', then the program has some of the powers
274of a super-user as well.
275.Sh SEE ALSO
276.Xr ktrace 1 ,
277.Xr _exit 2 ,
278.Xr fork 2 ,
279.Xr execl 3 ,
280.Xr exit 3 ,
281.Xr sysctl 3 ,
282.Xr environ 7 ,
283.Xr mount 8
284.Sh HISTORY
285The
286.Fn execve
287function call appeared in
288.Bx 4.2 .
| 122are set to default action in the new process image.
123Blocked signals remain blocked regardless of changes to the signal action.
124The signal stack is reset to be undefined (see
125.Xr sigaction 2
126for more information).
127.Pp
128If the set-user-ID mode bit of the new process image file is set
129(see
130.Xr chmod 2 ) ,
131the effective user ID of the new process image is set to the owner ID
132of the new process image file.
133If the set-group-ID mode bit of the new process image file is set,
134the effective group ID of the new process image is set to the group ID
135of the new process image file.
136(The effective group ID is the first element of the group list.)
137The real user ID, real group ID and
138other group IDs of the new process image remain the same as the calling
139process image.
140After any set-user-ID and set-group-ID processing,
141the effective user ID is recorded as the saved set-user-ID,
142and the effective group ID is recorded as the saved set-group-ID.
143These values may be used in changing the effective IDs later (see
144.Xr setuid 2 ) .
145.ne 1i
146.Pp
147The set-ID bits are not honored if the respective file system has the
148.Ar nosuid
149option enabled or if the new process file is an interpreter file. Syscall
150tracing is disabled if effective IDs are changed.
151.Pp
152The new process also inherits the following attributes from
153the calling process:
154.Pp
155.Bl -column parent_process_ID -offset indent -compact
156.It process ID Ta see Xr getpid 2
157.It parent process ID Ta see Xr getppid 2
158.It process group ID Ta see Xr getpgrp 2
159.It access groups Ta see Xr getgroups 2
160.It working directory Ta see Xr chdir 2
161.It root directory Ta see Xr chroot 2
162.It control terminal Ta see Xr termios 4
163.It resource usages Ta see Xr getrusage 2
164.It interval timers Ta see Xr getitimer 2
165.It resource limits Ta see Xr getrlimit 2
166.It file mode mask Ta see Xr umask 2
167.It signal mask Ta see Xr sigvec 2 ,
168.Xr sigsetmask 2
169.El
170.Pp
171When a program is executed as a result of an
172.Fn execve
173call, it is entered as follows:
174.Bd -literal -offset indent
175main(argc, argv, envp)
176int argc;
177char **argv, **envp;
178.Ed
179.Pp
180where
181.Fa argc
182is the number of elements in
183.Fa argv
184(the ``arg count'')
185and
186.Fa argv
187points to the array of character pointers
188to the arguments themselves.
189.Sh IMPLEMENTATION NOTES
190.Pp
191In the non-threaded library
192.Fn execve
193is implemented as the
194.Va execve
195syscall.
196.Pp
197In the threaded library, the
198.Va execve
199syscall is assembled to
200.Fn _thread_sys_execve
201and
202.Fn execve
203is implemented as a function which performs user-thread
204library re-initialization and then calls
205.Fn _thread_sys_execve .
206.Sh RETURN VALUES
207As the
208.Fn execve
209function overlays the current process image
210with a new process image the successful call
211has no process to return to.
212If
213.Fn execve
214does return to the calling process an error has occurred; the
215return value will be -1 and the global variable
216.Va errno
217is set to indicate the error.
218.Sh ERRORS
219.Fn Execve
220will fail and return to the calling process if:
221.Bl -tag -width [ENAMETOOLONG]
222.It Bq Er ENOTDIR
223A component of the path prefix is not a directory.
224.It Bq Er ENAMETOOLONG
225A component of a pathname exceeded 255 characters,
226or an entire path name exceeded 1023 characters.
227.It Bq Er ENOENT
228The new process file does not exist.
229.It Bq Er ELOOP
230Too many symbolic links were encountered in translating the pathname.
231.It Bq Er EACCES
232Search permission is denied for a component of the path prefix.
233.It Bq Er EACCES
234The new process file is not an ordinary file.
235.It Bq Er EACCES
236The new process file mode denies execute permission.
237.It Bq Er ENOEXEC
238The new process file has the appropriate access
239permission, but has an invalid magic number in its header.
240.It Bq Er ETXTBSY
241The new process file is a pure procedure (shared text)
242file that is currently open for writing or reading by some process.
243.ne 1i
244.It Bq Er ENOMEM
245The new process requires more virtual memory than
246is allowed by the imposed maximum
247.Pq Xr getrlimit 2 .
248.It Bq Er E2BIG
249The number of bytes in the new process' argument list
250is larger than the system-imposed limit.
251This limit is specified by the
252.Xr sysctl 3
253MIB variable
254.Dv KERN_ARGMAX .
255.It Bq Er EFAULT
256The new process file is not as long as indicated by
257the size values in its header.
258.It Bq Er EFAULT
259.Fa Path ,
260.Fa argv ,
261or
262.Fa envp
263point
264to an illegal address.
265.It Bq Er EIO
266An I/O error occurred while reading from the file system.
267.El
268.Sh CAVEAT
269If a program is
270.Em setuid
271to a non-super-user, but is executed when
272the real
273.Em uid
274is ``root'', then the program has some of the powers
275of a super-user as well.
276.Sh SEE ALSO
277.Xr ktrace 1 ,
278.Xr _exit 2 ,
279.Xr fork 2 ,
280.Xr execl 3 ,
281.Xr exit 3 ,
282.Xr sysctl 3 ,
283.Xr environ 7 ,
284.Xr mount 8
285.Sh HISTORY
286The
287.Fn execve
288function call appeared in
289.Bx 4.2 .
|