jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: execve.2,v 1.60 2025/08/04 04:59:31 guenther Exp $
2.\" $NetBSD: execve.2,v 1.9 1995/02/27 12:32:25 cgd Exp $
3.\"
4.\" Copyright (c) 1980, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)execve.2 8.3 (Berkeley) 1/24/94
32.\"
33.Dd $Mdocdate: August 4 2025 $
34.Dt EXECVE 2
35.Os
36.Sh NAME
37.Nm execve
38.Nd execute a file
39.Sh SYNOPSIS
40.In unistd.h
41.Ft int
42.Fn execve "const char *path" "char *const argv[]" "char *const envp[]"
43.Sh DESCRIPTION
44.Fn execve
45transforms the calling process into a new process.
46The new process is constructed from an ordinary file,
47whose name is pointed to by
48.Fa path ,
49called the
50.Em new process file .
51This file is either an executable object file,
52or a file of data for an interpreter.
53An executable object file consists of an identifying header,
54followed by pages of data representing the initial program (text)
55and initialized data pages.
56Additional pages may be specified by the header to be initialized
57with zero data; see
58.Xr elf 5 .
59.Pp
60An interpreter file begins with a line of the form:
61.Pp
62.D1 #! Ar interpreter Op Ar arg
63.Pp
64When an interpreter file is passed to
65.Fn execve ,
66the system instead calls
67.Fn execve
68with the specified
69.Ar interpreter .
70If the optional
71.Ar arg
72is specified, it becomes the first argument to the
73.Ar interpreter ,
74and the original
75.Fa path
76becomes the second argument;
77otherwise,
78.Fa path
79becomes the first argument.
80The original arguments are shifted over to become the subsequent arguments.
81The zeroth argument, normally the name of the file being executed, is left
82unchanged.
83.Pp
84The argument
85.Fa argv
86is a pointer to a null-terminated array of
87character pointers to NUL-terminated character strings.
88These strings construct the argument list to be made available to the new
89process.
90At least one non-null argument must be present in the array;
91by custom, the first element should be
92the name of the executed program (for example, the last component of
93.Fa path ) .
94.Pp
95The argument
96.Fa envp
97is also a pointer to a null-terminated array of
98character pointers to NUL-terminated strings.
99A pointer to this array is normally stored in the global variable
100.Va environ .
101These strings pass information to the
102new process that is not directly an argument to the command (see
103.Xr environ 7 ) .
104.Pp
105File descriptors open in the calling process image remain open in
106the new process image, except for those for which the close-on-exec
107flag is set (see
108.Xr close 2
109and
110.Xr fcntl 2 ) .
111Descriptors that remain open are unaffected by
112.Fn execve ,
113except that the close-on-fork flag is cleared on all descriptors.
114In the case of a new setuid or setgid executable being executed, if
115file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr)
116are currently unallocated, these descriptors will be opened to point to
117some system file like
118.Pa /dev/null .
119The intent is to ensure these descriptors are not unallocated, since
120many libraries make assumptions about the use of these 3 file descriptors.
121.Pp
122Signals set to be ignored in the calling process,
123with the exception of
124.Dv SIGCHLD ,
125are set to be ignored in
126the
127new process.
128Other signals
129are set to default action in the new process image.
130Blocked signals remain blocked regardless of changes to the signal action.
131The signal stack is reset to be undefined (see
132.Xr sigaction 2
133for more information).
134.Pp
135If the set-user-ID mode bit of the new process image file is set
136(see
137.Xr chmod 2 ) ,
138the effective user ID of the new process image is set to the owner ID
139of the new process image file.
140If the set-group-ID mode bit of the new process image file is set,
141the effective group ID of the new process image is set to the group ID
142of the new process image file.
143(The effective group ID is the first element of the group list.)
144The real user ID, real group ID and
145other group IDs of the new process image remain the same as the calling
146process image.
147After any set-user-ID and set-group-ID processing,
148the effective user ID is recorded as the saved set-user-ID,
149and the effective group ID is recorded as the saved set-group-ID.
150These values may be used in changing the effective IDs later (see
151.Xr setuid 2 ) .
152The set-user-ID and set-group-ID bits have no effect if the
153new process image file is located on a file system mounted with
154the nosuid flag.
155The process will be started without the new permissions.
156.Pp
157The new process also inherits the following attributes from
158the calling process:
159.Pp
160.Bl -tag -width controlling_terminal -offset indent -compact
161.It process ID
162see
163.Xr getpid 2
164.It parent process ID
165see
166.Xr getppid 2
167.It process group ID
168see
169.Xr getpgrp 2
170.It session ID
171see
172.Xr getsid 2
173.It access groups
174see
175.Xr getgroups 2
176.It working directory
177see
178.Xr chdir 2
179.It root directory
180see
181.Xr chroot 2
182.It controlling terminal
183see
184.Xr termios 4
185.It resource usages
186see
187.Xr getrusage 2
188.It interval timers
189see
190.Xr getitimer 2
191(unless process image file is setuid or setgid,
192in which case all timers are disabled)
193.It resource limits
194see
195.Xr getrlimit 2
196.It file mode mask
197see
198.Xr umask 2
199.It signal mask
200see
201.Xr sigaction 2 ,
202.Xr sigprocmask 2
203.El
204.Pp
205When a program is executed as a result of an
206.Fn execve
207call, it is entered as follows:
208.Pp
209.Dl main(int argc, char **argv, char **envp)
210.Pp
211where
212.Fa argc
213is the number of elements in
214.Fa argv
215(the
216.Dq arg count )
217and
218.Fa argv
219points to the array of character pointers
220to the arguments themselves.
221.Sh RETURN VALUES
222As the
223.Fn execve
224function overlays the current process image
225with a new process image, the successful call
226has no process to return to.
227If
228.Fn execve
229does return to the calling process, an error has occurred; the
230return value will be \-1 and the global variable
231.Va errno
232is set to indicate the error.
233.Sh ERRORS
234.Fn execve
235will fail and return to the calling process if:
236.Bl -tag -width Er
237.It Bq Er ENOTDIR
238A component of the path prefix is not a directory.
239.It Bq Er ENAMETOOLONG
240A component of a pathname exceeded
241.Dv NAME_MAX
242characters, or an entire pathname (including the terminating NUL)
243exceeded
244.Dv PATH_MAX
245bytes.
246.It Bq Er ENOENT
247The new process file does not exist.
248.It Bq Er ELOOP
249Too many symbolic links were encountered in translating the pathname.
250.It Bq Er EACCES
251Search permission is denied for a component of the path prefix.
252.It Bq Er EACCES
253The new process file is not an ordinary file.
254.It Bq Er EACCES
255The new process file mode denies execute permission.
256.It Bq Er EACCES
257The new process file is on a filesystem mounted with execution
258disabled
259.Pf ( Dv MNT_NOEXEC
260in
261.In sys/mount.h ) .
262.It Bq Er EACCES
263The new process file is marked with
264.Xr ld 1
265.Fl z Cm wxneeded
266to allow W^X violating operations, but it is located on a file
267system which does not allow such operations (because it is mounted
268without the
269.Xr mount 8
270.Fl o Cm wxallowed
271flag).
272.It Bq Er EACCES
273The parent used
274.Xr pledge 2
275to declare an
276.Va execpromise ,
277and that is not permitted for setuid or setgid images.
278.It Bq Er ENOEXEC
279The new process file has the appropriate access
280permission, but has an invalid magic number in its header.
281.It Bq Er ETXTBSY
282The new process file is a pure procedure (shared text)
283file that is currently open for writing by some process.
284.It Bq Er ENOMEM
285The new process requires more virtual memory than
286is allowed by the imposed maximum
287.Pq Xr getrlimit 2 .
288.It Bq Er E2BIG
289The number of bytes in the new process's argument list
290is larger than the system-imposed limit.
291The limit in the system as released is 524288 bytes
292.Pq Dv ARG_MAX .
293.It Bq Er EFAULT
294The new process file is not as long as indicated by
295the size values in its header.
296.It Bq Er EFAULT
297.Fa path ,
298.Fa argv ,
299or
300.Fa envp
301point
302to an illegal address.
303.It Bq Er EINVAL
304.Fa argv
305did not contain at least one element.
306.It Bq Er EIO
307An I/O error occurred while reading from the file system.
308.It Bq Er ENFILE
309During startup of an
310.Ar interpreter ,
311the system file table was found to be full.
312.El
313.Sh SEE ALSO
314.Xr _exit 2 ,
315.Xr fork 2 ,
316.Xr execl 3 ,
317.Xr exit 3 ,
318.Xr elf 5 ,
319.Xr environ 7
320.Sh STANDARDS
321The
322.Fn execve
323function is expected to conform to
324.St -p1003.1-2024 ,
325except that the
326.Dv FD_CLOFORK
327flag is cleared on all file descriptors.
328(The behavior required by the standard is not safe and
329was reported as a defect by
330.Ox . )
331.Sh HISTORY
332The predecessor of these functions, the former
333.Fn exec
334system call, first appeared in
335.At v1 .
336The
337.Fn execve
338function first appeared in
339.At v7 .
340.Sh CAVEATS
341If a program is
342.Em setuid
343to a non-superuser, but is executed when the real
344.Em uid
345is
346.Dq root ,
347then the process has some of the powers of a superuser as well.
348.Pp
349.St -p1003.1-2008
350permits
351.Nm
352to leave
353.Dv SIGCHLD
354as ignored in the new process; portable programs cannot rely on
355.Nm
356resetting it to the default disposition.