unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



exec(2)								      exec(2)



NAME

  environ, execl, execv, execle, execve, execlp, execvp	- Executes a file

LIBRARY

  Standard C Library (libc.a, libc.so)

SYNOPSIS

  #include <&lt;unistd.h>&gt;

  extern char **environ;
  int execl (
	  const	char *path,
	  const	char *arg,
	  ...  );

  int execv (
	  const	char *path,
	  char * const argv[ ] );

  int execle (
	  const	char *path,
	  const	char *arg,
	  ...
	  char * const envp[ ] );

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

  int execlp (
	  const	char *file,
	  const	char *arg,
	  ... );

  int execvp (
	  const	char *file,
	  char * const argv[ ] );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  execl(), execv(), execv(), execle(), execve(), execlp(), execvp(): POSIX.1,
  XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  path	    Points to a	pathname identifying the new process image file.

  arg...    Specifies a	pointer	to a null-terminated string, which is one
	    argument available to the new process image. The first of these
	    parameters points to the filename that is associated with the
	    process being started by execl(), execle(),	or execlp(). The last
	    element in the list	of arg parameters must be a null pointer.

  argv	    Specifies an array of character pointers to	null-terminated
	    strings, which are the arguments available to the new process
	    image. The value in	the argv[0] parameter points to	the filename
	    of the process being started by execv(), execve(), or execvp().
	    The	last member of this array must be a null pointer.

  envp	    Specifies an array of character pointers to	null-terminated
	    strings, constituting the environment for the new process. This
	    array must be terminated by	a null pointer.

  file	    Identifies the new process image file.  If this parameter points
	    to a string	containing a slash character, its contents are used
	    as the absolute or relative	pathname to the	process	image file.
	    Otherwise, the system searches the directories specified in	the
	    PATH environment variable definition associated with the new pro-
	    cess image to obtain a path	prefix for the file.

DESCRIPTION

  The exec functions replace the current process image with a new process
  image. The system constructs the new image from an executable	file, called
  a new	process	image file. Successful calls to	the exec functions do not
  return because the system overlays the calling process with the new pro-
  cess.

  To run an executable file using one of the exec functions, applications
  include a function call such as the following:

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

  Here,	the argc parameter contains the	number of arguments being passed to
  the new main function.  The argv[ ] parameter	is a null-terminated array of
  character pointers that point	to the arguments themselves.  (The null
  pointer is not included in the count specified in the	argc parameter.) The
  value	in argv[0] should point	to the filename	that is	associated with	the
  process being	started	by one of the exec functions.  The system passes the
  arguments to the new process image in	the corresponding arguments to
  main().

  For forms of the exec	functions that do not include the envp parameter,
  applications also define the environ variable	to be a	pointer	to an array
  of character strings.	 The character strings define the environment in
  which	the new	process	image runs. For	example, the following shows how an
  application defines the environment variable:

  extern char **environ;

  The environ array is terminated by a null pointer.

  The format of	the new	process	image file must	be one that is recognized by
  the exec function being used.	The exec functions recognize executable	text
  files	and binary files.


  An executable	text file is one that contains a header	line with the follow-
  ing syntax:

  #! interpreter_name [	optional_string	]


  The #! identifies the	file as	an executable text file.  The new process
  image	is constructed from the	process	image file named by the
  interpreter_name string.  When executing an executable text file, the	sys-
  tem modifies the arguments passed to the exec	function being used as fol-
  lows:

    +  argv[0] is set to the name of the interpreter.  For example, the	ksh
       shell might be the interpreter.

    +  If the optional_string is present, argv[1] is set to the
       optional_string.

    +  The next	element	of argv[] is set to the	original value of path.

    +  The remaining elements of argv[]	are set	to the original	elements of
       argv[], starting	at argv[1].  The original argv[0] is discarded.

  A binary file	can be loaded either directly by an exec function or
  indirectly by	the program loader.  The exec functions	choose to use direct
  or indirect loading based on the contents of the new process image file.
  For example, the functions use indirect loading if the new process image
  file contains	unresolved symbols, requiring use of a shared library.

  When an exec function	loads a	binary file indirectly,	it constructs the new
  process image	from the default program loader, /sbin/loader, in the same
  manner as the	exec_with_loader() function (see exec_with_loader(2)).	The
  default program loader is then responsible for completing the	new program
  image	by loading the new process image file and any shared libraries on
  which	it depends.

  If the process image file is not a valid executable object, the execlp()
  and execvp() functions use the contents of that file as standard input to a
  command interpreter conforming to the	system() function.  In this case, the
  command interpreter becomes the new process image.

  The number of	bytes available	for the	combined argument and environment
  lists	of the new process image is ARG_MAX.  ARG_MAX includes the null	ter-
  minators on the strings;  it does not	include	the pointers.

  File descriptors open	in the calling process image remain open in the	new
  process image, except	for those whose	close-on-exec flag, FD_CLOEXEC,	is
  set (see fcntl(2) for	more information).  For	those file descriptors that
  remain open, all attributes of the open file description, including file
  locks, remain	unchanged.

  Directory streams open in the	calling	process	image are closed in the	new
  process image.

  The state of directory streams and message catalog descriptors in the	new
  process image	is undefined.  For the new process, the	equivalent of the
  following command is executed	at startup:

  setlocale(LC_ALL, "C")

  Each mapped file and shared memory region created with the mmap() function
  is unmapped by a successful call to any of the exec functions, except	those
  regions mapped with the MAP_INHERIT option.  Regions mapped with the
  MAP_INHERIT option remain mapped in the new process image.


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

  After	a successful call to any of the	exec functions,	alternate signal
  stacks are not preserved and the SA_ONSTACK flag is cleared for all sig-
  nals.

  After	a successful call to any of the	exec functions,	any functions previ-
  ously	registered by atexit() are no longer registered.

  If the ST_NOSUID bit is set for the file system containing the new process
  image	file, the effective user ID, effective group ID, saved set user	ID,
  and saved set	group ID are unchanged in the new process.

  Otherwise, if	the set	user ID	mode bit of the	new process image file is set
  (see chmod(2)	for more information), the effective user ID of	the new	pro-
  cess image is	set to the owner ID of the new process image file.  Simi-
  larly, 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 real	user ID, real group ID,	and supple-
  mentary group	IDs of the new process image remain the	same as	those of the
  calling process image.  The effective	user ID	and effective group ID of the
  new process image are	saved (as the saved set	user ID	and the	saved set
  group	ID) for	use by the setuid() function.

  Any shared memory segments attached to the calling process image are not
  attached to the new process image.

  Any mappings established through mmap() are not preserved across an exec.

  The following	attributes of the calling process image	are unchanged after
  successful completion	of any of the exec functions.  For example, a new
  process inherits these attributes:

    +  Process ID

    +  Parent process ID

    +  Process group ID

    +  Session membership

    +  Real user ID

    +  Real group ID

    +  Supplementary group IDs

    +  Time left until an alarm	clock signal (see alarm(3) for more informa-
       tion)

    +  Current working directory

    +  Root directory

    +  File mode creation mask (see umask(2) for more information)

    +  Process signal mask (see	sigprocmask(2) for more	information)

    +  Pending signals (see sigpending(2) for more information)

    +  The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms
       structure

    +  File size limit (see the	ulimit() function)

    +  Nice value (see nice(3) for more	information)

    +  Adjust-on-exit values (see semop(2) for more information)

    +  Resource	limits

    +  Controlling terminal

    +  Interval	timers

  Upon successful completion, the exec functions mark for update the st_atime
  field	of the file.

