unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

EXECL(3V)                                                            EXECL(3V)



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

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

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

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

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

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

       extern char **environ;

DESCRIPTION
       These  routines provide various interfaces to the execve() system call.
       Refer to execve(2V) for a description of their properties;  only  brief
       descriptions are provided here.

       exec()  in  all  its  forms overlays the calling process with the named
       file, then transfers to the entry point of the core image of the  file.
       There can be no return from a successful exec(); the calling core image
       is lost.

       The filename argument is a pointer to the name of the file to  be  exe-
       cuted.    The   pointers  arg[0],  arg[1]...   address  null-terminated
       strings.  Conventionally arg[0] is the name of the file.

       Two interfaces are available.  execl() is useful when a known file with
       known arguments is being called; the arguments to execl() are the char-
       acter strings constituting the file and the arguments; the first  argu-
       ment  is  conventionally  the same as the file name (or its last compo-
       nent).  A (char *)0 argument must end the argument list.  The  cast  to
       type char * insures portability.

       The  execv()  version is useful when the number of arguments is unknown
       in advance; the arguments to execv() are the name of  the  file  to  be
       executed  and  a  vector of strings containing the arguments.  The last
       argument string must be followed by a 0 pointer.

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

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

       where argc is the argument count and argv  is  an  array  of  character
       pointers  to  the  arguments themselves.  As indicated, argc is conven-
       tionally at least one and the first member of the  array  points  to  a
       string containing the name of the file.

       argv is directly usable in another execv() because argv[argc] is 0.

       envp  is  a pointer to an array of strings that constitute the environ-
       ment of the process.  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.   The  C  run-time  start-off  routine
       places  a  copy  of  envp  in the global cell environ, which is used by
       execv() and execl() to pass the environment to any subprograms executed
       by the current program.

       execlp() and execvp() are called with the same arguments as execl() and
       execv(), but duplicate the shell's actions in  searching  for  an  exe-
       cutable  file in a list of directories.  The directory list is obtained
       from the environment.

RETURN VALUES
       These functions return to the calling process only  on  failure.   They
       return -1 and set errno to indicate the error if path or file cannot be
       found, if it is not executable, if it does not start with a valid magic
       number  (see  a.out(5)), if maximum memory is exceeded, or if the argu-
       ments require too much space.  Even for the super-user, at least one of
       the execute-permission bits must be set for a file to be executed.

ERRORS
       If  any  of the following conditions occur, these functions will return
       and set errno to one of the following:

       E2BIG               The number of bytes used by the new process image's
                           argument  list and environment list is greater than
                           {ARG_MAX} bytes (see sysconf(2V)).

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

                           The new process image file denies execution permis-
                           sion.

                           The new process image file is not a regular file.

       ENAMETOOLONG        The length of the path or file, or  an  element  of
                           the  environment  variable PATH prefixed to a file,
                           exceeds {PATH_MAX}.

                           A pathname  component  is  longer  than  {NAME_MAX}
                           while  {_POSIX_NO_TRUNC} is in effect for that file
                           (see pathconf(2V)).

       ENOENT              One or more components of  the  new  process  image
                           file's pathname do not exist.

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

       if the following condition occurs, execl(), execv(), and  execle()  set
       errno to:

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

       If the following condition is detected, the exec  functions  set  errno
       to:

       ENOMEM              The  new  process  image  requires more memory than
                           there is swap space available.

                           On Sun-3 systems, the new  process  image  requires
                           more than 231 bytes.

SYSTEM V ERRORS
       In  addition  to the above, if the following condition occurs, the exec
       functions set errno to:

       ENOENT              path or file points to a null pathname.

FILES
       /usr/bin/sh         shell, invoked if command file found by execlp() or
                           execvp()

SEE ALSO
       csh(1),   sh(1),   execve(2V),   fork(2V),  pathconf(2V),  sysconf(2V),
       a.out(5), environ(5V)

                                21 January 1990                      EXECL(3V)