execle -- Overlay Calling Process and Run New Program

SYNOPSIS

 #include <unistd.h>

 int execle(const char *file, const char *arg0, ..., NULL,
            char *const envp[]);

DESCRIPTION

Like all of the exec functions, execle replaces the calling process image with a new process image. This has the effect of running a new progam with the process ID of the calling process. Note that a new process is not started; the new process image simply overlays the original process image. The execle function is most commonly used to overlay a process image that has been created by a call to the fork function.

file

is the filename of the file that contains the executable image of the new process.

arg0, ..., NULL

is a variable length list of arguments that are passed to the new process image. Each argument is specified as a null-terminated string, and the list must end with a NULL pointer. The first argument, arg0, is required and must contain the name of the executable file for the new process image. If the new process image is a normal SAS/C main program, the list of arguments will be passed to argv as a pointer to an array of strings. The number of strings in the array is passed to the main() function as argc.

ARG_MAX specifies the maximum number of bytes, including the NULL terminator at the end of the string, that can be passed as arguments to the new process image. The value of ARG_MAX is obtained by calling the sysconf function with the _SC_ARG_MAX symbol.

envp

is a pointer to an array of pointers to null-terminated character strings. A NULL pointer is used to mark the end of the array. Each character string pointed to by the array is used to pass an environment variable to the new process image. Each string should have the following form:

 " var = value "

RETURN VALUE

A successful call to execle does not have a return value because the new process image overlays the calling process image. However, a -1 is returned if the call to execle is unsuccessful.

EXAMPLE

The following code fragment illustrates creating a new process and executing an HFS file called newShell. The STEPLIB environment variable is passed to define a step library for the execution of newShell.

  #include <sys/types.h>
  #include <unistd.h>
  #include <stdio.h>

  main()
  {
     pid_t pid;
     char *const envp[2] = {"STEPLIB=SASC.V6.LINKLIB", NULL};

     if ((pid = fork()) == -1)
        perror("fork error");
     else if (pid == 0) {
        execle("/u/userid/bin/newShell", "newShell", NULL, envp);
        printf("Return not expected. Must be an execle() error.n");
     }
  }

RELATED FUNCTIONS

execl, execlp