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 following 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 */
};
DESCRIPTIONlwres_getaddrinfo() is used to get a list of IP addresses
and port numbers 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/services.
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 structure 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 family 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 suc-
cessful call to lwres_getaddrinfo() will return a a
null-terminated string containing 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 connect(2) for a connection-ori-
ented protocol or connect(2), sendto(2), or
sendmsg(2) if a connectionless protocol was chosen.
The IP address portion of the socket address struc-
ture will be set to the loopback address if host-
name 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 reso-
lution 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 struc-
tures. 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 con-
tain the corresponding arguments for a call to socket(2).
For each addrinfo structure in the list, the ai_addr mem-
ber 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 suc-
cessful call to lwres_getaddrinfo() is released by
lwres_freeaddrinfo(). ai is a pointer to a struct
addrinfo created by a call to lwres_getaddrinfo().
RETURN VALUESlwres_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 ALSOlwres(3), lwres_getaddrinfo(3), lwres_freeaddrinfo(3),
lwres_gai_strerror(3), RFC2133, getservbyname(3), bind(2),
connect(2), sendto(2), sendmsg(2), socket(2).
BIND9 Jun 30, 2000 LWRES_GETADDRINFO(3)
