__poe() (BPX1POE, BPX4POE) — Port of entry information

Function

Requirements

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 complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The __poe() service can return 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. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. The ability to register port of entry is a privileged operation. An installation has two ways of allowing an application to use this service:
   1. 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.
   2. 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.
2. 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

   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

3. 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 userid change)
4. When z/OS UNIX services call RACF to build a new security context, POE data is passed to RACF using the following parameters for RACROUTE REQUEST=VERIFY ENVIR=CREATE

   Table 2. RACROUTE parameters for POE data

   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.

   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
       1. Thread level (Otcb)
       2. Process level (Oapb)
       3. Address space seclabel (SYSMULTI)
     • SERVAUTH
       1. Thread level (Otcb)
       2. Process level (Oapb)
     • TERMID (only for the __passwd() and setuid(0/seteuid()/setreuid() services)
       1. Thread level (Otcb)
       2. Process level (Oapb)
5. The Table 3 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 3. POE data propagation for z/OS UNIX 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.

Characteristics and restrictions

The __poe() service is restricted to users that have the appropriate privileges, as defined under Function.