The getaddrinfo callable service translates the name of a service location (for example, a host name) or a service name (for example, FTP) into a set of socket addresses and other associated information. This information can be used to open a socket and connect to, or to send a datagram to, the specified service. The TCP/IP Services resolver attempts to resolve the host name through a name server, if one is present, or through the local data sets.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1GAI): | 31-bit |
AMODE (BPX4GAI): | 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 BPX4GAI with the same parameters. Hints_Ptr and Results_Ptr are doubleword pointer fields.
You must specify Node_Name or Service_Name, or both.
The name of a fullword that contains the length of the Node_Name parameter.
The name of a fullword that contains the length of the Service_Name parameter.
See Addr_Info – AddrInfo Data Structure in the EZBREHST assembler macro for more information about the format of this structure. The EZBREHST macro is shipped in the installation's MACLIB SMP/E DDEF location.
If the Hints_Ptr parameter is not specified (zero), the invocation is treated as if ai_family=AF_UNSPEC, ai_socktype=0, ai_protocol=0, and all the ai_flags are specified as off.
The length of the canonical name is returned in the Canonical_Length parameter. If no canonical name exists, this field contains the input value that was passed in the Node_Name parameter. If AI_CANONNAMEOK in the input Addr_Info structure was zero, ai_canonname in the output Addr_Info structure is set to zero.
See Addr_Info – AddrInfo Data Structure in EZBREHST for more information about the format of this structure.
The name of a fullword in which the getaddrinfo service returns the length of the canonical name that was returned in the first Addr_Info structure pointed to by the Results_Ptr parameter.
Return_code | Explanation |
---|---|
EAI_NONAME | One of the following occurred:
|
EAI_AGAIN | The name specified by the Node_Name or Service_Name parameter could not be resolved within the configured time interval, or the resolver address space has not been started. The request can be retried later. |
EAI_FAIL | An unrecoverable error occurred. |
EAI_SOCKTYPE | The intended socket type was not recognized. |
EAI_SERVICE | The service that was passed was not recognized for the specified socket type. |
EAI_BADFLAGS | The ai_flags parameter had an incorrect setting. |
EAI_FAMILY | The ai_family parameter had an incorrect setting. |
EAI_MEMORY | A memory allocation failure occurred during an attempt to acquire an Addr_Info structure. |
The name of a fullword in which the getaddrinfo service stores the reason code. The getaddrinfo service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. Seez/OS V2R1.0 Communications Server: IP and SNA Codes for the reason codes.
Flag | Description |
---|---|
AI_PASSIVE (X'00000001') | Specifies how to fill in the NAME pointed to
in Results_Ptr. If this flag is specified, the returned address information
will be suitable for use in binding a socket for accepting incoming
connections for the specified service (such as the bind syscall).
If the Node_Name parameter is not specified, the IP address portion
of the socket address structure pointed to in Results_Ptr will be
set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY for an IPv6 address. If this flag is not specified, the returned address information will be suitable for the connect syscall (for a connection-mode protocol); or for a connect, sendto, or sendmsg syscall (for a connectionless protocol). In this case, if the Node_Name parameter is not specified, the IP address portion of the socket address structure pointed to by Results_Ptr will be set to the default loopback address for an IPv4 address (127.0.0.0) or the default loopback address for an IPv6 address (::1). This flag is ignored if the Node_Name parameter is specified. |
AI_CANONNAMEOK (X'00000002') | If this flag is specified and the Node_Name parameter is also specified, the getaddrinfo call attempts to determine the canonical name that corresponds to the Node_Name. |
AI_NUMERICHOST (X'00000004') | If this flag is specified, the Node_Name parameter must be an IP address specified in EBCDIC format, or an error (EAI_NONAME) is returned. |
AI_NUMERICSERV (X'00000008') | If this flag is specified, the Service_Name parameter must be a port number specified in EBCDIC format, or an error (EAI_NONAME) is returned. |
AI_V4MAPPED (X'00000010') | If this flag is specified when ai_family=AF_INET6
or AF_UNSPEC in the input Addr_Info structure pointed to by the Hints_Ptr
parameter and when IPv6 is supported on the system, the caller will
accept IPv4-mapped IPv6 addresses. When the AI_ALL flag is not also
specified and no IPv6 addresses are found, a query is made for IPv4
addresses. If any IPv4 addresses are found, they are returned as IPv4-mapped
IPv6 addresses. This flag is ignored if ai_family is not AF_INET6, or if ai_family is AF_UNSPEC but IPv6 is not supported on the system. |
AI_ALL (X'00000020') | When the ai_family field has a value of AF_INET6
and AI_ALL is set, the AI_V4MAPPED flag must also be set to indicate
that the caller will accept all addresses (IPv6 and IPv4-mapped IPv6
addresses). When the ai_family field has a value of AF_UNSPEC when
the system supports IPv6 and AI_ALL is set, the caller accepts IPv6
addresses and either IPv4 (if AI_V4MAPPED is not set) or IPv4-mapped
IPv6 (if AI_V4MAPPED is set) addresses. A query is first made for
IPv6 addresses and if it is successful, the IPv6 addresses are returned.
Another query is then made for IPv4 addresses, and any found are returned
as IPv4 addresses (if AI_V4MAPPED was not set) or as IPv4-mapped IPv6
addresses (if AI_V4MAPPED was set). If the ai_family field does not have the value of AF_INET6, or the value of AF_UNSPEC when the system supports IPv6, the flag is ignored. |
AI_ADDRCONFIG (X'00000040') | If this flag is specified, a query for IPv6
on the Node_Name will occur if the resolver determines whether either
of the following is true:
|
None.
For an example using this callable service, see BPX1GAI (getaddrinfo) example.