__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_SOCKETScope 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_SETGETAction 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 | |
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.
- 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.