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

FreeBSD Manual Pages

  
 
  

home | help
EXECVE(2)		      System Calls Manual		     EXECVE(2)

NAME
       execve -	execute	a file

SYNOPSIS
       execve(name, argv, envp)
       char *name, *argv[], *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 identify-
       ing  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'';
       when an interpreter file	is execve'd, the system	execve's the specified
       interpreter.

       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 an	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 argu-
       ment 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 arument envp	is also	an array of character pointers to  null-termi-
       nated strings.  These strings pass information to the new process which
       are not directly	arguments to the command, see environ(5).

       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 ioctl(2).
       Descriptors which remain	open are unaffected by	execve.	  Ignored/held
       signals	remain ignored/held across execve, but signals that are	caught
       are reset to their default values; see signal(2).

       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 his access privileges.  Execve changes the  ef-
       fective 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 inheirits the following attributes	from the call-
       ing process:

	    process ID		see getpid(2)
	    parent process ID	see getpid(2)
	    process group ID	see getpgrp(2)
	    working directory	see chdir(2)
	    root directory	see chdir(2)
	    control terminal	see tty(4)
	    file mode mask	see umask(2)

       When a C	program	is executed, 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'')  and
       argv is an 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 arrya 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	 envi-
       ron(5) for some conventionally used names.

DIAGNOSTICS
       If execve returns to the	calling	process	an error has occurred; the re-
       turn value will be -1 and the global variable errno  will  receive  the
       error code.

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

       [EINVAL]		   The path name contains a non-ASCII byte.

       [ENOENT]		   One or more components of the  new  process	file's
			   path	name does not exist.

       [ENOTDIR]	   A component of the new process file is not a	direc-
			   tory.

       [EACCES]		   Search permission is	denied for a directory	listed
			   in the new process file's path prefix.

       [EACCES]		   The new process file	is not a regular file.

       [EACCES]		   The	new  process  file mode	denies execute permis-
			   sion.

       [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 memory	 than  is  al-
			   lowed.

       [E2BIG]		   The	number	of bytes in the	new process's argument
			   list	is larger than the system imposed limit.

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

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

SEE ALSO
       csh(1), fork(2),	vfork(2), environ(5)

ASSEMBLER (PDP-11)
       (exec = 11.)
       sys exec; name; argv

       (exece =	59.)
       sys exece; name;	argv; envp

       Exec is obsoleted by exece, but remains for historical reasons.

       When  the  called file starts execution on the PDP11, the stack pointer
       points to a word	containing the number of arguments.  Just  above  this
       number  is  a  list  of pointers	to the argument	strings, followed by a
       null pointer, followed by the pointers to the environment  strings  and
       then  another null pointer.  The	strings	themselves follow; a 0 word is
       left at the very	top of memory.

	 sp->	 nargs
	    arg0
	    ...
	    argn
	    0
	    env0
	    ...
	    envm
	    0

	arg0:	 <arg0\0>
	    ...
	env0:	 <env0\0>
	    0

       On the Interdata	8/32, the stack	begins at a conventional  place	 (cur-
       rently  0xD0000)	 and grows upwards.  After exec, the layout of data on
       the stack is as follows.

	    int	 0
	arg0:	 byte ...
	    ...
       argp0:	 int  arg0
	    ...
	    int	 0
       envp0:	 int  env0
	    ...
	    int	 0
	%2->	 space	   40
	    int	 nargs
	    int	 argp0
	    int	 envp0
	%3->

       This arrangement	happens	to conform well	to C calling conventions.

       On a VAX-11, the	stack begins at	0x7ffff000  and	 grows	towards	 lower
       numbered	 addresses.  After exec, the layout of data on the stack is as
       follows.

	ap ->
	fp ->
	sp ->  .long nargs
	       .long arg0
	       ...
	       .long argn
	       .long 0
	       .long env0
	       ...
	       .long envn
	       .long 0
	arg0:  .byte "arg0\0"
	       ...
	envn:  .byte "envn\0"
	       .long 0

3rd Berkeley Distribution					     EXECVE(2)

NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | ERRORS | SEE ALSO | ASSEMBLER (PDP-11)

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=execve&sektion=2&manpath=2.9.1+BSD>

home | help