doc/html/ref/net-ns-dns-api.html

   1 <!-- 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 >DNS</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="DNS for eCos and RedBoot"
  23 HREF="net-ns-dns.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="DNS for eCos and RedBoot"
  26 HREF="net-ns-dns.html"><LINK
  27 REL="NEXT"
  28 TITLE="Ethernet Device Drivers"
  29 HREF="io-eth-drv-generic.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  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-ns-dns.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-eth-drv-generic.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="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="NET-NS-DNS-API">Chapter 45. DNS</H1
  85 ><DIV
  86 CLASS="SECT1"
  87 ><H1
  88 CLASS="SECT1"
  89 ><A
  90 NAME="NET-NS-DNS-API1">DNS API</H1
  91 ><P
  92 >The DNS client uses the normal BSD API for performing lookups:
  93 <TT
  94 CLASS="FUNCTION"
  95 >gethostbyname()</TT
  96 > and
  97 <TT
  98 CLASS="FUNCTION"
  99 >gethostbyaddr()</TT
 100 >.</P
 101 ><P
 102 >There are a few restrictions:</P
 103 ><P
 104 ></P
 105 ><UL
 106 ><LI
 107 ><P
 108 >Only IPv4 is supported, ie IPv6 addresses cannot be looked
 109 up.</P
 110 ></LI
 111 ><LI
 112 ><P
 113 >If the DNS server returns multiple authoritive records
 114 for a host name, the hostent will only contain a record for the
 115 first entry.</P
 116 ></LI
 117 ><LI
 118 ><P
 119 >The code has been made thread safe. ie multiple threads
 120 may call
 121 <TT
 122 CLASS="FUNCTION"
 123 >gethostbyname()</TT
 124 >
 125  without causing problems to the hostent structure returned. What
 126 is not safe is one thread using both
 127 <TT
 128 CLASS="FUNCTION"
 129 >gethostbyname()</TT
 130 >
 131  and
 132 <TT
 133 CLASS="FUNCTION"
 134 >gethostbyaddr()</TT
 135 >.
 136 A call to one will destroy the results from the previous call
 137 to the other function.</P
 138 ></LI
 139 ></UL
 140 ><P
 141 >To initialise the DNS client the following function must be
 142 called:</P
 143 ><TABLE
 144 BORDER="5"
 145 BGCOLOR="#E0E0F0"
 146 WIDTH="70%"
 147 ><TR
 148 ><TD
 149 ><PRE
 150 CLASS="PROGRAMLISTING"
 151 >#include &lt;network.h&gt;
 152 int cyg_dns_res_init(struct in_addr *dns_server)</PRE
 153 ></TD
 154 ></TR
 155 ></TABLE
 156 ><P
 157 >where dns_server is the address of the DNS server
 158 the client should query. On Error this function returns -1, otherwise
 159 0 for success. If lookups are attemped before this function has
 160 been called, they will fail and return NULL.</P
 161 ><P
 162 >A default, hard coded, server may be specified in the CDL option
 163 <TT
 164 CLASS="LITERAL"
 165 >CYGDAT_NS_DNS_DEFAULT_SERVER</TT
 166 >. The use of this is
 167 controlled by <TT
 168 CLASS="LITERAL"
 169 >CYGPKG_NS_DNS_DEFAULT</TT
 170 >. If this is
 171 enabled, <TT
 172 CLASS="LITERAL"
 173 >init_all_network_interfaces</TT
 174 > will
 175 initialize the resolver with the hard coded address. The DHCP client
 176 or user code my override this address by calling
 177 <TT
 178 CLASS="LITERAL"
 179 >cyg_dns_res_init</TT
 180 > again. </P
 181 ><P
 182 >The DNS client understands the concepts of the target being
 183 in a domain. By default no domain will be used. Host name lookups
 184 should be for fully qualified names. The domain name can be set
 185 and retrieved using the functions:
 186 <DIV
 187 CLASS="FUNCSYNOPSIS"
 188 ><A
 189 NAME="AEN14685"><P
 190 ></P
 191 ><P
 192 ><CODE
 193 ><CODE
 194 CLASS="FUNCDEF"
 195 >int getdomainname</CODE
 196 >(char *name, size_t len);</CODE
 197 ></P
 198 ><P
 199 ><CODE
 200 ><CODE
 201 CLASS="FUNCDEF"
 202 >int setdomainname</CODE
 203 >(const char *name, size_t len);</CODE
 204 ></P
 205 ><P
 206 ></P
 207 ></DIV
 208 ></P
 209 ><P
 210 >Alternatively, a hard coded domain name can be set using CDL.
 211 The boolean <TT
 212 CLASS="LITERAL"
 213 >CYGPKG_NS_DNS_DOMAINNAME</TT
 214 > enables this
 215 and the domain name is taken from
 216 <TT
 217 CLASS="LITERAL"
 218 >CYGPKG_NS_DNS_DOMAINNAME_NAME</TT
 219 >.</P
 220 ><P
 221 >Once set, the DNS client will first perform a lookup with the domain
 222 name appended. If this fails it will then perform a second lookup
 223 without the appended domain name. </P
 224 ></DIV
 225 ></DIV
 226 ><DIV
 227 CLASS="NAVFOOTER"
 228 ><HR
 229 ALIGN="LEFT"
 230 WIDTH="100%"><TABLE
 231 SUMMARY="Footer navigation table"
 232 WIDTH="100%"
 233 BORDER="0"
 234 CELLPADDING="0"
 235 CELLSPACING="0"
 236 ><TR
 237 ><TD
 238 WIDTH="33%"
 239 ALIGN="left"
 240 VALIGN="top"
 241 ><A
 242 HREF="net-ns-dns.html"
 243 ACCESSKEY="P"
 244 >Prev</A
 245 ></TD
 246 ><TD
 247 WIDTH="34%"
 248 ALIGN="center"
 249 VALIGN="top"
 250 ><A
 251 HREF="ecos-ref.html"
 252 ACCESSKEY="H"
 253 >Home</A
 254 ></TD
 255 ><TD
 256 WIDTH="33%"
 257 ALIGN="right"
 258 VALIGN="top"
 259 ><A
 260 HREF="io-eth-drv-generic.html"
 261 ACCESSKEY="N"
 262 >Next</A
 263 ></TD
 264 ></TR
 265 ><TR
 266 ><TD
 267 WIDTH="33%"
 268 ALIGN="left"
 269 VALIGN="top"
 270 >DNS for eCos and RedBoot</TD
 271 ><TD
 272 WIDTH="34%"
 273 ALIGN="center"
 274 VALIGN="top"
 275 ><A
 276 HREF="net-ns-dns.html"
 277 ACCESSKEY="U"
 278 >Up</A
 279 ></TD
 280 ><TD
 281 WIDTH="33%"
 282 ALIGN="right"
 283 VALIGN="top"
 284 >Ethernet Device Drivers</TD
 285 ></TR
 286 ></TABLE
 287 ></DIV
 288 ></BODY
 289 ></HTML
 290 >