OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [net-common-tcpip-manpages-getaddrinfo.html] - Blame information for rev 858

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
2
<!-- This material may be distributed only subject to the terms      -->
3
<!-- and conditions set forth in the Open Publication License, v1.0  -->
4
<!-- or later (the latest version is presently available at          -->
5
<!-- http://www.opencontent.org/openpub/).                           -->
6
<!-- Distribution of the work or derivative of the work in any       -->
7
<!-- standard (paper) book form is prohibited unless prior           -->
8
<!-- permission is obtained from the copyright holder.               -->
9
<HTML
10
><HEAD
11
><TITLE
12
>getaddrinfo</TITLE
13
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14
<META
15
NAME="GENERATOR"
16
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17
"><LINK
18
REL="HOME"
19
TITLE="eCos Reference Manual"
20
HREF="ecos-ref.html"><LINK
21
REL="UP"
22
TITLE="TCP/IP Library Reference"
23
HREF="tcpip-library-reference.html"><LINK
24
REL="PREVIOUS"
25
TITLE="ethers"
26
HREF="net-common-tcpip-manpages-ethers.html"><LINK
27
REL="NEXT"
28
TITLE="gethostbyname"
29
HREF="net-common-tcpip-manpages-gethostbyname.html"></HEAD
30
><BODY
31
CLASS="SECT1"
32
BGCOLOR="#FFFFFF"
33
TEXT="#000000"
34
LINK="#0000FF"
35
VLINK="#840084"
36
ALINK="#0000FF"
37
><DIV
38
CLASS="NAVHEADER"
39
><TABLE
40
SUMMARY="Header navigation table"
41
WIDTH="100%"
42
BORDER="0"
43
CELLPADDING="0"
44
CELLSPACING="0"
45
><TR
46
><TH
47
COLSPAN="3"
48
ALIGN="center"
49
>eCos Reference Manual</TH
50
></TR
51
><TR
52
><TD
53
WIDTH="10%"
54
ALIGN="left"
55
VALIGN="bottom"
56
><A
57
HREF="net-common-tcpip-manpages-ethers.html"
58
ACCESSKEY="P"
59
>Prev</A
60
></TD
61
><TD
62
WIDTH="80%"
63
ALIGN="center"
64
VALIGN="bottom"
65
>Chapter 38. TCP/IP Library Reference</TD
66
><TD
67
WIDTH="10%"
68
ALIGN="right"
69
VALIGN="bottom"
70
><A
71
HREF="net-common-tcpip-manpages-gethostbyname.html"
72
ACCESSKEY="N"
73
>Next</A
74
></TD
75
></TR
76
></TABLE
77
><HR
78
ALIGN="LEFT"
79
WIDTH="100%"></DIV
80
><DIV
81
CLASS="SECT1"
82
><H1
83
CLASS="SECT1"
84
><A
85
NAME="NET-COMMON-TCPIP-MANPAGES-GETADDRINFO">getaddrinfo</H1
86
><TABLE
87
BORDER="5"
88
BGCOLOR="#E0E0F0"
89
WIDTH="70%"
90
><TR
91
><TD
92
><PRE
93
CLASS="SCREEN"
94
>GETADDRINFO(3)          System Library Functions Manual         GETADDRINFO(3)
95
 
96
NAME
97
     getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
98
     in protocol-independent manner
99
 
100
SYNOPSIS
101
     #include &lt;sys/types.h&#62;
102
     #include &lt;sys/socket.h&#62;
103
     #include &lt;netdb.h&#62;
104
 
105
     int
106
     getaddrinfo(const char *nodename, const char *servname,
107
             const struct addrinfo *hints, struct addrinfo **res);
108
 
109
     void
110
     freeaddrinfo(struct addrinfo *ai);
111
 
112
     char *
113
     gai_strerror(int ecode);
114
 
115
DESCRIPTION
116
     The getaddrinfo() function is defined for protocol-independent nodename-
117
     to-address translation.  It performs the functionality of
118
     gethostbyname(3) and getservbyname(3), but in a more sophisticated man-
119
     ner.
120
 
121
     The addrinfo structure is defined as a result of including the &lt;netdb.h&#62;
122
     header:
123
 
124
     struct addrinfo {                                                  *
125
          int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
126
          int     ai_family;    /* PF_xxx */
127
          int     ai_socktype;  /* SOCK_xxx */
128
          int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
129
          size_t  ai_addrlen;   /* length of ai_addr */
130
          char   *ai_canonname; /* canonical name for nodename */
131
          struct sockaddr  *ai_addr; /* binary address */
132
          struct addrinfo  *ai_next; /* next structure in linked list */
133
     };
134
 
135
     The nodename and servname arguments are pointers to NUL-terminated
136
     strings or NULL.  One or both of these two arguments must be a non-null
137
     pointer.  In the normal client scenario, both the nodename and servname
138
     are specified.  In the normal server scenario, only the servname is spec-
139
     ified.  A non-null nodename string can be either a node name or a numeric
140
     host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
141
     address).  A non-null servname string can be either a service name or a
