gno/usr.man/man2/execve.2

.\" 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.