lib/liblwres/man/lwres_getipnode.html

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