exec–Process a file
This set of functions (execl, execle, execlp, execv, execve, and execvp) transforms the calling process into a new process. The new process is constructed from an ordinary file, located in the z/TPF collection support file system (TFS), whose name is pointed to by the first function parameter. This file contains the 4-character z/TPF program name where the new process image begins processing.
This set of functions replaces the current process image with a new process image. The image is constructed from a regular, executable file called the new process image file. There is no return from an exec call when it is processed successfully because the calling process image is overlaid by the new process image.
When a C language program is
processed as a result of an exec call, the program
is entered as a C function call as follows, where argc is the
argument count and argv is an array of character pointers to
the arguments themselves:
int main (int argc, char *argv[]);The arguments specified by a program with one of the exec functions are passed to the new process image in the corresponding main arguments.
For those forms that do not contain an envp pointer (execl, execv, execlp, and execvp), the environment for the new process image is taken from the external variable environ in the calling process.
In the execle function, the
environment arguments are specified after the NULL parameter that
ends the arg0 arguments; for example:
execle("/usr/bin/monitor", "monitor",NULL, "DEV=COMMS", NULL);The number of bytes available for the combined argument and environment lists for the new process image is ARG_MAX.
Last updated
- Changed for PUT11
- Changed for PUT05.
- Changed for PUT00.
Format
#include <unistd.h>
int execl(const char *path, const char *arg0, ...);
int execv(const char *path, char *const argv[]);
int execle(const char *path, const char *arg0, ...);
int execve(const char *path, char *const argv[],
char *const envp[]);
int execlp(const char *file, const char *arg0, ...);
int execvp(const char *file, char *const argv[]);
- path
- A pointer to a path name that identifies the new process image file for the new process image.
- file
- A pointer that is used to construct a path name that identifies
the file for the new process image. If you specify a value that begins with a slash, the value is used as the path name for the file. Otherwise, the system obtains the path prefix for the file by searching the directories that are passed in the PATH environment variable. The current working directory is used if one of the following situations occurs:
- The PATH environment variable is not set.
- The search for the process image file fails during the search of the directories that are passed in the PATH environment variable.
- arg0
- 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 new process image. The list is ended by a NULL pointer. The
argument
argv[0]should point to a file name that is associated with the process being started by one of the exec functions. - argv
- 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 new process image. The value in
argv[0]should point to a file name that is associated with the process being started by one of the exec functions. - envp
- 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 image.
Normal return
The new process image is processed.
Error return
A value of -1 and errno is set to one
of the following for all the exec functions:
- E2BIG
- The number of bytes used by the argument list and environment list of the new process image is greater than the system-imposed limit of ARG_MAX bytes.
- EACCES
- One of the following occurred:
- The process did not have search permission for a directory listed in the path prefix for the new process image file
- The new process image file denied processing permission
- The new process image file is not a regular file and the implementation does not support processing files of its type.
- ELOOP
- This error is issued if too many symbolic links were encountered when resolving the path.
- ENAMETOOLONG
- The length of the path, the length of the file arguments, or an element of the environment variable prefixed to a file exceeds PATH_MAX; or, a component of the path name is longer than NAME_MAX.
- ENOENT
- A component of the path or file does not name an existing path or file, or the file is an empty string.
- ENOTDIR
- A component of the path prefix for the new process image file is not a directory.
- ETPFFSNOTRDY
- The TFS has not been initialized or cannot be used by the process.
The execl, execle, execv, and execve functions return:
- ENOEXEC
- The new process image file has the appropriate access permission, but it is not in the correct format. The new process image file must be a valid executable file object and the first line of that file object must be a valid program path.
The exec functions may return:
- ENAMETOOLONG
- Resolution of a symbolic link in the path name produced an intermediate result whose length exceeds PATH_MAX.
- ENOMEM
- The new process image requires more memory than is allowed by the hardware or system-imposed memory management constraints.
Programming considerations
- You must have authorization to use a restricted macro to call this function.
- The new process image file must be a valid executable file object and the first line of that file object must be a valid program path.
- File descriptors open in the calling process image remain open in the new prcess image except for those whose FD_CLOEXEC flag is set. For those file descriptors that remain open, all attributes of the open file description, including file locks, remain unchanged.
- Directory streams open in the calling process image are closed in the new process image.
- Signals set to the default action (SIG_DFL) in the calling process image are set to the default action in the new process image. Signals set to be ignored (SIG_IGN) by the calling process image are set to be ignored by the new process image. Signals set to be caught by the calling process image are set to the default action in the new process image. See the signal.h header file.
- After a successful call to any of the exec functions, any functions previously registered by atexit and any handlers previously registered by pthread_atfork are no longer registered.
- If the ST_NOSUID bit is set for the TFS that contains the new process image file, then the effective user ID, effective group ID, saved set-user-ID, and saved set-group-ID are unchanged in the new process image. Othewise, if the set-user-ID mode bit of the new process image file is set, the effective user ID of the new process image is set to the user ID of the new process image file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. The real user ID, real group ID, and supplementary group IDs of the new process image remain the same as those of the callng process image. The effective user ID and the effective group ID of the new process image are saved as the saved set-user-ID and the saved set-group-ID for use by the setuid function.
- Any shared memory segments attached to the calling process image will not be attached to the new process image.
- If the asynchronous input and output option is in use, any outstanding asynchronous input/output (I/O) operations may be canceled. Asynchronous I/O operations that are not canceled will complete as if the exec functions had not yet occurred, but any associated signal notifications are suppressed. It is not known whether the exec functions block awaiting such I/O completion. In no event, however, will the new process image created by the exec functions be affected by the presence of outstanding asynchronous I/O operations at the time the exec functions are called. Whether any I/O is canceled, and which I/O may be canceled when using the exec functions, is implementation dependent.
- At a minimum, the new process image inherits the following attributes
from the calling process image:
- Process ID
- Parent process ID
- Process group ID
- Real user ID
- Real group ID
- Supplementary group IDs
- Time left until an alarm clock signal (see alarm–Schedule an alarm)
- Current working directory
- Root directory
- File mode creation mask (see the umask ) function
- File size limit
- Process signal mask (see sigprocmask–Examine and change blocked signals)
- Pending signal (see sigpending–Examine pending signals)
- Resource limits
- Controlling terminal.
Examples
The following example shows a
simple way of using fork and exec.
// Test driver for Posix fork() and exec()
#include <unistd.h>
#include <tpf/tpfapi.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <c_proc.h>
#include <i_fdes.h>
FILE* file;
void
QZZ1()
{
static pid_t pid;
int rc;
printf("Starting fork() test...\n");
file = fopen("/qzz0.test", "a");
pid = fork();
if (pid == -1) {
printf("Error return from fork(). errno = %d\n", errno);
} else {
if (pid) {
printf("Returning to parent\n");
rc = fwrite("parent\n", 7, 1, file);
} else {
printf("Returning to child\n");
rc = fwrite("child \n", 7, 1, file);
rc = execl("/test.sh", "test.sh", parm1, parm2, NULL);
}
}
fclose(file);
exit(0);
} // end Related information
- alarm–Schedule an alarm
- fork: Create a new process
- sigpending–Examine pending signals
- sigprocmask–Examine and change blocked signals
- tpf_exec–Execute a program.
For more information about z/TPF C/C++ language support, see z/TPF C functions overview.