EXECVE(2) System Calls EXECVE(2)
NAME
execve, _execve, - replace current process with an executable image
from a file
SYNOPSIS
#include <unistd.h>
int _execve(const char *path, const char *cmdline);
int execve(const char *path, char * const *argv, char * const *envp);
DESCRIPTION
The exec family of calls, not including exec(3), are the preferred
method for loading program files to be executed under the GNO system.
This manual page describes execve(2) and _execve(2). (See the section
on HISTORY, below.) All other calls in the exec family are implemented
in terms of _execve.
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 cur‐
rent process. path can be a partial or complete path. A partial path‐
name will suffice only if the file resides in the current directory.
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).
The argument 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 path).
The argument envp is also a pointer to a null-terminated array of char‐
acter pointers to null-terminated strings. A pointer to this array is
normally stored in the global variable environ if environInit(3) has
been previously called. (If not, then the same information still re‐
sides in the shell's internal variables.) These strings pass informa‐
tion to the new process that is not directly an argument to the command
(see environ(7)).
The parameter cmdline is functionally equivalent to argv, but it is im‐
plemented as a single string consisting of a list of whitespace delim‐
ited arguments. C programs parse cmdline automatically, and the indi‐
vidual pieces can be accessed through the argc/argv arguments to
main().
cmdline can be accessed from assembly langugage through the X (high-or‐
der word of cmdline) and Y (low-order word) registers. See parsearg(3)
for a method of parsing the command line under assembly language.
If the executable file is of filetype S16 ($B3), the 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 BYTEWRKS are
prepended to cmdline before being passed to the process (this is the
same identifier used by ORCA/Shell). This Shell Identifier distin‐
guishes 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 li‐
brary function shellid(3). The A register is set to the userID allo‐
cated for the process.
GS/OS prefixes 1 and 9 are set to the pathname of the directory con‐
taining the executable file; if the length of path exceeds 64 charac‐
ters prefix 1 is set to the null prefix (length 0). The following in‐
formation is inherited by the child:
current machine state;
controlling TTY;
process group ID; and
prefixes 0 and 8.
Caught signals are reset to the default action. Ignored signals remain
ignored across the 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.
RETURN VALUE
A successful execve does not return, as the current executable is re‐
placed with the one specified in the call. If for some reason the call
fails, execve returns -1 and sets errno to indicate the error.
ERRORS
ENOENT The filename specified does not exist.
ENOMEM Could not allocate necessary memory to build arguments.
EIO Some general I/O error occurred trying to load the executable.
NOTES
Since all of the exec family calls are implemented using _execve, if a
single string consisting of all arguments is already available then
calling _execve is the most efficient choice. If, however, the argu‐
ment list must be constructed, then an appropriate choice of one of the
other exec family functions should be made.
Use of the exec(3) call is discouraged; this call is provided only for
backward compatibility.
BUGS
execve is not currently implemented in the kernel; instead it is imple‐
mented as a library routine on top of _execve. Consequently, any envi‐
ronment information passed in by envp will modify the environment of
the parent process as well as that of the child process. It is possi‐
ble to use environPush(3) in the parent process before the fork, fol‐
lowed by a environPop(3) in the parent after child has had a chance to
execve, however this is normally a race condition and the result is
therefore indeterminant.
Programs compiled with ORCA/C v1.3 (and earlier) ignore any stack space
allocated by the GS/OS Loader (which _execve calls. Stack space in
ORCA/C programs is determined by code in the *.root object file, and
can be set with the #pragma stacksize directive. Read the chapter on
GNO Compliance in the GNO Kernel Reference Manual for more information
on this topic. ORCA/C v2.0 and later versions use the system-provided
stack space.
SEE ALSO
exit(2), fork(2), ioctl(2), wait(2), exec(3), execl(3), environInit(3),
environPush(3), tty(4), environ(7), and the GNO Kernel Reference Man
ual.
HISTORY
The _execve function call appeared in GNO versions 1.0 through 2.0.4
inclusive under the name execve.
The execve function call appeared in 4.2BSD. The first GNO implementa‐
tion was part of the lenviron library by Devin Reade, written for GNO
v2.0.3.
These implementations of _execve and execve became part of the GNO dis‐
tribution as of v2.0.6.
GNO 19 January 1997 EXECVE(2)
Man(1) output converted with
man2html