GETADDRINFO

The GETADDRINFO macro translates either the name of a service location (for example, a host name), a service name, or both, and returns a set of socket addresses and associated information to be used in creating a socket with which to address the specified service or sending a datagram to the specified service.

The following requirements apply to this call:

Authorization:

Supervisor state or problem state, any PSW key.

Dispatchable unit mode:

Task.

Cross memory mode:

PASN = HASN.

Amode:

31-bit or 24-bit.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

ASC mode:

Primary address space control (ASC) mode.

Interrupt status:

Enabled for interrupts.

Locks:

Unlocked.

Control parameters:

All parameters must be addressable by the caller and in the primary address space.


>>-EZASMI--TYPE=GETADDRINFO--+-----------------------+---------->
                             '-NODE--=--+-address--+-'   
                                        +-*indaddr-+     
                                        '-(reg)----'     

>--+--------------------------+--+--------------------------+--->
   '-NODELEN--=--+-number---+-'  '-SERVICE--=--+-address--+-'   
                 +-address--+                  +-*indaddr-+     
                 +-*indaddr-+                  '-(reg)----'     
                 '-(reg)----'                                   

>--+--------------------------+--+------------------------+----->
   '-SERVLEN--=--+-number---+-'  '-HINTS--=--+-address--+-'   
                 +-address--+                +-*indaddr-+     
                 +-*indaddr-+                '-(reg)----'     
                 '-(reg)----'                                 

>--RES--=--+-address--+--+--------------------------+----------->
           +-*indaddr-+  '-CANNLEN--=--+-address--+-'   
           '-(reg)----'                +-*indaddr-+     
                                       '-(reg)----'     

>--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+----------->
              +-*indaddr-+               +-*indaddr-+   
              '-(reg)----'               '-(reg)----'   

>--+-------------------------+---------------------------------><
   '-,ERROR--=--+-address--+-'   
                +-*indaddr-+     
                '-(reg)----'

Keyword

Description

NODE

An input parameter. Storage up to 255 bytes long that contains the host name being queried. If the AI_NUMERICHOST flag is specified in the storage pointed to by the HINTS operand, then NODE should contain the queried host's IP address in network byte order presentation form. This is an optional field, but if specified you must also code NODELEN. The NODE name being queried consists of up to NODELEN or up to the first binary zero.

You can append scope information to the host name by using the format node%scope information. The combined information must be 255 bytes or less. For more information, see z/OS Communications Server: IPv6 Network and Application Design Guide.

NODELEN

An input parameter. A fullword binary field set to the length of the host name specified in the NODE field and should not include extraneous blanks. This is an optional field, but if specified you must also code NODE.

SERVICE

An input parameter. Storage up to 32 bytes long that contains the service name being queried. If the AI_NUMERICSERV flag is specified in the storage pointed to by the HINTS operand, then SERVICE should contain the queried port number in presentation form. This is an optional field, but if specified you must also code SERVLEN. The SERVICE name being queried consists of up to SERVLEN or up to the first binary zero.

SERVLEN

An input parameter. A fullword binary field set to the length of the service name specified in the SERVICE field and should not include extraneous blanks. This is an optional field but if specified you must also code SERVICE.

HINTS

An input parameter. If the HINTS argument is specified, then it contains the address of an addrinfo structure containing input values that can direct the operation by providing options and limiting the returned information to a specific socket type, address family, or protocol. If the HINTS argument is not specified, then the information returned is as if it referred to a structure containing the value 0 for the FLAGS, SOCTYPE and PROTO fields, and AF_UNSPEC for the AF field. Include the EZBREHST Resolver macro to enable your program to contain the assembler mappings for the ADDR_INFO structure.

This is an optional field.

The address information structure has the following fields:

Field

Description

FLAGS

A fullword binary field. Must have the value of 0 or the bitwise OR of one or more of the following values:

AI_PASSIVE (X'00000001')

Specifies how to specify the NAME pointed to in the returned RES. If this flag is specified, then the returned address information is suitable for use in binding a socket for accepting incoming connections for the specified service (that is the TYPE=BIND call). In this case, if the NODE argument is not specified, then the IP address portion of the socket address structure pointed to by the returned RES is set to INADDR_ANY for an IPv4 address or to the IPv6 unspecified address (in6addr_any) for an IPv6 address.
If this flag is not set, the returned address information is suitable for the TYPE=CONNECT call (for a connection-mode protocol) or for a TYPE=CONNECT, TYPE=SENDTO, or TYPE=SENDMSG call (for a connectionless protocol). In this case, if the NODE argument is not specified, then the IP address portion of the socket address structure pointed to by the returned RES is 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 argument is specified.

AI_CANONNAMEOK (X'00000002')

If this flag is specified and the NODE argument is specified, then the TYPE=GETADDRINFO call attempts to determine the canonical name corresponding to the NODE argument.

AI_NUMERICHOST (X'00000004')

If this flag is specified then the NODE argument must be a numeric host address in presentation form. Otherwise, an error of host not found [EAI_NONAME] is returned.

AI_NUMERICSERV (X'00000008')

