attach_exec (BPX1ATX, BPX4ATX) — Attach a z/OS UNIX program

Function

The attach_exec callable service attaches a task to run a z/OS UNIX executable program in a newly created child process of the caller. The child process that is created has the same attributes that a child process would have if it were created by the fork service and followed immediately by a call to the exec service. The new process is created in the same address space as the caller, and is a subtask of the caller's task.

Requirements

Parameters

Pathname_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the path name of the file. 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.

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

Environment_count

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the number of pointers in the lists for the Environment_data_length and the 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) containing 0.

Environment_data_list

Supplied parameter

Type:

Structure

Length:

Variable, specified by the 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 the 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 program enabled by Language Environment®, 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 invoked, define Exit_routine_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.

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 contained in this fullword (doubleword) is in register 1 when the user exit receives control. If the user exit is not to be invoked or does not require parameters, define Exit_parameter_list_address as the name of a fullword (doubleword) that contains 0.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the attach_exec service returns the process ID of the created child process, if it is successful. If it is not successful, the service returns -1.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
EAGAIN	The resources required for another process to be created are not available now; or you have already reached the maximum number of processes you are allowed to run. The following reason codes can accompany the return code: JRMaxChild, JRMaxProc, JRMaxUIDs.
EACCES	The caller does not have appropriate permissions to run the specified file. It may lack permission to search a directory that is 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 codes can accompany the return code: JRExecParmErr and JRExitRtnError.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname.
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	Pathname is longer than 1023 characters, or some component of the Pathname is longer than 255 characters. Name truncation is not supported.
ENOENT	No Pathname was specified, or one or more of the components of the specified Pathname 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 codes can accompany the return code: JRExecFileTooBig and JRNoSpace.
ENOTDIR	A directory component of Pathname is not a directory.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the attach_exec service stores the reason code. The attach_exec service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the majority of 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 new process (called the child process) has similarities to the process that calls attach_exec (called the parent process), except for the following:
   • The child process has a unique process ID (PID) that does not match any active process group ID.
   • The child has a different parent process ID (namely, the process ID of the process that called attach_exec).
   • The child has its own copy of the parent's file descriptors. Each file descriptor in the child refers to the same open file as the corresponding file descriptor in the parent.
   • If a file has its FCTLCLOFORK or FTCLOEXEC flag set on, it is not inherited by the child process. These flags are set with the fcntl service. For more information, see the fcntl service Parameters.
   • Directories opened via a call to the opendir (BPX1OPD, BPX4OPD) service in the parent process are not inherited by the child process.
   • The process and system utilization times for the child are set to zero.
   • Any file locks previously set by the parent are not inherited by the child.
   • The child process has no interval timers (for example, alarms) set. This is similar to a call to the alarm service with Wait_time specified as zero.
   • The child process has no pending signals.
   • The child process does not get a copy of the parent's storage, as it would if it were created via a call to the fork service.
   • The child process can address a shared memory segment only while the parent process maintains its attachment.
   • The semaphore adjustment values (semadj) in the child process will be zero.
   • The child process created by this service is terminated when its parent terminates.
2. The executable file to be run receives control with the following attributes:
   • Problem program state
   • TCB key of caller
   • AMODE=31(64), taken from the executable
   • Primary ASC mode
3. The information that the service passes to the executable file that is to be run is a parameter list pointed to by register 1. The parameter list consists of the parameter addresses listed in this topic. 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 attach_exec passed to the executable file identifies the caller of the file as the attach_exec or exec service.

