exec (BPX1EXC, BPX4EXC) — Run a program

Function

The exec callable service runs a z/OS UNIX executable file that is either a program object or a REXX exec. The exec callable service replaces the current process image that calls the exec service with a new process image for the executable file that is being run.

Requirements

Parameters

Pathname_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the Pathname parameter. The length can be up to 1023 bytes long.

Pathname

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Pathname_length parameter

The name of a field that contains the fully qualified path name of the file to be run. Each component of the path name (directory name, subdirectory name, or file name) can be up to 255 characters long. The complete path name can be up to 1023 characters long, and does not require an ending NUL character.

The path name can begin with or without a slash.

• A path name that begins with a slash is an absolute path name. The slash refers to the root directory; the search for the file starts at the root directory.
• A path name that does not begin with a slash is a relative path name. The search for the file starts at the working directory.

Argument_count

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the number of pointers in the lists for the Argument_length_list and the Argument_list. If the program needs no arguments, define Argument_count as the name of a fullword that contains 0.

Argument_length_list

Supplied parameter

Type:

Structure

Length:

Variable

The name of a list of 31(64)-bit pointers. Each pointer in the list is the address of a fullword that gives the length of an argument that is to be passed to the specified program. If the program needs no arguments, define Argument_length_list as the name of a fullword (doubleword) that contains 0.

Argument_list

Supplied parameter

Type:

Structure

Length:

Variable

The name of a list of 31(64)-bit pointers. Each pointer in the list is the address of a character string that is an argument to be passed to the specified program. Each argument is of the length specified by the corresponding element in the Argument_length_list. If the program needs no arguments, define Argument_list as the name of a fullword (doubleword) that contains 0.

If the target executable file arguments require null terminators, the arguments that are supplied to this service must include the null terminator as part of the data string and the length.

Environment_count

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the number of pointers in the lists for Environment_data_length and Environment_data. If the program needs no environment data, define Environment_count as the name of a fullword that contains 0.

Environment_data_length

Supplied parameter

Type:

Structure

Length:

Variable

The name of a list of 31(64)-bit pointers. Each pointer in the list is the address of a fullword that gives the length of an environment variable to be passed to the specified program. If the program does not use environment variables, define Environment_data_length as the name of a fullword (doubleword) that contains 0.

Environment_data_list

Supplied parameter

Type:

Structure

Length:

Variable, specified by Environment_data_length

The name of a list of 31(64)-bit pointers. Each pointer in the list is the address of a character string that is an environment variable to be passed to the specified program. Each environment variable is of the length specified by the corresponding element in Environment_data_length. If the program does not use environment variables, define Environment_data_list as the name of a fullword (doubleword) that contains 0. If the target executable file is a Language Environment®-enabled program, the environment variables that are supplied to this service must include the null terminator as part of the data string and length.

Exit_routine_address

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the user's exit routine. If a user exit is not to be called, define Exit_routine_address as the name of a fullword (doubleword) that contains 0.

Exit_parameter_list_address

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the user exit parameter list. The value that is contained in this fullword (doubleword) is in register 1 when the user exit receives control. If the user exit is not to be called or does not require parameters, define Exit_parameter_link_address as the name of a fullword (doubleword) that contains 0. Currently the exit must be RMODE 31, and therefore the address must reside below the 2-gigabyte bar.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the exec service returns -1 if it is not successful. If it is successful, the exec service does not return.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the exec service stores the return code. The exec service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The exec service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The caller does not have appropriate permissions to run the specified file. It may lack permission to search a directory named in the Pathname parameter; it may lack execute permission for the file to be run; or the file to be run is not a regular file, and the system cannot run files of its type. The following reason code can accompany the return code: JRExecNotRegFile.
EFAULT	A bad address was received as an argument of the call, or the user exit program checked. The following reason code can accompany the return code: JRExecParmErr and JRExitRtnError.
ELOOP	A loop exists in symbolic links encountered during resolution of the Filename argument. This error is issued if more than 24 symbolic links are detected in the resolution of Filename.
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	File_name is longer than 1023 characters, or some component of the file name is longer than 255 characters. Name truncation is not supported.
ENOENT	No file name was specified, or one or more of the components of the specified Filename were not found. The following reason codes can accompany the return code: JRExecNmLenZero and JRQuiescing.
ENOEXEC	The specified file has execute permission, but it is not in the proper format to be a process image. Reason_code contains the loader reason code for the error.
ENOMEM	The new process requires more memory than is permitted by the hardware or the operating system. The following reason code can accompany the return code: JRExecFileTooBig.
ENOTDIR	A directory component of Filename is not a directory.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the exec service stores the reason code. The exec service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For most of the reason codes, see z/OS UNIX System Services Messages and Codes. For the ENOEXEC Return_code, Reason_code contains the loader reason code for the error:

