mirror of https://github.com/GnoConsortium/gno.git
216 lines
6.5 KiB
Groff
216 lines
6.5 KiB
Groff
.\" This man page was orginally written to conform with the lenviron v1.1.3
|
|
.\" release for Gno v2.0.3 by Devin Reade. As of GNO v2.0.6 it is now
|
|
.\" part of libc.
|
|
.\"
|
|
.\" $Id: execve.2,v 1.2 1998/01/25 18:03:27 gdr-ftp Exp $
|
|
.\"
|
|
.TH EXECVE 2 "19 January 1997" GNO "System Calls"
|
|
.SH NAME
|
|
.BR execve ,
|
|
.BR _execve ,
|
|
\- replace current process with an executable image from a file
|
|
.SH SYNOPSIS
|
|
#include <unistd.h>
|
|
.sp 1
|
|
int
|
|
\fB_execve\fR(const char *\fIpath\fR, const char *\fIcmdline\fR);
|
|
.br
|
|
int
|
|
\fBexecve\fR(const char *\fIpath\fR, char * const *\fIargv\fR,
|
|
char * const *\fIenvp\fR);
|
|
.SH DESCRIPTION
|
|
The
|
|
.B exec
|
|
family of calls,
|
|
.IR not
|
|
including
|
|
.BR exec (3),
|
|
are the preferred
|
|
method for loading program files to be executed under the GNO system.
|
|
This manual page describes
|
|
.BR execve (2)
|
|
and
|
|
.BR _execve (2).
|
|
(See the section on HISTORY, below.)
|
|
All other calls in the exec family are implemented in terms of
|
|
.BR _execve .
|
|
.LP
|
|
A new userID is allocated for the process, and the GS/OS System Loader
|
|
is used to bring the executable file specified by pathname into memory.
|
|
The executable loaded replaces the executable associated with the
|
|
current process.
|
|
.I path
|
|
can be a partial or complete path. A partial pathname
|
|
will suffice only if the file resides in the current directory.
|
|
.LP
|
|
If the executable file does not contain an OMF Stack
|
|
Segment (SEGKIND = $12), a default stack of 4096 bytes
|
|
is allocated to the process. The direct-page pointer
|
|
is set to the bottom of the stack memory (for C
|
|
programs this is irrelevant).
|
|
.LP
|
|
The argument
|
|
.I 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 (a copy is actually passed). 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 \fIpath\fR).
|
|
.LP
|
|
The argument
|
|
.I 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
|
|
.I environ
|
|
if
|
|
.BR environInit (3)
|
|
has been previously called. (If not, then the same
|
|
information still resides in the shell's internal variables.)
|
|
These strings pass information to the new process that is not directly
|
|
an argument to the command (see
|
|
.IR environ (7)).
|
|
.LP
|
|
The parameter
|
|
.IR cmdline
|
|
is functionally equivalent to
|
|
.IR argv ,
|
|
but it is implemented as a single string consisting of a list of
|
|
whitespace delimited arguments. C programs parse
|
|
.IR cmdline
|
|
automatically, and the individual pieces can be accessed through
|
|
the argc/argv arguments to main().
|
|
.LP
|
|
.I cmdline
|
|
can be accessed from assembly
|
|
langugage through the X (high-order word of \fIcmdline\fR) and Y
|
|
(low-order word) registers. See
|
|
.BR parsearg (3)
|
|
for a method of parsing the command line under assembly language.
|
|
.LP
|
|
If the executable file is of filetype S16 ($B3), the
|
|
.IR cmdline
|
|
argument is ignored and
|
|
the X&Y registers are set to null (i.e. the command line is only
|
|
passed to an EXE executable). The 8 characters
|
|
.BR BYTEWRKS
|
|
are prepended to
|
|
.I cmdline
|
|
before being passed to the process (this is the same identifier used
|
|
by ORCA/Shell). This Shell Identifier distinguishes the GNO and ORCA
|
|
environments from others that don't support the full range of shell
|
|
calls, and can be accessed from C with the library function
|
|
.BR shellid (3).
|
|
The A register is set to the userID allocated for the process.
|
|
.LP
|
|
GS/OS prefixes 1 and 9 are set to the pathname of the
|
|
directory containing the executable file; if the length of
|
|
.IR path
|
|
exceeds 64 characters prefix 1 is set to the null prefix (length 0).
|
|
The following information is inherited by the child:
|
|
.RS
|
|
.nf
|
|
|
|
current machine state;
|
|
controlling TTY;
|
|
process group ID; and
|
|
prefixes 0 and 8.
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Caught signals are reset to the default action.
|
|
Ignored signals remain ignored across the
|
|
.BR execve .
|
|
Any signals in the parent's queue are not passed to the
|
|
child, and the child is started with no signals blocked.
|
|
The child inherits all the open files of its parent.
|
|
.SH RETURN VALUE
|
|
A successful
|
|
.BR execve
|
|
does not return, as the current executable is replaced with the one
|
|
specified in the call. If for some reason the call fails,
|
|
.BR execve
|
|
returns -1 and sets
|
|
.BR errno
|
|
to indicate the error.
|
|
.SH ERRORS
|
|
.IP \fBENOENT\fR
|
|
The filename specified does not exist.
|
|
.IP \fBENOMEM\fR
|
|
Could not allocate necessary memory to build arguments.
|
|
.IP \fBEIO\fR
|
|
Some general I/O error occurred trying to load the executable.
|
|
.SH NOTES
|
|
Since all of the exec family calls are implemented using \fI_execve\fR,
|
|
if a single string consisting of all arguments is already available then
|
|
calling \fI_execve\fR is the most efficient choice. If, however, the
|
|
argument list must be constructed, then an appropriate choice of one
|
|
of the other exec family functions should be made.
|
|
.LP
|
|
Use of the \fIexec\fR(3) call is discouraged; this call is provided only
|
|
for backward compatibility.
|
|
.SH BUGS
|
|
.IR execve
|
|
is not currently implemented in the kernel; instead it is implemented
|
|
as a library routine on top of
|
|
.BR _execve .
|
|
Consequently, any environment information passed in by
|
|
.IR envp
|
|
will modify the environment of the parent process as well as that of
|
|
the child process. It is possible to use
|
|
.BR environPush (3)
|
|
in the parent process before the
|
|
.BR fork ,
|
|
followed by a
|
|
.BR environPop (3)
|
|
in the parent after child has had a chance to
|
|
.BR execve ,
|
|
however this is normally a race condition and the result is therefore
|
|
indeterminant.
|
|
.LP
|
|
Programs compiled with ORCA/C v1.3 (and earlier) ignore any stack space
|
|
allocated by the GS/OS Loader (which
|
|
.BR _execve
|
|
calls. Stack space in ORCA/C programs is determined by code in the
|
|
.BR "*.root"
|
|
object file, and can be set with the
|
|
.BR "#pragma stacksize"
|
|
directive. Read the chapter on GNO Compliance in the
|
|
.I "GNO Kernel Reference Manual"
|
|
for more information on this topic. ORCA/C v2.0 and later versions use
|
|
the system-provided stack space.
|
|
.SH SEE ALSO
|
|
.BR exit (2),
|
|
.BR fork (2),
|
|
.BR ioctl (2),
|
|
.BR wait (2),
|
|
.BR exec (3),
|
|
.BR execl (3),
|
|
.BR environInit (3),
|
|
.BR environPush (3),
|
|
.BR tty (4),
|
|
.BR environ (7),
|
|
and the
|
|
.IR "GNO Kernel Reference Manual" .
|
|
.SH HISTORY
|
|
The
|
|
.B _execve
|
|
function call appeared in GNO versions 1.0 through 2.0.4 inclusive
|
|
under the name
|
|
.BR execve .
|
|
.LP
|
|
The
|
|
.B execve
|
|
function call appeared in 4.2BSD.
|
|
The first GNO implementation was part of the
|
|
.BR lenviron
|
|
library by Devin Reade, written for GNO v2.0.3.
|
|
.LP
|
|
These implementations of
|
|
.BR _execve
|
|
and
|
|
.BR execve
|
|
became part of the GNO distribution as of v2.0.6.
|