|
Description
The getaddrinfo() function returns protocol-independent host information for the AF_INET and AF_INET6 address families. The values are determined using either the Domain Name Service (DNS) or system-specific tables.
Parameters nodename and servname
When getaddrinfo() is called, at least one of the parameters nodename or servname must be not be the null pointer. nodename and servname are either a null pointer or a string terminated with the null byte. The nodename parameter can be a name or an IPv4 address in decimal dotted notation or an IPv6 address in hexadecimal colon notation. The servname parameter can be either a service name or a decimal port number.
Parameter hints
The hints parameter can be used to pass an addrinfo structure if desired. If not, the hints parameter must be the null pointer.
The addrinfo structure is declared as follows:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* AF_INET, AF_INET6 */
int ai_socktype; /* SOCK_STREAM, SOCK_DGRAM */
int ai_protocol; /* 0 or IPPROTO_xxx for IP */
size_t ai_addrlen; /* length of ai_addr */
char*ai_canonname; /* canon name */
struct sockaddr *ai_addr; /* socket address structure */
struct addrinfo *ai_next; /* next structure in list */
};
All the elements in the object of the type struct addrinfo passed with hints except ai_flags, ai_family and ai_socktype must have the value 0 or must be the null pointer.
A selection is made with the values for the addrinfo components ai_flags, ai_family and ai_socktype:
ai_family = PF_UNSPEC means that any protocol family is desired.
ai_socktype = 0 means that any socket type is accepted.
ai_flags = AI_PASSIVE means that the returned socket address structure is to be used for a bind() call. If nodename = NULL (see above), the IP address element is set to INADDR_ANY for an IPv4 address and to IN6ADDR_ANY for an IPv6 address.
If the AI_PASSIVE bit is not set, the returned socket address structure is used
for a connect() call in case of ai_socktype = SOCK_STREAM
for a connect(), sendto() or sendmsg() call in case of ai_socktype = SOCK_DGRAM
If, in these cases, nodename is the null pointer, the IP address of sockaddr is supplied with the value of the loopback address.
If the ai_flags = AI_CANONNAME bit is set and getaddrinfo() is executed successfully, the first returned addrinfo structure in the element ai_canonname contains the socket host name terminated with the null byte of the selected host.
If the ai_flags = AI_NUMERICHOST bit is set, a nodename which is not the null pointer must be an IPv4 address string in decimal dotted notation or an IPv6 address string in hexadecimal colon notation. Otherwise, the return value is EAI_NONAME. The flag prevents a call that would resolve the name via a DNS service or internal host table.
hints = NULL has the same effect as an addrinfo structure initialized with 0 and ai_family = PF_UNSPEC.
Parameter res
If getaddrinfo() is executed successfully, a pointer to one or more concatenated addrinfo structures is passed in res, where the element ai_next = NULL indicates the last element in the chain. Each of the returned addrinfo structures contains a value corresponding to the socket() call in the elements ai_family and ai_socktype. ai_addr always points to a socket address structure whose length is specified in ai_addrlen.
Return value
0:
If successful.
>0:
If errors occur. Return value is an error code EAI_xxx defined in <netdb.h>.
-1:
If errors occur. errno is set to indicate the error.
Errors
EAFNOSUPPORT
The function is not supported on this system. See also "Dependencies on the BS2000 transport system BCAM" for more information.
Error codes defined in <netdb.h>:
EAI_ADDRFAMILY
The address family is not supported for the specified host.
EAI_AGAIN
Temporary error while accessing the host name information (e.g. DNS error).
The function should be called again.
EAI_BADFLAGS
Invalid value for the ai_flags parameter.
EAI_FAIL
Error while accessing the host name information
EAI_FAMILY
The protocol family is not supported.
EAI_MEMORY
Error when requesting memory.
EAI_NODATA
No address corresponding to the host name was found.
EAI_NONAME
Host or service name is not supported or is unknown.
EAI_SERVICE
Service is not supported for this socket type.
EAI_SOCKTYPE
The socket type is not supported.
EAI_SYSTEM
System error; is specified in more detail in errno.
Note
Memory for the addrinfo structures returned by the getaddrinfo() function is requested dynamically and must be released again with the freeaddrinfo() function.