206 lines
5.8 KiB
Groff
206 lines
5.8 KiB
Groff
.\" Copyright (c) 1980 Regents of the University of California.
|
|
.\" All rights reserved. The Berkeley software License Agreement
|
|
.\" specifies the terms and conditions for redistribution.
|
|
.\"
|
|
.\" @(#)execve.2 6.7 (Berkeley) 5/22/86
|
|
.\"
|
|
.TH EXECVE 2 "May 22, 1986"
|
|
.UC 4
|
|
.SH NAME
|
|
execve \- execute a file
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <unistd.h>
|
|
|
|
int execve(const char *\fIname\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[])
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.B Execve
|
|
transforms the calling process into a new process.
|
|
The new process is constructed from an ordinary file
|
|
called the \fInew process file\fP.
|
|
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
|
|
.BR a.out (5).
|
|
.PP
|
|
An interpreter file begins with a line of the form ``#! \fIinterpreter\fP''.
|
|
When an interpreter file is
|
|
.BR execve\| 'd,
|
|
the system \fBexecve\fP\|'s the specified \fIinterpreter\fP, giving
|
|
it the name of the originally exec'd file as an argument and
|
|
shifting over the rest of the original arguments.
|
|
.PP
|
|
There can be no return from a successful \fBexecve\fP because the calling
|
|
core image is lost.
|
|
This is the mechanism whereby different process images become active.
|
|
.PP
|
|
The argument \fIargv\fP is a null-terminated array of character pointers
|
|
to null-terminated character strings. These strings constitute
|
|
the argument list to be made available to the new
|
|
process. By convention, at least one argument must be present in
|
|
this array, and the first element of this array should be
|
|
the name of the executed program (i.e., the last component of \fIname\fP).
|
|
.PP
|
|
The argument \fIenvp\fP is also a null-terminated array of character pointers
|
|
to null-terminated strings. These strings pass information to the
|
|
new process that is not directly an argument to the command (see
|
|
.BR environ (7)).
|
|
.PP
|
|
Descriptors open in the calling process remain open in
|
|
the new process, except for those for which the close-on-exec
|
|
flag is set (see
|
|
.BR close (2)).
|
|
Descriptors that remain open are unaffected by
|
|
.BR execve .
|
|
.PP
|
|
Ignored signals remain ignored across an
|
|
.BR execve ,
|
|
but signals that are caught are reset to their default values.
|
|
Blocked signals remain blocked regardless of changes to the signal action.
|
|
The signal stack is reset to be undefined (see
|
|
.BR sigaction (2)
|
|
for more information).
|
|
.PP
|
|
Each process has
|
|
.I real
|
|
user and group IDs and an
|
|
.I effective
|
|
user and group IDs. The
|
|
.I real
|
|
ID identifies the person using the system; the
|
|
.I effective
|
|
ID determines his access privileges.
|
|
.B Execve
|
|
changes the effective user and group ID to
|
|
the owner of the executed file if the file has the \*(lqset-user-ID\*(rq
|
|
or \*(lqset-group-ID\*(rq modes. The
|
|
.I real
|
|
user ID is not affected.
|
|
.PP
|
|
The new process also inherits the following attributes from
|
|
the calling process:
|
|
.PP
|
|
.in +5n
|
|
.nf
|
|
.ta +2i
|
|
process ID see \fBgetpid\fP\|(2)
|
|
parent process ID see \fBgetppid\fP\|(2)
|
|
process group ID see \fBgetpgrp\fP\|(2)
|
|
access groups see \fBgetgroups\fP\|(2)
|
|
working directory see \fBchdir\fP\|(2)
|
|
root directory see \fBchroot\fP\|(2)
|
|
control terminal see \fBtty\fP\|(4)
|
|
alarm timer see \fBalarm\fP\|(2)
|
|
file mode mask see \fBumask\fP\|(2)
|
|
signal mask see \fBsigaction\fP\|(2), \fBsigprocmask\fP\|(2)
|
|
.in -5n
|
|
.fi
|
|
.PP
|
|
When the executed program begins, it is called as follows:
|
|
.PP
|
|
.RS
|
|
.ft B
|
|
.nf
|
|
int main(int \fIargc\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]);
|
|
|
|
exit(main(\fIargc\fP, \fIargv\fP, \fIenvp\fP));
|
|
.fi
|
|
.ft R
|
|
.RE
|
|
.PP
|
|
where
|
|
.I argc
|
|
is the number of elements in \fIargv\fP
|
|
(the ``arg count'')
|
|
and
|
|
.I argv
|
|
is the array of character pointers
|
|
to the arguments themselves.
|
|
.PP
|
|
.I Envp
|
|
is a pointer to an array of strings that constitute
|
|
the
|
|
.I environment
|
|
of the process.
|
|
A pointer to this array is also stored in the global variable ``environ''.
|
|
Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value.
|
|
The array of pointers is terminated by a null pointer.
|
|
The shell
|
|
.BR sh (1)
|
|
passes an environment entry for each global shell variable
|
|
defined when the program is called.
|
|
See
|
|
.BR environ (7)
|
|
for some conventionally
|
|
used names.
|
|
.SH "RETURN VALUE
|
|
If
|
|
.B execve
|
|
returns to the calling process an error has occurred; the
|
|
return value will be \-1 and the global variable
|
|
.B errno
|
|
will contain an error code.
|
|
.SH ERRORS
|
|
.B Execve
|
|
will fail and return to the calling process if one or more
|
|
of the following are true:
|
|
.TP 15
|
|
[ENOTDIR]
|
|
A component of the path prefix is not a directory.
|
|
.TP 15
|
|
[ENAMETOOLONG]
|
|
The path name exceeds PATH_MAX characters.
|
|
.TP 15
|
|
[ENOENT]
|
|
The new process file does not exist.
|
|
.TP 15
|
|
[ELOOP]
|
|
Too many symbolic links were encountered in translating the pathname.
|
|
(Minix-vmd)
|
|
.TP 15
|
|
[EACCES]
|
|
Search permission is denied for a component of the path prefix.
|
|
.TP 15
|
|
[EACCES]
|
|
The new process file is not an ordinary file.
|
|
.TP 15
|
|
[EACCES]
|
|
The new process file mode denies execute permission.
|
|
.TP 15
|
|
[ENOEXEC]
|
|
The new process file has the appropriate access
|
|
permission, but has an invalid magic number in its header.
|
|
.TP 15
|
|
[ENOMEM]
|
|
The new process requires more (virtual) memory than
|
|
is currently available.
|
|
.TP 15
|
|
[E2BIG]
|
|
The number of bytes in the new process's argument list
|
|
is larger than the system-imposed limit ARG_MAX.
|
|
The limit in the system as released is 4096 bytes for
|
|
16-bit Minix, 16384 bytes for 32-bit Minix, and unlimited for Minix-vmd.
|
|
.TP 15
|
|
[EFAULT]
|
|
\fIPath\fP\|, \fIargv\fP\|, or \fIenvp\fP point
|
|
to an illegal address.
|
|
.TP 15
|
|
[EIO]
|
|
An I/O error occurred while reading from the file system.
|
|
.SH CAVEATS
|
|
If a program is
|
|
.I setuid
|
|
to a non-super-user, but is executed when
|
|
the real \fBuid\fP is ``root'', then the program has some of the powers
|
|
of a super-user as well.
|
|
.SH "SEE ALSO"
|
|
.BR exit (2),
|
|
.BR fork (2),
|
|
.BR execl (3),
|
|
.BR environ (7).
|