Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <process.h>
    int execl(   path, arg0, arg1..., argn, NULL );
    int execle(  path, arg0, arg1..., argn, NULL, envp );
    int execlp(  file, arg0, arg1..., argn, NULL );
    int execlpe( file, arg0, arg1..., argn, NULL, envp );
    int execv(   path, argv );
    int execve(  path, argv, envp );
    int execvp(  file, argv );
    int execvpe( file, argv, envp );
      const char *path;             /* file name incl. path */
      const char *file;             /* file name            */
      const char *arg0, ..., *argn; /* arguments            */
      const char *const argv[];     /* array of arguments   */
      const char *const envp[];     /* environment strings  */
    int _wexecl(   path, arg0, arg1..., argn, NULL );
    int _wexecle(  path, arg0, arg1..., argn, NULL, envp );
    int _wexeclp(  file, arg0, arg1..., argn, NULL );
    int _wexeclpe( file, arg0, arg1..., argn, NULL, envp );
    int _wexecv(   path, argv );
    int _wexecve(  path, argv, envp );
    int _wexecvp(  file, argv );
    int _wexecvpe( file, argv, envp );
      const wchar_t *path;            /* file name incl. path */
      const wchar_t *file;            /* file name            */
      const wchar_t *arg0, ..., *argn;/* arguments            */
      const wchar_t *const argv[];    /* array of arguments   */
      const wchar_t *const envp[];    /* environment strings  */

Description:
    The exec functions load and execute a new child process, named by path
    or file.  If the child process is successfully loaded, it replaces the
    current process in memory.  No return is made to the original program.

    The program is located by using the following logic in sequence:

     1. An attempt is made to locate the program in the current working
        directory if no directory specification precedes the program name;
        otherwise, an attempt is made in the specified directory.

     2. If no file extension is given, an attempt is made to find the
        program name, in the directory indicated in the first point, with
        .COM concatenated to the end of the program name.

     3. If no file extension is given, an attempt is made to find the
        program name, in the directory indicated in the first point, with
        .EXE concatenated to the end of the program name.

     4. When no directory specification is given as part of the program
        name, the  execlp,  execlpe,  execvp, and  execvpe functions will
        repeat the preceding three steps for each of the directories
        specified by the  PATH environment variable.  The command


             path c:\myapps;d:\lib\applns

        indicates that the two directories


             c:\myapps
             d:\lib\applns

        are to be searched.  The DOS PATH command (without any directory
        specification) will cause the current path definition to be
        displayed.

    An error is detected when the program cannot be found.

    Arguments are passed to the child process by supplying one or more
    pointers to character strings as arguments in the exec call.  These
    character strings are concatenated with spaces inserted to separate the
    arguments to form one argument string for the child process.  The length
    of this concatenated string must not exceed 128 bytes for DOS systems.

    The arguments may be passed as a list of arguments ( execl,  execle,
     execlp, and  execlpe) or as a vector of pointers ( execv,  execve,
     execvp, and  execvpe).  At least one argument, arg0 or argv[0], must be
    passed to the child process.  By convention, this first argument is a
    pointer to the name of the program.

    If the arguments are passed as a list, there must be a NULL pointer to
    mark the end of the argument list.  Similarly, if a pointer to an
    argument vector is passed, the argument vector must be terminated by a
    NULL pointer.

    The environment for the invoked program is inherited from the parent
    process when you use the  execl,  execlp,  execv, and  execvp functions.
     The  execle,  execlpe,  execve, and  execvpe functions allow a
    different environment to be passed to the child process through the envp
    argument.  The argument envp is a pointer to an array of character
    pointers, each of which points to a string defining an environment
    variable.  The array is terminated with a NULL pointer.  Each pointer
    locates a character string of the form


             variable=value

    that is used to define an environment variable.  If the value of envp is
    NULL, then the child process inherits the environment of the parent
    process.

    The environment is the collection of environment variables whose values
    have been defined with the DOS SET command or by the successful
    execution of the  putenv function.  A program may read these values with
    the  getenv function.

    The  execvpe and  execlpe functions are extensions to POSIX 1003.1.  The
    wide-character  _wexecl,  _wexecle,  _wexeclp,  _wexeclpe,  _wexecv,
     _wexecve,  _wexecvp and  _wexecvpe functions are similar to their
    counterparts but operate on wide-character strings.

Returns:
    When the invoked program is successfully initiated, no return occurs.
     When an error is detected while invoking the indicated program, exec
    returns -1 and  errno is set to indicate the error.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    Constant     Meaning

E2BIG
    The argument list exceeds 128 bytes, or the space required for the
    environment information exceeds 32K.

EACCES
    The specified file has a locking or sharing violation.

EMFILE
    Too many files open

ENOENT
    Path or file not found

ENOMEM
    Not enough memory is available to execute the child process.


Example:
    #include <stddef.h>
    #include <process.h>

    execl( "myprog",
            "myprog", "ARG1", "ARG2", NULL );

    The preceding invokes "myprog" as if

        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe

    is found in the current working directory.

    #include <stddef.h>
    #include <process.h>

    char *env_list[] = { "SOURCE=MYDATA",
                         "TARGET=OUTPUT",
                         "lines=65",
                         NULL
                        };

    execle( "myprog",
            "myprog", "ARG1", "ARG2", NULL,
             env_list );

    The preceding invokes "myprog" as if

        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe

    is found in the current working directory.  The DOS environment for the
    invoked program will consist of the three environment variables SOURCE,
    TARGET and lines.

    #include <stddef.h>
    #include <process.h>

    char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL };

    execv( "myprog", arg_list );

    The preceding invokes "myprog" as if
        myprog ARG1 ARG2

    had been entered as a command to DOS.  The program will be found if one
    of

        myprog.
        myprog.com
        myprog.exe

    is found in the current working directory.

Classification:
    exec...  is POSIX 1003.1 with extensions, _wexec...  is not POSIX

Systems:
     execl - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32

    execle - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execlp - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execlpe - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execv - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execve - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execvp - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    execvpe - DOS/16, Win32, QNX, OS/2 1.x(all), OS/2-32
    _wexecle - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexeclp - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexeclpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexecv - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexecve - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexecvp - DOS/16, Win32, OS/2 1.x(all), OS/2-32
    _wexecvpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32

See Also:
    abort, atexit, exit, _exit, getcmd, getenv, main, putenv, spawn
    Functions, system