4. The user exit receives control with the following attributes:
   • Problem program state
   • PSW key of caller
   • AMODE=31(64), same as the invoker of BPX1ATX (BPX4ATX)
   • Primary ASC mode
   See Characteristics and restrictions for more information about the execution of the user exit.
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 attach_exec service.
   • R2–R12: Undefined.
   • R13: Address of a 96-byte work area in the same key as the caller of the attach_exec service.
   • R14: The return address from the user exit to the attach_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 attach_exec service.
   • R2–R12: Undefined.
   • R13: 64-bit address of a 96-byte work area in the same key as the caller of the attach_exec service. Bits 0–32 of this address are 0.
   • R14: The 64-bit return address from the user exit to the attach_exec service. This address must be preserved by the user exit. Bits 0–32 of this address are 0.
   • 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. To support the creation and propagation of a STEPLIB environment to the new process image, attach_exec 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 attach_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. 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. Those data sets found to be in violation of this standard are ignored. If the data sets follow the standard, but:
      • The caller does not have the proper security access to a data set, or
      • 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 default behavior of the attach_exec service is the same as if STEPLIB=CURRENT were specified.

   For information about STEPLIB performance considerations, see the section on tuning performance in z/OS UNIX System Services Planning.

8. A prior loaded copy of an HFS program is reused by this service 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 HFS program found is in storage modifiable by the caller, the prior copy is not reused.
9. If the specified file name resolves to 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 used only if the name is eight characters or less; otherwise the caller receives an error from the attach_exec service. For a sticky bit program, the specified file name is used if it is eight characters or less. Otherwise, the program is loaded from the z/OS® UNIX file system. If the attach_exec caller is running APF authorized and the specified sticky bit file or link resolves to an MVS program 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 task attached to run the MVS program to end abnormally with a EC6-xxxxC04A abend when the MVS program is invoked via the attach_exec service.
10. If the calling parent task is in a WLM enclave, the child task is joined to the same WLM enclave. This allows WLM to manage the parent and child as one "business unit of work" entity for system accounting and management purposes.
11. If the target executable program is a Language Environment-enabled program, the environment variables supplied to the service must include the null terminator as part of the string and length.
12. 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.
13. 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.
14. A thread that issues an attach_exec or attach_execmvs may receive an A03 abend if any attached children are still running. To avoid the A03 abend, the thread that issued the attach can use waitpid (BPX1WAT) to determine when the attached process has completed, then call mvsprocclp (BPX1MPC) to allow time for a full MVS subtask termination to occur after the child process has terminated.
15. 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 Commonly used environment variables in z/OS UNIX System Services Planning

Related services

• fork (BPX1FRK, BPX4FRK) — Create a new process
• exec (BPX1EXC, BPX4EXC) — Run a program
• attach_execmvs (BPX1ATM, BPX4ATM) — Attach an MVS program
• spawn (BPX1SPN, BPX4SPN) — Spawn a process

Characteristics and restrictions

The user exit is given control in the newly created child process on the attached task before the invocation of the specified program. The user exit should not attempt to use any kernel services. Signals cannot be delivered while in the user exit because the attach_exec service is still in progress and signal delivery is inhibited.

The setuid, setgid, setegid and seteuid services, if invoked from a process created by this service, affect the calling process and any other processes that exist in the address space. In a multiprocessing environment, however, when a process created by this service attempts to change the security environment, the request is rejected.

If exec or execmvs is invoked from a process that was created via the attach_exec service, the initial thread of the process and all of its subtasks are terminated, and a new task is attached to run the specified program. This does not result in the ending of any other tasks in the calling job step, nor does it end other processes in the address space. Because of this behavior, only unauthorized, non-privileged programs are supported on the invocation of exec and execmvs.

Sticky bit programs that are link-edited as APF-authorized may be called only by callers that run APF-authorized.

The newly attached task created for the child process does not share user storage subpools 0-127 with the caller.

MVS-related information

Because the newly created child process runs on a subtask in the same address space as the caller, it has access to the same MVS environment as the caller. This includes the same allocation (DDs) and storage environment. Because of this, programs that run on each of these tasks should be careful not to interfere with other programs running in the same environment. Although the child subtask has access to the same storage as the calling task, it does not share any user subpools with the calling task; thus it cannot free any user storage that is obtained by the calling task.