If this flag is specified then the SERVICE argument must be a numeric port in presentation form. Otherwise, an error [EAI_NONAME] is returned.

AI_V4MAPPED (X'00000010')

If this flag is specified along with the AF field with the value of AF_INET6, or a value of AF_UNSPEC when IPv6 is supported on the system, then the caller accepts IPv4-mapped IPv6 addresses. When the AI_ALL flag is not also specified and no IPv6 addresses are found, then a query is made for IPv4 addresses. If any IPv4 addresses are found, they are returned as IPv4-mapped IPv6 addresses.
If the AF field does not have the value of AF_INET6 or the AF field contains AF_UNSPEC but IPv6 is not supported on the system, this flag is ignored.

AI_ALL (X'00000020')

When the AF 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 accepts all addresses (IPv6 and IPv4-mapped IPv6 addresses). When the AF 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 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 AF 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, then a query for IPv6 on the NODE will occur if the Resolver determines whether either of the following conditions is true:

If the system is IPv6 enabled and has at least one IPv6 interface, the Resolver makes a query for IPv6 (AAAA or A6 DNS) records.
If the system is IPv4 enabled and has at least one IPv4 interface, the Resolver makes a query for IPv4 (A DNS) records.

The loopback address is not considered in this case as a valid interface.

AI_EXTFLAGS (X'00000080') or a decimal value of 128

Requests the extended form of the getaddrinfo function. The extended form allows for additional hints to be passed to the resolver for determining the order of destination addresses that is returned. If this flag is specified, the EFLAGS field is required.

AF

A fullword binary field. Used to limit the returned information to a specific address family. The value of AF_UNSPEC means that the caller accepts any protocol family. The value of a decimal 0 indicates AF_UNSPEC. The value of a decimal 2 indicates AF_INET, and the value of a decimal 19 indicates AF_INET6.

SOCTYPE

A fullword binary field. Used to limit the returned information to a specific socket type. A value of 0 means that the caller accepts any socket type. If a specific socket type is not given (for example, a value of 0), then information on all supported socket types is returned.

The following table shows the acceptable socket types:

Type name	Decimal value	Description
SOCK_STREAM	1	for stream socket
SOCK_DGRAM	2	for datagram socket
SOCK_RAW	3	for raw-protocol interface

Anything else will fail with return code EAI_SOCKTYPE. Note that although SOCK_RAW is accepted, it is valid only when SERVICE is numeric (for example, SERVICE=23). A lookup for a SERVICE name will never occur in the appropriate services file (for example, hlq.ETC.SERVICES) using any protocol value other than SOCK_STREAM or SOCK_DGRAM.

If PROTO is not 0 and SOCTYPE is 0, then the only acceptable input values for PROTO are IPPROTO_TCP and IPPROTO_UDP. Otherwise, the TYPE=GETADDRINFO fails with return code EAI_BADFLAGS.

If SOCTYPE and PROTO are both specified as 0 then TYPE=GETADDRINFO proceeds as follows:

If SERVICE is null, or if SERVICE is numeric, then any returned addrinfos defaults to a specification of SOCTYPE as SOCK_STREAM.
If SERVICE is specified as a service name (for example, SERVICE=FTP), then TYPE=GETADDRINFO searches the appropriate services file (such as, hlq.ETC.SERVICES) twice. The first search uses SOCK_STREAM as the protocol, and the second search uses SOCK_DGRAM as the protocol. No default socket type is provided in this case.

If both SOCTYPE and PROTO are specified as a value other than 0 then they should be compatible, regardless of the value specified by SERVICE. In this context, compatible can have one of the following meanings:

SOCTYPE=SOCK_STREAM and PROTO=IPPROTO_TCP
SOCTYPE=SOCK_DGRAM and PROTO=IPPROTO_UDP
SOCTYPE=SOCK_RAW and PROTO can be anything

PROTO

A fullword binary field. Used to limit the returned information to a specific protocol. A value of 0 means that the caller accepts any protocol.

The following table shows the acceptable protocols:

Protocol name	Decimal value	Description
IPPROTO_TCP	6	TCP
IPPROTO_UDP	17	user datagram

If SOCKTYPE is 0 and PROTO is not 0, then the only acceptable input values for PROTO are IPPROTO_TCP and IPPROTO_UDP. Otherwise, the TYPE=GETADDRINFO is failed with return code EAI_BADFLAGS.

If PROTO and SOCKTYPE are both specified as 0, then TYPE=GETADDRINFO proceeds as follows:

If SERVICE is null, or if SERVICE is numeric, then any returned addrinfos default to a specification of SOCKTYPE as SOCK_STREAM.
If SERVICE is specified as a service name (for example, SERVICE=FTP), then TYPE=GETADDRINFO searches the appropriate services file (such as, hlq.ETC.SERVICES) twice. The first search uses SOCK_STREAM as the protocol, and the second search uses SOCK_DGRAM as the protocol. No default socket type is provided in this case.

If both PROTO and SOCKTYPE are specified as nonzero, then they should be compatible, regardless of the value specified by SERVICE. In this context, compatible can have one of the following meanings:

