Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1POE): | 31-bit |
AMODE (BPX4POE): | 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. |
|
AMODE 64 callers use BPX4POE with the same parameters.
The name of a fullword field that contains the length of the Poecb control block that is being passed in the next parameter. To determine the value of Poecb_length, use the BPXYPOE macro (BPXYPOE — Map poe syscall parameters).
The name of a Poecb structure that is to be used to control this port of entry operation. See the section on the Poecb control block in the usage notes for details on setting the fields of the Poecb. The BPXYPOE macro (BPXYPOE — Map poe syscall parameters) maps the Poecb.
Return_code | Explanation |
---|---|
EINVAL | The Poecb structure is incorrect. Consult Reason_code to determine the exact reason the error occurred. The following reason codes unique to the __poe() service can accompany the return code: JRPoeLenErr, JRPoeScopeErr, JRPoeEntryTypeErr, and JRPoeEntryLenErr. |
EPERM | The calling address space does not have the appropriate privileges to set the POE attributes. |
EFAULT | A bad address was received in the POEEntryPtr field of the BPXYPOE mapping that was pointed to by the Poecb parameter. |
The name of a fullword in which the __poe() service stores the reason code. The __poe() service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.
When the POE data for a process or thread has been cleared, that data will no longer be included in the search order that z/OS® UNIX services use to determine the POE data to be passed to RACF® when creating a security context. For example, when both process and thread POE data has been registered, the thread-level data would take precedence over the process data. Clearing the thread-level data would cause it to be skipped and the process level data would be used if available.
POE#ScopeThread, POE#ScopeProcess and POE#ScopeSocket are mutually exclusive; only one must be specified. If none or more than one are specified the request will fail with –1/EINVAL/JRPoeScopeErr
POE#ReadPOE, POE#WritePOE and POE#SetGetPOE are mutually exclusive. If more than one is specified the request will fail with EINVAL/JRPoeActionErr.
If the POE#ReadPOE, POE#WritePOE or POE#SetGetPOE options are specified the storage obtained for the POE control block should be POE#LenV2 bytes in length. POE#LenV2 must be specified for the Poecb_length parameter on the BPX1POE syscall. If the length is incorrect the request will fail with -1/EINVAL/JrPOELenErr
POE options | POE data | Description | ||
---|---|---|---|---|
Scope | Action | Source | Destination | |
Socket | Read | Socket or file descriptor | POEAttributes area in the BPXYPOE mapping | POE data is extracted from the file/socket descriptor supplied by the caller and returned to the caller via the BPXYPOE area. The caller's thread and process level POE data in the Oaob and Otcb is unchanged. |
Write | n/a | n/a | Request fails with EINVAL/JrPoeSocketScopeErr | |
SetGet | n/a | n/a | Request fails with EINVAL/JrPoeSocketScopeErr | |
None | n/a | n/a | Request fails with EINVAL/JrPoeSocketScopeErr | |
Process | R | Process level (OapbPOEAttrs) | POEAttributes area in the BPXYPOE mapping | Process level POE data copied from the Oapb is returned to the caller via the BPXYPOE area |
W | POEAttributes area in the BPXYPOE mapping | Process level (OapbPOEAttrs) | POE data received from the caller in the BPXYPOE area is copied to the process level POE data in the Oapb | |
SetGet | Socket or file descriptor | Process level (OapbPOEAttrs) and POEAttributes area in the BPXYPOE mapping | POE data is extracted form the file/socket descriptor supplied by the caller. The data is copied to the process level POE data in the Oapb and returned to the caller via the BPXYPOE area | |
None | Socket or file descriptor | Process level (OapbPOEAttrs) | POE data is extracted from the file/socket descriptor supplied by the caller and copied to the process level POE data in the Oapb | |
Thread | R | Thread level (OtcbPOEAttrs) | POEAttributes area in the BPXYPOE mapping | Thread level POE data copied from the Otcb is returned to the caller via the BPXYPOE area |
W | POEAttributes area in the BPXYPOE mapping | Thread level (OtcbPOEAttrs) | POE data received from the caller in the BPXYPOE area is copied to the thread-level POE data in the Otcb | |
SetGet | Socket or file descriptor | Thread level (OtcbPOEAttrs) and POEAttributes area in the BPXYPOE mapping | POE data is extracted form the file/socket descriptor supplied by the caller. The data is copied to the thread-level POE data in the Otcb and returned to the caller via the BPXYPOE area | |
None | Socket or file descriptor | Thread level (OtcbPOEAttrs) | POE data is extracted from the file/socket descriptor supplied by the caller and copied to the thread-level POE data in the Otcb |
POE data | RACROUTE parameter |
---|---|
POELabel | SECLABL |
POEProfile | SERVAUTH |
POETermid | TERMID (1) |
(1) TERMID is only specified by the z/OS UNIX __passwd() and setuid()/seteuid()/setreuid() services. |
POE data propagation | ||
---|---|---|
Service | Thread POE data | Process POE data |
fork() | Yes | Yes |
spawn() | No | Yes |
exec() | No | Yes |
pthread_create() | No | Yes (*) |
attach_exec() | No | Yes |
attach_execMVS() | No | Yes |
execMVS() | No | Yes |
* The newly created thread is in the same process as the thread calling pthread_create(). By default, process level POE data is shared between all thread in the process. |
The __poe() service is restricted to users that have the appropriate privileges, as defined under Function.
For an example using this callable service, see BPX1POE (__poe) example.