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.
|
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.1) 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.