142
     decimal port number.
143
 
144
     The caller can optionally pass an addrinfo structure, pointed to by the
145
     third argument, to provide hints concerning the type of socket that the
146
     caller supports.  In this hints structure all members other than
147
     ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a null
148
     pointer.  A value of PF_UNSPEC for ai_family means the caller will accept
149
     any protocol family.  A value of 0 for ai_socktype means the caller will
150
     accept any socket type.  A value of 0 for ai_protocol means the caller
151
     will accept any protocol.  For example, if the caller handles only TCP
152
     and not UDP, then the ai_socktype member of the hints structure should be
153
     set to SOCK_STREAM when getaddrinfo() is called.  If the caller handles
154
     only IPv4 and not IPv6, then the ai_family member of the hints structure
155
     should be set to PF_INET when getaddrinfo() is called.  If the third
156
     argument to getaddrinfo() is a null pointer, this is the same as if the
157
     caller had filled in an addrinfo structure initialized to zero with
158
     ai_family set to PF_UNSPEC.
159
 
160
     Upon successful return a pointer to a linked list of one or more addrinfo
161
     structures is returned through the final argument.  The caller can pro-
162
     cess each addrinfo structure in this list by following the ai_next
163
     pointer, until a null pointer is encountered.  In each returned addrinfo
164
     structure the three members ai_family, ai_socktype, and ai_protocol are
165
     the corresponding arguments for a call to the socket() function.  In each
166
     addrinfo structure the ai_addr member points to a filled-in socket
167
     address structure whose length is specified by the ai_addrlen member.
168
 
169
     If the AI_PASSIVE bit is set in the ai_flags member of the hints struc-
170
     ture, then the caller plans to use the returned socket address structure
171
     in a call to bind().  In this case, if the nodename argument is a null
172
     pointer, then the IP address portion of the socket address structure will
173
     be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
174
     address.
175
 
176
     If the AI_PASSIVE bit is not set in the ai_flags member of the hints
177
     structure, then the returned socket address structure will be ready for a
178
     call to connect() (for a connection-oriented protocol) or either
179
     connect(), sendto(), or sendmsg() (for a connectionless protocol).  In
180
     this case, if the nodename argument is a null pointer, then the IP
181
     address portion of the socket address structure will be set to the loop-
182
     back address.
183
 
184
     If the AI_CANONNAME bit is set in the ai_flags member of the hints struc-
185
     ture, then upon successful return the ai_canonname member of the first
186
     addrinfo structure in the linked list will point to a NUL-terminated
187
     string containing the canonical name of the specified nodename.
188
 
189
     If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
190
     structure, then a non-null nodename string must be a numeric host address
191
     string.  Otherwise an error of EAI_NONAME is returned.  This flag pre-
192
     vents any type of name resolution service (e.g., the DNS) from being
193
     called.
194
 
195
     The arguments to getaddrinfo() must sufficiently be consistent and unam-
196
     biguous.  Here are pitfall cases you may encounter:
197
 
198
     o   getaddrinfo() will raise an error if members of the hints structure
199
         are not consistent.  For example, for internet address families,
200
         getaddrinfo() will raise an error if you specify SOCK_STREAM to
201
         ai_socktype while you specify IPPROTO_UDP to ai_protocol.
202
 
203
     o   If you specify a servname which is defined only for certain
204
         ai_socktype, getaddrinfo() will raise an error because the arguments
205
         are not consistent.  For example, getaddrinfo() will raise an error
206
         if you ask for ``tftp'' service on SOCK_STREAM.
207
 
208
     o   For internet address families, if you specify servname while you set
209
         ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because
210
         service names are not defined for the internet SOCK_RAW space.
211
 
212
     o   If you specify a numeric servname, while leaving ai_socktype and
213
         ai_protocol unspecified, getaddrinfo() will raise an error.  This is
214
         because the numeric servname does not identify any socket type, and
