lwres_freeaddrinfo
LWRES_GETADDRINFO(3) LWRES_GETADDRINFO(3)
NAME
lwres_getaddrinfo, lwres_freeaddrinfo - socket address structure to
host and service name
SYNOPSIS
#include <lwres/netdb.h>
int lwres_getaddrinfo(const char *hostname, const char *servname, const
struct addrinfo *hints, struct addrinfo **res);
void lwres_freeaddrinfo(struct addrinfo *ai);
If the operating system does not provide a struct addrinfo, the follow-
ing structure is used:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
size_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for hostname */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
DESCRIPTION
lwres_getaddrinfo() is used to get a list of IP addresses and port num-
bers for host hostname and service servname. The function is the
lightweight resolver's implementation of getaddrinfo() as defined in
RFC2133. hostname and servname are pointers to null-terminated strings
or NULL. hostname is either a host name or a numeric host address
string: a dotted decimal IPv4 address or an IPv6 address. servname is
either a decimal port number or a service name as listed in /etc/ser-
vices.
hints is an optional pointer to a struct addrinfo. This structure can
be used to provide hints concerning the type of socket that the caller
supports or wishes to use. The caller can supply the following struc-
ture elements in *hints:
ai_family
The protocol family that should be used. When ai_family is set
to PF_UNSPEC, it means the caller will accept any protocol fam-
ily supported by the operating system.
ai_socktype
denotes the type of socket ¿ SOCK_STREAM, SOCK_DGRAM or SOCK_RAW
¿ that is wanted. When ai_socktype is zero the caller will
accept any socket type.
ai_protocol
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP. If ai_protocol is zero the caller will accept any
protocol.
ai_flags
Flag bits. If the AI_CANONNAME bit is set, a successful call to
lwres_getaddrinfo() will return a a null-terminated string con-
taining the canonical name of the specified hostname in
ai_canonname of the first addrinfo structure returned. Setting
the AI_PASSIVE bit indicates that the returned socket address
structure is intended for used in a call to bind(2). In this
case, if the hostname argument is a NULL pointer, then the IP
address portion of the socket address structure will be set to
INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
address.
When ai_flags does not set the AI_PASSIVE bit, the returned
socket address structure will be ready for use in a call to con-
nect(2) for a connection-oriented protocol or connect(2),
sendto(2), or sendmsg(2) if a connectionless protocol was cho-
sen. The IP address portion of the socket address structure
will be set to the loopback address if hostname is a NULL
pointer and AI_PASSIVE is not set in ai_flags.
If ai_flags is set to AI_NUMERICHOST it indicates that hostname
should be treated as a numeric string defining an IPv4 or IPv6
address and no name resolution should be attempted.
All other elements of the struct addrinfo passed via hints must be
zero.
A hints of NULL is treated as if the caller provided a struct addrinfo
initialized to zero with ai_familyset to PF_UNSPEC.
After a successful call to lwres_getaddrinfo(), *res is a pointer to a
linked list of one or more addrinfo structures. Each struct addrinfo
in this list cn be processed by following the ai_next pointer, until a
NULL pointer is encountered. The three members ai_family, ai_socktype,
and ai_protocol in each returned addrinfo structure contain the corre-
sponding arguments for a call to socket(2). For each addrinfo struc-
ture in the list, the ai_addr member points to a filled-in socket
address structure of length ai_addrlen.
All of the information returned by lwres_getaddrinfo() is dynamically
allocated: the addrinfo structures, and the socket address structures
and canonical host name strings pointed to by the addrinfostructures.
Memory allocated for the dynamically allocated structures created by a
successful call to lwres_getaddrinfo() is released by lwres_freead-
drinfo(). ai is a pointer to a struct addrinfo created by a call to
lwres_getaddrinfo().
RETURN VALUES
lwres_getaddrinfo() returns zero on success or one of the error codes
listed in gai_strerror(3) if an error occurs. If both hostname and
servname are NULL lwres_getaddrinfo() returns EAI_NONAME.
SEE ALSO
lwres(3), lwres_getaddrinfo(3), lwres_freeaddrinfo(3), lwres_gai_str-
error(3), RFC2133, getservbyname(3), bind(2), connect(2), sendto(2),
sendmsg(2), socket(2).
BIND9 Jun 30, 2000 LWRES_GETADDRINFO(3)
