| @@ -1,468 +1,468 @@ | | | @@ -1,468 +1,468 @@ |
1 | .\" $NetBSD: getaddrinfo.3,v 1.48 2009/10/02 06:49:23 cegger Exp $ | | 1 | .\" $NetBSD: getaddrinfo.3,v 1.49 2009/10/02 06:59:37 wiz Exp $ |
2 | .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ | | 2 | .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ |
3 | .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ | | 3 | .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ |
4 | .\" | | 4 | .\" |
5 | .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") | | 5 | .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") |
6 | .\" Copyright (C) 2000, 2001 Internet Software Consortium. | | 6 | .\" Copyright (C) 2000, 2001 Internet Software Consortium. |
7 | .\" | | 7 | .\" |
8 | .\" Permission to use, copy, modify, and distribute this software for any | | 8 | .\" Permission to use, copy, modify, and distribute this software for any |
9 | .\" purpose with or without fee is hereby granted, provided that the above | | 9 | .\" purpose with or without fee is hereby granted, provided that the above |
10 | .\" copyright notice and this permission notice appear in all copies. | | 10 | .\" copyright notice and this permission notice appear in all copies. |
11 | .\" | | 11 | .\" |
12 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH | | 12 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH |
13 | .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY | | 13 | .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
14 | .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, | | 14 | .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, |
15 | .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM | | 15 | .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM |
16 | .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE | | 16 | .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE |
17 | .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR | | 17 | .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
18 | .\" PERFORMANCE OF THIS SOFTWARE. | | 18 | .\" PERFORMANCE OF THIS SOFTWARE. |
19 | .\" | | 19 | .\" |
20 | .Dd November 24, 2006 | | 20 | .Dd October 2, 2009 |
21 | .Dt GETADDRINFO 3 | | 21 | .Dt GETADDRINFO 3 |
22 | .Os | | 22 | .Os |
23 | .Sh NAME | | 23 | .Sh NAME |
24 | .Nm getaddrinfo , | | 24 | .Nm getaddrinfo , |
25 | .Nm freeaddrinfo , | | 25 | .Nm freeaddrinfo , |
26 | .Nm allocaddrinfo | | 26 | .Nm allocaddrinfo |
27 | .Nd host and service name to socket address structure | | 27 | .Nd host and service name to socket address structure |
28 | .Sh SYNOPSIS | | 28 | .Sh SYNOPSIS |
29 | .In netdb.h | | 29 | .In netdb.h |
30 | .Ft int | | 30 | .Ft int |
31 | .Fn getaddrinfo "const char * restrict hostname" \ | | 31 | .Fn getaddrinfo "const char * restrict hostname" \ |
32 | "const char * restrict servname" \ | | 32 | "const char * restrict servname" \ |
33 | "const struct addrinfo * restrict hints" "struct addrinfo ** restrict res" | | 33 | "const struct addrinfo * restrict hints" "struct addrinfo ** restrict res" |
34 | .Ft void | | 34 | .Ft void |
35 | .Fn freeaddrinfo "struct addrinfo *ai" | | 35 | .Fn freeaddrinfo "struct addrinfo *ai" |
36 | .Ft struct addrinfo * | | 36 | .Ft struct addrinfo * |
37 | .Fn allocaddrinfo "socklen_t len" | | 37 | .Fn allocaddrinfo "socklen_t len" |
38 | .Sh DESCRIPTION | | 38 | .Sh DESCRIPTION |
39 | The | | 39 | The |
40 | .Fn getaddrinfo | | 40 | .Fn getaddrinfo |
41 | function is used to get a list of | | 41 | function is used to get a list of |
42 | .Tn IP | | 42 | .Tn IP |
43 | addresses and port numbers for host | | 43 | addresses and port numbers for host |
44 | .Fa hostname | | 44 | .Fa hostname |
45 | and service | | 45 | and service |
46 | .Fa servname . | | 46 | .Fa servname . |
47 | It is a replacement for and provides more flexibility than the | | 47 | It is a replacement for and provides more flexibility than the |
48 | .Xr gethostbyname 3 | | 48 | .Xr gethostbyname 3 |
49 | and | | 49 | and |
50 | .Xr getservbyname 3 | | 50 | .Xr getservbyname 3 |
51 | functions. | | 51 | functions. |
52 | .Pp | | 52 | .Pp |
53 | The | | 53 | The |
54 | .Fa hostname | | 54 | .Fa hostname |
55 | and | | 55 | and |
56 | .Fa servname | | 56 | .Fa servname |
57 | arguments are either pointers to NUL-terminated strings or the null pointer. | | 57 | arguments are either pointers to NUL-terminated strings or the null pointer. |
58 | An acceptable value for | | 58 | An acceptable value for |
59 | .Fa hostname | | 59 | .Fa hostname |
60 | is either a valid host name or a numeric host address string consisting | | 60 | is either a valid host name or a numeric host address string consisting |
61 | of a dotted decimal IPv4 address or an IPv6 address. | | 61 | of a dotted decimal IPv4 address or an IPv6 address. |
62 | The | | 62 | The |
63 | .Fa servname | | 63 | .Fa servname |
64 | is either a decimal port number or a service name listed in | | 64 | is either a decimal port number or a service name listed in |
65 | .Xr services 5 . | | 65 | .Xr services 5 . |
66 | At least one of | | 66 | At least one of |
67 | .Fa hostname | | 67 | .Fa hostname |
68 | and | | 68 | and |
69 | .Fa servname | | 69 | .Fa servname |
70 | must be non-null. | | 70 | must be non-null. |
71 | .Pp | | 71 | .Pp |
72 | .Fa hints | | 72 | .Fa hints |
73 | is an optional pointer to a | | 73 | is an optional pointer to a |
74 | .Li struct addrinfo , | | 74 | .Li struct addrinfo , |
75 | as defined by | | 75 | as defined by |
76 | .Aq Pa netdb.h : | | 76 | .Aq Pa netdb.h : |
77 | .Bd -literal | | 77 | .Bd -literal |
78 | struct addrinfo { | | 78 | struct addrinfo { |
79 | int ai_flags; /* input flags */ | | 79 | int ai_flags; /* input flags */ |
80 | int ai_family; /* protocol family for socket */ | | 80 | int ai_family; /* protocol family for socket */ |
81 | int ai_socktype; /* socket type */ | | 81 | int ai_socktype; /* socket type */ |
82 | int ai_protocol; /* protocol for socket */ | | 82 | int ai_protocol; /* protocol for socket */ |
83 | socklen_t ai_addrlen; /* length of socket-address */ | | 83 | socklen_t ai_addrlen; /* length of socket-address */ |
84 | struct sockaddr *ai_addr; /* socket-address for socket */ | | 84 | struct sockaddr *ai_addr; /* socket-address for socket */ |
85 | char *ai_canonname; /* canonical name for service location */ | | 85 | char *ai_canonname; /* canonical name for service location */ |
86 | struct addrinfo *ai_next; /* pointer to next in list */ | | 86 | struct addrinfo *ai_next; /* pointer to next in list */ |
87 | }; | | 87 | }; |
88 | .Ed | | 88 | .Ed |
89 | .Pp | | 89 | .Pp |
90 | This structure can be used to provide hints concerning the type of socket | | 90 | This structure can be used to provide hints concerning the type of socket |
91 | that the caller supports or wishes to use. | | 91 | that the caller supports or wishes to use. |
92 | The caller can supply the following structure elements in | | 92 | The caller can supply the following structure elements in |
93 | .Fa hints : | | 93 | .Fa hints : |
94 | .Bl -tag -width "ai_socktypeXX" | | 94 | .Bl -tag -width "ai_socktypeXX" |
95 | .It Fa ai_family | | 95 | .It Fa ai_family |
96 | The protocol family that should be used. | | 96 | The protocol family that should be used. |
97 | When | | 97 | When |
98 | .Fa ai_family | | 98 | .Fa ai_family |
99 | is set to | | 99 | is set to |
100 | .Dv PF_UNSPEC , | | 100 | .Dv PF_UNSPEC , |
101 | it means the caller will accept any protocol family supported by the | | 101 | it means the caller will accept any protocol family supported by the |
102 | operating system. | | 102 | operating system. |
103 | .It Fa ai_socktype | | 103 | .It Fa ai_socktype |
104 | Denotes the type of socket that is wanted: | | 104 | Denotes the type of socket that is wanted: |
105 | .Dv SOCK_STREAM , | | 105 | .Dv SOCK_STREAM , |
106 | .Dv SOCK_DGRAM , | | 106 | .Dv SOCK_DGRAM , |
107 | or | | 107 | or |
108 | .Dv SOCK_RAW . | | 108 | .Dv SOCK_RAW . |
109 | When | | 109 | When |
110 | .Fa ai_socktype | | 110 | .Fa ai_socktype |
111 | is zero the caller will accept any socket type. | | 111 | is zero the caller will accept any socket type. |
112 | .It Fa ai_protocol | | 112 | .It Fa ai_protocol |
113 | Indicates which transport protocol is desired, | | 113 | Indicates which transport protocol is desired, |
114 | .Dv IPPROTO_UDP | | 114 | .Dv IPPROTO_UDP |
115 | or | | 115 | or |
116 | .Dv IPPROTO_TCP . | | 116 | .Dv IPPROTO_TCP . |
117 | If | | 117 | If |
118 | .Fa ai_protocol | | 118 | .Fa ai_protocol |
119 | is zero the caller will accept any protocol. | | 119 | is zero the caller will accept any protocol. |
120 | .It Fa ai_flags | | 120 | .It Fa ai_flags |
121 | .Fa ai_flags | | 121 | .Fa ai_flags |
122 | is formed by | | 122 | is formed by |
123 | .Tn OR Ns 'ing | | 123 | .Tn OR Ns 'ing |
124 | the following values: | | 124 | the following values: |
125 | .Bl -tag -width "AI_CANONNAMEXX" | | 125 | .Bl -tag -width "AI_CANONNAMEXX" |
126 | .It Dv AI_CANONNAME | | 126 | .It Dv AI_CANONNAME |
127 | If the | | 127 | If the |
128 | .Dv AI_CANONNAME | | 128 | .Dv AI_CANONNAME |
129 | bit is set, a successful call to | | 129 | bit is set, a successful call to |
130 | .Fn getaddrinfo | | 130 | .Fn getaddrinfo |
131 | will return a NUL-terminated string containing the canonical name | | 131 | will return a NUL-terminated string containing the canonical name |
132 | of the specified hostname in the | | 132 | of the specified hostname in the |
133 | .Fa ai_canonname | | 133 | .Fa ai_canonname |
134 | element of the first | | 134 | element of the first |
135 | .Li addrinfo | | 135 | .Li addrinfo |
136 | structure returned. | | 136 | structure returned. |
137 | .It Dv AI_NUMERICHOST | | 137 | .It Dv AI_NUMERICHOST |
138 | If the | | 138 | If the |
139 | .Dv AI_NUMERICHOST | | 139 | .Dv AI_NUMERICHOST |
140 | bit is set, it indicates that | | 140 | bit is set, it indicates that |
141 | .Fa hostname | | 141 | .Fa hostname |
142 | should be treated as a numeric string defining an IPv4 or IPv6 address | | 142 | should be treated as a numeric string defining an IPv4 or IPv6 address |
143 | and no name resolution should be attempted. | | 143 | and no name resolution should be attempted. |
144 | .It Dv AI_NUMERICSERV | | 144 | .It Dv AI_NUMERICSERV |
145 | If the | | 145 | If the |
146 | .Dv AI_NUMERICSERV | | 146 | .Dv AI_NUMERICSERV |
147 | bit is set, it indicates that the | | 147 | bit is set, it indicates that the |
148 | .Fa servname | | 148 | .Fa servname |
149 | string contains a numeric port number. | | 149 | string contains a numeric port number. |
150 | This is used to prevent service name resolution. | | 150 | This is used to prevent service name resolution. |
151 | .It Dv AI_PASSIVE | | 151 | .It Dv AI_PASSIVE |
152 | If the | | 152 | If the |
153 | .Dv AI_PASSIVE | | 153 | .Dv AI_PASSIVE |
154 | bit is set it indicates that the returned socket address structure | | 154 | bit is set it indicates that the returned socket address structure |
155 | is intended for use in a call to | | 155 | is intended for use in a call to |
156 | .Xr bind 2 . | | 156 | .Xr bind 2 . |
157 | In this case, if the | | 157 | In this case, if the |
158 | .Fa hostname | | 158 | .Fa hostname |
159 | argument is the null pointer, then the IP address portion of the | | 159 | argument is the null pointer, then the IP address portion of the |
160 | socket address structure will be set to | | 160 | socket address structure will be set to |
161 | .Dv INADDR_ANY | | 161 | .Dv INADDR_ANY |
162 | for an IPv4 address or | | 162 | for an IPv4 address or |
163 | .Dv IN6ADDR_ANY_INIT | | 163 | .Dv IN6ADDR_ANY_INIT |
164 | for an IPv6 address. | | 164 | for an IPv6 address. |
165 | .Pp | | 165 | .Pp |
166 | If the | | 166 | If the |
167 | .Dv AI_PASSIVE | | 167 | .Dv AI_PASSIVE |
168 | bit is not set, the returned socket address structure will be ready | | 168 | bit is not set, the returned socket address structure will be ready |
169 | for use in a call to | | 169 | for use in a call to |
170 | .Xr connect 2 | | 170 | .Xr connect 2 |
171 | for a connection-oriented protocol or | | 171 | for a connection-oriented protocol or |
172 | .Xr connect 2 , | | 172 | .Xr connect 2 , |
173 | .Xr sendto 2 , | | 173 | .Xr sendto 2 , |
174 | or | | 174 | or |
175 | .Xr sendmsg 2 | | 175 | .Xr sendmsg 2 |
176 | if a connectionless protocol was chosen. | | 176 | if a connectionless protocol was chosen. |
177 | The | | 177 | The |
178 | .Tn IP | | 178 | .Tn IP |
179 | address portion of the socket address structure will be set to the | | 179 | address portion of the socket address structure will be set to the |
180 | loopback address if | | 180 | loopback address if |
181 | .Fa hostname | | 181 | .Fa hostname |
182 | is the null pointer and | | 182 | is the null pointer and |
183 | .Dv AI_PASSIVE | | 183 | .Dv AI_PASSIVE |
184 | is not set. | | 184 | is not set. |
185 | .El | | 185 | .El |
186 | .El | | 186 | .El |
187 | .Pp | | 187 | .Pp |
188 | All other elements of the | | 188 | All other elements of the |
189 | .Li addrinfo | | 189 | .Li addrinfo |
190 | structure passed via | | 190 | structure passed via |
191 | .Fa hints | | 191 | .Fa hints |
192 | must be zero or the null pointer. | | 192 | must be zero or the null pointer. |
193 | .Pp | | 193 | .Pp |
194 | If | | 194 | If |
195 | .Fa hints | | 195 | .Fa hints |
196 | is the null pointer, | | 196 | is the null pointer, |
197 | .Fn getaddrinfo | | 197 | .Fn getaddrinfo |
198 | behaves as if the caller provided a | | 198 | behaves as if the caller provided a |
199 | .Li struct addrinfo | | 199 | .Li struct addrinfo |
200 | with | | 200 | with |
201 | .Fa ai_family | | 201 | .Fa ai_family |
202 | set to | | 202 | set to |
203 | .Dv PF_UNSPEC | | 203 | .Dv PF_UNSPEC |
204 | and all other elements set to zero or | | 204 | and all other elements set to zero or |
205 | .Dv NULL . | | 205 | .Dv NULL . |
206 | .Pp | | 206 | .Pp |
207 | After a successful call to | | 207 | After a successful call to |
208 | .Fn getaddrinfo , | | 208 | .Fn getaddrinfo , |
209 | .Fa *res | | 209 | .Fa *res |
210 | is a pointer to a linked list of one or more | | 210 | is a pointer to a linked list of one or more |
211 | .Li addrinfo | | 211 | .Li addrinfo |
212 | structures. | | 212 | structures. |
213 | The list can be traversed by following the | | 213 | The list can be traversed by following the |
214 | .Fa ai_next | | 214 | .Fa ai_next |
215 | pointer in each | | 215 | pointer in each |
216 | .Li addrinfo | | 216 | .Li addrinfo |
217 | structure until a null pointer is encountered. | | 217 | structure until a null pointer is encountered. |
218 | The three members | | 218 | The three members |
219 | .Fa ai_family , | | 219 | .Fa ai_family , |
220 | .Fa ai_socktype , | | 220 | .Fa ai_socktype , |
221 | and | | 221 | and |
222 | .Fa ai_protocol | | 222 | .Fa ai_protocol |
223 | in each returned | | 223 | in each returned |
224 | .Li addrinfo | | 224 | .Li addrinfo |
225 | structure are suitable for a call to | | 225 | structure are suitable for a call to |
226 | .Xr socket 2 . | | 226 | .Xr socket 2 . |
227 | For each | | 227 | For each |
228 | .Li addrinfo | | 228 | .Li addrinfo |
229 | structure in the list, the | | 229 | structure in the list, the |
230 | .Fa ai_addr | | 230 | .Fa ai_addr |
231 | member points to a filled-in socket address structure of length | | 231 | member points to a filled-in socket address structure of length |
232 | .Fa ai_addrlen . | | 232 | .Fa ai_addrlen . |
233 | .Pp | | 233 | .Pp |
234 | This implementation of | | 234 | This implementation of |
235 | .Fn getaddrinfo | | 235 | .Fn getaddrinfo |
236 | allows numeric IPv6 address notation with scope identifier, | | 236 | allows numeric IPv6 address notation with scope identifier, |
237 | as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. | | 237 | as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. |
238 | By appending the percent character and scope identifier to addresses, | | 238 | By appending the percent character and scope identifier to addresses, |
239 | one can fill the | | 239 | one can fill the |
240 | .Li sin6_scope_id | | 240 | .Li sin6_scope_id |
241 | field for addresses. | | 241 | field for addresses. |
242 | This would make management of scoped addresses easier | | 242 | This would make management of scoped addresses easier |
243 | and allows cut-and-paste input of scoped addresses. | | 243 | and allows cut-and-paste input of scoped addresses. |
244 | .Pp | | 244 | .Pp |
245 | At this moment the code supports only link-local addresses with the format. | | 245 | At this moment the code supports only link-local addresses with the format. |
246 | The scope identifier is hardcoded to the name of the hardware interface | | 246 | The scope identifier is hardcoded to the name of the hardware interface |
247 | associated | | 247 | associated |
248 | with the link | | 248 | with the link |
249 | .Po | | 249 | .Po |
250 | such as | | 250 | such as |
251 | .Li ne0 | | 251 | .Li ne0 |
252 | .Pc . | | 252 | .Pc . |
253 | An example is | | 253 | An example is |
254 | .Dq Li fe80::1%ne0 , | | 254 | .Dq Li fe80::1%ne0 , |
255 | which means | | 255 | which means |
256 | .Do | | 256 | .Do |
257 | .Li fe80::1 | | 257 | .Li fe80::1 |
258 | on the link associated with the | | 258 | on the link associated with the |
259 | .Li ne0 | | 259 | .Li ne0 |
260 | interface | | 260 | interface |
261 | .Dc . | | 261 | .Dc . |
262 | .Pp | | 262 | .Pp |
263 | The current implementation assumes an one-to-one relationship between | | 263 | The current implementation assumes an one-to-one relationship between |
264 | the interface and link, which is not necessarily true from the specification. | | 264 | the interface and link, which is not necessarily true from the specification. |
265 | .Pp | | 265 | .Pp |
266 | All of the information returned by | | 266 | All of the information returned by |
267 | .Fn getaddrinfo | | 267 | .Fn getaddrinfo |
268 | is dynamically allocated: the | | 268 | is dynamically allocated: the |
269 | .Li addrinfo | | 269 | .Li addrinfo |
270 | structures themselves as well as the socket address structures and | | 270 | structures themselves as well as the socket address structures and |
271 | the canonical host name strings included in the | | 271 | the canonical host name strings included in the |
272 | .Li addrinfo | | 272 | .Li addrinfo |
273 | structures. | | 273 | structures. |
274 | .Pp | | 274 | .Pp |
275 | Memory allocated for the dynamically allocated structures created by | | 275 | Memory allocated for the dynamically allocated structures created by |
276 | a successful call to | | 276 | a successful call to |
277 | .Fn getaddrinfo | | 277 | .Fn getaddrinfo |
278 | is released by the | | 278 | is released by the |
279 | .Fn freeaddrinfo | | 279 | .Fn freeaddrinfo |
280 | function. | | 280 | function. |
281 | The | | 281 | The |
282 | .Fa ai | | 282 | .Fa ai |
283 | pointer should be an | | 283 | pointer should be an |
284 | .Li addrinfo | | 284 | .Li addrinfo |
285 | structure created by a call to | | 285 | structure created by a call to |
286 | .Fn getaddrinfo | | 286 | .Fn getaddrinfo |
287 | or | | 287 | or |
288 | .Fn allocaddrinfo . | | 288 | .Fn allocaddrinfo . |
289 | The | | 289 | The |
290 | .Fn allocaddrinfo | | 290 | .Fn allocaddrinfo |
291 | function is intended primarily for authors of | | 291 | function is intended primarily for authors of |
292 | .Xr nsdispatch 3 | | 292 | .Xr nsdispatch 3 |
293 | plugins implementing | | 293 | plugins implementing |
294 | .Fn getaddrinfo | | 294 | .Fn getaddrinfo |
295 | backends. | | 295 | backends. |
296 | .Fn allocaddrinfo | | 296 | .Fn allocaddrinfo |
297 | allocates a | | 297 | allocates a |
298 | .Li struct addrinfo | | 298 | .Li struct addrinfo |
299 | in a way that is compatible with being returned from | | 299 | in a way that is compatible with being returned from |
300 | .Fn getaddrinfo | | 300 | .Fn getaddrinfo |
301 | and being ultimately freed by | | 301 | and being ultimately freed by |
302 | .Fn freeaddrinfo . | | 302 | .Fn freeaddrinfo . |
303 | The returned structure is zeroed, except for the | | 303 | The returned structure is zeroed, except for the |
304 | .Fa ai_addr | | 304 | .Fa ai_addr |
305 | field, which | | 305 | field, which |
306 | will point to | | 306 | will point to |
307 | .Fa len | | 307 | .Fa len |
308 | bytes of memory for storage of a socket address. | | 308 | bytes of memory for storage of a socket address. |
309 | It is safe to allocate memory separately for | | 309 | It is safe to allocate memory separately for |
310 | .Fa ai_canonname | | 310 | .Fa ai_canonname |
311 | with | | 311 | with |
312 | .Xr malloc 3 , | | 312 | .Xr malloc 3 , |
313 | or in any other way that is compatible with deallocation by | | 313 | or in any other way that is compatible with deallocation by |
314 | .Xr free 3 . | | 314 | .Xr free 3 . |
315 | .Sh RETURN VALUES | | 315 | .Sh RETURN VALUES |
316 | .Fn getaddrinfo | | 316 | .Fn getaddrinfo |
317 | returns zero on success or one of the error codes listed in | | 317 | returns zero on success or one of the error codes listed in |
318 | .Xr gai_strerror 3 | | 318 | .Xr gai_strerror 3 |
319 | if an error occurs. | | 319 | if an error occurs. |
320 | .Sh EXAMPLES | | 320 | .Sh EXAMPLES |
321 | The following code tries to connect to | | 321 | The following code tries to connect to |
322 | .Dq Li www.kame.net | | 322 | .Dq Li www.kame.net |
323 | service | | 323 | service |
324 | .Dq Li http | | 324 | .Dq Li http |
325 | via a stream socket. | | 325 | via a stream socket. |
326 | It loops through all the addresses available, regardless of address family. | | 326 | It loops through all the addresses available, regardless of address family. |
327 | If the destination resolves to an IPv4 address, it will use an | | 327 | If the destination resolves to an IPv4 address, it will use an |
328 | .Dv AF_INET | | 328 | .Dv AF_INET |
329 | socket. | | 329 | socket. |
330 | Similarly, if it resolves to IPv6, an | | 330 | Similarly, if it resolves to IPv6, an |
331 | .Dv AF_INET6 | | 331 | .Dv AF_INET6 |
332 | socket is used. | | 332 | socket is used. |
333 | Observe that there is no hardcoded reference to a particular address family. | | 333 | Observe that there is no hardcoded reference to a particular address family. |
334 | The code works even if | | 334 | The code works even if |
335 | .Fn getaddrinfo | | 335 | .Fn getaddrinfo |
336 | returns addresses that are not IPv4/v6. | | 336 | returns addresses that are not IPv4/v6. |
337 | .Bd -literal -offset indent | | 337 | .Bd -literal -offset indent |
338 | struct addrinfo hints, *res, *res0; | | 338 | struct addrinfo hints, *res, *res0; |
339 | int error; | | 339 | int error; |
340 | int s; | | 340 | int s; |
341 | const char *cause = NULL; | | 341 | const char *cause = NULL; |
342 | | | 342 | |
343 | memset(\*[Am]hints, 0, sizeof(hints)); | | 343 | memset(\*[Am]hints, 0, sizeof(hints)); |
344 | hints.ai_family = PF_UNSPEC; | | 344 | hints.ai_family = PF_UNSPEC; |
345 | hints.ai_socktype = SOCK_STREAM; | | 345 | hints.ai_socktype = SOCK_STREAM; |
346 | error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); | | 346 | error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); |
347 | if (error) { | | 347 | if (error) { |
348 | errx(1, "%s", gai_strerror(error)); | | 348 | errx(1, "%s", gai_strerror(error)); |
349 | /*NOTREACHED*/ | | 349 | /*NOTREACHED*/ |
350 | } | | 350 | } |
351 | s = -1; | | 351 | s = -1; |
352 | for (res = res0; res; res = res-\*[Gt]ai_next) { | | 352 | for (res = res0; res; res = res-\*[Gt]ai_next) { |
353 | s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, | | 353 | s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, |
354 | res-\*[Gt]ai_protocol); | | 354 | res-\*[Gt]ai_protocol); |
355 | if (s \*[Lt] 0) { | | 355 | if (s \*[Lt] 0) { |
356 | cause = "socket"; | | 356 | cause = "socket"; |
357 | continue; | | 357 | continue; |
358 | } | | 358 | } |
359 | | | 359 | |
360 | if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { | | 360 | if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { |
361 | cause = "connect"; | | 361 | cause = "connect"; |
362 | close(s); | | 362 | close(s); |
363 | s = -1; | | 363 | s = -1; |
364 | continue; | | 364 | continue; |
365 | } | | 365 | } |
366 | | | 366 | |
367 | break; /* okay we got one */ | | 367 | break; /* okay we got one */ |
368 | } | | 368 | } |
369 | if (s \*[Lt] 0) { | | 369 | if (s \*[Lt] 0) { |
370 | err(1, "%s", cause); | | 370 | err(1, "%s", cause); |
371 | /*NOTREACHED*/ | | 371 | /*NOTREACHED*/ |
372 | } | | 372 | } |
373 | freeaddrinfo(res0); | | 373 | freeaddrinfo(res0); |
374 | .Ed | | 374 | .Ed |
375 | .Pp | | 375 | .Pp |
376 | The following example tries to open a wildcard listening socket onto service | | 376 | The following example tries to open a wildcard listening socket onto service |
377 | .Dq Li http , | | 377 | .Dq Li http , |
378 | for all the address families available. | | 378 | for all the address families available. |
379 | .Bd -literal -offset indent | | 379 | .Bd -literal -offset indent |
380 | struct addrinfo hints, *res, *res0; | | 380 | struct addrinfo hints, *res, *res0; |
381 | int error; | | 381 | int error; |
382 | int s[MAXSOCK]; | | 382 | int s[MAXSOCK]; |
383 | int nsock; | | 383 | int nsock; |
384 | const char *cause = NULL; | | 384 | const char *cause = NULL; |
385 | | | 385 | |
386 | memset(\*[Am]hints, 0, sizeof(hints)); | | 386 | memset(\*[Am]hints, 0, sizeof(hints)); |
387 | hints.ai_family = PF_UNSPEC; | | 387 | hints.ai_family = PF_UNSPEC; |
388 | hints.ai_socktype = SOCK_STREAM; | | 388 | hints.ai_socktype = SOCK_STREAM; |
389 | hints.ai_flags = AI_PASSIVE; | | 389 | hints.ai_flags = AI_PASSIVE; |
390 | error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); | | 390 | error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); |
391 | if (error) { | | 391 | if (error) { |
392 | errx(1, "%s", gai_strerror(error)); | | 392 | errx(1, "%s", gai_strerror(error)); |
393 | /*NOTREACHED*/ | | 393 | /*NOTREACHED*/ |
394 | } | | 394 | } |
395 | nsock = 0; | | 395 | nsock = 0; |
396 | for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { | | 396 | for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { |
397 | s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, | | 397 | s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, |
398 | res-\*[Gt]ai_protocol); | | 398 | res-\*[Gt]ai_protocol); |
399 | if (s[nsock] \*[Lt] 0) { | | 399 | if (s[nsock] \*[Lt] 0) { |
400 | cause = "socket"; | | 400 | cause = "socket"; |
401 | continue; | | 401 | continue; |
402 | } | | 402 | } |
403 | | | 403 | |
404 | if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { | | 404 | if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { |
405 | cause = "bind"; | | 405 | cause = "bind"; |
406 | close(s[nsock]); | | 406 | close(s[nsock]); |
407 | continue; | | 407 | continue; |
408 | } | | 408 | } |
409 | (void) listen(s[nsock], 5); | | 409 | (void) listen(s[nsock], 5); |
410 | | | 410 | |
411 | nsock++; | | 411 | nsock++; |
412 | } | | 412 | } |
413 | if (nsock == 0) { | | 413 | if (nsock == 0) { |
414 | err(1, "%s", cause); | | 414 | err(1, "%s", cause); |
415 | /*NOTREACHED*/ | | 415 | /*NOTREACHED*/ |
416 | } | | 416 | } |
417 | freeaddrinfo(res0); | | 417 | freeaddrinfo(res0); |
418 | .Ed | | 418 | .Ed |
419 | .Sh SEE ALSO | | 419 | .Sh SEE ALSO |
420 | .Xr bind 2 , | | 420 | .Xr bind 2 , |
421 | .Xr connect 2 , | | 421 | .Xr connect 2 , |
422 | .Xr send 2 , | | 422 | .Xr send 2 , |
423 | .Xr socket 2 , | | 423 | .Xr socket 2 , |
424 | .Xr gai_strerror 3 , | | 424 | .Xr gai_strerror 3 , |
425 | .Xr gethostbyname 3 , | | 425 | .Xr gethostbyname 3 , |
426 | .Xr getnameinfo 3 , | | 426 | .Xr getnameinfo 3 , |
427 | .Xr getservbyname 3 , | | 427 | .Xr getservbyname 3 , |
428 | .Xr resolver 3 , | | 428 | .Xr resolver 3 , |
429 | .Xr hosts 5 , | | 429 | .Xr hosts 5 , |
430 | .Xr resolv.conf 5 , | | 430 | .Xr resolv.conf 5 , |
431 | .Xr services 5 , | | 431 | .Xr services 5 , |
432 | .Xr hostname 7 , | | 432 | .Xr hostname 7 , |
433 | .Xr named 8 | | 433 | .Xr named 8 |
434 | .Rs | | 434 | .Rs |
435 | .%A R. Gilligan | | 435 | .%A R. Gilligan |
436 | .%A S. Thomson | | 436 | .%A S. Thomson |
437 | .%A J. Bound | | 437 | .%A J. Bound |
438 | .%A J. McCann | | 438 | .%A J. McCann |
439 | .%A W. Stevens | | 439 | .%A W. Stevens |
440 | .%T Basic Socket Interface Extensions for IPv6 | | 440 | .%T Basic Socket Interface Extensions for IPv6 |
441 | .%R RFC 3493 | | 441 | .%R RFC 3493 |
442 | .%D February 2003 | | 442 | .%D February 2003 |
443 | .Re | | 443 | .Re |
444 | .Rs | | 444 | .Rs |
445 | .%A S. Deering | | 445 | .%A S. Deering |
446 | .%A B. Haberman | | 446 | .%A B. Haberman |
447 | .%A T. Jinmei | | 447 | .%A T. Jinmei |
448 | .%A E. Nordmark | | 448 | .%A E. Nordmark |
449 | .%A B. Zill | | 449 | .%A B. Zill |
450 | .%T "IPv6 Scoped Address Architecture" | | 450 | .%T "IPv6 Scoped Address Architecture" |
451 | .%R internet draft | | 451 | .%R internet draft |
452 | .%N draft-ietf-ipv6-scoping-arch-02.txt | | 452 | .%N draft-ietf-ipv6-scoping-arch-02.txt |
453 | .%O work in progress material | | 453 | .%O work in progress material |
454 | .Re | | 454 | .Re |
455 | .Rs | | 455 | .Rs |
456 | .%A Craig Metz | | 456 | .%A Craig Metz |
457 | .%T Protocol Independence Using the Sockets API | | 457 | .%T Protocol Independence Using the Sockets API |
458 | .%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" | | 458 | .%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" |
459 | .%D June 2000 | | 459 | .%D June 2000 |
460 | .Re | | 460 | .Re |
461 | .Sh STANDARDS | | 461 | .Sh STANDARDS |
462 | The | | 462 | The |
463 | .Fn getaddrinfo | | 463 | .Fn getaddrinfo |
464 | function is defined by the | | 464 | function is defined by the |
465 | .St -p1003.1g-2000 | | 465 | .St -p1003.1g-2000 |
466 | draft specification and documented in | | 466 | draft specification and documented in |
467 | .Dv "RFC 3493" , | | 467 | .Dv "RFC 3493" , |
468 | .Dq Basic Socket Interface Extensions for IPv6 . | | 468 | .Dq Basic Socket Interface Extensions for IPv6 . |