215
         getaddrinfo() is not allowed to glob the argument in such case.
216
 
217
     All of the information returned by getaddrinfo() is dynamically allo-
218
     cated: the addrinfo structures, the socket address structures, and canon-
219
     ical node name strings pointed to by the addrinfo structures.  To return
220
     this information to the system the function freeaddrinfo() is called.
221
     The addrinfo structure pointed to by the ai argument is freed, along with
222
     any dynamic storage pointed to by the structure.  This operation is
223
     repeated until a NULL ai_next pointer is encountered.
224
 
225
     To aid applications in printing error messages based on the EAI_xxx codes
226
     returned by getaddrinfo(), gai_strerror() is defined.  The argument is
227
     one of the EAI_xxx values defined earlier and the return value points to
228
     a string describing the error.  If the argument is not one of the EAI_xxx
229
     values, the function still returns a pointer to a string whose contents
230
     indicate an unknown error.
231
 
232
   Extension for scoped IPv6 address
233
     The implementation allows experimental numeric IPv6 address notation with
234
     scope identifier.  By appending the percent character and scope identi-
235
     fier to addresses, you can fill sin6_scope_id field for addresses.  This
236
     would make management of scoped address easier, and allows cut-and-paste
237
     input of scoped address.
238
 
239
     At this moment the code supports only link-local addresses with the for-
240
     mat.  Scope identifier is hardcoded to name of hardware interface associ-
241
     ated with the link.  (such as ne0).  Example would be like
242
     ``fe80::1%ne0'', which means ``fe80::1 on the link associated with ne0
243
     interface''.
244
 
245
     The implementation is still very experimental and non-standard.  The cur-
246
     rent implementation assumes one-by-one relationship between interface and
247
     link, which is not necessarily true from the specification.
248
 
249
EXAMPLES
250
     The following code tries to connect to ``www.kame.net'' service ``http''.
251
     via stream socket.  It loops through all the addresses available, regard-
252
     less from address family.  If the destination resolves to IPv4 address,
253
     it will use AF_INET socket.  Similarly, if it resolves to IPv6, AF_INET6
254
     socket is used.  Observe that there is no hardcoded reference to particu-
255
     lar address family.  The code works even if getaddrinfo returns addresses
256
     that are not IPv4/v6.
257
 
258
           struct addrinfo hints, *res, *res0;
259
           int error;
260
           int s;
261
           const char *cause = NULL;
262
 
263
           memset(&amp;hints, 0, sizeof(hints));
264
           hints.ai_family = PF_UNSPEC;
265
           hints.ai_socktype = SOCK_STREAM;
266
           error = getaddrinfo("www.kame.net", "http", &amp;hints, &amp;res0);
267
           if (error) {
268
                   errx(1, "%s", gai_strerror(error));
269
                   /*NOTREACHED*/
270
           }
271
           s = -1;