Reason code	Explanation
X'xxxx0C27'	The target file is not in the correct format to be an executable file.
X'xxxx0C31'	The target file is built at a level that is higher than that supported by the running system.

Usage notes

1. The following characteristics of the calling process are changed when the service gives control to the new executable file:
   • The current process image is replaced with a new process image for the executable file to be run.
   • All directories that are opened via a call to the opendir service are closed in the new process image.
   • All open file descriptors remain open unless the close-on-exec flag is set.
   • Signals set to be caught are reset to their default.

     If the SSTFNOSUID bit is set for the file system containing the new process image file, the effective user ID, effective group ID, saved set-user-ID and saved set-group-ID are unchanged in the new process image. Otherwise, if the setuid bit of the new process image file is set, the effective user ID of the new process image is set to the owner ID of the new process image file. Similarly, if the setgid 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 calling process image. The effective user ID and effective group ID of the new process image is saved (as the saved set-user-ID and the saved set-group-ID) for use by the setuid and setgid functions. For more information, see BPXYMODE — Map the mode constants of the file services.

2. The executable file to be run receives control with the following attributes:
   • Problem program state
   • PSW key 8
   • AMODE=31(64), taken from the executable
   • Primary ASC mode
3. The new process image inherits the following from the calling process image:
   • Process ID
   • Parent process ID
   • The time left until an alarm signal is generated
   • File mode creation mask
   • Process signal mask
   • Pending signals
   • Time accounting information

   For more information, see times (BPX1TIM, BPX4TIM) — Get process and child process times and BPXYTIMS — Map the response structure for times.

4. The information that the service passes to the executable file to be run is a parameter list, which is pointed to by register 1. The parameter list consists of the following parameter addresses. In the last parameter address, the high-order bit is 1.

   For AMODE 31 callers, the high-order bit in the last parameter address is 1. For AMODE 64 callers, the high-order bit is part of the 64-bit address. There are always n parameters, passed with no end-of-parameter-list indicator.

   The last parameter that the exec service passed to the executable file identifies the caller of the file as the exec service. The exit gets control in the same AMODE as the caller.

5. The register usage on entry to the user exit in AMODE 31 is:
   • R0: Undefined.
   • R1: Address of the user exit parameter list, as specified by the caller of the exec service.
   • R2–R12: Undefined.
   • R13: Address of a 96-byte work area in the same key as the caller of the exec service.
   • R14: The return address from the user exit to the exec service. This address must be preserved by the user exit.
   • R15: Address of the user exit.
6. The register usage on entry to the user exit in AMODE 64 is:
   • R0: Undefined.
   • R1: 64-bit address of the user exit parameter list, as specified by the caller of the exec service.
   • R2–R12: Undefined.
   • R13: Address of a 96-byte work area in the same key as the caller of the exec service.
   • R14: The return address from the user exit to the exec service. This address must be preserved by the user exit.
   • R15: Information about the caller. Bit 61 is on and bit 62 is off, indicating an AMODE 64 caller. Bit 63 is also off, indicating that the addressing mode should not be changed on return to the caller, and that a BRANCH ON CONDITION (BCR) should be used for the return. The other bits in R15 are not relevant. Because R15 does not contain the address of the exit routine on entry, BRANCH RELATIVE instructions should be used for branching within the user exit.