NOTES

  If a multithreaded process calls one of the exec functions, all threads
  except the calling thread are	terminated and the calling thread begins exe-
  cution within	the new	process	image.

RETURN VALUES

  If one of the	exec functions returns to the calling process image, an	error
  has occurred;	the return value is -1,	and the	function sets errno to indi-
  cate the error.

ERRORS

  The exec functions set errno to the specified	values for the following con-
  ditions:

  [E2BIG]   The	number of bytes	used by	the new	process	image's	argument list
	    and	environment list is greater than ARG_MAX bytes.

  [EACCES]  Search permission is denied	for a directory	listed in the new
	    process image file's path prefix, or the new process image file
	    denies execution permission, or the	new process image file is not
	    an executable file type.

  [EACCES]  [Tru64 UNIX]  The security attributes of the program file do not
	    allow execute permission.

  [EAGAIN]  [Tru64 UNIX]  The calling process is using a kernel	subsystem
	    that prevents executing the	new image.  The	call to	one of the
	    exec functions will	not succeed until the process has detached
	    itself from	the subsystem.

  [EFAULT]  [Tru64 UNIX]  The path argument is an invalid address.

  [EIO]	    [Tru64 UNIX]  An I/O error occurred.

  [ELOOP]   Too	many symbolic links were encountered in	pathname resolution.

  [ENAMETOOLONG]
	    One	of the following conditions occurred:

	    - The length of the	path argument, the file	argument, or an	ele-
	      ment of the environment variable PATH prefixed to	a file
	      exceeds PATH_MAX.

	    - A	pathname component is longer than NAME_MAX, and
	      _POSIX_NO_TRUNC is in effect for that file.

  [ENOENT]  One	or more	components of the new process image file's pathname
	    do not exist, or the path or file argument points to an empty
	    string.

  [ENOMEM]  Insufficient memory	is available.

  [ENOTDIR] A component	of the new process image file's	path prefix is not a
	    directory.

  The execl(), execv(),	execle(), and execve() functions also set errno	as
  follows:

  [ENOEXEC] The	new process image file has the appropriate access permission
	    but	is not in the proper format.

  The execlp() and execvp() functions also set errno as	follows:

  [EWOULDBLOCK]
	    [Tru64 UNIX]  Indicates that another thread	in the process is
	    already performing an execlp() or execvp() operation.

RELATED	INFORMATION

  Functions: exit(2), fcntl(2),	fork(2), sigaction(2), umask(2), mmap(2),
  exec_with_loader(2)

  Routines: alarm(3), getenv(3), nice(3), putenv(3), system(3),	times(3),
  ulimit(3)

  Standards: standards(5)