getaddrinfo (BPX1GAI, BPX4GAI) — Get the IP address and information for a service name or location

Function

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.

Requirements

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.

Format

The syntax format is as follows:

AMODE 64 callers use BPX4GAI with the same parameters. Hints_Ptr and Results_Ptr are doubleword pointer fields.

Parameters

Node_Name
Supplied parameter
Type:
Character
Character set:
EBCDIC
Length:
Specified by Node_Name_Length
Node_Name can be specified as one of the following:
  1. An EBCDIC character string, up to 255 characters long, set to the node name (host name) that is being queried.
  2. An EBCDIC character string set to the IP address of the node (host) where the service resides.
Also, Node_Name can include scope information in the form host name%scope information or IP address%scope information. The scope information can be an interface name or an interface index, and must be specified as an EBCDIC character string. The combined character string of host name and scope information cannot exceed 255 characters in length.

You must specify Node_Name or Service_Name, or both.

Node_Name_Length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the length of the Node_Name parameter.

Service_Name
Supplied parameter
Type:
Character
Character set:
EBCDIC
Length:
Specified by Service_Name_Length
Service_Name can be specified as one of the following:
  1. An EBCDIC character string, up to 32 characters long, set to the service name that is being queried.
  2. An EBCDIC character string set to the port number of the required service.
You must specify Node_Name or Service_Name, or both.
Service_Name_Length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the length of the Service_Name parameter.

Hints_Ptr
Supplied parameter
Type:
Pointer
Length:
Fullword (doubleword)
The name of a field that contains a pointer to an input Addr_Info structure. The following information can be specified in the input Addr_Info:
  • A set of flags (ai_flags) for interpreting the request. The flag settings are as follows: AI_PASSIVE, AI_CANONNAMEOK, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.
  • The address family (ai_family) that the caller expects to be returned by the resolver. Valid settings are AF_UNSPEC, AF_INET, and AF_INET6.
  • The socket type (ai_socktype) that the caller can accept as a response.
  • The protocol (ai_protocol) that the caller can accept as a response.
All other fields in the Addr_Info structure must be set to zero.

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.

Results_Ptr
Returned parameter
Type:
Pointer
Length:
Fullword (doubleword)
The name of a field that contains a pointer to an output Addr_Info structure. If more than one address is returned, this field contains a linked list of output Addr_Info structures. Each output Addr_Info structure contains the following information:
  • A set of flags (ai_flags) for interpreting the address that is returned in this Addr_Info structure. For output Addr_Info structures, this value is unpredictable.
  • The address family (ai_family) for the address returned in this Addr_Info structure.
  • The socket type (ai_socktype) for the address returned in this Addr_Info structure.
  • The protocol (ai_protocol) for the address returned in this Addr_Info structure.
  • The length (ai_addrlen) of the sock_inet_sockaddr or sock_inet6_sockaddr structure returned in the ai_addr field.
  • The canonical name (ai_canonname) associated with the input Node_Name, if this was requested using the input AI_CANONNAMEOK flag. If more than one Addr_Info structure is returned, the canonical name is supplied in only the first Addr_Info structure.

    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.

  • The socket address (ai_addr) returned by the resolver in this Addr_Info structure, in the form of a sock_inet_sockaddr or sock_inet6_sockaddr address structure. The length of the address returned is supplied by ai_addrlen.
  • The next Addr_Info structure (ai_next) returned by the resolver. If this is the last Addr_Info structure returned as part of the reply, this value is X'00000000'.

See Addr_Info – AddrInfo Data Structure in EZBREHST for more information about the format of this structure.

Canonical_Length
Returned parameter
Type:
Integer
Length:
Fullword

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_value
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the getaddrinfo 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 getaddrinfo service stores the return code. The getaddrinfo service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS Communications Server: IP and SNA Codes. The getaddrinfo service can return one of the following values in the Return_code parameter:
Return_code Explanation
EAI_NONAME One of the following situations occurred:
  1. The name does not resolve for the specified parameters.
  2. A Name or Service operand was not specified. At least one of the Name or Service operands must be specified.
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.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

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 Communications Server: IP and SNA Codes for the reason codes.

Usage notes

  1. When you specify Node_Name as an EBCDIC IP address, you must use the conventional forms for expressing IPv4 and IPv6 addresses as text strings. For example, the IPv4 address 1.1.1.1 would be specified as F14BF14BF14BF1, and the IPv6 address 1:1:1:1:1:1:1:1 would be specified as F17AF17AF17AF17AF17AF17AF17AF1.
  2. When you specify the AI_NUMERICHOST flag in the input Addr_Info structure pointed to by the Hints_Ptr parameter, Node_Name must be an IP address specified as an EBCDIC character string.
  3. When you specify Node_Name as an IP address, the address returned in the different structures is in different formats:
    • The IP address returned in the ai_canonname field of the first Addr_Info structure pointed to by Results_Ptr is in its EBCDIC format.
    • The IP address returned in the sock_inet_sockaddr or sock_inet6_sockaddr structure of each returned Addr_Info structure pointed to by Results_Ptr is in numeric form (hexadecimal).
  4. When the AI_NUMERICSERV flag is specified in the input Addr_Info structure pointed to by the Hints_Ptr parameter, Service_Name must be a port number specified as an EBCDIC character string.
  5. The gettaddrinfo service supports a fully thread-safe environment. The Addr_Info structure or structures are allocated by the resolver and returned to the invoking application. The storage is subsequently returned to the resolver task, to be freed by the freeaddrinfo service (freeaddrinfo (BPX1FAI, BPX4FAI) — Free Addr_Info structures). The storage for the Addr_Info structures is allocated in the caller's TCB key, and can be accessed in any key. To free the Addr_Info structures using the freeaddrinfo service, or change the contents of the structures, the application must be in their TCB key.
  6. To get the most useful set of IP addresses available for the requested host name, applications that are enabled for IPv6 processing should specify AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG in the ai_flags field; and AF_UNSPEC for the ai_family field in the input Addr_Info structure pointed to by the Hints_Ptr parameter. When the stack has IPv6 capability, requests that are coded with AF_UNSPEC are treated as if the request is for AF_INET6, and all addresses are returned using sock_inet6_sockaddr structures (with the IPv4 addresses mapped appropriately, based on the AI_V4MAPPED setting). If there is no IPv6 capability, IPv4 addresses are returned in sock_inet_sockaddr structures. This frees the application, to some extent, from having to decide what format works for the stack.
  7. Applications are encouraged to attempt all returned addresses, in order, when using the getaddrinfo results to open a socket and connect, or to send a datagram.
  8. Scope information specified as part of the Node_Name input parameter is resolved into a zone index value and is returned in all the sock_inet6_sockaddr structures that represent IPv6 link-local addresses. Scope information is ignored for resolved IPv4 addresses and for IPv6 addresses that are not link-local scoped addresses.
  9. These are the flag descriptions specified with the Addr_Info_Structure parameter:
    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 occurs if the resolver determines whether either of the following situation is true:
    • If the system is IPv6 enabled and has at least one IPv6 interface, the resolver will make a query for IPv6 (AAAA or A6 DNS) records.
    • If the system is IPv4 enabled and has at least one IPv4 interface, the resolver will make a query for IPv4 (A DNS) records. The loopback address is not considered in this case as a valid interface.

Related services

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1GAI (getaddrinfo) example.

Parent topic: Callable services descriptions