Copyright (C) 2000 Internet Software Consortium.

Permission to use, copy, modify, and distribute this document for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

$Id: lwres_getaddrinfo.3,v 1.1 2000/06/27 21:53:04 jim Exp $

.Dd Jun 30, 2000 .Dt LWRES_GETADDRINFO 3 .Os BIND9 9 .Sh NAME .Nm lwres_getaddrinfo , .Nm lwres_freeaddrinfo .Nd socket address structure to host and service name .Sh SYNOPSIS .Fd #include <lwres/lwres.h> .Fd .Ft int .Fo lwres_getaddrinfo .Fa "const char *hostname" .Fa "const char *servname" .Fa "const struct addrinfo *hints" .Fa "struct addrinfo **res" .Fc .Ft void .Fo lwres_freeaddrinfo .Fa "struct addrinfo *ai" .Fc

p If the operating system does not provide a .Dv "struct addrinfo" , the following structure is used d -literal -offset indent 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 */ }; .Ed .Sh DESCRIPTION

p .Fn lwres_getaddrinfo is used to get a list of IP addresses and port numbers for host .Fa hostname and .Fa servname . The function is the lightweight resolver's implementation of .Fn getaddrinfo as defined in RFC2133. .Fa hostname and .Fa servname arguments are pointers to null-terminated strings or .Dv NULL . .Fa hostname either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 hex address. .Fa servname is either a decimal port number or a service name as listed in

a /etc/services .

p .Fa hints is an optional pointer to a .Dv "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 .Fa *hints : l -tag -width ai_socktyp -offset indent -compact t Li ai_family the protocol family that should be used. When .Li ai_family is set to .Dv PF_UNSPEC , it means the caller will accept any protocol family supported by the operating system. t Dv ai_socktype denotes the type of socket - .Dv SOCK_STREAM , .Dv SOCK_DGRAM or .Dv SOCK_RAW - that is wanted. When .Li ai_socktype is zero the caller will accept any socket type. t Li ai_protocol indicates which transport protocol is wanted: UDP or TCP. If .Li ai_protocol is zero the caller will accept any protocol. t Li ai_flags sets some flag bits. If the .Dv AI_CANONNAME bit is set, a successful call to .Fn lwres_getaddrinfo will return a a null-terminated string containing the canonical name of the specified hostname in .Li ai_canonname of the first .Dv addrinfo structure returned. Setting the .Dv AI_PASSIVE bit indicates that the returned socket address structure is intended for used in a call to .Xr bind 2 . In this case, if the hostname argument is a .Dv NULL pointer, then the IP address portion of the socket address structure will be set to .Dv INADDR_ANY for an IPv4 address or .Dv IN6ADDR_ANY_INIT for an IPv6 address.

p When .Li ai_flags does not set the .Dv AI_PASSIVE bit, the returned socket address structure will be ready for use in a call to .Xr connect 2 for a connection-oriented protocol or .Xr connect 2 , .Xr sendto 2 , or .Xr sendmsg 2 if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if .Fa hostname is a .Dv NULL pointer and .Dv AI_PASSIVE is not set in .Li ai_flags .

p If .Li ai_flags is set to .Dv AI_NUMERICHOST it indicates that the .Dv non-NuLL .Fa hostname should be treated as a numeric string defining an IPv4 or IPv6 address. This will prevent a numeric IPv4 address from being considered as a domain name when .Fn lwres_getaddrinfo is looking for IPv6 addresses or vice versa. .El

p All other elements of the .Dv "struct addrinfo" passed via .Fa arg must be zero.

p If .Fa arg is not supplied, a .Dv NULL pointer should be given for this argument. It will be treated as if the caller provided an .Dv "struct addrinfo" structure initialized to zero with .Li ai_family set to .Li PF_UNSPEC .

p After a successful call to .Fn lwres_getaddrinfo , .Fa *res is a pointer to a linked list of one or more .Dv addrinfo structures. Each .Dv "struct addrinfo" in this list cn be processed by following the .Li ai_next pointer, until a .Dv NULL pointer is encountered. The three members .Li ai_family , ai_socktype, and .Li ai_protocol in each returned .Dv addrinfo structure contain the corresponding arguments for a call to .Xr socket 2 . For each .Dv addrinfo structure in the list, the .Li ai_addr member points to a filled-in socket address structure of length .Li ai_addrlen .

p All of the information returned by .Fn lwres_getaddrinfo is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the .Li addrinfo structures. Memory allocated for the dynamically allocated structures created by a successful call to .Fn lwres_getaddrinfo is released by .Fn lwres_freeaddrinfo . .Fa ai is a pointer to a .Dv "struct addrinfo" created by a call to .Fn lwres_getaddrinfo . .Sh RETURN VALUES .Fn lwres_getaddrinfo returns zero on success or one of the error codes listed in .Xr gai_strerror 3 if an error occurs. If both .Fa hostname and .Fa servname are .Dv NULL .Fn lwres_getaddrinfo returns .Er EAI_NONAME . .Sh SEE ALSO .Xr lwres_getaddrinfo 3 , .Xr lwres_freeaddrinfo 3 , .Xr lwres_gai_strerror 3 , .Xr RFC2133 , .Xr getservbyname 3 , .Xr bind 2 .Xr connect 2 .Xr connect 2 , .Xr sendto 2 , .Xr sendmsg 2 , .Xr socket 2 .