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
       resides in the shell's internal variables.)  These strings pass  infor-
       mation  to the new process that is not directly an argument to the com-
       mand (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 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
       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 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
       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 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