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
Operation | Environment |
---|---|
Authorization: | Supervisor or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1EXC): | 31-bit |
AMODE (BPX4EXC): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
CALL BPX1EXC,(Pathname_length,
Pathname,
Argument_count,
Argument_length_list,
Argument_list,
Environment_count,
Environment_data_length,
Environment_data_list,
Exit_routine_address,
Exit_parameter_list_address,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4EXC with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.
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 that is 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 that is 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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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 might lack permission to search a directory that is named in the Pathname parameter; it might 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 that are 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 a list of reason codes, see Reason codes in 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 the level that is supported by the running system.
Usage notes for exec
- If a UNIX set-user-ID or set-group-ID privileged program that switched the caller's effective
UID or GID invokes exec to execute a z/OS UNIX executable program file, the following conditions
must be met:
- The program file and any symbolic links that comprise the path name to the file must have the proper attributes to allow the invocation.
- The z/OS UNIX executable file must be installed with an owning UID of 0 or with an owning UID equal to that of the calling set-user-ID program or have the program control extended attribute.
Any symbolic link that comprises the path name to the file or any external symbolic link, must follow these conditions, except that the program control extended attribute cannot be used because links do not have extended attributes.
Additionally, a file or link found in a file system that is mounted as NOSECURITY is not considered trusted for this type of invocation, regardless of its attributes. Not following this setup causes the caller of the exec service to end abnormally with a EC6-xxxxE04B abend. If a UNIX set-user-ID or set-group-ID privileged program that switched the caller's effective UID or GID invokes exec to run a non-privileged program, the new process image created to run the program inherits the privilege of the set-user-ID or set-group-ID program.
If a UNIX set-user-ID or set-group-ID privileged program that switched the caller's effective UID or GID invokes exec to execute a z/OS UNIX executable program file, the program file and any symbolic links that comprise the path name to the file must have the proper attributes to allow the invocation.- The z/OS UNIX executable file must be installed with an owning UID of 0 or with an owning UID equal to that of the calling set-user-ID program or have the program control extended attribute.
- The same is true for any symbolic link that comprises the path name to the file or any external symbolic link, except that, the program control extended attribute cannot be used because links do not have extended attributes.
- 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 that contains 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.
If an exit was registered to get control during a shutdown by an unauthorized caller and the new process image will run authorized, then the exit address will not be propagated to the new process.
- 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
- The new process image inherits the following from the calling
process image:
- Process ID
- Parent process ID
- The time that is 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.
- 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.
- 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.
- 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.
- 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.
- 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 table
lists the accepted values for the STEPLIB environment variable and the actions taken for each value.
Value Action taken STEPLIB=NONE No STEPLIB DD is 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 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. 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. Instead, it 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. If they do not follow the standard naming conventions, they are ignored. The data sets are also ignored if they do follow the standard naming conventions but these 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 will also ignore the data set and continue allocating the 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. This case is similar but not strictly equal to the case of uncataloged data sets.
Because the data sets are ignored, the executable file might run without the proper STEPLIB environment. If a data set is ignored due to improper security access, a X'913' abend is generated. The dump for this abend can be suppressed by your installation
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 more information about the sanction list, see Using sanction lists in z/OS UNIX System Services Planning. For information about STEPLIB performance considerations, see Controlling use of STEPLIBs in z/OS UNIX System Services Planning.
If the STEPLIB environment variable is not specified, the default behavior of the exec service is the same as if STEPLIB=CURRENT were specified.
- 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.
- The _BPX_ACCT_DATA environment variable can be used to change the account data of the new
process image. Specifying this environment variable triggers a new job. The rules for specifying the
account data are as follows:
- 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 is ignored. No other validity or syntax checking will be done.
- Each shared-memory segment attached to the calling process is detached, and the value of the number of processes that are attached to each detached segment (shm_nattch) is decremented by 1. If this is the last process that is 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.
- The semaphore adjustment value,
semadj
, is inherited by the new process. - 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.
- 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.The following restriction exists for sticky bit programs that have the set-user-ID or set-group-ID attributes:
- 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 to
be successfully exec'ed. For examples of BPX.STICKYSUG.program_name, see Setting up the UNIX-related FACILITY and SURROGAT class profiles in z/OS UNIX System Services Planning.
Failure to follow this restriction will cause the caller of exec to end abnormally with a EC6-xxxxE055 abend.
- 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 to
be successfully exec'ed. For examples of BPX.STICKYSUG.program_name, see Setting up the UNIX-related FACILITY and SURROGAT class profiles in z/OS UNIX System Services Planning.
- 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.
- 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.
- If the target executable program is an IBM® Language Environment-enabled program, the environment variables that are supplied to the service must include the null terminator as part of the string and length.
- If the program that is 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.
- 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.
- The _BPXK_MDUMP environment variable can be used to specify where a SYSMDUMP is to be written.
The following table lists the allowable values:
Value Description OFF The dump is 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 that is named coredump.pid in the user's working directory (where pid is the process ID for the process that is being dumped) and writes the core dump (SYSMDUMP) in hexadecimal format. MVS data set name The dump is 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 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. - 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 table lists the allowable values:
Value Description nn Job log messages are written to open file descriptor nn. STDERR Job log messages are written to the standard error file descriptor, 2. NONE Job log messages are not written. NONE 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 can 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.
- If the BPXK_SIGDANGER environment variable is set to YES, the process receives 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.
- 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.
- 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 Using sanction lists in z/OS UNIX System Services Planning.
- 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 about _BPXK_SUID_FORK, see Commonly used environment variables in z/OS UNIX System Services Planning.
- 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 about _BPXK_DISABLE_SHLIB, see 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 path name
- umask (BPX1UMK, BPX4UMK) — Set the file mode creation mask
Characteristics and restrictions
- 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.
- 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.
- 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.
- 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.
- 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.
- For semaphore users, when the process exec is issued, the SemAdj values are inherited by the new process image.
- 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.
- 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 Commonly used environment variables in z/OS UNIX System Services Planning.
Examples
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 calling process does not have any subtasks that are part of another process, and if the calling process was created via a call to the attach_execmvs or attach_exec service, only the initial thread task of the process and all of its subtasks are terminated, and a new task is attached to the parent process creator task to run the specified program. The initial thread task in such a process is the task that was created as a result of the call to the attach_execmvs or attach_exec service. This call to the exec service does not result in the ending of any other tasks in the calling job step, nor does it end other processes in the same address space.
- If the calling process has any subtasks that are part of another process, or if the calling process was not created via a call to the attach_exec or attach_execmvs service, the exec invocation is not allowed to prevent the unexpected termination of other processes in the address space. The caller receives a return code and reason code detailing the error.
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.