contrib/bind-9.2.4rc7/lib/lwres/man/lwres_getipnode.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001, 2003  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: lwres_getipnode.html,v 1.7.2.2 2004/03/15 04:45:02 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_getipnode</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres_getipnode</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent&nbsp;--&nbsp;lightweight resolver nodename / address translation API</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN13"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN14"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/netdb.h&gt;</PRE
  65 ><P
  66 ><CODE
  67 ><CODE
  68 CLASS="FUNCDEF"
  69 >struct hostent *
  70 lwres_getipnodebyname</CODE
  71 >(const char *name, int af, int flags, int *error_num);</CODE
  72 ></P
  73 ><P
  74 ><CODE
  75 ><CODE
  76 CLASS="FUNCDEF"
  77 >struct hostent *
  78 lwres_getipnodebyaddr</CODE
  79 >(const void *src, size_t len, int af, int *error_num);</CODE
  80 ></P
  81 ><P
  82 ><CODE
  83 ><CODE
  84 CLASS="FUNCDEF"
  85 >void
  86 lwres_freehostent</CODE
  87 >(struct hostent *he);</CODE
  88 ></P
  89 ><P
  90 ></P
  91 ></DIV
  92 ></DIV
  93 ><DIV
  94 CLASS="REFSECT1"
  95 ><A
  96 NAME="AEN34"
  97 ></A
  98 ><H2
  99 >DESCRIPTION</H2
 100 ><P
 101 >These functions perform thread safe, protocol independent
 102 nodename-to-address and address-to-nodename
 103 translation as defined in RFC2553.</P
 104 ><P
 105 >They use a
 106 <SPAN
 107 CLASS="TYPE"
 108 >struct hostent</SPAN
 109 >
 110 which is defined in
 111 <TT
 112 CLASS="FILENAME"
 113 >namedb.h</TT
 114 >:
 115 <PRE
 116 CLASS="PROGRAMLISTING"
 117 >struct  hostent {
 118         char    *h_name;        /* official name of host */
 119         char    **h_aliases;    /* alias list */
 120         int     h_addrtype;     /* host address type */
 121         int     h_length;       /* length of address */
 122         char    **h_addr_list;  /* list of addresses from name server */
 123 };
 124 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */</PRE
 125 ></P
 126 ><P
 127 >The members of this structure are:
 128 <P
 129 ></P
 130 ><DIV
 131 CLASS="VARIABLELIST"
 132 ><DL
 133 ><DT
 134 ><TT
 135 CLASS="CONSTANT"
 136 >h_name</TT
 137 ></DT
 138 ><DD
 139 ><P
 140 >The official (canonical) name of the host.</P
 141 ></DD
 142 ><DT
 143 ><TT
 144 CLASS="CONSTANT"
 145 >h_aliases</TT
 146 ></DT
 147 ><DD
 148 ><P
 149 >A NULL-terminated array of alternate names (nicknames) for the host.</P
 150 ></DD
 151 ><DT
 152 ><TT
 153 CLASS="CONSTANT"
 154 >h_addrtype</TT
 155 ></DT
 156 ><DD
 157 ><P
 158 >The type of address being returned - usually
 159 <SPAN
 160 CLASS="TYPE"
 161 >PF_INET</SPAN
 162 >
 163 or
 164 <SPAN
 165 CLASS="TYPE"
 166 >PF_INET6</SPAN
 167 >.&#13;</P
 168 ></DD
 169 ><DT
 170 ><TT
 171 CLASS="CONSTANT"
 172 >h_length</TT
 173 ></DT
 174 ><DD
 175 ><P
 176 >The length of the address in bytes.</P
 177 ></DD
 178 ><DT
 179 ><TT
 180 CLASS="CONSTANT"
 181 >h_addr_list</TT
 182 ></DT
 183 ><DD
 184 ><P
 185 >A
 186 <SPAN
 187 CLASS="TYPE"
 188 >NULL</SPAN
 189 >
 190 terminated array of network addresses for the host.
 191 Host addresses are returned in network byte order.</P
 192 ></DD
 193 ></DL
 194 ></DIV
 195 ></P
 196 ><P
 197 ><TT
 198 CLASS="FUNCTION"
 199 >lwres_getipnodebyname()</TT
 200 >
 201 looks up addresses of protocol family
 202 <TT
 203 CLASS="PARAMETER"
 204 ><I
 205 >af</I
 206 ></TT
 207 >
 208
 209 for the hostname
 210 <TT
 211 CLASS="PARAMETER"
 212 ><I
 213 >name</I
 214 ></TT
 215 >.
 216
 217 The
 218 <TT
 219 CLASS="PARAMETER"
 220 ><I
 221 >flags</I
 222 ></TT
 223 >
 224 parameter contains ORed flag bits to
 225 specify the types of addresses that are searched
 226 for, and the types of addresses that are returned.
 227 The flag bits are:
 228 <P
 229 ></P
 230 ><DIV
 231 CLASS="VARIABLELIST"
 232 ><DL
 233 ><DT
 234 ><TT
 235 CLASS="CONSTANT"
 236 >AI_V4MAPPED</TT
 237 ></DT
 238 ><DD
 239 ><P
 240 >This is used with an
 241 <TT
 242 CLASS="PARAMETER"
 243 ><I
 244 >af</I
 245 ></TT
 246 >
 247 of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
 248 IPv6 addresses.</P
 249 ></DD
 250 ><DT
 251 ><TT
 252 CLASS="CONSTANT"
 253 >AI_ALL</TT
 254 ></DT
 255 ><DD
 256 ><P
 257 >This is used with an
 258 <TT
 259 CLASS="PARAMETER"
 260 ><I
 261 >af</I
 262 ></TT
 263 >
 264 of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
 265 If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
 266 IPv6 addresses.</P
 267 ></DD
 268 ><DT
 269 ><TT
 270 CLASS="CONSTANT"
 271 >AI_ADDRCONFIG</TT
 272 ></DT
 273 ><DD
 274 ><P
 275 >Only return an IPv6 or IPv4 address if here is an active network
 276 interface of that type.  This is not currently implemented
 277 in the BIND 9 lightweight resolver, and the flag is ignored.</P
 278 ></DD
 279 ><DT
 280 ><TT
 281 CLASS="CONSTANT"
 282 >AI_DEFAULT</TT
 283 ></DT
 284 ><DD
 285 ><P
 286 >This default sets the
 287 <TT
 288 CLASS="CONSTANT"
 289 >AI_V4MAPPED</TT
 290 >
 291 and
 292 <TT
 293 CLASS="CONSTANT"
 294 >AI_ADDRCONFIG</TT
 295 >
 296 flag bits.</P
 297 ></DD
 298 ></DL
 299 ></DIV
 300 ></P
 301 ><P
 302 ><TT
 303 CLASS="FUNCTION"
 304 >lwres_getipnodebyaddr()</TT
 305 >
 306 performs a reverse lookup
 307 of address
 308 <TT
 309 CLASS="PARAMETER"
 310 ><I
 311 >src</I
 312 ></TT
 313 >
 314 which is
 315 <TT
 316 CLASS="PARAMETER"
 317 ><I
 318 >len</I
 319 ></TT
 320 >
 321 bytes long.
 322 <TT
 323 CLASS="PARAMETER"
 324 ><I
 325 >af</I
 326 ></TT
 327 >
 328 denotes the protocol family, typically
 329 <SPAN
 330 CLASS="TYPE"
 331 >PF_INET</SPAN
 332 >
 333 or
 334 <SPAN
 335 CLASS="TYPE"
 336 >PF_INET6</SPAN
 337 >.&#13;</P
 338 ><P
 339 ><TT
 340 CLASS="FUNCTION"
 341 >lwres_freehostent()</TT
 342 >
 343 releases all the memory associated with
 344 the
 345 <SPAN
 346 CLASS="TYPE"
 347 >struct hostent</SPAN
 348 >
 349 pointer
 350 <TT
 351 CLASS="PARAMETER"
 352 ><I
 353 >he</I
 354 ></TT
 355 >.
 356
 357 Any memory allocated for the
 358 <TT
 359 CLASS="CONSTANT"
 360 >h_name</TT
 361 >,
 362
 363 <TT
 364 CLASS="CONSTANT"
 365 >h_addr_list</TT
 366 >
 367 and
 368 <TT
 369 CLASS="CONSTANT"
 370 >h_aliases</TT
 371 >
 372 is freed, as is the memory for the
 373 <SPAN
 374 CLASS="TYPE"
 375 >hostent</SPAN
 376 >
 377 structure itself.</P
 378 ></DIV
 379 ><DIV
 380 CLASS="REFSECT1"
 381 ><A
 382 NAME="AEN116"
 383 ></A
 384 ><H2
 385 >RETURN VALUES</H2
 386 ><P
 387 >If an error occurs,
 388 <TT
 389 CLASS="FUNCTION"
 390 >lwres_getipnodebyname()</TT
 391 >
 392 and
 393 <TT
 394 CLASS="FUNCTION"
 395 >lwres_getipnodebyaddr()</TT
 396 >
 397 set
 398 <TT
 399 CLASS="PARAMETER"
 400 ><I
 401 >*error_num</I
 402 ></TT
 403 >
 404 to an appropriate error code and the function returns a
 405 <SPAN
 406 CLASS="TYPE"
 407 >NULL</SPAN
 408 >
 409 pointer.
 410 The error codes and their meanings are defined in
 411 <TT
 412 CLASS="FILENAME"
 413 >&lt;lwres/netdb.h&gt;</TT
 414 >:
 415 <P
 416 ></P
 417 ><DIV
 418 CLASS="VARIABLELIST"
 419 ><DL
 420 ><DT
 421 ><TT
 422 CLASS="CONSTANT"
 423 >HOST_NOT_FOUND</TT
 424 ></DT
 425 ><DD
 426 ><P
 427 >No such host is known.</P
 428 ></DD
 429 ><DT
 430 ><TT
 431 CLASS="CONSTANT"
 432 >NO_ADDRESS</TT
 433 ></DT
 434 ><DD
 435 ><P
 436 >The server recognised the request and the name but no address is
 437 available.  Another type of request to the name server for the
 438 domain might return an answer.</P
 439 ></DD
 440 ><DT
 441 ><TT
 442 CLASS="CONSTANT"
 443 >TRY_AGAIN</TT
 444 ></DT
 445 ><DD
 446 ><P
 447 >A temporary and possibly transient error occurred, such as a
 448 failure of a server to respond.  The request may succeed if
 449 retried.</P
 450 ></DD
 451 ><DT
 452 ><TT
 453 CLASS="CONSTANT"
 454 >NO_RECOVERY</TT
 455 ></DT
 456 ><DD
 457 ><P
 458 >An unexpected failure occurred, and retrying the request
 459 is pointless.</P
 460 ></DD
 461 ></DL
 462 ></DIV
 463 ></P
 464 ><P
 465 ><SPAN
 466 CLASS="CITEREFENTRY"
 467 ><SPAN
 468 CLASS="REFENTRYTITLE"
 469 >lwres_hstrerror</SPAN
 470 >(3)</SPAN
 471 >
 472 translates these error codes to suitable error messages.</P
 473 ></DIV
 474 ><DIV
 475 CLASS="REFSECT1"
 476 ><A
 477 NAME="AEN149"
 478 ></A
 479 ><H2
 480 >SEE ALSO</H2
 481 ><P
 482 ><SPAN
 483 CLASS="CITEREFENTRY"
 484 ><SPAN
 485 CLASS="REFENTRYTITLE"
 486 >RFC2553</SPAN
 487 ></SPAN
 488 >,
 489
 490 <SPAN
 491 CLASS="CITEREFENTRY"
 492 ><SPAN
 493 CLASS="REFENTRYTITLE"
 494 >lwres</SPAN
 495 >(3)</SPAN
 496 >,
 497
 498 <SPAN
 499 CLASS="CITEREFENTRY"
 500 ><SPAN
 501 CLASS="REFENTRYTITLE"
 502 >lwres_gethostent</SPAN
 503 >(3)</SPAN
 504 >,
 505
 506 <SPAN
 507 CLASS="CITEREFENTRY"
 508 ><SPAN
 509 CLASS="REFENTRYTITLE"
 510 >lwres_getaddrinfo</SPAN
 511 >(3)</SPAN
 512 >,
 513
 514 <SPAN
 515 CLASS="CITEREFENTRY"
 516 ><SPAN
 517 CLASS="REFENTRYTITLE"
 518 >lwres_getnameinfo</SPAN
 519 >(3)</SPAN
 520 >,
 521
 522 <SPAN
 523 CLASS="CITEREFENTRY"
 524 ><SPAN
 525 CLASS="REFENTRYTITLE"
 526 >lwres_hstrerror</SPAN
 527 >(3)</SPAN
 528 >.</P
 529 ></DIV
 530 ></BODY
 531 ></HTML
 532 >