home | help
EXEC(3) 		     Library Functions Manual			 EXEC(3)

NAME
     execl, execlp, execle, exect, execv, execvp -- execute a file

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <unistd.h>

     extern char **environ;

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

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

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

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

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

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

DESCRIPTION
     The  exec family of functions replaces the current process image with a new
     process image.  The functions described in this manual page are  front-ends
     for  the  function  execve(2).   (See the manual page for execve(2) for de-
     tailed information about the replacement of the current process.)

     The initial argument for these functions is the pathname of a file which is
     to be executed.

     The const char *arg and subsequent ellipses in the execl(),  execlp(),  and
     execle()  functions  can  be thought of as arg0, arg1, ..., argn.	Together
     they describe a list of one or more  pointers  to	null-terminated  strings
     that  represent  the  argument list available to the executed program.  The
     first argument, by convention, should point to  the  file	name  associated
     with  the file being executed.  The list of arguments must be terminated by
     a NULL pointer.

     The exect(), execv(), and execvp() functions provide an array  of	pointers
     to  null-terminated  strings  that represent the argument list available to
     the new program.  The first argument, by convention, should  point  to  the
     file  name  associated with the file being executed.  The array of pointers
     must be terminated by a NULL pointer.

     The execle() and exect() functions also specify the environment of the exe-
     cuted process by following the NULL pointer that terminates the list of ar-
     guments in the parameter list or the pointer to the argv array with an  ad-
     ditional  parameter.   This additional parameter is an array of pointers to
     null-terminated strings and must be terminated  by  a  NULL  pointer.   The
     other functions take the environment for the new process image from the ex-
     ternal variable environ in the current process.

     Some of these functions have special semantics.

     The functions execlp() and execvp() will duplicate the actions of the shell
     in  searching  for  an  executable file if the specified file name does not
     contain a slash "/" character.  The search path is the  path  specified  in
     the  environment by "PATH" variable.  If this variable isn't specified, the
     default path is set according to the _PATH_DEFPATH definition in <paths.h>,
     which is set to "/usr/bin:/bin".  In addition, certain errors  are  treated
     specially.

     If  an error is ambiguous (for simplicity, we shall consider all errors ex-
     cept ENOEXEC as being ambiguous here,  although  only  the  critical  error
     EACCES  is really ambiguous), then these functions will act as if they stat
     the file to determine whether the file exists and has suitable execute per-
     missions.	If it does, they will return immediately with the  global  vari-
     able  errno  restored  to the value set by execve().  Otherwise, the search
     will be continued.  If the search completes without performing a successful
     execve() or terminating due to an error, these functions will  return  with
     the  global  variable errno set to EACCES or ENOENT according to whether at
     least one file with suitable execute permissions was found.

     If the header of a file isn't recognized (the attempted  execve()	returned
     ENOEXEC),	these functions will execute the shell with the path of the file
     as its first argument.  (If this attempt fails,  no  further  searching  is
     done.)

     The  function  exect()  executes a file with the program tracing facilities
     enabled (see ptrace(2)).

RETURN VALUES
     If any of the exec() functions returns, an error will have  occurred.   The
     return  value  is -1, and the global variable errno will be set to indicate
     the error.

FILES
     /bin/sh  The shell.

ERRORS
     Execl(), execle(), execlp() and execvp() may fail and set errno for any  of
     the errors specified for the library functions execve(2) and malloc(3).

     Exect()  and execv() may fail and set errno for any of the errors specified
     for the library function execve(2).

SEE ALSO
     sh(1), execve(2), fork(2), ktrace(2), ptrace(2), environ(7)

COMPATIBILITY
     Historically, the default path for the execlp() and execvp() functions  was
     ":/bin:/usr/bin".	 This was changed to place the current directory last to
     enhance system security.

     The behavior of execlp() and execvp() when errors occur while attempting to
     execute the file is not quite historic practice, and has not  traditionally
     been documented and is not specified by the POSIX standard.

     Traditionally,  the  functions execlp() and execvp() ignored all errors ex-
     cept for the ones described above and ETXTBSY, upon which they retried  af-
     ter sleeping for several seconds, and ENOMEM and E2BIG, upon which they re-
     turned.   They  now  return  for  ETXTBSY, and determine existence and exe-
     cutability more carefully.  In particular, EACCES for inaccessible directo-
     ries in the path prefix is no longer confused with EACCES	for  files  with
     unsuitable  execute  permissions.	In 4.4BSD, they returned upon all errors
     except EACCES, ENOENT, ENOEXEC and ETXTBSY.  This was inferior to the  tra-
     ditional  error  handling,  since it breaks the ignoring of errors for path
     prefixes and only improves the handling  of  the  unusual	ambiguous  error
     EFAULT  and  the unusual error EIO.  The behaviour was changed to match the
     behaviour of sh(1).

STANDARDS
     Execl(), execv(), execle(), execlp()  and	execvp()  conform  to  IEEE  Std
     1003.1-1988 ("POSIX.1").

FreeBSD 4.5			January 24, 1994			 EXEC(3)

home | help