272
           for (res = res0; res; res = res-&#62;ai_next) {
273
                   s = socket(res-&#62;ai_family, res-&#62;ai_socktype,
274
                       res-&#62;ai_protocol);
275
                   if (s &lt; 0) {
276
                           cause = "socket";
277
                           continue;
278
                   }
279
 
280
                   if (connect(s, res-&#62;ai_addr, res-&#62;ai_addrlen) &lt; 0) {
281
                           cause = "connect";
282
                           close(s);
283
                           s = -1;
284
                           continue;
285
                   }
286
 
287
                   break;  /* okay we got one */
288
           }
289
           if (s &lt; 0) {
290
                   err(1, cause);
291
                   /*NOTREACHED*/
292
           }
293
           freeaddrinfo(res0);
294
 
295
     The following example tries to open a wildcard listening socket onto ser-
296
     vice ``http'', for all the address families available.
297
 
298
           struct addrinfo hints, *res, *res0;
299
           int error;
300
           int s[MAXSOCK];
301
           int nsock;
302
           const char *cause = NULL;
303
 
304
           memset(&amp;hints, 0, sizeof(hints));
305
           hints.ai_family = PF_UNSPEC;
306
           hints.ai_socktype = SOCK_STREAM;
307
           hints.ai_flags = AI_PASSIVE;
308
           error = getaddrinfo(NULL, "http", &amp;hints, &amp;res0);
309
           if (error) {
310
                   errx(1, "%s", gai_strerror(error));
311
                   /*NOTREACHED*/
312
           }
313
           nsock = 0;
314
           for (res = res0; res &amp;&amp; nsock &lt; MAXSOCK; res = res-&#62;ai_next) {
315
                   s[nsock] = socket(res-&#62;ai_family, res-&#62;ai_socktype,
316
                       res-&#62;ai_protocol);
317
                   if (s[nsock] &lt; 0) {
318
                           cause = "socket";
319
                           continue;
320
                   }
321
 
322
                   if (bind(s[nsock], res-&#62;ai_addr, res-&#62;ai_addrlen) &lt; 0) {
323
                           cause = "bind";
324
                           close(s[nsock]);
325
                           continue;
326
                   }
327
                   (void) listen(s[nsock], 5);
328
 
329
                   nsock++;
330
           }
331
           if (nsock == 0) {
332
                   err(1, cause);
333
                   /*NOTREACHED*/
334
           }
335
           freeaddrinfo(res0);
336
 
337
DIAGNOSTICS
338
     Error return status from getaddrinfo() is zero on success and non-zero on
339
     errors.  Non-zero error codes are defined in &lt;netdb.h&#62;, and as follows:
340
 
341
     EAI_ADDRFAMILY  Address family for nodename not supported.
342
     EAI_AGAIN       Temporary failure in name resolution.
343
     EAI_BADFLAGS    Invalid value for ai_flags.
344
     EAI_FAIL        Non-recoverable failure in name resolution.
345
     EAI_FAMILY      ai_family not supported.
346
     EAI_MEMORY      Memory allocation failure.
347
     EAI_NODATA      No address associated with nodename.
348
     EAI_NONAME      nodename nor servname provided, or not known.
349
     EAI_SERVICE     servname not supported for ai_socktype.
350
     EAI_SOCKTYPE    ai_socktype not supported.
351
     EAI_SYSTEM      System error returned in errno.
352
 
353
     If called with proper argument, gai_strerror() returns a pointer to a
354
     string describing the given error code.  If the argument is not one of
355
     the EAI_xxx values, the function still returns a pointer to a string
356
     whose contents indicate an unknown error.
357
 
358
SEE ALSO
359
     getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
360
     resolv.conf(5), services(5), hostname(7), named(8)
361
 
362
     R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
363
     Extensions for IPv6, RFC2553, March 1999.
364
 
365
     Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
366
     Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
367
     work in progress material.
368
 
369
     Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
370
     the freenix track: 2000 USENIX annual technical conference, June 2000.
371
 
372
HISTORY
373
     The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
374
     kit.
375
 
376
STANDARDS
377
     The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
378
     fication, and documented in ``Basic Socket Interface Extensions for
379
     IPv6'' (RFC2553).
380
 
381
BUGS
382
     The current implementation is not thread-safe.
383
 
384
     The text was shamelessly copied from RFC2553.
385
 
386
BSD                              May 25, 1995                              BSD
387
    </PRE
388
></TD
389
></TR
390
></TABLE
391
></DIV
392
><DIV
393
CLASS="NAVFOOTER"
394
><HR
395
ALIGN="LEFT"
396
WIDTH="100%"><TABLE
397
SUMMARY="Footer navigation table"
398
WIDTH="100%"
399
BORDER="0"
400
CELLPADDING="0"
401
CELLSPACING="0"
402
><TR
403
><TD
404
WIDTH="33%"
405
ALIGN="left"
406
VALIGN="top"
407
><A
408
HREF="net-common-tcpip-manpages-ethers.html"
409
ACCESSKEY="P"
410
>Prev</A
411
></TD
412
><TD
413
WIDTH="34%"
414
ALIGN="center"
415
VALIGN="top"
416
><A
417
HREF="ecos-ref.html"
418
ACCESSKEY="H"
419
>Home</A
420
></TD
421
><TD
422
WIDTH="33%"
423
ALIGN="right"
424
VALIGN="top"
425
><A
426
HREF="net-common-tcpip-manpages-gethostbyname.html"
427
ACCESSKEY="N"
428
>Next</A
429
></TD
430
></TR
431
><TR
432
><TD
433
WIDTH="33%"
434
ALIGN="left"
435
VALIGN="top"
436
>ethers</TD
437
><TD
438
WIDTH="34%"
439
ALIGN="center"
440
VALIGN="top"
441
><A
442
HREF="tcpip-library-reference.html"
443
ACCESSKEY="U"
444
>Up</A
445
></TD
446
><TD
447
WIDTH="33%"
448
ALIGN="right"
449
VALIGN="top"
450
>gethostbyname</TD
451
></TR
452
></TABLE
453
></DIV
454
></BODY
455
></HTML
456
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.