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 current process. path can be a partial or complete path. A partial pathname 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 character 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 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 environ(7)).

The parameter cmdline is functionally equivalent to argv, but it is implemented as a single string consisting of a list of whitespace delimited arguments. C programs parse cmdline automatically, and the individual pieces can be accessed through the argc/argv arguments to main().

cmdline can be accessed from assembly langugage through the X (high-order 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 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 shellid(3). The A register is set to the userID allocated for the process.

GS/OS prefixes 1 and 9 are set to the pathname of the directory containing the executable file; if the length of path exceeds 64 characters prefix 1 is set to the null prefix (length 0). The following information 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 replaced 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 argument 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 implemented as a library routine on top of _execve. Consequently, any environment information passed in by envp will modify the environment of the parent process as well as that of the child process. It is possible to use environPush(3) in the parent process before the fork, followed 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 Manual.

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 implementation 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 distribution as of v2.0.6.