/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 206 lines · 196 code · 10 blank · 0 comment · 0 complexity · 60b96e811a1a954221b3fd80800e7103 MD5 · raw file

  1. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  2. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
  3. [<!ENTITY mdash "&#8212;">]>
  4. <!--
  5. - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  6. - Copyright (C) 2000, 2001 Internet Software Consortium.
  7. -
  8. - Permission to use, copy, modify, and/or distribute this software for any
  9. - purpose with or without fee is hereby granted, provided that the above
  10. - copyright notice and this permission notice appear in all copies.
  11. -
  12. - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13. - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14. - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15. - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16. - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17. - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18. - PERFORMANCE OF THIS SOFTWARE.
  19. -->
  20. <!-- $Id$ -->
  21. <refentry>
  22. <refentryinfo>
  23. <date>Jun 30, 2000</date>
  24. </refentryinfo>
  25. <refmeta>
  26. <refentrytitle>lwres_getnameinfo</refentrytitle>
  27. <manvolnum>3</manvolnum>
  28. <refmiscinfo>BIND9</refmiscinfo>
  29. </refmeta>
  30. <docinfo>
  31. <copyright>
  32. <year>2004</year>
  33. <year>2005</year>
  34. <year>2007</year>
  35. <year>2012</year>
  36. <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  37. </copyright>
  38. <copyright>
  39. <year>2000</year>
  40. <year>2001</year>
  41. <holder>Internet Software Consortium.</holder>
  42. </copyright>
  43. </docinfo>
  44. <refnamediv>
  45. <refname>lwres_getnameinfo</refname>
  46. <refpurpose>lightweight resolver socket address structure to hostname and
  47. service name
  48. </refpurpose>
  49. </refnamediv>
  50. <refsynopsisdiv>
  51. <funcsynopsis>
  52. <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  53. <funcprototype>
  54. <funcdef>
  55. int
  56. <function>lwres_getnameinfo</function></funcdef>
  57. <paramdef>const struct sockaddr *<parameter>sa</parameter></paramdef>
  58. <paramdef>size_t <parameter>salen</parameter></paramdef>
  59. <paramdef>char *<parameter>host</parameter></paramdef>
  60. <paramdef>size_t <parameter>hostlen</parameter></paramdef>
  61. <paramdef>char *<parameter>serv</parameter></paramdef>
  62. <paramdef>size_t <parameter>servlen</parameter></paramdef>
  63. <paramdef>int <parameter>flags</parameter></paramdef>
  64. </funcprototype>
  65. </funcsynopsis>
  66. </refsynopsisdiv>
  67. <refsect1>
  68. <title>DESCRIPTION</title>
  69. <para>
  70. This function is equivalent to the
  71. <citerefentry>
  72. <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
  73. </citerefentry> function defined in RFC2133.
  74. <function>lwres_getnameinfo()</function> returns the
  75. hostname for the
  76. <type>struct sockaddr</type> <parameter>sa</parameter> which
  77. is
  78. <parameter>salen</parameter> bytes long. The hostname is of
  79. length
  80. <parameter>hostlen</parameter> and is returned via
  81. <parameter>*host.</parameter> The maximum length of the
  82. hostname is
  83. 1025 bytes: <constant>NI_MAXHOST</constant>.
  84. </para>
  85. <para> The name of the service associated with the port number in
  86. <parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
  87. It is <parameter>servlen</parameter> bytes long. The
  88. maximum length
  89. of the service name is <constant>NI_MAXSERV</constant> - 32
  90. bytes.
  91. </para>
  92. <para>
  93. The <parameter>flags</parameter> argument sets the
  94. following
  95. bits:
  96. <variablelist>
  97. <varlistentry>
  98. <term><constant>NI_NOFQDN</constant></term>
  99. <listitem>
  100. <para>
  101. A fully qualified domain name is not required for local hosts.
  102. The local part of the fully qualified domain name is returned
  103. instead.
  104. </para>
  105. </listitem>
  106. </varlistentry>
  107. <varlistentry>
  108. <term><constant>NI_NUMERICHOST</constant></term>
  109. <listitem>
  110. <para>
  111. Return the address in numeric form, as if calling inet_ntop(),
  112. instead of a host name.
  113. </para>
  114. </listitem>
  115. </varlistentry>
  116. <varlistentry>
  117. <term><constant>NI_NAMEREQD</constant></term>
  118. <listitem>
  119. <para>
  120. A name is required. If the hostname cannot be found in the DNS
  121. and
  122. this flag is set, a non-zero error code is returned.
  123. If the hostname is not found and the flag is not set, the
  124. address is returned in numeric form.
  125. </para>
  126. </listitem>
  127. </varlistentry>
  128. <varlistentry>
  129. <term><constant>NI_NUMERICSERV</constant></term>
  130. <listitem>
  131. <para>
  132. The service name is returned as a digit string representing the
  133. port number.
  134. </para>
  135. </listitem>
  136. </varlistentry>
  137. <varlistentry>
  138. <term><constant>NI_DGRAM</constant></term>
  139. <listitem>
  140. <para>
  141. Specifies that the service being looked up is a datagram
  142. service, and causes getservbyport() to be called with a second
  143. argument of "udp" instead of its default of "tcp". This is
  144. required
  145. for the few ports (512-514) that have different services for UDP
  146. and
  147. TCP.
  148. </para>
  149. </listitem>
  150. </varlistentry>
  151. </variablelist>
  152. </para>
  153. </refsect1>
  154. <refsect1>
  155. <title>RETURN VALUES</title>
  156. <para><function>lwres_getnameinfo()</function>
  157. returns 0 on success or a non-zero error code if an error occurs.
  158. </para>
  159. </refsect1>
  160. <refsect1>
  161. <title>SEE ALSO</title>
  162. <para><citerefentry>
  163. <refentrytitle>RFC2133</refentrytitle>
  164. </citerefentry>,
  165. <citerefentry>
  166. <refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
  167. </citerefentry>,
  168. <citerefentry>
  169. <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
  170. </citerefentry>,
  171. <citerefentry>
  172. <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
  173. </citerefentry>,
  174. <citerefentry>
  175. <refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
  176. </citerefentry>.
  177. <citerefentry>
  178. <refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
  179. </citerefentry>.
  180. </para>
  181. </refsect1>
  182. <refsect1>
  183. <title>BUGS</title>
  184. <para>
  185. RFC2133 fails to define what the nonzero return values of
  186. <citerefentry>
  187. <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
  188. </citerefentry>
  189. are.
  190. </para>
  191. </refsect1>
  192. </refentry><!--
  193. - Local variables:
  194. - mode: sgml
  195. - End:
  196. -->