/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 322 lines · 289 code · 16 blank · 17 comment · 0 complexity · 3ce1a0c80ebd0476ae9c3d989ef9379c MD5 · raw file 

    

  1. <!--
    2. 

  2.  - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
    3. 

  3.  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
    4. 

  4.  - 
    5. 

  5.  - Permission to use, copy, modify, and/or distribute this software for any
    6. 

  6.  - purpose with or without fee is hereby granted, provided that the above
    7. 

  7.  - copyright notice and this permission notice appear in all copies.
    8. 

  8.  - 
    9. 

  9.  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
    10. 

  10.  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
    11. 

  11.  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
    12. 

  12.  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
    13. 

  13.  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
    14. 

  14.  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
    15. 

  15.  - PERFORMANCE OF THIS SOFTWARE.
    16. 

  16. -->
    17. 

  17. <!-- $Id$ -->
    18. 

  18. <html>
    19. 

  19. <head>
    20. 

  20. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    21. 

  21. <title>lwres_getaddrinfo</title>
    22. 

  22. <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
    23. 

  23. </head>
    24. 

  24. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
    25. 

  25. <a name="id2476275"></a><div class="titlepage"></div>
    26. 

  26. <div class="refnamediv">
    27. 

  27. <h2>Name</h2>
    28. 

  28. <p>lwres_getaddrinfo, lwres_freeaddrinfo &#8212; socket address structure to host and service name</p>
    29. 

  29. </div>
    30. 

  30. <div class="refsynopsisdiv">
    31. 

  31. <h2>Synopsis</h2>
    32. 

  32. <div class="funcsynopsis">
    33. 

  33. <pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
    34. 

  34. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
    35. 

  35. <tr>
    36. 

  36. <td><code class="funcdef">
    37. 

  37. int
    38. 

  38. <b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
    39. 

  39. <td>const char * </td>
    40. 

  40. <td>
    41. 

  41. <var class="pdparam">hostname</var>, </td>
    42. 

  42. </tr>
    43. 

  43. <tr>
    44. 

  44. <td> </td>
    45. 

  45. <td>const char * </td>
    46. 

  46. <td>
    47. 

  47. <var class="pdparam">servname</var>, </td>
    48. 

  48. </tr>
    49. 

  49. <tr>
    50. 

  50. <td> </td>
    51. 

  51. <td>const struct addrinfo * </td>
    52. 

  52. <td>
    53. 

  53. <var class="pdparam">hints</var>, </td>
    54. 

  54. </tr>
    55. 

  55. <tr>
    56. 

  56. <td> </td>
    57. 

  57. <td>struct addrinfo ** </td>
    58. 

  58. <td>
    59. 

  59. <var class="pdparam">res</var><code>)</code>;</td>
    60. 

  60. </tr>
    61. 

  61. </table>
    62. 

  62. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
    63. 

  63. <td><code class="funcdef">
    64. 

  64. void
    65. 

  65. <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
    66. 

  66. <td>struct addrinfo * </td>
    67. 

  67. <td>
    68. 

  68. <var class="pdparam">ai</var><code>)</code>;</td>
    69. 

  69. </tr></table>
    70. 

  70. </div>
    71. 

  71. <p>
    72. 

  72.       If the operating system does not provide a
    73. 

  73.       <span class="type">struct addrinfo</span>,
    74. 

  74.       the following structure is used:
    75. 

  75.     </p>
    76. 

  76. <pre class="programlisting">
    77. 

  77. struct  addrinfo {
    78. 

  78.         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
    79. 

  79.         int             ai_family;      /* PF_xxx */
    80. 

  80.         int             ai_socktype;    /* SOCK_xxx */
    81. 

  81.         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
    82. 

  82.         size_t          ai_addrlen;     /* length of ai_addr */
    83. 

  83.         char            *ai_canonname;  /* canonical name for hostname */
    84. 

  84.         struct sockaddr *ai_addr;       /* binary address */
    85. 

  85.         struct addrinfo *ai_next;       /* next structure in linked list */
    86. 

  86. };
    87. 

  87. </pre>
    88. 

  88. <p>
    89. 

  89.     </p>
    90. 

  90. </div>
    91. 

  91. <div class="refsect1" lang="en">
    92. 

  92. <a name="id2543416"></a><h2>DESCRIPTION</h2>
    93. 

  93. <p><code class="function">lwres_getaddrinfo()</code>
    94. 

  94.       is used to get a list of IP addresses and port numbers for host
    95. 

  95.       <em class="parameter"><code>hostname</code></em> and service
    96. 

  96.       <em class="parameter"><code>servname</code></em>.
    97. 

  97. 

  98.       The function is the lightweight resolver's implementation of
    99. 

  99.       <code class="function">getaddrinfo()</code> as defined in RFC2133.
    100. 

  100.       <em class="parameter"><code>hostname</code></em> and
    101. 

  101.       <em class="parameter"><code>servname</code></em> are pointers to null-terminated
    102. 

  102.       strings or <span class="type">NULL</span>.
    103. 

  103. 

  104.       <em class="parameter"><code>hostname</code></em> is either a host name or a
    105. 

  105.       numeric host address string: a dotted decimal IPv4 address or an
    106. 

  106.       IPv6 address.  <em class="parameter"><code>servname</code></em> is either a
    107. 

  107.       decimal port number or a service name as listed in
    108. 

  108.       <code class="filename">/etc/services</code>.
    109. 

  109.     </p>
    110. 

  110. <p><em class="parameter"><code>hints</code></em>
    111. 

  111.       is an optional pointer to a
    112. 

  112.       <span class="type">struct addrinfo</span>.
    113. 

  113.       This structure can be used to provide hints concerning the type of
    114. 

  114.       socket
    115. 

  115.       that the caller supports or wishes to use.
    116. 

  116.       The caller can supply the following structure elements in
    117. 

  117.       <em class="parameter"><code>*hints</code></em>:
    118. 

  118. 

  119.       </p>
    120. 

  120. <div class="variablelist"><dl>
    121. 

  121. <dt><span class="term"><code class="constant">ai_family</code></span></dt>
    122. 

  122. <dd><p>
    123. 

  123.               The protocol family that should be used.
    124. 

  124.               When
    125. 

  125.               <code class="constant">ai_family</code>
    126. 

  126.               is set to
    127. 

  127.               <span class="type">PF_UNSPEC</span>,
    128. 

  128.               it means the caller will accept any protocol family supported by
    129. 

  129.               the
    130. 

  130.               operating system.
    131. 

  131.             </p></dd>
    132. 

  132. <dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
    133. 

  133. <dd><p>
    134. 

  134.               denotes the type of socket &#8212;
    135. 

  135.               <span class="type">SOCK_STREAM</span>,
    136. 

  136.               <span class="type">SOCK_DGRAM</span>
    137. 

  137.               or
    138. 

  138.               <span class="type">SOCK_RAW</span>
    139. 

  139.               &#8212; that is wanted.
    140. 

  140.               When
    141. 

  141.               <code class="constant">ai_socktype</code>
    142. 

  142.               is zero the caller will accept any socket type.
    143. 

  143.             </p></dd>
    144. 

  144. <dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
    145. 

  145. <dd><p>
    146. 

  146.               indicates which transport protocol is wanted: IPPROTO_UDP or
    147. 

  147.               IPPROTO_TCP.
    148. 

  148.               If
    149. 

  149.               <code class="constant">ai_protocol</code>
    150. 

  150.               is zero the caller will accept any protocol.
    151. 

  151.             </p></dd>
    152. 

  152. <dt><span class="term"><code class="constant">ai_flags</code></span></dt>
    153. 

  153. <dd>
    154. 

  154. <p>
    155. 

  155.               Flag bits.
    156. 

  156.               If the
    157. 

  157.               <span class="type">AI_CANONNAME</span>
    158. 

  158.               bit is set, a successful call to
    159. 

  159.               <code class="function">lwres_getaddrinfo()</code>
    160. 

  160.               will return a null-terminated string containing the canonical
    161. 

  161.               name
    162. 

  162.               of the specified hostname in
    163. 

  163.               <code class="constant">ai_canonname</code>
    164. 

  164.               of the first
    165. 

  165.               <span class="type">addrinfo</span>
    166. 

  166.               structure returned.
    167. 

  167.               Setting the
    168. 

  168.               <span class="type">AI_PASSIVE</span>
    169. 

  169.               bit indicates that the returned socket address structure is
    170. 

  170.               intended
    171. 

  171.               for used in a call to
    172. 

  172.               <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
    173. 

  173. 

  174.               In this case, if the hostname argument is a
    175. 

  175.               <span class="type">NULL</span>
    176. 

  176.               pointer, then the IP address portion of the socket
    177. 

  177.               address structure will be set to
    178. 

  178.               <span class="type">INADDR_ANY</span>
    179. 

  179.               for an IPv4 address or
    180. 

  180.               <span class="type">IN6ADDR_ANY_INIT</span>
    181. 

  181.               for an IPv6 address.
    182. 

  182.             </p>
    183. 

  183. <p>
    184. 

  184.               When
    185. 

  185.               <code class="constant">ai_flags</code>
    186. 

  186.               does not set the
    187. 

  187.               <span class="type">AI_PASSIVE</span>
    188. 

  188.               bit, the returned socket address structure will be ready
    189. 

  189.               for use in a call to
    190. 

  190.               <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>
    191. 

  191.               for a connection-oriented protocol or
    192. 

  192.               <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
    193. 

  193. 

  194.               <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
    195. 

  195. 

  196.               or
    197. 

  197.               <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>
    198. 

  198.               if a connectionless protocol was chosen.
    199. 

  199.               The IP address portion of the socket address structure will be
    200. 

  200.               set to the loopback address if
    201. 

  201.               <em class="parameter"><code>hostname</code></em>
    202. 

  202.               is a
    203. 

  203.               <span class="type">NULL</span>
    204. 

  204.               pointer and
    205. 

  205.               <span class="type">AI_PASSIVE</span>
    206. 

  206.               is not set in
    207. 

  207.               <code class="constant">ai_flags</code>.
    208. 

  208.             </p>
    209. 

  209. <p>
    210. 

  210.               If
    211. 

  211.               <code class="constant">ai_flags</code>
    212. 

  212.               is set to
    213. 

  213.               <span class="type">AI_NUMERICHOST</span>
    214. 

  214.               it indicates that
    215. 

  215.               <em class="parameter"><code>hostname</code></em>
    216. 

  216.               should be treated as a numeric string defining an IPv4 or IPv6
    217. 

  217.               address
    218. 

  218.               and no name resolution should be attempted.
    219. 

  219.             </p>
    220. 

  220. </dd>
    221. 

  221. </dl></div>
    222. 

  222. <p>
    223. 

  223.     </p>
    224. 

  224. <p>
    225. 

  225.       All other elements of the <span class="type">struct addrinfo</span> passed
    226. 

  226.       via <em class="parameter"><code>hints</code></em> must be zero.
    227. 

  227.     </p>
    228. 

  228. <p>
    229. 

  229.       A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
    230. 

  230.       treated as if
    231. 

  231.       the caller provided a <span class="type">struct addrinfo</span> initialized to zero
    232. 

  232.       with <code class="constant">ai_family</code>set to
    233. 

  233.       <code class="constant">PF_UNSPEC</code>.
    234. 

  234.     </p>
    235. 

  235. <p>
    236. 

  236.       After a successful call to
    237. 

  237.       <code class="function">lwres_getaddrinfo()</code>,
    238. 

  238.       <em class="parameter"><code>*res</code></em>
    239. 

  239.       is a pointer to a linked list of one or more
    240. 

  240.       <span class="type">addrinfo</span>
    241. 

  241.       structures.
    242. 

  242.       Each
    243. 

  243.       <span class="type">struct addrinfo</span>
    244. 

  244.       in this list cn be processed by following
    245. 

  245.       the
    246. 

  246.       <code class="constant">ai_next</code>
    247. 

  247.       pointer, until a
    248. 

  248.       <span class="type">NULL</span>
    249. 

  249.       pointer is encountered.
    250. 

  250.       The three members
    251. 

  251.       <code class="constant">ai_family</code>,
    252. 

  252.       <code class="constant">ai_socktype</code>,
    253. 

  253.       and
    254. 

  254.       <code class="constant">ai_protocol</code>
    255. 

  255.       in each
    256. 

  256.       returned
    257. 

  257.       <span class="type">addrinfo</span>
    258. 

  258.       structure contain the corresponding arguments for a call to
    259. 

  259.       <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
    260. 

  260.       For each
    261. 

  261.       <span class="type">addrinfo</span>
    262. 

  262.       structure in the list, the
    263. 

  263.       <code class="constant">ai_addr</code>
    264. 

  264.       member points to a filled-in socket address structure of length
    265. 

  265.       <code class="constant">ai_addrlen</code>.
    266. 

  266.     </p>
    267. 

  267. <p>
    268. 

  268.       All of the information returned by
    269. 

  269.       <code class="function">lwres_getaddrinfo()</code>
    270. 

  270.       is dynamically allocated: the addrinfo structures, and the socket
    271. 

  271.       address structures and canonical host name strings pointed to by the
    272. 

  272.       <code class="constant">addrinfo</code>structures.
    273. 

  273.       Memory allocated for the dynamically allocated structures created by
    274. 

  274.       a successful call to
    275. 

  275.       <code class="function">lwres_getaddrinfo()</code>
    276. 

  276.       is released by
    277. 

  277.       <code class="function">lwres_freeaddrinfo()</code>.
    278. 

  278.       <em class="parameter"><code>ai</code></em>
    279. 

  279.       is a pointer to a
    280. 

  280.       <span class="type">struct addrinfo</span>
    281. 

  281.       created by a call to
    282. 

  282.       <code class="function">lwres_getaddrinfo()</code>.
    283. 

  283.     </p>
    284. 

  284. </div>
    285. 

  285. <div class="refsect1" lang="en">
    286. 

  286. <a name="id2543794"></a><h2>RETURN VALUES</h2>
    287. 

  287. <p><code class="function">lwres_getaddrinfo()</code>
    288. 

  288.       returns zero on success or one of the error codes listed in
    289. 

  289.       <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3)</span>
    290. 

  290.       if an error occurs.  If both <em class="parameter"><code>hostname</code></em> and
    291. 

  291.       <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
    292. 

  292.       <code class="function">lwres_getaddrinfo()</code> returns
    293. 

  293.       <span class="errorcode">EAI_NONAME</span>.
    294. 

  294.     </p>
    295. 

  295. </div>
    296. 

  296. <div class="refsect1" lang="en">
    297. 

  297. <a name="id2543831"></a><h2>SEE ALSO</h2>
    298. 

  298. <p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
    299. 

  299. 

  300.       <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
    301. 

  301. 

  302.       <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
    303. 

  303. 

  304.       <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
    305. 

  305. 

  306.       <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
    307. 

  307. 

  308.       <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
    309. 

  309. 

  310.       <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>,
    311. 

  311. 

  312.       <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
    313. 

  313. 

  314.       <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
    315. 

  315. 

  316.       <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>,
    317. 

  317. 

  318.       <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
    319. 

  319.     </p>
    320. 

  320. </div>
    321. 

  321. </div></body>
    322. 

  322. </html>
    323.