7. When the exec or execmvs service is called in any environment except single task, single RB, and no linkage stack, z/OS UNIX issues an abend EC6. This takes down the calling task and all of its subtasks. The subtasks receive a 33E abend. All other thread tasks in the address space receive a 422 abend with a reason code of 00000181, and their subtasks receive a 33E abend.
8. To support the creation and propagation of a STEPLIB environment to the new process image, the exec service allows for the specification of a STEPLIB environment variable. The following are the accepted values for the STEPLIB environment variable and the actions taken for each value:
   1. STEPLIB=NONE. No STEPLIB DD is to be created for the new process image.
   2. 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 the exec service 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.
   3. 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 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. If the data sets do follow the standard, but:

      • 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 data set is ignored. 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.

   If the STEPLIB environment variable is not specified, the exec service's 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 about the sanction list, see z/OS UNIX System Services Planning. For information about STEPLIB performance considerations, see z/OS UNIX System Services Planning.

9. The _BPX_JOBNAME environment variable can be used to change the job name of the new process image. The job name change is allowed only if the invoker has appropriate privileges (see Authorization) and is running in an address space that is 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.
10. The _BPX_ACCT_DATA environment variable can be used to change the account data of the new process image. Specifying this environment variable will trigger a new job. The rules for specifying the account data are:
    • Up to 142 actual account data characters are allowed, including any commas.
    • Subparameters must be separated by commas.
    • There is no restriction on the character set.

    If the account data is greater than 142 characters, the data will be ignored. No other validity or syntax checking will be done.

