__poe() (BPX1POE, BPX4POE) — Port of entry information
Function
- Read access to the BPX.POE resource in the FACILITY class
- A UID of 0 when the BPX.POE resource is not defined
Requirements
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. |
Format
CALL BPX1POE,(Poecb_length,
Poecb,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4POE with the same parameters.
Parameters
- Poecb_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
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).
- Poecb
- Supplied and returned parameter
- Type:
- Structure
- Length:
- Specified by the Poecb_length parameter
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_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the __poe() service returns one of the following:0
, if the request is successful.-1
, if the request is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the __poe() service stores the return code. The __poe() 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 __poe() service returns one of the following values in the Return_code parameter: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. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
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. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- The ability to register port of entry is a privileged operation.
An installation has two ways of allowing an application to use this
service:
- For the highest level of security, the installation defines the BPX.POE resource in the FACILITY class. For an application to use this service, the user ID it runs under must be given read access to that resource.
- For a lower security arrangement, you can assign the user ID under which the application runs a UID of 0 so that it operates as a superuser.
- Poecb control block: When the POEEntryPtr field in the BPXYPOE
mapping contains the address of a file descriptor, the caller must
indicate in the POEEntryType field what type of file the file descriptor
represents. The two supported file types are:
- POE#EntrySocket — the file descriptor is for a socket file.
- POE#EntryFile — the file descriptor is for a non-socket
file. This includes the following file types:
- Character special
- FIFO
- Regular
- Symbolic link
- Directory
To clear the POE data that has been registered for a thread or process, specify the following data and options in the poecb and call the __poe() service.- POE#Attributes set to zeros (X'00) or blanks (X'40)
- POE#ActionWrite
- POE#ScopeProcess or POE#ScopeThread
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
Table 1. Poecb control block: Socket scope Action Source Destination Results 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 Not applicable Not applicable Request fails with EINVAL/JrPoeSocketScopeErr SetGet Not applicable Not applicable Request fails with EINVAL/JrPoeSocketScopeErr None Not applicable Not applicable Request fails with EINVAL/JrPoeSocketScopeErr Table 2. Poecb control block: Process scope Action Source Destination Results 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 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 Table 3. Poecb control block: Thread scope Action Source Destination Results 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 - The POE data registered via the __poe() service is passed to RACF by z/OS UNIX services
that create a new security context (ACEE). The z/OS UNIX services
that utilize POE data are:
- __passwd()
- pthread_security_np()
- __login()
- setuid()/seteuid()/setreuid()
- spawn (only with user ID change)
- When z/OS UNIX services call RACF to build a new security context, POE data
is passed to RACF using the
parameters in Table 4 for RACROUTE REQUEST=VERIFY ENVIR=CREATE
Table 4. RACROUTE parameters for POE data POE data RACROUTE parameter POELabel SECLABL POEProfile SERVAUTH POETermid TERMID. is only specified by the z/OS UNIX __passwd() and setuid()/seteuid()/setreuid() services. The amount and source of POE data passed to RACF varies based on the caller's environment.- When the caller's address space security label is non-SYSMULTI, only the SECLABL parameter is specified.
- When the caller's address space security label is SYSMULTI, the
following RACROUTE parameters are specified when the corresponding
POE data is found in the search order. POE data from only one level
will ever be specified. When valid POE data is found in the search
order the search stops. For example, if a thread-level POELabel (SECLABL)
is found the search will continue for POEProfile (SERVAUTH) and POETermid
(TERMID) thread-level data but will not search at the process or address
space level.
- SECLABL
- Thread level (Otcb)
- Process level (Oapb)
- Address space seclabel (SYSMULTI)
- SERVAUTH
- Thread level (Otcb)
- Process level (Oapb)
- TERMID (only for the __passwd() and setuid(0/seteuid()/setreuid()
services)
- Thread level (Otcb)
- Process level (Oapb)
- SECLABL
- Table 5 describes the POE data propagation
for z/OS UNIX services that create a new process, a new
process image (exec), or a new thread.
Table 5. POE data propagation for z/OS UNIX services Service Thread POE data Process POE data fork() Yes Yes spawn() No Yes exec() No Yes pthread_create() 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. attach_exec() No Yes attach_execMVS() No Yes execMVS() No Yes
Characteristics and restrictions
The __poe() service is restricted to users that have the appropriate privileges, as defined under Function.