Mercurial > ecos-v3_0-branch

annotate packages/net/ns/dns/current/doc/dns.sgml @ 2863:7d8c61e6225c default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Added execute permissions to files missed in conversion from CVS
author alexs
date Thu, 26 Mar 2009 20:39:18 +0000
parents 74dbf4c3f2e1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
333
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
1 <!-- {{{ Banner -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
2
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
3 <!-- =============================================================== -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
4 <!-- -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
5 <!-- dns.sgml -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
6 <!-- -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
7 <!-- eCos TCP/IP Stacks -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
8 <!-- -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
9 <!-- =============================================================== -->
2729
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
10 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
11 <!-- =============================================================== -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
12 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
13 <!-- This material may be distributed only subject to the terms -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
14 <!-- and conditions set forth in the Open Publication License, v1.0 -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
15 <!-- or later (the latest version is presently available at -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
16 <!-- http://www.opencontent.org/openpub/) -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
17 <!-- Distribution of the work or derivative of the work in any -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
18 <!-- standard (paper) book form is prohibited unless prior -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
19 <!-- permission obtained from the copyright holder -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
20 <!-- =============================================================== -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 1040
diff changeset
21 <!-- ####ECOSDOCCOPYRIGHTEND#### -->
333
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
22 <!-- =============================================================== -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
23 <!-- #####DESCRIPTIONBEGIN#### -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
24 <!-- -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
25 <!-- ####DESCRIPTIONEND#### -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
26 <!-- =============================================================== -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
27
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
28 <!-- }}} -->
26852e80cb37 Update documentation licenses to remove restriction on redistributing
bartv
parents: 208
diff changeset
29
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
30 <PART ID="net-ns-dns">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
31 <TITLE>DNS for eCos and RedBoot</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
32 <PARTINTRO>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
33 <PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
34 <productname>eCos</productname> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
35 <productname>RedBoot</productname>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
36 can both use the DNS package to perform network name lookups.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
37 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
38 </PARTINTRO>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
39 <CHAPTER id="net-ns-dns-api">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
40 <TITLE>DNS</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
41 <SECT1 id="net-ns-dns-api1">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
42 <TITLE>DNS API</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
43 <PARA>The DNS client uses the normal BSD API for performing lookups:
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
44 <function>gethostbyname(),</function>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
45 <FUNCTION>gethostbyaddr()</FUNCTION>,
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
46 <FUNCTION>getaddrinfo()</function>,
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
47 <FUNCTION>getnameinfo()</function>.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
48 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
49 <PARA>There are a few restrictions:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
50 <ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
51 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
52 <PARA>If the DNS server returns multiple authoritive records
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
53 for a host name to <function>gethostbyname</function>, the hostent will only contain a record for the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
54 first entry. If multiple records are desired, use
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
55 <function>getaddrinfo</function>, which will return multiple results.</PARA>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
56 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
57 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
58 <PARA>The code has been made thread safe. ie multiple threads
500
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
59 may call
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
60 <FUNCTION>gethostbyname()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
61 without causing problems to the hostent structure returned. What
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
62 is not safe is one thread using both
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
63 <FUNCTION>gethostbyname()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
64 and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
65 <FUNCTION>gethostbyaddr()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
66 A call to one will destroy the results from the previous call
1040
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
67 to the other function. <FUNCTION>getaddrinfo()</FUNCTION> and
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
68 <FUNCTION>getnameinfo()</FUNCTION> are thread
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
69 safe and so these are the preferred interfaces. They are also address
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
70 family independent so making it easier to port code to IPv6.</PARA>
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
71 </LISTITEM>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
72 <LISTITEM><PARA>The DNS client will only return IPv4 addresses to
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
73 RedBoot. At the moment this is not really a limitation,
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
74 since RedBoot only supports IPv4 and not IPv6.</PARA>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
75 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
76 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
77 <PARA>To initialise the DNS client the following function must be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
78 called:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
79 <PROGRAMLISTING>#include &lt;network.h&gt;
1040
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
80 int cyg_dns_res_start(char * dns_server)</PROGRAMLISTING>
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
81
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
82 <PARA>Where dns_server is the address of the DNS server. The address
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
83 must be in numeric form and can be either an IPv4 or an IPv6 address.
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
84 </PARA>
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
85 <PARA>There also exists a deprecated function to start the DNS
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
86 client:</PARA>
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
87 <PROGRAMLISTING>
500
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
88 int cyg_dns_res_init(struct in_addr *dns_server)</PROGRAMLISTING>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
89 <PARA>where dns_server is the address of the DNS server
1040
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
90 the client should query. The address should be in network order and
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
91 can only be an IPv4 address.
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
92 </PARA>
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
93
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
94 <PARA> On error both this function returns -1, otherwise
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
95 0 for success. If lookups are attemped before this function has
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
96 been called, they will fail and return NULL, unless numeric host addresses
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
97 are passed. In this cause, the address will be converted and returned
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
98 without the need for a lookup.</PARA>
500
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
99
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
100 <PARA>A default, hard coded, server may be specified in the CDL option
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
101 <literal>CYGDAT_NS_DNS_DEFAULT_SERVER</literal>. The use of this is
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
102 controlled by <literal>CYGPKG_NS_DNS_DEFAULT</literal>. If this is
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
103 enabled, <literal>init_all_network_interfaces()</literal> will
500
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
104 initialize the resolver with the hard coded address. The DHCP client
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
105 or user code my override this address by calling
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
106 <literal>cyg_dns_res_init</literal> again. </PARA>
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
107
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
108 <PARA>The DNS client understands the concepts of the target being
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
109 in a domain. By default no domain will be used. Host name lookups
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
110 should be for fully qualified names. The domain name can be set
527
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
111 and retrieved using the functions:
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
112 <funcsynopsis>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
113 <funcprototype>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
114 <funcdef>int <function>getdomainname</function></funcdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
115 <paramdef>char *<parameter>name</parameter></paramdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
116 <paramdef>size_t <parameter>len</parameter></paramdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
117 </funcprototype>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
118 <funcprototype>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
119 <funcdef>int <function>setdomainname</function></funcdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
120 <paramdef>const char *<parameter>name</parameter></paramdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
121 <paramdef>size_t <parameter>len</parameter></paramdef>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
122 </funcprototype>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
123 </funcsynopsis>
3982e53923d5 * doc/dns.sgml: Use correct (and working!) docbook.
jlarmour
parents: 505
diff changeset
124 </para>
500
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
125
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
126 <PARA>Alternatively, a hard coded domain name can be set using CDL.
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
127 The boolean <literal>CYGPKG_NS_DNS_DOMAINNAME</literal> enables this
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
128 and the domain name is taken from
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
129 <literal>CYGPKG_NS_DNS_DOMAINNAME_NAME</literal>.</PARA>
b6080ba5b75a * cdl/dns.cdl: Added the ability to hard code a domain name.
jlarmour
parents: 333
diff changeset
130
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
131 <PARA>Once set, the DNS client will use some simple heuristics when
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
132 deciding how to use the domainname. If the name given to the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
133 client ends with a "." it is assumed to be a FQDN and the domain
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
134 name will not be used. If the name contains a "." somewhere
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
135 within it, first a lookup will be performed without the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
136 domainname. If that fails the domainname will be appended and
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
137 looked up. If the name does not contain a ".", the domainname is
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
138 appended and used for the first query. If that fails, the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
139 unadorned name is lookup.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
140 </PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
141 <PARA>The <FUNCTION>getaddrinfo</FUNCTION> will return both IPv4 and
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
142 IPv6 addresses for a given host name, when IPv6 is enabled in
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
143 the eCos configuration. The CDL option
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
144 <LITERAL>CYGOPT_NS_DNS_FIRST_FAMILY</LITERAL> controls the order
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
145 IPv6 and IPv4 addresses are returned in the linked list of
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
146 <LITERAL>addrinfo</LITERAL> structures. If the value
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
147 <LITERAL>AF_INET</LITERAL> is used, the IPv4 addresses will be
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
148 first. If the value <LITERAL>AF_INET6</LITERAL>, which is the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
149 default, is used, IPv6 address will be first. This ordering will
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
150 control how clients attempt to connect to servers, ie using IPv6
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
151 or IPv4 first.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
152 </PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
153 </SECT1>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
154 <SECT1 id="net-ns-dns-testing">
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
155 <TITLE>DNS Client Testing</TITLE>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
156
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
157 <PARA>The DNS client has a test program, dns1.c, which tests many of
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
158 the features of the DNS client and the functions
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
159 <FUNCTION>gethostbyname(),</FUNCTION>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
160 <FUNCTION>gethostbyaddr()</FUNCTION>,
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
161 <FUNCTION>getaddrinfo()</FUNCTION>,
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
162 <FUNCTION>getnameinfo()</FUNCTION>.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
163 </PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
164 <PARA>In order for this test to work, a DNS server must be configured
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
165 with a number of names and addresses. The following is an example
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
166 forward address resolution database for bind v9, which explains the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
167 requirements.</para>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
168
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
169 <PROGRAMLISTING>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
170 $TTL 680400
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
171 @ IN SOA lunn.org. andrew.lunn.lunn.org (
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
172 2003041801 ; serial
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
173 10800 ; refresh
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
174 1800 ; retry
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
175 3600000 ; expire
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
176 259200) ; mimimum
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
177 IN NS londo.lunn.org.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
178
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
179 hostnamev4 IN A 192.168.88.1
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
180 cnamev4 IN CNAME hostnamev4
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
181 hostnamev6 IN AAAA fec0::88:4:3:2:1
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
182 cnamev6 IN CNAME hostnamev6
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
183 hostnamev46 IN A 192.168.88.2
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
184 hostnamev46 IN AAAA fec0::88:4:3:2:2
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
185 cnamev46 IN CNAME hostnamev46
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
186 </PROGRAMLISTING>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
187 <PARA>The actual names and addresses do not matter, since they are
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
188 configurable in the test. What is important is the relationship
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
189 between the names and the addresses and there family. ie
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
190 hostnamev4 should map to one IPv4 address. hostnamev46 should
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
191 map to both an IPv4 and an IPv6 address. cnamev4 should be a
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
192 CNAME record for hostname4. Reverse lookup information is also
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
193 needed by the test.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
194 </PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
195 <PARA>The information placed into the DNS server is also need in the
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
196 test case. A structure is defined to hold this
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
197 information:</PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
198 <PROGRAMLISTING>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
199 struct test_info_s {
1040
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
200 char * dns_server_v4;
1aaed612fe59 * src/dns.c: (cyg_dns_res_start) New: Allow IPv6 to be used to
asl
parents: 1005
diff changeset
201 char * dns_server_v6;
1005
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
202 char * domain_name;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
203 char * hostname_v4;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
204 char * cname_v4;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
205 char * ip_addr_v4;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
206 char * hostname_v6;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
207 char * cname_v6;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
208 char * ip_addr_v6;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
209 char * hostname_v46;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
210 char * cname_v46;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
211 char * ip_addr_v46_v4;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
212 char * ip_addr_v46_v6;
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
213 };
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
214 </PROGRAMLISTING>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
215 <PARA>The test program may hold a number of such structures for
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
216 different DNS server. The test will use each structure in turn
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
217 to perform the tests. If IPv6 is not enabled in the eCos
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
218 configuration, the entries which use IPv6 may be assigned to
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
219 NULL.
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
220 </PARA>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
221 </SECT1>
1f968b35cd30 * doc/dns.sgml: Updated to reflect changes for IPv6.
asl
parents: 527
diff changeset
222 </CHAPTER>
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
223 </PART>