.\" 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.1 1997/02/27 07:32:12 gdr 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 .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.