Home
Main website
Display Sidebar
Hide Ads
Recent Changes
View Source:
freeaddrinfo(3)
Edit
PageHistory
Diff
Info
LikePages
getaddrinfo !!!getaddrinfo NAME SYNOPSIS DESCRIPTION RETURN VALUE SEE ALSO ---- !!NAME getaddrinfo - network address and service translation !!SYNOPSIS __#include __''node''__, const char *__''service''__, const struct addrinfo *__''hints''__, struct addrinfo **__''res''__); void freeaddrinfo(struct addrinfo *__''res''__); const char *gai_strerror(int__ ''errcode''__); __ !!DESCRIPTION The getaddrinfo(3) function combines the functionality provided by the getipnodebyname(3), getipnodebyaddr(3), getservbyname(3), and getservbyport(3) functions into a single interface. The thread-safe getaddrinfo(3) function creates one or more socket address structures that can be used by the bind(2) and connect(2) system calls to create a client or a server socket. The getaddrinfo(3) function is not limited to creating IPv4 socket address structures; IPv6 socket address structures can be created if IPv6 support is available. These socket address structures can be used directly by bind(2) or connect(2), to prepare a client or a server socket. The __addrinfo__ structure used by this function contains the following members: __struct addrinfo { int__ '' ai_flags''__; int__ '' ai_family''__; int__ '' ai_socktype''__; int__ '' ai_protocol''__; size_t__ '' ai_addrlen''__; struct sockaddr *__''ai_addr''__; char *__''ai_canonname''__; struct addrinfo *__''ai_next''__; }; __getaddrinfo(3) sets ''res'' to point to a dynamically-allocated link list of __addrinfo__ structures, linked by the ''ai_next'' member. There are several reasons why the link list may have more than one __addrinfo__ structure, including: if the network host is multi-homed; or if the same service is available from multiple socket protocols (one __SOCK_STREAM__ address and another __SOCK_DGRAM__ address, for example). The members ''ai_family'', ''ai_socktype'', and ''ai_protocol'' have the same meaning as the corresponding parameters in the socket(2) system call. The getaddrinfo(3) function returns socket addresses in either IPv4 or IPv6 address family, (''ai_family'' will be set to either __PF_INET__ or __PF_INET6__). The ''hints'' parameter specifies the preferred socket type, or protocol. A NULL ''hints'' specifies that any network address or protocol is acceptable. If this parameter is not __NULL__ it points to an __addrinfo__ structure whose ''ai_family'', ''ai_socktype'', and ''ai_protocol'' members specify the preferred socket type. __PF_UNSPEC__ in ''ai_family'' specifies any protocol family (either IPv4 or IPv6, for example). 0 in ''ai_socktype'' or ''ai_protocol'' specifies that any socket type or protocol is acceptable as well. The ''ai_flags'' member specifies additional options, defined below. Multiple flags are specified by logically OR-ing them together. All the other members in the ''hints'' parameter must contain either 0, or a null pointer. The ''node'' or ''service'' parameter, but not both, may be NULL. ''node'' specifies either a numerical network address (dotted-decimal format for IPv4, hexadecimal format for IPv6) or a network hostname, whose network addresses are looked up and resolved. If the ''ai_flags'' member in the ''hints'' parameter contains the __AI_NUMERICHOST__ flag then the ''node'' parameter must be a numerical network address. The __AI_NUMERICHOST__ flag suppresses any potentially lengthy network host address lookups. The getaddrinfo(3) function creates a link list of __addrinfo__ structures, one for each network address subject to any restrictions imposed by the ''hints'' parameter. ''ai_canonname'' is set to point to the official name of the host, if ''ai_flags'' in ''hints'' includes the __AI_CANONNAME__ flag. ''ai_family'', ''ai_socktype'', and ''ai_protocol'' specify the socket creation parameters. A pointer to the socket address is placed in the ''ai_addr'' member, and the length of the socket address, in bytes, is placed in the ''ai_addrlen'' member. If ''node'' is NULL, the network address in each socket structure is initialized according to the __AI_PASSIVE__ flag, which is set in the ''ai_flags'' member of the ''hints'' parameter. The network address in each socket structure will be left unspecified if __AI_PASSIVE__ flag is set. This is used by server applications, which intend to accept client connections on any network address. The network address will be set to the loopback interface address if the __AI_PASSIVE__ flag is not set. This is used by client applications, which intend to connect to a server running on the same network host. ''service'' sets the port number in the network address of each socket structure. If ''service'' is NULL the port number will be left uninitialized. The freeaddrinfo(3) function frees the memory that was allocated for the dynamically allocated link list ''res''. !!RETURN VALUE getaddrinfo(3) returns 0 if it succeeds, or one of the following non-zero error codes: __EAI_FAMILY__ The requested address family is not supported at all. __EAI_SOCKTYPE__ The requested socket type is not supported at all. __EAI_BADFLAGS__ ''ai_flags'' contains invalid flags. __EAI_NONAME__ The ''node'' or ''service'' is not known. This error is also returned if both ''node'' and ''service'' are NULL. __EAI_SERVICE__ The requested service is not available for the requested socket type. It may be available through another socket type. __EAI_ADDRFAMILY__ The specified network host does not have any network addresses in the requested address family. __EAI_NODATA__ The specified network host exists, but does not have any network addresses defined. __EAI_MEMORY__ Out of memory. __EAI_FAIL__ The name server returned a permanent failure indication. __EAI_AGAIN__ The name server returned a temporary failure indication. Try again later. __EAI_SYSTEM__ Other system error, check ''errno'' for details. The gai_strerror(3) function translates these error codes to a human readable string, suitable for error reporting. !!SEE ALSO getipnodebyname(3), getipnodebyaddr(3) ----
3 pages link to
freeaddrinfo(3)
:
Man3f
gai_strerror(3)
getaddrinfo(3)
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
