SYNOPSIS<\/a>
DESCRIPTION<\/a>
RETURN VALUE<\/a>
FILES<\/a>
ATTRIBUTES<\/a>
CONFORMING TO<\/a>
NOTES<\/a>
EXAMPLES<\/a>
SEE ALSO<\/a>
COLOPHON<\/a> <\/p>\n
\n
NAME <\/a> <\/h2>\ngetaddrinfo, freeaddrinfo, gai_strerror \u2212 network address and service translation<\/p>\n
SYNOPSIS <\/a> <\/h2>\n#include
#include
#include <\/b><\/p>\nint getaddrinfo(const char *<\/b>node<\/i>, const char *<\/b>service<\/i>,
const struct addrinfo *<\/b>hints<\/i>,
struct addrinfo **<\/b>res<\/i>);<\/b><\/p>\n
void freeaddrinfo(struct addrinfo *<\/b>res<\/i>);<\/b><\/p>\n
const char *gai_strerror(int<\/b> errcode<\/i>);<\/b><\/p>\n
Feature Test Macro Requirements for glibc (see feature_test_macros<\/b>(7)):<\/p>\n
getaddrinfo<\/b>(), freeaddrinfo<\/b>(), gai_strerror<\/b>():
Since glibc 2.22: _POSIX_C_SOURCE >= 200112L
Glibc 2.21 and earlier: _POSIX_C_SOURCE<\/p>\nDESCRIPTION <\/a> <\/h2>\nGiven node<\/i> and service<\/i>, which identify an Internet host and a service, getaddrinfo<\/b>() returns one or more addrinfo<\/i> structures, each of which contains an Internet address that can be specified in a call to bind<\/b>(2) or connect<\/b>(2). The getaddrinfo<\/b>() function combines the functionality provided by the gethostbyname<\/b>(3) and getservbyname<\/b>(3) functions into a single interface, but unlike the latter functions, getaddrinfo<\/b>() is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.<\/p>\n
The addrinfo<\/i> structure used by getaddrinfo<\/b>() contains the following fields:<\/p>\n
struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
socklen_t ai_addrlen;
struct sockaddr *ai_addr;
char *ai_canonname;
struct addrinfo *ai_next;
};<\/p>\n
The hints<\/i> argument points to an addrinfo<\/i> structure that specifies criteria for selecting the socket address structures returned in the list pointed to by res<\/i>. If hints<\/i> is not NULL it points to an addrinfo<\/i> structure whose ai_family<\/i>, ai_socktype<\/i>, and ai_protocol<\/i> specify criteria that limit the set of socket addresses returned by getaddrinfo<\/b>(), as follows:
ai_family<\/i><\/p>\n
This field specifies the desired address family for the returned addresses. Valid values for this field include AF_INET<\/b> and AF_INET6<\/b>. The value AF_UNSPEC<\/b> indicates that getaddrinfo<\/b>() should return socket addresses for any address family (either IPv4 or IPv6, for example) that can be used with node<\/i> and service<\/i>.<\/p>\n
ai_socktype<\/i><\/p>\n
This field specifies the preferred socket type, for example SOCK_STREAM<\/b> or SOCK_DGRAM<\/b>. Specifying 0 in this field indicates that socket addresses of any type can be returned by getaddrinfo<\/b>().<\/p>\n
ai_protocol<\/i><\/p>\n
This field specifies the protocol for the returned socket addresses. Specifying 0 in this field indicates that socket addresses with any protocol can be returned by getaddrinfo<\/b>().<\/p>\n
ai_flags<\/i><\/p>\n
This field specifies additional options, described below. Multiple flags are specified by bitwise OR-ing them together.<\/p>\n
All the other fields in the structure pointed to by hints<\/i> must contain either 0 or a null pointer, as appropriate.<\/p>\n
Specifying hints<\/i> as NULL is equivalent to setting ai_socktype<\/i> and ai_protocol<\/i> to 0; ai_family<\/i> to AF_UNSPEC<\/b>; and ai_flags<\/i> to (AI_V4MAPPED\u00a0|\u00a0AI_ADDRCONFIG)<\/b>. (POSIX specifies different defaults for ai_flags<\/i>; see NOTES.) node<\/i> specifies either a numerical network address (for IPv4, numbers-and-dots notation as supported by inet_aton<\/b>(3); for IPv6, hexadecimal string format as supported by inet_pton<\/b>(3)), or a network hostname, whose network addresses are looked up and resolved. If hints.ai_flags<\/i> contains the AI_NUMERICHOST<\/b> flag, then node<\/i> must be a numerical network address. The AI_NUMERICHOST<\/b> flag suppresses any potentially lengthy network host address lookups.<\/p>\n
If the AI_PASSIVE<\/b> flag is specified in hints.ai_flags<\/i>, and node<\/i> is NULL, then the returned socket addresses will be suitable for bind<\/b>(2)ing a socket that will accept<\/b>(2) connections. The returned socket address will contain the “wildcard address” (INADDR_ANY<\/b> for IPv4 addresses, IN6ADDR_ANY_INIT<\/b> for IPv6 address). The wildcard address is used by applications (typically servers) that intend to accept connections on any of the host\u2019s network addresses. If node<\/i> is not NULL, then the AI_PASSIVE<\/b> flag is ignored.<\/p>\n
If the AI_PASSIVE<\/b> flag is not set in hints.ai_flags<\/i>, then the returned socket addresses will be suitable for use with connect<\/b>(2), sendto<\/b>(2), or sendmsg<\/b>(2). If node<\/i> is NULL, then the network address will be set to the loopback interface address (INADDR_LOOPBACK<\/b> for IPv4 addresses, IN6ADDR_LOOPBACK_INIT<\/b> for IPv6 address); this is used by applications that intend to communicate with peers running on the same host.<\/p>\n
service<\/i> sets the port in each returned address structure. If this argument is a service name (see services<\/b>(5)), it is translated to the corresponding port number. This argument can also be specified as a decimal number, which is simply converted to binary. If service<\/i> is NULL, then the port number of the returned socket addresses will be left uninitialized. If AI_NUMERICSERV<\/b> is specified in hints.ai_flags<\/i> and service<\/i> is not NULL, then service<\/i> must point to a string containing a numeric port number. This flag is used to inhibit the invocation of a name resolution service in cases where it is known not to be required.<\/p>\n
Either node<\/i> or service<\/i>, but not both, may be NULL.<\/p>\n
The getaddrinfo<\/b>() function allocates and initializes a linked list of addrinfo<\/i> structures, one for each network address that matches node<\/i> and service<\/i>, subject to any restrictions imposed by hints<\/i>, and returns a pointer to the start of the list in res<\/i>. The items in the linked list are linked by the ai_next<\/i> field.<\/p>\n
There are several reasons why the linked list may have more than one addrinfo<\/i> structure, including: the network host is multihomed, accessible over multiple protocols (e.g., both AF_INET<\/b> and AF_INET6<\/b>); or the same service is available from multiple socket types (one SOCK_STREAM<\/b> address and another SOCK_DGRAM<\/b> address, for example). Normally, the application should try using the addresses in the order in which they are returned. The sorting function used within getaddrinfo<\/b>() is defined in RFC\u00a03484; the order can be tweaked for a particular system by editing \/etc\/gai.conf<\/i> (available since glibc 2.5).<\/p>\n
If hints.ai_flags<\/i> includes the AI_CANONNAME<\/b> flag, then the ai_canonname<\/i> field of the first of the addrinfo<\/i> structures in the returned list is set to point to the official name of the host.<\/p>\n
The remaining fields of each returned addrinfo<\/i> structure are initialized as follows:<\/p>\n
#include int getaddrinfo(const char *<\/b>node<\/i>, const char *<\/b>service<\/i>, void freeaddrinfo(struct addrinfo *<\/b>res<\/i>);<\/b><\/p>\n const char *gai_strerror(int<\/b> errcode<\/i>);<\/b><\/p>\n Feature Test Macro Requirements for glibc (see feature_test_macros<\/b>(7)):<\/p>\n getaddrinfo<\/b>(), freeaddrinfo<\/b>(), gai_strerror<\/b>(): Given node<\/i> and service<\/i>, which identify an Internet host and a service, getaddrinfo<\/b>() returns one or more addrinfo<\/i> structures, each of which contains an Internet address that can be specified in a call to bind<\/b>(2) or connect<\/b>(2). The getaddrinfo<\/b>() function combines the functionality provided by the gethostbyname<\/b>(3) and getservbyname<\/b>(3) functions into a single interface, but unlike the latter functions, getaddrinfo<\/b>() is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.<\/p>\n The addrinfo<\/i> structure used by getaddrinfo<\/b>() contains the following fields:<\/p>\n struct addrinfo { The hints<\/i> argument points to an addrinfo<\/i> structure that specifies criteria for selecting the socket address structures returned in the list pointed to by res<\/i>. If hints<\/i> is not NULL it points to an addrinfo<\/i> structure whose ai_family<\/i>, ai_socktype<\/i>, and ai_protocol<\/i> specify criteria that limit the set of socket addresses returned by getaddrinfo<\/b>(), as follows: This field specifies the desired address family for the returned addresses. Valid values for this field include AF_INET<\/b> and AF_INET6<\/b>. The value AF_UNSPEC<\/b> indicates that getaddrinfo<\/b>() should return socket addresses for any address family (either IPv4 or IPv6, for example) that can be used with node<\/i> and service<\/i>.<\/p>\n ai_socktype<\/i><\/p>\n This field specifies the preferred socket type, for example SOCK_STREAM<\/b> or SOCK_DGRAM<\/b>. Specifying 0 in this field indicates that socket addresses of any type can be returned by getaddrinfo<\/b>().<\/p>\n ai_protocol<\/i><\/p>\n This field specifies the protocol for the returned socket addresses. Specifying 0 in this field indicates that socket addresses with any protocol can be returned by getaddrinfo<\/b>().<\/p>\n ai_flags<\/i><\/p>\n This field specifies additional options, described below. Multiple flags are specified by bitwise OR-ing them together.<\/p>\n All the other fields in the structure pointed to by hints<\/i> must contain either 0 or a null pointer, as appropriate.<\/p>\n Specifying hints<\/i> as NULL is equivalent to setting ai_socktype<\/i> and ai_protocol<\/i> to 0; ai_family<\/i> to AF_UNSPEC<\/b>; and ai_flags<\/i> to (AI_V4MAPPED\u00a0|\u00a0AI_ADDRCONFIG)<\/b>. (POSIX specifies different defaults for ai_flags<\/i>; see NOTES.) node<\/i> specifies either a numerical network address (for IPv4, numbers-and-dots notation as supported by inet_aton<\/b>(3); for IPv6, hexadecimal string format as supported by inet_pton<\/b>(3)), or a network hostname, whose network addresses are looked up and resolved. If hints.ai_flags<\/i> contains the AI_NUMERICHOST<\/b> flag, then node<\/i> must be a numerical network address. The AI_NUMERICHOST<\/b> flag suppresses any potentially lengthy network host address lookups.<\/p>\n If the AI_PASSIVE<\/b> flag is specified in hints.ai_flags<\/i>, and node<\/i> is NULL, then the returned socket addresses will be suitable for bind<\/b>(2)ing a socket that will accept<\/b>(2) connections. The returned socket address will contain the “wildcard address” (INADDR_ANY<\/b> for IPv4 addresses, IN6ADDR_ANY_INIT<\/b> for IPv6 address). The wildcard address is used by applications (typically servers) that intend to accept connections on any of the host\u2019s network addresses. If node<\/i> is not NULL, then the AI_PASSIVE<\/b> flag is ignored.<\/p>\n If the AI_PASSIVE<\/b> flag is not set in hints.ai_flags<\/i>, then the returned socket addresses will be suitable for use with connect<\/b>(2), sendto<\/b>(2), or sendmsg<\/b>(2). If node<\/i> is NULL, then the network address will be set to the loopback interface address (INADDR_LOOPBACK<\/b> for IPv4 addresses, IN6ADDR_LOOPBACK_INIT<\/b> for IPv6 address); this is used by applications that intend to communicate with peers running on the same host.<\/p>\n service<\/i> sets the port in each returned address structure. If this argument is a service name (see services<\/b>(5)), it is translated to the corresponding port number. This argument can also be specified as a decimal number, which is simply converted to binary. If service<\/i> is NULL, then the port number of the returned socket addresses will be left uninitialized. If AI_NUMERICSERV<\/b> is specified in hints.ai_flags<\/i> and service<\/i> is not NULL, then service<\/i> must point to a string containing a numeric port number. This flag is used to inhibit the invocation of a name resolution service in cases where it is known not to be required.<\/p>\n Either node<\/i> or service<\/i>, but not both, may be NULL.<\/p>\n The getaddrinfo<\/b>() function allocates and initializes a linked list of addrinfo<\/i> structures, one for each network address that matches node<\/i> and service<\/i>, subject to any restrictions imposed by hints<\/i>, and returns a pointer to the start of the list in res<\/i>. The items in the linked list are linked by the ai_next<\/i> field.<\/p>\n There are several reasons why the linked list may have more than one addrinfo<\/i> structure, including: the network host is multihomed, accessible over multiple protocols (e.g., both AF_INET<\/b> and AF_INET6<\/b>); or the same service is available from multiple socket types (one SOCK_STREAM<\/b> address and another SOCK_DGRAM<\/b> address, for example). Normally, the application should try using the addresses in the order in which they are returned. The sorting function used within getaddrinfo<\/b>() is defined in RFC\u00a03484; the order can be tweaked for a particular system by editing \/etc\/gai.conf<\/i> (available since glibc 2.5).<\/p>\n If hints.ai_flags<\/i> includes the AI_CANONNAME<\/b> flag, then the ai_canonname<\/i> field of the first of the addrinfo<\/i> structures in the returned list is set to point to the official name of the host.<\/p>\n The remaining fields of each returned addrinfo<\/i> structure are initialized as follows:<\/p>\n
#include
#include
const struct addrinfo *<\/b>hints<\/i>,
struct addrinfo **<\/b>res<\/i>);<\/b><\/p>\n
Since glibc 2.22: _POSIX_C_SOURCE >= 200112L
Glibc 2.21 and earlier: _POSIX_C_SOURCE<\/p>\nDESCRIPTION <\/a> <\/h2>\n
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
socklen_t ai_addrlen;
struct sockaddr *ai_addr;
char *ai_canonname;
struct addrinfo *ai_next;
};<\/p>\n
ai_family<\/i><\/p>\n
![\"Image](\"grohtml-1651831.png\")
<\/p>\n