*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> execve (2)              



NAME    [Toc]    [Back]

     execve, exect - execute a file

SYNOPSIS    [Toc]    [Back]

     #include <unistd.h>

     execve(const char *path, char  *const  argv[],  char  *const

     exect(const  char  *path,  char  *const  argv[], char *const

DESCRIPTION    [Toc]    [Back]

     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
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) and elf(5).

     An interpreter file begins with a line of the form:

           #! interpreter [arg]

     When  an  interpreter  file  is  execve(Ap,  d),  the system
execve(Ap, s) runs
     the specified interpreter.  If the optional  arg  is  specified, it becomes
     the  first  argument to the interpreter, and the name of the
     execve(Ap, d) file becomes the second  argument;  otherwise,
the name of
     the  originally  execve(Ap,  d) file becomes the first argument.  The original
 arguments are shifted over to become the subsequent  arguments.  The
     zeroth  argument,  normally  the  name  of the execve(Ap, d)
file, is left unchanged.

     The argument argv is a pointer to a null-terminated array of
     pointers to nul-terminated character strings.  These strings
     the argument list to be made available to the  new  process.
At least one
     argument  must be present in the array; by custom, the first
     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 nul-terminated strings.  A pointer  to  this
array is normally
  stored in the global variable environ.  These strings
pass information
 to the new process that is not directly an argument  to
the command
     (see environ(7)).

     File  descriptors  open  in the calling process image remain
open in the new
     process image, except for those for which the  close-on-exec
flag is set
     (see  close(2)  and fcntl(2)).  Descriptors that remain open
are unaffected
     by execve().  In the case of a new  setuid  or  setgid  executable being executed,
  if  file descriptors 0, 1, or 2 (representing stdin,
stdout, and
     stderr) are currently unallocated, these descriptors will be
opened to
     point  to some system file like /dev/null.  The intent is to
ensure these
     descriptors are not unallocated, since many  libraries  make
     about the use of these 3 file descriptors.

     Signals  set to be ignored in the calling process are set to
be ignored in
     the new process.  Signals which are set to be caught in  the
calling process
  image are set to default action in the new process image.  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).

     If the set-user-ID mode bit of the new process image file is
set (see
     chmod(2)), the effective user ID of the new process image is
set to the
     owner ID of the new process image file.  If the set-group-ID
mode bit of
     the new process image file is set, the effective group ID of
the new process
 image is set to the group ID of the new  process  image
file.  (The
     effective  group ID is the first element of the group list.)
The real user
 ID, real group ID and other group IDs of the new  process
image remain
     the  same as the calling process image.  After any set-userID and setgroup-ID
 processing, the effective user ID  is  recorded  as
the saved setuser-ID,
 and the effective group ID is recorded as the saved
  These values may be used in changing the effective  IDs
later (see
     setuid(2)).   The  set-user-ID and set-group-ID bits have no
effect if the
     new process image file is located on a file  system  mounted
with the nosuid
 flag.  The process will be started without the new permissions.

     The new process also inherits the following attributes  from
the calling

           process ID           see getpid(2)
           parent process ID    see getppid(2)
           process group ID     see getpgrp(2)
           session ID           see getsid(2)
           access groups        see getgroups(2)
           working directory    see chdir(2)
           root directory       see chroot(2)
           control terminal     see termios(4)
           resource usages      see getrusage(2)
           interval  timers      see getitimer(2) (unless process
image file is
                                setuid or setgid, in  which  case
all timers are
           resource limits      see getrlimit(2)
           file mode mask       see umask(2)
           signal mask          see sigaction(2), sigsetmask(3)

     When  a program is executed as a result of an execve() call,
it is entered
     as follows:

           main(int argc, char **argv, char **envp)

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

     The exect() function is equivalent to execve() with the  additional property
  that it executes the file with the program tracing facilities enabled
 (see ptrace(2)).

RETURN VALUES    [Toc]    [Back]

     As the execve() function overlays the current process  image
with a new
     process  image  the successful call has no process to return
to.  If
     execve() does return to the calling process an error has occurred; the
     return value will be -1 and the global variable errno is set
to indicate
     the error.

ERRORS    [Toc]    [Back]

     execve() will fail and return to the calling process if:

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

                   A  component of a pathname exceeded {NAME_MAX}
                   or an entire  path  name  exceeded  {PATH_MAX}

     [ENOENT]      The new process file does not exist.

     [ELOOP]        Too  many  symbolic links were encountered in
translating the

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

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

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

     [EACCES]      The new process file is on a filesystem mounted with execution
 disabled (MNT_NOEXEC in <sys/mount.h>).

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

     [ETXTBSY]     The new  process  file  is  a  pure  procedure
(shared text) file
                   that  is currently open for writing or reading
by some process.

     [ENOMEM]      The new process requires more  virtual  memory
than is allowed
 by the imposed maximum (getrlimit(2)).

     [E2BIG]       The number of bytes in the new process's argument list is
                   larger than  the  system-imposed  limit.   The
limit in the
                   system as released is 262144 bytes (NCARGS in

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

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

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

     [ENFILE]      During startup of an interpreter,  the  system
file table was
                   found to be full.

SEE ALSO    [Toc]    [Back]

     _exit(2), fork(2), execl(3), exit(3), a.out(5), elf(5), environ(7)

STANDARDS    [Toc]    [Back]

     The exect() function should not be used in portable applications.

HISTORY    [Toc]    [Back]

     The execve() function call appeared in 4.2BSD.

CAVEATS    [Toc]    [Back]

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

OpenBSD      3.6                         January     24,     1994
[ Back ]
 Similar pages
Name OS Title
exec_with_loader Tru64 Execute a file with a loader
rexec IRIX execute a file on a remote cell
lockf FreeBSD execute a command while holding a file lock
fileevent IRIX Execute a script when a file becomes readable or writable
hosts.equiv Tru64 A file containing the names of remote systems and users that can execute commands on the local syste...
execve Linux execute program
VkCmdManager IRIX execute commands
if IRIX Execute scripts conditionally
perlrun OpenBSD how to execute the Perl interpreter
pagsh OpenBSD execute a command without authentication
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service