exec functions

STEPLIB

Supports the creation and propagation of a STEPLIB environment to the new process image. The following are the accepted values for the STEPLIB environment variable and the actions taken for each value:

• STEPLIB=NONE. No Steplib DD is to be created for the new process image.
• STEPLIB=CURRENT. The TASKLIB, STEPLIB or JOBLIB DD data set allocations that are active for the calling task at the time of the call to exec() are propagated to the new process image, if they are found to be cataloged. Uncataloged data sets are not propagated to the new process image.
• STEPLIB=Dsn1:Dsn2:,...DsnN. The specified data sets, Dsn1:Dsn2:...DsnN, are built into a STEPLIB DD in the new process image.
  Note: The actual name of the DD is not STEPLIB, but is a system-generated name that has the same effect as a STEPLIB DD. The data sets are concatenated in the order specified. The specified data sets must follow standard MVS data set naming conventions. Data sets found to be in violation of this standard are ignored. The data sets are ignored if the data sets do follow the standard, but the following situations exist:

  • The caller does not have the proper security access to a data set
  • A data set is uncataloged or is not in load library format

  The system also ignores the data set and continues allocating other data sets in these situations:

  • If the system cannot acquire a shared ENQueue on the data set name because another job has ENQueued it exclusively.
  • If the specified data set does not exist, which is similar but not strictly equal to the case of uncataloged data sets.

  Because the data sets in error are ignored, the executable file may run without the proper STEPLIB environment. If a data set is in error due to improper security access, a X'913' abend is generated. The dump for this abend can be suppressed by your installation.

The ENQueues on an original STEPLIB DD (from submitting the job) are DEQueued (freed) if this is the last JCL step naming the data set on a STEPLIB or other DD statement. This is standard initiator behavior. The system acquires new ENQueues for the data sets named in the STEPLIB variable each time an exec() type function is called.

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.

_BPX_JOBNAME

Used to change the jobname of the new process image. The jobname change is allowed only if the invoker has appropriate privileges and is running in an address space created by fork. If these conditions are not met, the environment variable is ignored. Accepted values are strings of 1–8 alphanumeric characters. Incorrect specifications are ignored.

_BPX_ACCT_DATA

Used to change the account data of the new process image. Rules for specifying account data:

• Up to 142 actual account data characters are allowed, including any commas
• Sub-parameters must be separated by commas.
• There is no restriction on the character set.
• If the account data is greater than 142 characters, the data is ignored.

_BPXK_JOBLOG

The _BPXK_JOBLOG environment variable can be used to specify that WTO messages are to be written to an open HFS job log file. The following are the allowable values:

Value

Description

nn

Job log messages are to be written to open file descriptor nn.

STDERR

Job log messages are to be written to the standard error file descriptor, 2.

None

Job log messages are not to be written. This is the default.

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().

Message capturing will only work in forked (BPXAS) address spaces.

Note: This is not true joblog support, messages that would normally go to the JESYSMSG data set are captured, but messages that go to JESMSGLG are not captured.

execl("/bin/sh",
      "sh",
      "--",
      fully_expanded_pathname,
      arg1, arg2, ..., argn,
      NULL
     );

• Controlling terminal (XPG4.2)
• Nice value (see nice() — Change priority of a process) (XPG4)
• semadj values (see semop() — Semaphore operations) (XPG4)
• Process ID
• Parent process ID
• Process group ID
• Resource limits (see setrlimit() — Control maximum resource consumption and ulimit() — Get or set process file size limits) (XPG4.2)
• Session membership
• Time left until an alarm clock signal
• Working directory
• Root directory
• File mode creation mask
• File size limit (see ulimit() — Get or set process file size limits) (XPG4)
• Process signal mask
• Pending signals
• tms_utime, tms_stime, tms_cutime, and tms_cstime. See times() — Get process and child process times for more about these qualities.

1. A prior loaded copy of an HFS program in the same address space is reused under the same circumstances that apply to the reuse of a prior loaded MVS unauthorized program from an unauthorized library by the MVS XCTL service with the following exceptions:
   • If the calling process is in Ptrace debug mode, a prior loaded copy is not reused.
   • If the calling process is not in Ptrace debug mode, but the only prior loaded usable copy found of the HFS program is in storage modifiable by the caller, the prior copy is not reused.
2. If the specified file name represents an external link or a sticky bit file, the program is loaded from the caller's MVS load library search order. For an external link, the external name is only used if the name is eight characters or less, otherwise the caller receives an error from the loadhfs service. For a sticky bit program, the file name is used if it is eight characters or less. Otherwise, the program is loaded from the HFS, and the following restriction exists for sticky bit programs that have the set-user-ID or set-group-ID attribute:

   If the program is found in the MVS program search order, the MVS program name must have a BPX.STICKYSUG.program_name resource profile defined in the RACF® FACILITY class. See z/OS UNIX System Services Planning for details on defining the resource profile. Failure to follow this restriction will cause the abend EC6 with code xxxxE055.

3. If the calling task is in a WLM enclave, the resulting task in the new process image is joined to the same WLM enclave. This allows WLM to manage the old and new process images as one ‘business unit of work’ entity for system accounting and management purposes.

Error Code

Description

E2BIG

The combined argument list and environment list of the new process has more bytes than the system-defined length. See sysconf() — Determine system configuration options for information about the system-defined length.

EACCES

The process did not have appropriate permissions to run the specified file, for one of these reasons:

• The process did not have permission to search a directory named in your path.
• The process did not have execute permission for the file to be run.
• The system cannot run files of this type.

EFAULT

A bad address was received as an argument of the call, or the user exit program checked.

Consult Reason Code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRExecParmErr and JRExitRtnError.

EINVAL

The new process image file has the appropriate permission and has a recognized format, but the system does not support execution of a file with this format.

ELOOP

A loop exists in symbolic links. This error is issued if the number of symbolic links detected in the resolution of the path or file argument is greater than POSIX_SYMLOOP (a value defined in the limits.h header file)

ELEMULTITHREAD

The exec function was invoked from a multithreaded environment.

EMVSSAF2ERR

The executable file is a set-user-ID or set-group-ID file, and the file owner's UID or GID is not defined to RACF.

ENAMETOOLONG

All or part of the file name is too long. This can happen if:

• A path or file argument exceeds the value of PATH_MAX, or an element of your path exceeds PATH_MAX.
• Any pathname component is greater than NAME_MAX, and _POSIX_NO_TRUNC is in effect.
• The length of a path name string substituted for a symbolic link in the path argument exceeds PATH_MAX.

The PATH_MAX and NAME_MAX values are determined with pathconf().

ENOENT

One or more pathname components in path or file does not exist. This error is also issued if path or file is a NULL string.

ENOEXEC

The new process image file has the appropriate access permission but has an unrecognized format. This errno can be returned from any one of the exec family of functions, except for execlp() and execvp().

Note: Reason codes further qualify the errno. For most of the reason codes, see z/OS UNIX System Services Messages and Codes.

For ENOEXEC, the reason codes are:

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.

ENOMEM

The new process requires more memory than is permitted by the operating system.

ENOTDIR

A directory component of path or file is not really a directory.

/* 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