__poe() — Port of entry information

Standards

Standards / Extensions	C or C++	Dependencies
z/OS UNIX	both	z/OS® V1R5

Format

#define _OPEN_SYS
#include <sys/socket.h>

int __poe(__poecb_t *poecbp);

General description

The __poe() function allows the application to specify what port of entry (POE) information the system should use in determining various levels of permission checking. The attributes for the port of entry are used by services that perform user ID security authorization (examples are: setuid(), __login(), __passwd()).

Argument poecbp is the address of a __poecb_t structure which is used to control the port of entry operation. The __poecb_t structure is defined in <sys/socket.h>. For proper behavior the user should ensure that this structure has been initialized to zeros before it is populated. The elements of the __poecb_t structure are as follows:

__poe_options

Port of entry options. There are scope and action options. The combination defines the behavior of the function.

The scope option values are:

_POE_SCOPE_THREAD
_POE_SCOPE_PROCESS
_POE_SCOPE_SOCKET

Scope options _POE_SCOPE_THREAD, _POE_SCOPE_PROCESS, and _POE_SCOPE_SOCKET are mutually exclusive. One must be specified.

Note: As of z/OS V1R12, scope options _POE_THREAD and _POE_PROCESS have been deprecated and replaced with new names. The old names remain for compatibility and must be used when TARGET compile option is prior to z/OS V1R12.

The action option values are:

_POE_ACTION_READ
_POE_ACTION_WRITE
_POE_ACTION_SETGET

Action options _POE_ACTION_READ, _POE_ACTION_WRITE, and _POE_ACTION_SETGET are mutually exclusive. These are optional.

__poe_entry_type

Port of entry type. The types are:

_POE_SOCKET: Entry is a file descriptor for a socket.
_POE_FILE: Entry is a file descriptor for a non-socket file. Supported file types are character special, FIFO, regular, symbolic link, and directory.

__poe_entry_len

Port of entry length. The lengths are:

_POE_SOCKET_LEN: Length of a file descriptor for a socket.
_POE_FILE_LEN: Length of a file descriptor for a non-socket file.

__poe_entry_ptr

Address of port of entry.

__poe_poeattr

Port of entry attributes. This element is an IocPoeAttr structure as defined in <termios.h>.

The following table summarizes the port of entry operation according to scope and action:

Options		POE Data		Description
Scope	Action	Source	Destination	Description
Socket	Read	Socket or file descriptor	POE data in struct __poecb_s	POE data is extracted from the file/socket descriptor supplied by the caller and returned to the caller via the struct __poecb_s.
	Write	n/a	n/a	Request fails with EINVAL
	SetGet	n/a	n/a	Request fails with EINVAL
	None	n/a	n/a	Request fails with EINVAL
Process	Read	Process level (OAPB)	POE data in struct __poecb_s	Process level POE data is copied from the OAPB and is returned to the caller via the struct __poecb_s.
	Write	POE data in struct __poecb_s	Process level (OAPB)	POE data received from the caller via the struct __poecb_s is copied to the process level POE data in the OAPB.
	SetGet	Socket or file descriptor	Process level (OAPB) and POE data in struct __poecb_s	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 struct __poecb_s.
	None	Socket or file descriptor	Process level (OAPB)	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	Read	Thread level (OTCB)	POE data in struct __poecb_s	Thread level POE data copied from the OTCB is returned to the caller via the struct __poecb_s.
	Write	POE data in struct __poecb_s	Thread level (OTCB)	POE data received from the caller via the struct __poecb_s is copied to the thread level POE data in the OTCB.
	SetGet	Socket or file descriptor	Thread level (OTCB) and POE data in struct __poecb_s	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 struct __poecb_s.
	None	Socket or file descriptor	Thread level (OTCB)	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 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 FACILITY class profile. For an application to use this service the user ID it runs under must be given read access to this profile. See z/OS UNIX System Services Planning for more information on setting up this profile.
For a lower security arrangement, you can assign the user ID under which the application is run a UID of 0 so that it operates as a superuser.

For more detailed information on the usage of this function see z/OS Planning for Multilevel Security and the Common Criteria and z/OS UNIX System Services Programming: Assembler Callable Services Reference.

Returned value

If successful, __poe() returns 0.

If unsuccessful, __poe() returns -1 and sets errno to one of the following values:

EINVAL: The __poecb_t structure is not correct. Use __errno2() for more details.
EPERM: The calling process does not have the appropriate privileges to read or write the POE attributes.
EFAULT: A bad address was received. Either the poecbp parameter or the __poe_entry_ptr field in the __poecb_t structure is not a valid address.

Related information

sys/socket.h
__poe() (BPX1POE, BPX4POE) -- Port of entry information” in z/OS UNIX System Services Programming: Assembler Callable Services Reference.