diff options
Diffstat (limited to 'static/netbsd/man2/execve.2')
| -rw-r--r-- | static/netbsd/man2/execve.2 | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/static/netbsd/man2/execve.2 b/static/netbsd/man2/execve.2 new file mode 100644 index 00000000..4890cf3b --- /dev/null +++ b/static/netbsd/man2/execve.2 @@ -0,0 +1,399 @@ +.\" $NetBSD: execve.2,v 1.48 2025/07/17 17:16:07 kre Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)execve.2 8.5 (Berkeley) 6/1/94 +.\" +.Dd July 8, 2025 +.Dt EXECVE 2 +.Os +.Sh NAME +.Nm execve , +.Nm fexecve +.Nd execute a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" +.Sh DESCRIPTION +The +.Fn execve +system call +transforms the calling process into a new process. +The new process is constructed from an ordinary file, +whose name is pointed to by +.Fa path , +called the +.Em new process file . +The +.Fn fexecve +system call is equivalent to +.Fn execve +except that the file to be executed is determined by the file +descriptor +.Fa fd +instead of a +.Fa path . +This file is either an executable object file, +or a file of data for an interpreter. +An executable object file consists of an identifying header, +followed by pages of data representing the initial program (text) +and initialized data pages. +Additional pages may be specified +by the header to be initialized with zero data; see +.Xr elf 5 +and +.Xr a.out 5 . +.Pp +An interpreter file begins with a line of the form: +.Bd -ragged -offset indent +.Ic \&#! Ns Ar interpreter Op Ar arg +.Ed +.Pp +When an interpreter file is +.Nm Ap d , +the system actually +.Nm Ap s +the specified +.Ar interpreter . +If the optional +.Ar arg +is specified, it becomes the first argument to the +.Ar interpreter , +and the name of the originally +.Nm Ap d +file becomes the second argument; +otherwise, the name of the originally +.Nm Ap d +file becomes the first argument. +The original arguments are shifted over to become the subsequent arguments. +The zeroth argument, normally the name of the +.Nm Ap d +file, is left unchanged. +The interpreter named by +.Ar interpreter +must not itself be an interpreter file. +(See +.Xr script 7 +for a detailed discussion of interpreter file execution.) +.Pp +The argument +.Fa argv +is a pointer to a null-terminated array of +character pointers to null-terminated character strings. +These strings construct the argument list to be made available to the new +process. +At least one argument must be present in +the array; by custom, the first element should be +the name of the executed program (for example, the last component of +.Fa path ) . +.Pp +The argument +.Fa envp +is also a pointer to a null-terminated array of +character pointers to null-terminated strings. +A pointer to this array is normally stored in the global variable +.Va environ . +These strings pass information to the +new process that is not directly an argument to the command +.Pq see Xr environ 7 . +.Pp +File descriptors open in the calling process image remain open in +the new process image, except for those for which the close-on-exec +flag is set (see +.Xr close 2 +and +.Xr fcntl 2 ) +which are closed. +Descriptors that remain open are unaffected by +.Fn execve , +except that the close-on-fork flag +is cleared from all descriptors remaining open. +.Pp +In the case of a new setuid or setgid executable being executed, if +file descriptors 0, 1, or 2 +.Po +representing +.Em stdin , stdout , +and +.Em stderr +.Pc +are currently unallocated, these descriptors will be opened to point to +some system file like +.Pa /dev/null . +The intent is to ensure these descriptors are not unallocated, since +many libraries make assumptions about the use of these three file descriptors. +.Pp +Signals set to be ignored in the calling process are set to be ignored in +the new process. +Signals which are set to be caught in the calling process image +are set to default action in the new process image. +Blocked signals remain blocked regardless of changes to the signal action. +The signal stack is reset to be undefined (see +.Xr sigaction 2 +for more information). +.Pp +If the set-user-ID mode bit of the new process image file is set +.Pq see Xr chmod 2 , +the effective user ID of the new process image is set to the owner ID +of the new process image file. +If the set-group-ID mode bit of the new process image file is set, +the effective group ID of the new process image is set to the group ID +of the new process image file. +(The effective group ID is the first element of the group list.) +The real user ID, real group ID and +other group IDs of the new process image remain the same as the calling +process image. +After any set-user-ID and set-group-ID processing, +the effective user ID is recorded as the saved set-user-ID, +and the effective group ID is recorded as the saved set-group-ID. +These values may be used in changing the effective IDs later +.Pq see Xr setuid 2 . +The set-ID bits are not honored if the respective file system has the +.Cm nosuid +option enabled or if the new process file is an interpreter file. +Syscall +tracing is disabled if effective IDs are changed. +.Pp +The new process also inherits the following attributes from +the calling process: +.Pp +.Bl -column "parent process ID" -offset indent -compact +.It process ID Ta see Xr getpid 2 +.It parent process ID Ta see Xr getppid 2 +.It process group ID Ta see Xr getpgrp 2 +.It access groups Ta see Xr getgroups 2 +.It working directory Ta see Xr chdir 2 +.It root directory Ta see Xr chroot 2 +.It control terminal Ta see Xr termios 4 +.It resource usages Ta see Xr getrusage 2 +.It interval timers Ta see Xr getitimer 2 +.It resource limits Ta see Xr getrlimit 2 +.It file mode mask Ta see Xr umask 2 +.It signal mask Ta see Xr sigaction 2 , Xr sigprocmask 2 +.El +.Pp +When a program is executed as a result of an +.Fn execve +system call, it is entered as follows: +.Bd -literal -offset indent +main(argc, argv, envp) +int argc; +char **argv, **envp; +.Ed +.Pp +where +.Fa argc +.Pq the Dq arg count +is the number of elements in +.Fa argv , +and +.Fa argv +points to the array of character pointers +to the arguments themselves. +.Pp +The +.Fn fexecve +function ignores the file offset of +.Fa fd . +Since execute permission is checked by +.Fn fexecve , +the file descriptor +.Fa fd +need not have been opened with the +.Dv O_EXEC +flag. +However, if the file to be executed denies read permission for the process +preparing to do the exec, the only way to provide the +.Fa fd +to +.Fn fexecve +is to use the +.Dv O_EXEC +flag when opening +.Fa fd . +Note that the file to be executed can not be open for writing. +.Sh RETURN VALUES +As the +.Fn execve +system call overlays the current process image +with a new process image the successful call +has no process to return to. +If +.Fn execve +does return to the calling process an error has occurred; the +return value will be \-1 and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn execve +system call +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er E2BIG +The number of bytes in the new process' argument list +is larger than the system-imposed limit. +The default compile time limit is 262144 bytes and is specified +in the variable +.Dv NCARGS +in +.In sys/param.h +and get be read from the +.Xr sysctl 3 +MIB variable +.Dv KERN_ARGMAX . +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, +the new process file is not an ordinary file, +its file mode denies execute permission, or +it is on a file system mounted with execution +disabled +.Po +.Dv MNT_NOEXEC +in +.In sys/mount.h +.Pc . +.It Bq Er EAGAIN +A +.Xr setuid 7 +process has exceeded the current resource limit for the number of +processes it is allowed to run concurrently. +.It Bq Er EFAULT +The new process file is not as long as indicated by +the size values in its header; or +the +.Fa path , +.Fa argv , +or +.Fa envp +arguments point to an illegal address. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters, or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The new process file does not exist, or +the new process file is a script starting with +.Ql #! +and the script interpreter does not exist. +.It Bq Er ENOEXEC +The new process file has the appropriate access +permission, but has an invalid magic number in its header. +.It Bq Er ENOMEM +The new process requires more virtual memory than +is allowed by the imposed maximum +.Pq Xr getrlimit 2 . +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ETXTBSY +The new process file is a pure procedure (shared text) +file that is currently open for writing or reading by some process. +.El +.Pp +In addition, the +.Fn fexecve +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor open for executing. +.El +.Sh SEE ALSO +.Xr _exit 2 , +.Xr fcntl 2 , +.Xr fork 2 , +.Xr open 2 , +.Xr execl 3 , +.Xr exit 3 , +.Xr sysctl 3 , +.Xr a.out 5 , +.Xr elf 5 , +.\" .Xr fdescfs 5 , +.Xr environ 7 , +.Xr script 7 , +.Xr mount 8 +.Sh STANDARDS +The +.Fn execve +system call conforms to +.St -p1003.1-2001 . +with the exception of reopening descriptors 0, 1, and/or 2 in certain +circumstances. +A future update of the Standard is expected to require this behavior, +and it may become the default for non-privileged processes as well. +.\" NB: update this caveat when TC1 is blessed. +The support for executing interpreted programs is an extension. +The +.Fn fexecve +system call conforms to The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn execve +function call first appeared in +.At v7 . +The +.Fn fexecve +system call appeared in +.Nx 10.0 . +.Sh BUGS +If a program is +.Em setuid +to a non-super-user, but is executed when +the real +.Em uid +is +.Dq root , +then the program has some of the powers of a super-user as well. +.\" .Pp +.\" When executing an interpreted program through +.\" .Fn fexecve , +.\" kernel supplies +.\" .Pa /dev/fd/n +.\" as a second argument to the interpreter, +.\" where +.\" .Ar n +.\" is the file descriptor passed in the +.\" .Fa fd +.\" argument to +.\" .Fn fexecve . +.\" For this construction to work correctly, the +.\" .Xr fdescfs 5 +.\" filesystem shall be mounted on +.\" .Pa /dev/fd . |