 |
» |
|
|
|
Executes a file.
Syntax | |
#include <unistd.h>
int execle (const char *path, const char *arg ...),
|
Parameters | |
- path
A pointer to a string containing the pathname of the executable file that is to become the new process image. The pathname must be terminated by a null character.
The elements of the pathname must be uppercase and must resolve to a valid MPE/iX file, group, and account. For example, the pathname /FINANCE/PAYROLL/JULY must resolve to JULY.PAYROLL.FINANCE, where JULY is an executable file located in MPE/iX group PAYROLL in MPE/iX account FINANCE.
- arg0, ..., argn
Each of the parameters arg0, ..., argn-1 point to a string containing an argument to the new process image. Each argument must be terminated by a null character. The last parameter, argn, must be a NULL pointer.
For an application to be strictly conforming, the first parameter, arg0, must point to a string containing a filename that identifies the executable file for the new process image.
Return Values | |
- No return
Success.
- -1
An error occurred. The current process image remains unchanged, and errno is set to indicate the error condition.
Description | |
The execle() function replaces the current process image with a new process image created from the executable file specified in pathname.
Use the execl() function if you know the exact number of arguments to be passed to the new process image. Use the execv() function if the number of arguments passed to the new process image might vary at run time.
If the new process image is a C program, it is entered as a C function call having the following declaration:
int main (int argc, const char *argv[])
|
In the above declaration, argc is a count of the number of pointers in the array argv[] and argv[] is an array of character pointers to the parameters arg0 through argn. The NULL pointer terminating argv[] is not counted in argc.
The environment for the new process image is identical to the environment of the calling process.
If the new process image is not a C program, no information is made available through the argument list in argv[].
The sum of the bytes used in both the argument list and environment list must not exceed {ARG_MAX} (defined in the file <limits.h>).
File descriptors open in the calling process image remain open in the new process image. For all file descriptors that remain open, all attributes of the open file description remain unchanged by this function, including file locks.
Streams open in the calling process image are not accessible in the new process image. (However, the underlying file descriptors that remain open, but inaccessible, are counted towards {OPEN_MAX}.)
Signals set to SIG_DFL or SIG_IGN in the calling process remain unchanged in the new process image. All signals of the calling process whose action is to invoke a signal handling function are set to SIG_DFL in the new process image.
The following attributes of the new process image are set to the same values of those of the calling process:
time remaining until a SIGALRM signal
current working directory
tms_utime, tms_stime, tms_cutime, and tms_cstime
The executable file's st_atime time field is marked for update. The executable file is open until the new process image terminates or executes another of the exec() functions.
Implementation Considerations | |
Refer to the EPERM, EIMPL, and ENOEXEC error descriptions below.
Some MPE/iX process attributes that are not specified in the POSIX 1003.1 standard are not inherited by the new process image.
NULL terminators and pointers are counted against {ARG_MAX}. Alignment bytes are counted against {ARG_MAX}.
The calling process's privilege level is used as the new program's maximum privilege level.
If the calling process entered debug mode through the ;DEBUG option of the MPE/iX CI RUN command, the new process image is also in debug mode.
Errors | |
If an error occurs, errno is set to one of the following values: | E2BIG | CAUSE
| The number of bytes used by the new process image's argument list and environment list combined is greater than the limit of {ARG_MAX} (defined in <limits.h>). | | | ACTION | Reduce the size of the argument list or environment list or both. | | EACCES | CAUSE | One of the following:
The calling process does not have search permission to a component of the pathname.
The calling process does not have execute permission to the file.
| | | ACTION | One of the following:
Make sure that the calling process has search permission to all components of the pathname.
Make sure that the calling process has execute permission to the file.
| | EFAULT | CAUSE | The system detected a NULL or bad address in attempting to use the pathname parameter, or the pathname was not terminated by a null character. | | | ACTION | Make sure that the pointer is correctly initialized. | EIMPL | CAUSE | The pathname did not resolve to a valid MPE/iX file, group, and account or the pathname begins with two slashes. | | | ACTION | Specify a valid pathname as described in the pathname parameter description. | ENAMETOOLONG | CAUSE | One of the following:
The length of the pathname exceeds the {PATH_MAX} limit (defined in the file <limits.h>).
A component of the pathname is longer than {NAME_MAX} (defined in <limits.h>), and {_POSIX_NO_TRUNC} is in effect for that directory.
| | | ACTION | Make sure that both the component's length and the full pathname
length do not exceed the {NAME_MAX} or {PATH_MAX} limits.
| ENOENT | CAUSE
| a component of the pathname for the executable file does not exist, or pathname points to an empty string. | | | ACTION
| Specify a valid pathname.
| | ENOEXEC | CAUSE
| The program file does not have the NMPRG file code. | | | ACTION
| Make sure that the program file has the NMPRG file code.
| | ENOMEM | CAUSE
| The new process image requires more memory than the system allows. | | | ACTION
| No action required. The new process image cannot be created.
| | ENOTDIR | CAUSE
| A component of the pathname is not a directory. | | | ACTION
| Specify a valid pathname.
| | EPERM | CAUSE
| One of the following:
The calling process does not have the MPE/iX process handling (PH) capability.
The calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource, or the calling process in in a procedure exit handler.
| | | ACTION | One of the following:
Link the program file with the MPE/iX PH capability.
Do not execute execl() when the calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource, or in a Procedure Exit handler.
| | EBUSY | CAUSE | The new process image file is loded by another user. | | | ACTION | None. |
See Also | |
alarm(), chmod(), _exit(), fcntl(), fork(), setuid(), <signal.h>, sigpromask(), sigpending, stat(), <sys/stat.h>, times(), umask, POSIX.1
|