SOCTYPE=SOCK_STREAM and PROTO=IPPROTO_TCP
SOCTYPE=SOC_DGRAM and PROTO=IPPROTO_UDP
SOCTYPE=SOCK_RAW and PROTO can be anything

If the lookup for the value specified in SERVICE fails [that is, the service name does not appear in the appropriate services file (for example, hlq.ETC.SERVICES) using the input protocol], then the TYPE=GETADDRINFO fails with return code EAI_SERVICE.

NAMELEN

A fullword binary field followed by 8 padding bytes. This field must be 0.

CANONNAME

A fullword binary field followed by 4 padding bytes. This field must be 0.

NAME

A fullword binary field followed by 4 padding bytes. This field must be 0.

NEXT

A fullword binary field. This field must be 0.

EFLAGS

A fullword binary field that specifies the source IPv6 address selection preferences. This field is required if AI_EXTFLAGS is specified in the FLAGS field.

This field must contain the value 0 or the bitwise OR of one or more of the following values:

IPV6_PREFER_SRC_HOME (X'00000001') or the decimal value 1: Indicates that home source IPv6 addresses are preferred over care-of source IPv6 addresses.
IPV6_PREFER_SRC_COA (X'00000002') or the decimal value 2: Indicates that care-of source IPv6 addresses are preferred over home source IPv6 addresses.
IPV6_PREFER_SRC_TMP (X'00000004') or the decimal value 4: Indicates that temporary source IPv6 addresses are preferred over public source IPv6 addresses.
IPV6_PREFER_SRC_PUBLIC (X'00000008') or the decimal value 8: Indicates that public source IPv6 addresses are preferred over temporary source IPv6 addresses.
IPV6_PREFER_SRC_CGA (X'00000010') or the decimal value 16: Indicates that cryptographically generated source IPv6 addresses are preferred over non-cryptographically generated source IPv6 addresses.
IPV6_PREFER_SRC_NONCGA (X'00000020') or the decimal value 32: Indicates that non-cryptographically generated source IPv6 addresses are preferred over cryptographically generated source IPv6 addresses.

If contradictory EFLAGS (for example, IPV6_PREFER_SRC_TMP and IPV6_PREFER_SRC_PUBLIC) or invalid EFLAGS (for example, X'00000040' or a decimal value 64) are specified, then the GETADDRINFO call fails with RETCODE -1 and ERRNO EAI_BADEXTFLAGS (decimal value 11).

RES

Initially a fullword binary field. On a successful return, this field contains a pointer to a chain of one or more address information structures. Use the EZBREHST macro to establish address information mapping. The structures are allocated in the key of the calling application. The structures that are returned by a TYPE=GETADDRINFO call are serially reusable storage for the z/OS® UNIX process. They can be used or referenced between process threads, but should not be used or referenced between processes. When you finish using the structures, explicitly release their storage by specifying the returned pointer on a TYPE=FREEADDRINFO call.

The address information structure contains the following fields. All fields in this structure that are not specified with an explicit value are set to 0:

Field: Description
FLAGS: A fullword binary field that is not used as output.
AF: A fullword binary field. The value returned in this field can be used as the AF= argument on the TYPE=SOCKET macro to create a socket suitable for use with the returned address NAME.
SOCTYPE: A fullword binary field. The value returned in this field can be used as the SOCTYPE= argument on the TYPE=SOCKET macro to create a socket suitable for use with the returned address NAME.
PROTO: A fullword binary field. The value returned in this field can be used as the PROTO= argument on the TYPE=SOCKET macro to create a socket suitable for use with the returned address NAME.
NAMELEN: A fullword binary field followed by 8 padding bytes. The length of the NAME socket address structure. The value returned in this field can be used as the arguments for the TYPE=CONNECT or TYPE=BIND macros with such a socket, according to the AI_PASSIVE flag.
CANONNAME: A fullword binary field followed by 4 padding bytes. The address of storage containing the canonical name for the value specified by NODE. Initially, this field must be 0. If the NODE argument is specified, and if the AI_CANONNAMEOK flag was specified by the HINTS argument, then the CANONNAME field in the first returned address information structure contains the address of storage containing the canonical name corresponding to the input NODE argument. If the canonical name is not available, then the CANONNAME field refers to the NODE argument or a string with the same contents. The CANNLEN field contains the length of the returned canonical name.
NAME: A fullword binary field followed by 4 padding bytes. The address of the returned socket address structure. The value returned in this field can be used as the arguments for the TYPE=CONNECT or TYPE=BIND macros with such a socket, according to the AI_PASSIVE flag.
NEXT: A fullword binary field. Contains the address of the next address information structure on the list, or 0's if it is the last structure on the list.
EFLAGS: A fullword binary field that is not used as output.

CANNLEN

Initially an input parameter. A fullword binary field used to contain the length of the canonical name returned by the RES CANONNAME field. This is an optional field.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore the ERRNO field.

See Socket call error return codes for information about ERRNO return codes.

RETCODE

Output parameter. A fullword binary field that returns one of the following values:

Value: Description
0: Successful call.
-1: Check ERRNO for an error code.

ERROR

Input parameter. The location in your program to receive control when the application programming interface (API) processing module cannot be loaded.