11. Each shared-memory segment attached to the calling process is detached, and the value of the number of processes attached to each detached segment (shm_nattch) is decremented by 1. If this is the last process attached to a shared memory segment and shmctl (BPX1SCT, BPX4SCT) IPC_RMID has been issued for the shared memory segment, the segment will be removed from the system.
12. The semaphore adjustment value, semadj, will be inherited by the new process.
13. A prior loaded copy of a 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 of the program found is in storage modifiable by the caller, the prior copy is not reused.
14. If the specified file or link resolves to a MVS program that is link-edited AC=1 located in an APF-authorized library, the attributes of the sticky bit file or external link must be set up properly to allow this type of invocation. For a sticky bit file, it must be installed with an owning UID of 0 or with the APF extended attribute. The owning UID of 0 requirement would also apply to a symbolic link that resolves to the sticky bit file. For an external link, it must be installed with an owning UID of 0. Also, a file with the APF extended attribute is not allowed if found in a file system mounted as NOSETUID. If the specified file name represents a symbolic link to a sticky bit file that has the set-user-id attribute, the symbolic link must have an owning uid of 0 or an owning UID equal to that of the sticky bit file. If the sticky bit file has the set-group-id attribute, the symbolic link must have an owning uid of 0 or an owning GID equal to that of the sticky bit file. A file or link found in a file system mounted as NOSECURITY is not considered trusted for this type of invocation, regardless of its attributes. Failure to follow this set up will cause the executing job to end abnormally with a EC6-xxxxC04A abend when invoking the MVS program via the exec service.
15. If the specified file is not in the correct format to be an executable, but contains the "magic number" (#!) in the first line, the program that is specified in the magic number header is executed. The expected format of the magic number header is as follows:

    #! Path String

    #! is the file magic number. It identifies the first line of the file as a special header that contains the name of the program to be run and any argument data to be supplied to it.

    The Path parameter specifies the path name of the file that is to be run. It is separated by blank or tab characters from the #! characters, or can immediately follow the characters.

    The String parameter is an optional character string that can be used to pass options to a target command interpreter (shell) that is to run the script. It must be separated from the Path parameter by tab or blank characters, and cannot itself contain tab or blank characters.

    The argument data list and argument length list that are passed to the magic number file are to contain the following argument data and corresponding argument data lengths:

    • The magic number path name, ended by a null character (X'00')
    • The string, if one is supplied, ended by a null character (X'00')

    The remaining arguments in the list are to contain the list of arguments that are specified by the caller of the exec service.

    If the path name that is specified in the magic number header cannot be executed for some reason, the exec request fails with return code ENOEXEC, regardless of the error. ENOEXEC is returned for compatibility purposes, so that existing scripts can continue to run successfully when invoked from an application such as a command interpreter (shell). The reason code indicates the exact reason the magic number file could not be executed.

16. 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 purposes of system accounting and of management.
17. If the target executable program is an IBM® Language Environment-enabled program, the environment variables supplied to the service must include the null terminator as part of the string and length.
18. If the program being executed is APF-authorized, link-edited with AC=1, and is being executed on the job step task, the address space is marked as APF-authorized.
19. If the _BPX_PTRACE_ATTACH environment variable is set to YES, the target executable program is loaded into user-modifiable storage to allow subsequent debugging. Any additional programs loaded into storage during the execution of the target program are also loaded into user-modifiable storage, with the exception of modules loaded from the LPA.
20. The _BPXK_MDUMP environment variable can be used to specify where a SYSMDUMP is to be written. The following are the allowable values:

    Value

    Description

    OFF

    The dump is to be written to the current directory. This is the default. This dump is only written if the user allocates a SYSMDUMP data set for the TSO/E session. The system creates a file named coredump.pid in the user's working directory (where pid is the process ID for the process being dumped) and writes the core dump (SYSMDUMP) in hexadecimal format.

    MVS data set name

    The dump is to be written to an MVS data set. The data set name must be fully qualified, and can be up to 44 characters. It can be specified in uppercase, lowercase, or both; it is folded to uppercase.

    z/OS UNIX file name

    The dump is to be written to a z/OS UNIX file. The file name can be up to 1024 characters and must begin with a slash. The slash refers to the root directory, in which the file is created. This specification is ignored for the MODIFY BPXOINIT,DUMP command and for the SIGDUMP signal.

21. The _BPXK_JOBLOG environment variable can be used to specify that WTO messages are to be written to an open 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 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.

    When the file that is used as a job log is shared by several processes (for example, by a parent and child), the file should be opened for append. Failure to do this causes unpredictable results.

    Only files that can be represented by file descriptors may be used as job log files; MVS data sets are not supported.

    Message capturing is propagated on a fork() or spawn(). If a file descriptor is specified, the physical file must be the same in order for message capturing to continue in the forked or spawned process. If STDERR is specified, the file descriptor may be remapped to a different physical file..

    Message capturing may be overridden on exec() or spawn() by specifying the _BPXK_JOBLOG environment variable as a parameter on the exec() or spawn().

    Message capturing only works in forked (BPXAS) address spaces.

    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.

22. If the BPXK_SIGDANGER environment variable is set to YES, the process will receive a SIGDANGER signal rather than a SIGTERM signal when an OMVS shutdown is initiated. This may be advantageous for an application that uses the SIGTERM signal for other purposes.
23. When the executable file to be run is a REXX exec, the first argument should be the path name of the REXX exec. Subsequent arguments for the exec can follow this. Each argument should be a string terminated by a null character; that is, the last byte should be X'00'. Each argument length should include this last byte.
24. An environment variable, AUTHPGMLIST, has been created to work with this system call. This environment variable specifies a list that identifies the sanctioned directories or authorized program names. If activated, an additional level of security checking will be performed to ensure that the program being instantiated is coming from an authorized directory in the z/OS UNIX file system or is an authorized MVS program name. For details about the sanction list, see the topic on using sanction lists in z/OS UNIX System Services Planning.
25. The _BPXK_SUID_FORK environment variable specifies whether the setuid indicator is propagated to child address spaces created by the fork service. For more information, see Commonly used environment variables in z/OS UNIX System Services Planning.
26. If the caller specifies _BPXK_DISABLE_SHLIB=YES then future loadhfs() and loadhfs_extended() system calls will ignore the st_sharelib attribute and load the program into private storage. If the caller specifies NO (the default) then normal system shared library processing takes place. For more information, see the section on commonly used environment variables in z/OS UNIX System Services Planning

Related services

• alarm (BPX1ALR, BPX4ALR) — Set an alarm
• chmod (BPX1CHM, BPX4CHM) — Change the mode of a file or directory
• fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
• fork (BPX1FRK, BPX4FRK) — Create a new process
• sigpending (BPX1SIP, BPX4SIP) — Examine pending signals
• sigprocmask (BPX1SPM, BPX4SPM) — Examine or change a process's signal mask
• spawn (BPX1SPN, BPX4SPN) — Spawn a process
• stat (BPX1STA, BPX4STA) — Get status information about a file by pathname
• umask (BPX1UMK, BPX4UMK) — Set the file mode creation mask

Characteristics and restrictions

1. The exec service dynamically inserts into a job a new job step that has no allocations associated with it, with the exception of the MVS data sets that may be built into the STEPLIB environment for the new process image.
2. If the exec service is invoked from a process that contains one task, one request block (RB), and no linkage stack entries, the process is ended. This action results in a normal return to the operating system. Almost all forked processes run in this manner. In all other cases, the calling task receives a nonretryable EC6 abend with reason code 0000FFFE to cause it to end. All other thread tasks in the address space that are not subtasks of the calling task receive a 422 abend with reason code 00000181.
3. The user exit is given control while the exec service is still in progress. The user exit should not attempt to use any z/OS UNIX service that alters or terminates the current process (that is, the exec, exit, and kill services). If such services are attempted, the results are unpredictable. Signals cannot be delivered while in the user exit, because the exec service is still in progress and signal delivery is inhibited.
4. If you intend to run a program in an APF-authorized environment, the program that is being run by the exec service should have the APF extended attribute turned on and should be linked AC=1. DLLs that are loaded by APF-authorized applications should have the APF extended attribute set on and should be linked AC=0.
5. Any shared memory segments attached to the caller will not be attached to the newly created process image. Any shared memory segments attached to the caller will be detached and the value of shm_nattch decremented by the number of shared memory segments attached to the caller. If this is the last process attached to a shared memory segment and a shmctl IPC_RMID has been issued, the segment is removed from the system.
6. For semaphore users, when the process exec is issued, the SemAdj values are inherited by the new process image.
7. Executing a program from z/OS UNIX causes the program environment to become uncontrolled, unless the program is identified as program controlled. (That is, unless the ST_PROGCTL attribute is ON for the z/OS UNIX program file). Running a z/OS UNIX program with the ST_PROGCTL attribute set to OFF prevents future invocations of authorized programs like Program Access to Data Sets (PADS) programs. These are programs given special authorization by the installation and by the installed security product (such as RACF) to read or write to protected data sets. In addition, PADS programs should not attempt to load programs from z/OS UNIX with the ST_PROGCTL attribute OFF, because these programs are considered uncontrolled and could have been modified by users that do not have the same level of authorization as the PADS program.
8. The _BPXK_TIMEOUT environment variable is processed for this callable service. It allows applications to specify whether a specific process waiting for terminal input should be timed out. For more information about the _BPXK_TIMEOUT environment variable, see z/OS UNIX System Services Planning.

MVS-related information

If the exec service is invoked from an address space containing a single process, it tears down the existing process image by ending the currently running job step and then inserting a new step for the specified file to run in. Any MVS task-related resources that existed in the old job step are cleaned up. The new job step that is created has no allocations associated with it, except for the MVS data sets that may be built into the STEPLIB environment for the new process image. When the newly created job step ends, the flow of the job continues, as it normally does, to the next sequential step in the job, depending on the completion code of the ending step.

If the exec service is invoked after a successful setuid that changes the MVS identity and the _BPX_JOBNAME environment variable was not specified, the job name of the new process image is set to the user ID associated with the new UID specified on the setuid invocation.