Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
EXECVE(2V)							    EXECVE(2V)

       execve -	execute	a file

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

       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 ex-

       Signals set to the default action (SIG_DFL) in the calling process  im-
       age  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-

       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

       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

	      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 directory		 chdir(2)
	      root directory		 chroot(2)
	      controlling terminal	 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),
	      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.

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

       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

       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

       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

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

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

       In addition to the above, the following may also	occur:

       ENOENT		   path	points to a null pathname.

       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), ex-
       ecl(3V),	setuid(3V), termio(4), a.out(5), environ(5V)

       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)


Want to link to this manual page? Use this URL:

home | help