| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
POSIX.1 |
both |
#define _POSIX_SOURCE
#include <unistd.h>
extern char **environ;
int execl(const char *path, const char *arg, …, NULL);
int execle(const char *path, const char *arg, …, NULL, char *const envp[]);
int execlp(const char *file, const char *arg, …, NULL);
int execv(const char *path, char *const argv[]);
int execve(const char *path, char *const argv[], char *const envp[]);
int execvp(const char *file, char *const argv[]);All exec functions run a new program by replacing the current process image with a new process image obtained from a file in the HFS (hierarchical file system).
For information on specifying names for MVS™ data sets and HFS files, see z/OS XL C/C++ Programming Guide.
A successful exec function never returns control because the calling process is overwritten with the new process.
The argument path is a string giving the absolute or relative path name of a file. This file contains the image of the process to be run.
file is a string that is used in determining the path name of the file containing the image of the process to be run. If file contains a slash character (/), it is assumed to be the absolute or relative path name of the file. If file does not contain a slash, the system searches for the given file name under the list of directories given by the PATH environment variable. The system checks under directories in the order they appear in the PATH variable, and executes the first file whose name matches the file string. The file must reside in the HFS.
If the STEPLIB environment variable is not specified, the exec() default behavior is the same as if STEPLIB=CURRENT were specified.
If the program to be invoked is a set-user-ID or set-group-ID file and the user-ID or group-ID of the file is different from that of the current process image, the data sets to be built into the STEPLIB environment for the new process image must be found in the system sanction list for set-user-id and set-group-id programs. Only those data sets that are found in the sanction list are built into the STEPLIB environment for the new process image. For detailed information regarding the sanction list, and for information on STEPLIB performance considerations, see z/OS UNIX System Services Planning.
The file that is used to capture messages can be changed at any time by calling the oe_env_np service (BPX1ENV) and specifying _BPXK_JOBLOG with a different file descriptor.
Message capturing is turned off if the specified file descriptor is marked for close on a fork or exec.
Message capturing is process-related. All threads under a given process share the same job log file. Message capturing may be initiated by any thread under that process.
Multiple processes in a single address space can each have different files active as the JOBLOG file; some or all of them can share the same file; and some processes can have message capturing active while others do not.
Only files that can be represented by file descriptors may be used as job log files; MVS data sets are not supported.
Message capturing will be propagated on a fork() or spawn(). In the case where a file descriptor was specified, the physical file must be the same for message capturing to continue in the forked or spawned process. If STDERR was specified, the file descriptor may be re-mapped to a different physical file.
Message capturing may be overridden on exec() or spawn() by specifying the _BPXK_JOBLOG environment variable as a parameter to the exec() or spawn().
execl("/bin/sh",
"sh",
"--",
fully_expanded_pathname,
arg1, arg2, ..., argn,
NULL
);arg, …, NULL is a series of pointers to NULL-terminated character strings specifying arguments for the process being invoked. If the new process is a main(), these strings are stored in an array, and a pointer to the array is passed in the argv parameter. The first argument is required, and it should point to a string containing the name of the file that is associated with the process that exec is starting. A NULL pointer must follow the last argument string pointer.
argv[ ] is a pointer to an array of pointers to NULL-terminated character strings. There must be a NULL pointer after the last character string to mark the end of the array. These strings are used as arguments for the process being invoked. argv[0] should point to a string containing the name of a file associated with the process being started by exec. envp[] is a pointer to an array of pointers to NULL-terminated character strings. There must be a NULL pointer after the last character string to mark the end of the array. The strings of envp provide the environment variables for the new process.
All the forms of exec functions provide a way to locate the file containing the new process you want to run and a collection of arguments that should be passed to the new process. Each form of exec has its own method for specifying this information.
Some exec calls explicitly pass an environment using an envp argument. In versions where an environment is not passed explicitly—execl(), execlp(), execv(), and execvp()—the system uses the entire environment of the caller. The caller's environment is assumed to be the environment variables that the external variable **environ points to.
The variable ARG_MAX, obtained from z/OS® UNIX services by an invocation of sysconf(_SC_ARG_MAX), specifies the maximum number of bytes that can be used for arguments and environment variables passed to the process being invoked. The number of bytes includes the NULL terminator on each string.
A process started by an exec function has all of the open file descriptors that were present in the caller, except for those files opened with the close-on-exec flag FD_CLOEXEC. See fcntl() — Control open file descriptors for more information about this flag. In file descriptors that remain open, all attributes remain unchanged (including file locks).
Directory streams that are open in the calling process image are closed in the new process image.
The state of conversion descriptors and message catalog descriptors is undefined.
Signals set to be ignored in the caller, SIG_IGN, are set to be ignored in the new process image. Be careful to take care of signals that are being ignored. Although sigaction() specifying a handler is not passed by, SIG_IGN is. Blocking of signals is also passed by. All other signals are set to the default action, SIG_DFL, in the new process image, no matter how the caller handled such signals.
The real user ID (UID), real group ID (GID), and supplementary group IDs of the new process are the same as those of the caller. If the set-user-ID mode bit of the program file is on, the effective user ID of the new process is set to the file's owner. Similarly, if the set-group-ID mode bit of the program file is on, the effective group ID of the new process is set to the file's group. The effective user ID of the new process image is saved as the saved set-user-ID, and the effective group ID of the new process image is saved as the saved set-group-ID.
Any shared memory segments attached to the calling process image will not be attached to the new process image, see shmat() — Shared memory attach operation. Any shared memory segments attached to the calling process image will be detached (that is, the value of shm_nattch decremented by one). If this is the last thread attached to the shared memory segment and a shmctl() RMID has been issued, the segment will be removed from the system.
Special behavior for XPG4.2: Interval timers are preserved across an exec.
A successful exec function automatically opens the specified program file, and updates the access time st_atime for that file. The program file is closed automatically after the program has been read from the file. The precise time of this close operation is undefined.
If successful, an exec function never returns control because the calling process is overwritten with the new process.
Consult Reason Code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRExecParmErr and JRExitRtnError.
| Reason Code | Explanation |
|---|---|
| X'xxxx0C27' | The target HFS file is not in the correct format to be an executable file. |
| X'xxxx0C31' | The target HFS file is built at a level that is higher than that supported by the running system. |
⁄* CELEBE03
This example runs a program, using the execl() function.
*⁄
#define _POSIX_SOURCE
#include <stdio.h>
#include <sys⁄wait.h> ⁄*FIX: used be <wait.h>*⁄
#include <sys⁄types.h>
#include <unistd.h>
main() {
pid_t pid;
int status;
if ((pid = fork()) == 0) {
execl("⁄bin⁄false", NULL);
perror("The execl() call must have failed");
exit(255);
}
else {
wait(&status);
if (WIFEXITED(status))
printf("child exited with status of %d\n", WEXITSTATUS(status));
else
puts("child did not exit successfully\n");
}
}child exited with status of 1