unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 exec(2)							     exec(2)




 NAME
      execl(), execle(), execlp(), execv(), execve(), execvp() - execute a
      file

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

      extern char **environ;

      int execl(const char *path,
		const char *arg0, ...
		/*
		 *  [const char *arg1, ..., const char *argn,]
		 */
		 (char *)0
      );

      int execle(const char *path,
		 const char *arg0, ...
		 /*
		  *  [const char *arg1, ..., const char *argn,]
		  */
		  (char *)0,
		  char * const envp[]
      );

      int execlp(const char *file,
		 const char *arg0, ...
		 /*
		  *  [const char *arg1, ..., const char *argn,]
		  */
		  (char *)0
      );

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

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

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

    Remarks
      The ANSI C ", ..." construct denotes a variable length argument list
      whose optional and required members are given in the associated comment
      (/* */).

 DESCRIPTION
      The exec*() system calls, in all their forms, load a program from an
      ordinary, executable file into the current process, replacing the
      current program.	The path or file argument refers to either an
      executable object file or a file of data for an interpreter.  In the
      latter case, the file of data is also called a script file.



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




      If the calling process is multi-threaded, a call to any of the exec
      functions will cause all threads and light weight processes in the
      calling process to be terminated and the new executable image to be
      loaded and executed.  No thread specific data destructor functions are
      called. If the exec function fails and returns to the caller, threads
      and light weight processes (LWPs) in the calling process will not be
      terminated.

      An executable object file consists of a header (see a.out(4)), text
      segment, and data segment.  The data segment contains an initialized
      portion and an uninitialized portion (bss).  For execlp() and execvp()
      the POSIX shell (see sh-posix(1)) can be loaded to interpret a script
      instead.	A successful call to exec*() does not return because the new
      program overwrites the calling program.

      When a C program is executed, it is called as follows:

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

      where argc is the argument count and argv is the address of an array
      of character pointers to the arguments themselves.  As indicated, argc
      usually has a value of at least one, and the first member of the array
      points to a string containing the name of the file.  Exit conditions
      from main are discussed in exit(2).

      path points to a path name that identifies the executable file
      containing the new program.

      file (in execlp() or execvp()) points to a file name identifying the
      executable file containing the new program.  The path prefix for this
      file is obtained by searching the directories passed in the
      environment variable PATH (see environ(5)).  The environment is
      supplied by the shell (see sh(1)).  If file does not have an
      executable magic number (see magic(4)), it is passed to the POSIX
      shell as a shell script.

      arg0, ..., argn are one or more pointers to null-terminated character
      strings.	These strings constitute the argument list available to the
      new program.  By convention, at least arg0 must be present and point
      to a string identical to path or to path's last component.

      argv is an array of character pointers to null-terminated strings.
      These strings constitute the argument list available to the new
      program.	By convention, argv must have at least one member, and must
      point to a string that is identical to path or path's last component.
      argv is terminated by a null pointer.

      envp is an array of character pointers to null-terminated strings.
      These strings constitute the environment in which the new program
      runs.  envp is terminated by a null pointer.  For execle() and
      execve(), the C run-time start-off routine places a pointer to the



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




      environment of the calling program in the global cell:

	   extern char **environ;

      and it is used to pass the environment of the calling program to the
      new program.

      Multi-threaded applications should not use the environ variable to
      access or modify any environment variable while another thread is
      concurrently modifying any environment variable. Calling any function
      which is dependent upon any environment variable is considered a use
      of the environ variable to access that environment variable.

      Open file descriptors remain open, except for those whose close-on-
      exec flag is set (see fcntl(2)).	The file offset, access mode, and
      status flags of open file descriptors are unchanged.

      Note that normal executable files are open only briefly when they
      start execution.	Other executable file types can be kept open for a
      long time, or even indefinitely under some circumstances.

      The processing of signals by the process is unchanged by exec*(),
      except that signals caught by the process are set to their default
      values (see signal(2)).

      If the set-user-ID mode bit of the executable file pointed to by path
      or file is set (see chmod(2)), exec*() sets the effective user ID of
      the new process to the user ID of the executable file.  Similarly, if
      the set-group-ID mode bit of the executable file is set, the effective
      group ID of the process is set to the group ID of the executable file.
      The real user ID and real group ID of the process are unchanged.	Note
      that the set-user-ID and set-group-ID functions do not apply to
      scripts; thus, if execlp() or execvp() executes a script, the set-
      user-ID and set-group-ID bits are ignored, even if they are set.

      The saved user ID and saved group ID of the process are always set to
      the effective user ID and effective group ID, respectively, of the
      process at the end of the exec*(), whether or not set-user-ID or set-
      group-ID is in effect.

      The shared memory segments attached to the calling program are not
      attached to the new program (see shmop(2)).

      Text and data segment memory locks are not passed on to the new
      program (see plock(2)).

      Profiling is disabled for the new process (see profil(2)).

      The process also retains the following attributes:





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




	   +  current working directory
	   +  file creation mode mask (see umask(2))
	   +  file locks (see fcntl(2)), except for files closed-on-
	      execution
	   +  file size limit (see ulimit(2))
	   +  interval timers (see getitimer(2))
	   +  nice value (see nice(2))
	   +  nice value (see parent process ID)
	   +  pending signals
	   +  process ID
	   +  process group ID
	   +  real user ID
	   +  real group ID
	   +  process start time
	   +  real-time priority (see rtprio(2))
	   +  root directory (see chroot(2))
	   +  semadj values (see semop(2))
	   +  session membership
	   +  signal mask (see sigvector(2))
	   +  supplementary group IDs
	   +  time left until an alarm clock signal (see alarm(2))
	   +  trace flag (see the PT_SETTRC request of ptrace(2))
	   +  tms_utime, tms_stime, tms_cutime, and tms_cstime (see
	      times(2))

      For a script file, the initial line of a script file must begin with
      #! as the first two bytes, followed by zero or more spaces, followed
      by interpreter or interpreter argument, as in:

	   #! interpreter [argument]

      One or more spaces or tabs must separate interpreter and argument.
      The first line should end with either a newline or a null character.

      When the script file is executed, the system executes the specified
      interpreter as an executable object file.	 Even in the case of
      execlp() or execvp(), no path searching is done of the interpreter
      name.

      The argument is anything that follows interpreter and tabs or spaces.
      If an argument is given, it is passed to the interpreter as argv[1],
      and the name of the script file is passed as argv[2].  Otherwise, the
      name of the script file is passed as argv[1].  argv[0] is passed as
      specified in the exec*() call.  All other arguments specified in the
      exec*() call are passed following the name of the script file (that
      is, beginning at argv[3] if there is an argument; otherwise, at
      argv[2]).

      Some interpreters process the interpreter and the argument internally,
      and do not provide the interpreter and the argument to the users
      script.



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




      If the initial line of the script file exceeds a system-defined
      maximum number of characters, exec*() fails.  The minimum value for
      this limit is 32.

      The set-user-ID and set-group-ID bits are honored for the script but
      not for the interpreter.

      For a executable object file, the arguments are passed as argv[1],
      ..., argv[n].  argv[0] is passed as specified in the exec*() call,
      unless either argv or argv[0] is null as specified, in which case a
      pointer to a null string is passed as argv[0].

 RETURN VALUE
      If exec*() returns to the calling program, an error has occurred; the
      return value is -1 and errno is set to indicate the error.

 ERRORS
      If exec*() fails and returns to the calling program, errno is set to
      one of the following values:

	   [E2BIG]	       The number of bytes in the new program's
			       argument list plus environment is greater
			       than the system-imposed limit.  This limit is
			       at least 5120 bytes on HP-UX systems.

	   [EACCES]	       Read permission is denied for the executable
			       file or interpreter, and the trace flag (see
			       ptrace(2) request PT_SETTRC) of the process
			       is set.

	   [EACCES]	       Search permission is denied for a directory
			       listed in the executable file's or the
			       interpreter's path prefix.

	   [EACCES]	       The executable file or the interpreter is not
			       an ordinary file.

	   [EACCES]	       The file described by path or file is not
			       executable.  The superuser cannot execute a
			       file unless at least one access permission
			       bit or entry in its access control list has
			       an execute bit set.

	   [EFAULT]	       path, argv, or envp point to an illegal
			       address.	 The reliable detection of this
			       error is implementation dependent.

	   [EINTR]	       A signal was caught during the exec*() system
			       call.





 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




	   [EINVAL]	       The executable file is incompatible with the
			       architecture on which the exec*() has been
			       performed, and is presumed to be for a
			       different architecture.	It is not guaranteed
			       that every architecture's executable files
			       will be recognized.

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

	   [ENAMETOOLONG]      The executable file's path name or the
			       interpreter's path name exceeds PATH_MAX
			       bytes, or the length of a component of the
			       path name exceeds NAME_MAX bytes while
			       _POSIX_NO_TRUNC is in effect.

	   [ENOENT]	       path is null.

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

	   [ENOEXEC]	       The executable file is shorter than indicated
			       by the size values in its header, or is
			       otherwise inconsistent.	The reliable
			       detection of this error is implementation
			       dependent.

	   [ENOEXEC]	       The function call is not execlp() or
			       execvp(), and the executable file has the
			       appropriate access permission, but there is
			       neither a valid magic number nor the
			       characters #! as the first two bytes of the
			       file's initial line.

	   [ENOEXEC]	       The number of bytes in the initial line of a
			       script file exceeds the system's maximum.

	   [ENOMEM]	       The new process requires more memory than is
			       available or allowed by the system-imposed
			       maximum.

	   [ENOTDIR]	       A component of the executable file's path
			       prefix or the interpreter's path prefix is
			       not a directory.

	   [ETXTBSY]	       The executable file is currently open for
			       writing.

 WARNINGS




 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 exec(2)							     exec(2)




      Unsharable executable files are not supported.  These are files whose
      EXEC_MAGIC magic number was produced with the -N option of ld (see
      ld(1)).

      It is recommended to use the execve() call in multi-threaded
      applications to avoid possible deadlocks.

 DEPENDENCIES
    HP Process Resource Manager
      If the optional HP Process Resource Manager (PRM) software is
      installed and configured, the process's process resource group ID is
      not changed by exec*().  See prmconfig(1) for a description of how to
      configure HP PRM, and prmconf(4) for the definition of process
      resource group.

 SEE ALSO
      sh(1), sh-posix(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2),
      semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),
      environ(5), signal(5).

      HP Process Resource Manager: prmconfig(1), prmconf(4) in HP Process
      Resource Manager User's Guide.

 STANDARDS CONFORMANCE
      environ: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execl(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execle(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execlp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execv(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execve(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      execvp(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

















 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000