# execve(2)

    NAME
         execve - execute a file

    SYNOPSIS
         #include <unistd.h>

         int execve(const char *name, char *const argv[], char *const envp[])

    DESCRIPTION
         Execve transforms the calling  process  into  a  new  process.   The  new
         process is constructed from an ordinary file called the new process file.
         This file is either an executable object file, or a file of data  for  an
         interpreter.   An  executable  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 initialized with zero data.  See a.out(5).

         An interpreter file begins with a line of the  form  ``#!  interpreter''.
         (Minix-vmd  only.)   When  an  interpreter  file  is execve'd, the system
         execve's the specified interpreter, giving it the name of the  originally
         exec'd  file  as  an  argument and shifting over the rest of the original
         arguments.

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

         The argument argv is a null-terminated array  of  character  pointers  to
         null-terminated character strings.  These strings constitute 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  program  (i.e.,  the  last
         component of name).

         The argument envp is also a null-terminated array of  character  pointers
         to  null-terminated  strings.   These strings pass information to the new
         process that is not directly an argument to the command (see environ(7)).

         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(2)).
         Descriptors that remain open are unaffected by execve.

         Ignored signals remain ignored across an execve,  but  signals  that  are
         caught are reset to their default values.  Blocked signals remain blocked
         regardless of changes to the signal action.  The signal stack is reset to
         be undefined (see sigaction(2) for more information).

         Each process has real user and group IDs and an effective user and  group
         IDs.   The  real ID identifies the person using the system; the effective
         ID determines his access privileges.  Execve changes the  effective  user
         and group ID to the owner of the executed file if the file has the  "set-
         user-ID" or "set-group-ID" modes.  The real user ID is not affected.

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

              process ID              see getpid(2)
              parent process ID       see getppid(2)
              process group ID        see getpgrp(2)
              access groups           see getgroups(2)
              working directory       see chdir(2)
              root directory          see chroot(2)
              control terminal        see tty(4)
              alarm timer             see alarm(2)
              file mode mask          see umask(2)
              signal mask             see sigaction(2), sigprocmask(2)

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

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

              exit(main(argc, argv, envp));

         where argc is the number of elements in argv (the ``arg count'') and argv
         is the array of character pointers to the arguments themselves.

         Envp is a pointer to an array of strings that constitute the  environment
         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(7) for
         some conventionally used names.

    RETURN VALUE
         If execve returns to the calling  process  an  error  has  occurred;  the
         return  value  will  be  -1 and the global variable errno will contain an
         error code.

    ERRORS
         Execve will fail and return to the calling process if one or more of  the
         following are true:

         [ENOTDIR]      A component of the path prefix is not a directory.

         [ENAMETOOLONG] The path name exceeds PATH_MAX characters.

         [ENOENT]       The new process file does not exist.

         [ELOOP]        Too many symbolic links were  encountered  in  translating
                        the pathname.  (Minix-vmd)

         [EACCES]       Search permission is denied for a component  of  the  path
                        prefix.

         [EACCES]       The new process file is not an ordinary file.

         [EACCES]       The new process file mode denies execute permission.

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

         [ENOMEM]       The new process requires more  (virtual)  memory  than  is
                        currently available.

         [E2BIG]        The number of bytes in the new process's argument list  is
                        larger  than  the system-imposed limit ARG_MAX.  The limit
                        in the system as released is 4096 bytes for 16-bit  Minix,
                        16384 bytes for 32-bit Minix, and unlimited for Minix-vmd.

         [EFAULT]       Path, argv, or envp point to an illegal address.

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

    CAVEATS
         If a program is setuid to a non-super-user, but is executed when the real
         uid  is ``root'', then the program has some of the powers of a super-user
         as well.

    SEE ALSO
         exit(2), fork(2), execl(3), environ(7).