1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this software 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 ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL ISC 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.
.\"
.\" $ISC: lwres_getaddrinfo.3,v 1.16.2.1.8.6 2005/10/13 02:33:53 marka Exp $
.\"
.hy 0
.ad l
.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" "BIND9"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
.SH "SYNOPSIS"
.nf
#include <lwres/netdb.h>
.fi
.HP 22
\fBint\ \fBlwres_getaddrinfo\fR\fR\fB(\fR\fBconst\ char\ *hostname\fR\fB, \fR\fBconst\ char\ *servname\fR\fB, \fR\fBconst\ struct\ addrinfo\ *hints\fR\fB, \fR\fBstruct\ addrinfo\ **res\fR\fB);\fR
.HP 24
\fBvoid\ \fBlwres_freeaddrinfo\fR\fR\fB(\fR\fBstruct\ addrinfo\ *ai\fR\fB);\fR
.PP
If the operating system does not provide a
\fBstruct addrinfo\fR, the following structure is used:
.sp
.nf
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 */
};
.fi
.sp
.SH "DESCRIPTION"
.PP
\fBlwres_getaddrinfo()\fR
is used to get a list of IP addresses and port numbers for host
\fIhostname\fR
and service
\fIservname\fR. The function is the lightweight resolver's implementation of
\fBgetaddrinfo()\fR
as defined in RFC2133.
\fIhostname\fR
and
\fIservname\fR
are pointers to null\-terminated strings or
\fBNULL\fR.
\fIhostname\fR
is either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 address.
\fIservname\fR
is either a decimal port number or a service name as listed in
\fI/etc/services\fR.
.PP
\fIhints\fR
is an optional pointer to a
\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
\fI*hints\fR:
.TP
\fBai_family\fR
The protocol family that should be used. When
\fBai_family\fR
is set to
\fBPF_UNSPEC\fR, it means the caller will accept any protocol family supported by the operating system.
.TP
\fBai_socktype\fR
denotes the type of socket \(em
\fBSOCK_STREAM\fR,
\fBSOCK_DGRAM\fR
or
\fBSOCK_RAW\fR
\(em that is wanted. When
\fBai_socktype\fR
is zero the caller will accept any socket type.
.TP
\fBai_protocol\fR
indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP. If
\fBai_protocol\fR
is zero the caller will accept any protocol.
.TP
\fBai_flags\fR
Flag bits. If the
\fBAI_CANONNAME\fR
bit is set, a successful call to
\fBlwres_getaddrinfo()\fR
will return a null\-terminated string containing the canonical name of the specified hostname in
\fBai_canonname\fR
of the first
\fBaddrinfo\fR
structure returned. Setting the
\fBAI_PASSIVE\fR
bit indicates that the returned socket address structure is intended for used in a call to
\fBbind\fR(2). In this case, if the hostname argument is a
\fBNULL\fR
pointer, then the IP address portion of the socket address structure will be set to
\fBINADDR_ANY\fR
for an IPv4 address or
\fBIN6ADDR_ANY_INIT\fR
for an IPv6 address.
.sp
When
\fBai_flags\fR
does not set the
\fBAI_PASSIVE\fR
bit, the returned socket address structure will be ready for use in a call to
\fBconnect\fR(2 )
for a connection\-oriented protocol or
\fBconnect\fR(2),
\fBsendto\fR(2), or
\fBsendmsg\fR(2 )
if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if
\fIhostname\fR
is a
\fBNULL\fR
pointer and
\fBAI_PASSIVE\fR
is not set in
\fBai_flags\fR.
.sp
If
\fBai_flags\fR
is set to
\fBAI_NUMERICHOST\fR
it indicates that
\fIhostname\fR
should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.
.PP
All other elements of the
\fBstruct addrinfo\fR
passed via
\fIhints\fR
must be zero.
.PP
A
\fIhints\fR
of
\fBNULL\fR
is treated as if the caller provided a
\fBstruct addrinfo\fR
initialized to zero with
\fBai_family\fRset to
\fBPF_UNSPEC\fR.
.PP
After a successful call to
\fBlwres_getaddrinfo()\fR,
\fI*res\fR
is a pointer to a linked list of one or more
\fBaddrinfo\fR
structures. Each
\fBstruct addrinfo\fR
in this list cn be processed by following the
\fBai_next\fR
pointer, until a
\fBNULL\fR
pointer is encountered. The three members
\fBai_family\fR,
\fBai_socktype\fR, and
\fBai_protocol\fR
in each returned
\fBaddrinfo\fR
structure contain the corresponding arguments for a call to
\fBsocket\fR(2). For each
\fBaddrinfo\fR
structure in the list, the
\fBai_addr\fR
member points to a filled\-in socket address structure of length
\fBai_addrlen\fR.
.PP
All of the information returned by
\fBlwres_getaddrinfo()\fR
is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the
\fBaddrinfo\fRstructures. Memory allocated for the dynamically allocated structures created by a successful call to
\fBlwres_getaddrinfo()\fR
is released by
\fBlwres_freeaddrinfo()\fR.
\fIai\fR
is a pointer to a
\fBstruct addrinfo\fR
created by a call to
\fBlwres_getaddrinfo()\fR.
.SH "RETURN VALUES"
.PP
\fBlwres_getaddrinfo()\fR
returns zero on success or one of the error codes listed in
\fBgai_strerror\fR(3 )
if an error occurs. If both
\fIhostname\fR
and
\fIservname\fR
are
\fBNULL\fR\fBlwres_getaddrinfo()\fR
returns
\fBEAI_NONAME\fR.
.SH "SEE ALSO"
.PP
\fBlwres\fR(3),
\fBlwres_getaddrinfo\fR(3),
\fBlwres_freeaddrinfo\fR(3),
\fBlwres_gai_strerror\fR(3),
\fBRFC2133\fR(),
\fBgetservbyname\fR(3),
\fBbind\fR(2),
\fBconnect\fR(2),
\fBsendto\fR(2),
\fBsendmsg\fR(2),
\fBsocket\fR(2).
|
