unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

EXECVE(2V)                                                          EXECVE(2V)



NAME
       execve - execute a file

SYNOPSIS
       int execve(path, argv, envp)
       char *path, *argv[], *envp[];

DESCRIPTION
       execve()  transforms  the  calling process into a new process.  The new
       process is constructed from an ordinary file, whose name is pointed  to
       by  path,  called  the  new  process file.  This file is either an exe-
       cutable object file, or a file of data for  an  interpreter.   An  exe-
       cutable  object  file  consists  of  an identifying header, followed by
       pages of data representing the initial program (text)  and  initialized
       data pages.  Additional pages may be specified by the header to be ini-
       tialized with zero data.  See a.out(5).

       An interpreter file begins with a line  of  the  form  `#!  interpreter
       [arg]'.  Only the first thirty-two characters of this line are signifi-
       cant.  When path refers to an interpreter file,  execve()  invokes  the
       specified  interpreter.   If  the optional arg is specified, it becomes
       the first argument to the interpreter, and the pathname to  which  path
       points  becomes  the second argument.  Otherwise, the pathname to which
       path points becomes the first argument.   The  original  arguments  are
       shifted  over to become the subsequent arguments.  The zeroth argument,
       normally the pathname to which path points, is left unchanged.

       There can be no return from a successful execve() because  the  calling
       process image is lost.  This is the mechanism whereby different process
       images become active.

       The argument argv is a pointer to a null-terminated array of  character
       pointers  to  null-terminated character strings.  These strings consti-
       tute the argument list to be made available to  the  new  process.   By
       convention,  at  least  one argument must be present in this array, and
       the first element of this array should be the name of the executed pro-
       gram (that is, 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.  These strings pass informa-
       tion to the new process which are not directly arguments to the command
       (see environ(5V)).

       The number of bytes available for the new process's  combined  argument
       and  environment lists (including null terminators, pointers and align-
       ment  bytes)  is  {ARG_MAX}  (see  sysconf(2V)).   On  SunOS   systems,
       {ARG_MAX} is currently one megabyte.

       Descriptors open in the calling process remain open in the new process,
       except for those for which the close-on-exec flag is set (see close(2V)
       and  fcntl(2V)).   Descriptors  which  remain  open  are  unaffected by
       execve().

       Signals set to the default action  (SIG_DFL)  in  the  calling  process
       image  are set to the default action in the new process image.  Signals
       set to be ignored (SIG_IGN) by the calling process image are ignored by
       the new process image.  Signals set to be caught by the calling process
       image are reset to the default action in the new process  image.   Sig-
       nals  set  to be blocked in the calling process image remain blocked in
       the new process image, regardless of changes to the signal action.  The
       signal  stack is reset to be undefined (see sigvec(2) for more informa-
       tion).

       Each process has a real user ID and group ID and an effective  user  ID
       and  group ID.  The real ID identifies the person using the system; the
       effective ID determines their access privileges.  execve() changes  the
       effective  user  or group ID to the owner or group of the executed file
       if the file has the "set-user-ID" or "set-group-ID"  modes.   The  real
       UID  and  GID  are  not  affected.  The effective user ID and effective
       group ID of the new process image are saved as  the  saved  set-user-ID
       and saved set-group-ID respectively, for use by setuid(3V).

       execve()  sets  the  SEXECED  flag  for  the  new  process  image  (see
       setpgid(2V)).

       The shared memory segments attached to the calling process will not  be
       attached to the new process (see shmop(2)).

       Profiling is disabled for the new process; see profil(2).

       Upon  successful  completion,  execve()  marks  for update the st_atime
       field of the file.  execve() also  marks  st_atime  for  update  if  it
       fails, but is able find the process image file.

       If execve() succeeds, the process image file is considered to have been
       opened (see open(2V)).  The corresponding close (see close(2V)) is con-
       sidered to occur after the open, but before process termination or suc-
       cessful completion of a subsequent call to execve().

       The new process also inherits the following attributes from the calling
       process:

              lI  lI  l  l  .   attribute see  process ID     getpid(2) parent
              process   ID   getpid(2)   process   group    ID    getpgrp(2V),
              setpgid(2V)     session    membership  setsid(2)    real    user
              ID   getuid(2)  real  group  ID  getgid(2)  supplementary  group
              IDs  Intro(2)  time  left until an alarm alarm(3C) supplementary
              group IDs getgroups(2) semadj  values  semop(2)  working  direc-
              tory   chdir(2)   root  directory chroot(2)  controlling  termi-
              nal     termio(4) trace flag     ptrace(2), request  0  resource
              usages     getrusage(2)     interval     timers     getitimer(2)
              resource limits   getrlimit(2) file mode  mask umask(2)  process
              signal  mask     sigvec(2),  sigprocmask(2V),      sigsetmask(2)
              pending    signals    sigpending(2)    tms_utime,     tms_stime,
              tms_cutime, tms_cstime    times(3C)

       When the executed program begins, it is called as follows:

              main(argc, argv, envp)
              int argc;
              char *argv[], *envp[];

       where  argc  is  the  number  of elements in argv (the "arg count", not
       counting the NULL terminating pointer) and argv points to the array  of
       character pointers to the arguments themselves.

       envp  is  a pointer to an array of strings that constitute the environ-
       ment of the process.  A pointer to this array is  also  stored  in  the
       global variable environ.  Each string consists of a name, an "=", and a
       null-terminated value.  The array of pointers is terminated by  a  NULL
       pointer.   The  shell sh(1) passes an environment entry for each global
       shell variable defined when the program is called.  See environ(5V) for
       some conventionally used names.

       Note: Passing values for argc, argv, and envp to main() is optional.

RETURN VALUES
       execve() returns to the calling process only on failure.  It returns -1
       and sets errno to indicate the error.

ERRORS
       E2BIG               The total number of bytes in the new process file's
                           argument  and  environment  lists exceeds {ARG_MAX}
                           (see sysconf(2V)).

       EACCES              Search permission is denied for a component of  the
                           new process file's path prefix.

                           The new process file is not an regular file.

                           Execute  permission  is  denied for the new process
                           file.

       EFAULT              The new process file is not as long as indicated by
                           the size values in its header.

                           path, argv, or envp points to an illegal address.

       EIO                 An  I/O  error occurred while reading from the file
                           system.

       ENAMETOOLONG        The length of the path argument exceeds {PATH_MAX}.

                           A pathname component is longer than {NAME_MAX} (see
                           sysconf(2V))  while  {_POSIX_NO_TRUNC} is in effect
                           (see pathconf(2V)).

       ELOOP               Too many symbolic links were encountered in  trans-
                           lating path.

       ENOENT              One  or  more  components of the path prefix of the
                           new process file does not exist.

                           The new process file does not exist.

       ENOEXEC             The new process file  has  the  appropriate  access
                           permission,  but has an invalid magic number in its
                           header.

       ENOMEM              The new process file requires more  virtual  memory
                           than  is  allowed  by  the  imposed  maximum (getr-
                           limit(2)).

       ENOTDIR             A component of the path prefix of the  new  process
                           file is not a directory.

SYSTEM V ERRORS
       In addition to the above, the following may also occur:

       ENOENT              path points to a null pathname.

SEE ALSO
       sh(1),  chdir(2V), chroot(2), close(2V), exit(2V), fcntl(2V), fork(2V),
       getgroups(2V), getitimer(2),  getpid(2V),  getrlimit(2),  getrusage(2),
       profil(2),   ptrace(2),  semop(2),  getpgrp(2V),  shmop(2),  sigvec(2),
       execl(3V), setuid(3V), termio(4), a.out(5), environ(5V)

WARNINGS
       If a program is setuid() to a non-super-user, but is executed when  the
       real  user ID is super-user, then the program has some of the powers of
       a super-user as well.



                                21 January 1990                     EXECVE(2V)