1 .\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
2 .\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 .\" PERFORMANCE OF THIS SOFTWARE.
16 .\" $Id: lwres_getaddrinfo.3,v 1.16.2.1.8.7 2006/06/29 13:02:31 marka Exp $
20 .\" Title: lwres_getaddrinfo
22 .\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
23 .\" Date: Jun 30, 2000
27 .TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" "BIND9"
28 .\" disable hyphenation
30 .\" disable justification (adjust text to left margin only)
33 lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
36 #include <lwres/netdb.h>
39 .BI "int lwres_getaddrinfo(const\ char\ *hostname, const\ char\ *servname, const\ struct\ addrinfo\ *hints, struct\ addrinfo\ **res);"
41 .BI "void lwres_freeaddrinfo(struct\ addrinfo\ *ai);"
43 If the operating system does not provide a
44 \fBstruct addrinfo\fR, the following structure is used:
49 int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
50 int ai_family; /* PF_xxx */
51 int ai_socktype; /* SOCK_xxx */
52 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
53 size_t ai_addrlen; /* length of ai_addr */
54 char *ai_canonname; /* canonical name for hostname */
55 struct sockaddr *ai_addr; /* binary address */
56 struct addrinfo *ai_next; /* next structure in linked list */
63 \fBlwres_getaddrinfo()\fR
64 is used to get a list of IP addresses and port numbers for host
67 \fIservname\fR. The function is the lightweight resolver's implementation of
69 as defined in RFC2133.
73 are pointers to null\-terminated strings or
76 is either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 address.
78 is either a decimal port number or a service name as listed in
82 is an optional pointer to a
83 \fBstruct addrinfo\fR. 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
87 The protocol family that should be used. When
90 \fBPF_UNSPEC\fR, it means the caller will accept any protocol family supported by the operating system.
93 denotes the type of socket \(em
98 \(em that is wanted. When
100 is zero the caller will accept any socket type.
103 indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP. If
105 is zero the caller will accept any protocol.
110 bit is set, a successful call to
111 \fBlwres_getaddrinfo()\fR
112 will return a null\-terminated string containing the canonical name of the specified hostname in
116 structure returned. Setting the
118 bit indicates that the returned socket address structure is intended for used in a call to
119 \fBbind\fR(2). In this case, if the hostname argument is a
121 pointer, then the IP address portion of the socket address structure will be set to
123 for an IPv4 address or
124 \fBIN6ADDR_ANY_INIT\fR
131 bit, the returned socket address structure will be ready for use in a call to
133 for a connection\-oriented protocol or
137 if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if
152 should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.
154 All other elements of the
155 \fBstruct addrinfo\fR
164 is treated as if the caller provided a
165 \fBstruct addrinfo\fR
166 initialized to zero with
167 \fBai_family\fRset to
170 After a successful call to
171 \fBlwres_getaddrinfo()\fR,
173 is a pointer to a linked list of one or more
176 \fBstruct addrinfo\fR
177 in this list cn be processed by following the
181 pointer is encountered. The three members
183 \fBai_socktype\fR, and
187 structure contain the corresponding arguments for a call to
188 \fBsocket\fR(2). For each
190 structure in the list, the
192 member points to a filled\-in socket address structure of length
195 All of the information returned by
196 \fBlwres_getaddrinfo()\fR
197 is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the
198 \fBaddrinfo\fRstructures. Memory allocated for the dynamically allocated structures created by a successful call to
199 \fBlwres_getaddrinfo()\fR
201 \fBlwres_freeaddrinfo()\fR.
204 \fBstruct addrinfo\fR
206 \fBlwres_getaddrinfo()\fR.
209 \fBlwres_getaddrinfo()\fR
210 returns zero on success or one of the error codes listed in
211 \fBgai_strerror\fR(3 )
212 if an error occurs. If both
218 \fBlwres_getaddrinfo()\fR
224 \fBlwres_getaddrinfo\fR(3),
225 \fBlwres_freeaddrinfo\fR(3),
226 \fBlwres_gai_strerror\fR(3),
228 \fBgetservbyname\fR(3),
235 Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC")