PageRenderTime 54ms CodeModel.GetById 42ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 1ms

/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
 21<!-- $Id$ -->
 22<refentry>
 23
 24  <refentryinfo>
 25    <date>Jun 30, 2000</date>
 26  </refentryinfo>
 27
 28  <refmeta>
 29    <refentrytitle>lwres_getnameinfo</refentrytitle>
 30    <manvolnum>3</manvolnum>
 31    <refmiscinfo>BIND9</refmiscinfo>
 32  </refmeta>
 33
 34  <docinfo>
 35    <copyright>
 36      <year>2004</year>
 37      <year>2005</year>
 38      <year>2007</year>
 39      <year>2012</year>
 40      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 41    </copyright>
 42    <copyright>
 43      <year>2000</year>
 44      <year>2001</year>
 45      <holder>Internet Software Consortium.</holder>
 46    </copyright>
 47  </docinfo>
 48
 49  <refnamediv>
 50    <refname>lwres_getnameinfo</refname>
 51    <refpurpose>lightweight resolver socket address structure to hostname and
 52      service name
 53    </refpurpose>
 54  </refnamediv>
 55  <refsynopsisdiv>
 56    <funcsynopsis>
 57<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
 58<funcprototype>
 59        <funcdef>
 60int
 61<function>lwres_getnameinfo</function></funcdef>
 62        <paramdef>const struct sockaddr *<parameter>sa</parameter></paramdef>
 63        <paramdef>size_t <parameter>salen</parameter></paramdef>
 64        <paramdef>char *<parameter>host</parameter></paramdef>
 65        <paramdef>size_t <parameter>hostlen</parameter></paramdef>
 66        <paramdef>char *<parameter>serv</parameter></paramdef>
 67        <paramdef>size_t <parameter>servlen</parameter></paramdef>
 68        <paramdef>int <parameter>flags</parameter></paramdef>
 69      </funcprototype>
 70</funcsynopsis>
 71  </refsynopsisdiv>
 72
 73  <refsect1>
 74    <title>DESCRIPTION</title>
 75
 76    <para>
 77       This function is equivalent to the
 78      <citerefentry>
 79        <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
 80      </citerefentry> function defined in RFC2133.
 81      <function>lwres_getnameinfo()</function> returns the
 82      hostname for the
 83      <type>struct sockaddr</type> <parameter>sa</parameter> which
 84      is
 85      <parameter>salen</parameter> bytes long.  The hostname is of
 86      length
 87      <parameter>hostlen</parameter> and is returned via
 88      <parameter>*host.</parameter> The maximum length of the
 89      hostname is
 90      1025 bytes: <constant>NI_MAXHOST</constant>.
 91    </para>
 92
 93    <para> The name of the service associated with the port number in
 94      <parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
 95      It is <parameter>servlen</parameter> bytes long.  The
 96      maximum length
 97      of the service name is <constant>NI_MAXSERV</constant> - 32
 98      bytes.
 99    </para>
100
101    <para>
102       The <parameter>flags</parameter> argument sets the
103      following
104      bits:
105      <variablelist>
106        <varlistentry>
107          <term><constant>NI_NOFQDN</constant></term>
108          <listitem>
109            <para>
110              A fully qualified domain name is not required for local hosts.
111              The local part of the fully qualified domain name is returned
112              instead.
113            </para>
114          </listitem>
115        </varlistentry>
116        <varlistentry>
117          <term><constant>NI_NUMERICHOST</constant></term>
118          <listitem>
119            <para>
120              Return the address in numeric form, as if calling inet_ntop(),
121              instead of a host name.
122            </para>
123          </listitem>
124        </varlistentry>
125        <varlistentry>
126          <term><constant>NI_NAMEREQD</constant></term>
127          <listitem>
128            <para>
129              A name is required. If the hostname cannot be found in the DNS
130              and
131              this flag is set, a non-zero error code is returned.
132              If the hostname is not found and the flag is not set, the
133              address is returned in numeric form.
134            </para>
135          </listitem>
136        </varlistentry>
137        <varlistentry>
138          <term><constant>NI_NUMERICSERV</constant></term>
139          <listitem>
140            <para>
141              The service name is returned as a digit string representing the
142              port number.
143            </para>
144          </listitem>
145        </varlistentry>
146        <varlistentry>
147          <term><constant>NI_DGRAM</constant></term>
148          <listitem>
149            <para>
150              Specifies that the service being looked up is a datagram
151              service,  and causes getservbyport() to be called with a second
152              argument of "udp" instead of its default of "tcp".  This is
153              required
154              for the few ports (512-514) that have different services for UDP
155              and
156              TCP.
157            </para>
158          </listitem>
159        </varlistentry>
160      </variablelist>
161    </para>
162  </refsect1>
163
164  <refsect1>
165    <title>RETURN VALUES</title>
166    <para><function>lwres_getnameinfo()</function>
167      returns 0 on success or a non-zero error code if an error occurs.
168    </para>
169  </refsect1>
170  <refsect1>
171    <title>SEE ALSO</title>
172    <para><citerefentry>
173        <refentrytitle>RFC2133</refentrytitle>
174      </citerefentry>,
175      <citerefentry>
176        <refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
177      </citerefentry>,
178      <citerefentry>
179        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
180      </citerefentry>,
181      <citerefentry>
182        <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
183      </citerefentry>,
184      <citerefentry>
185        <refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
186      </citerefentry>.
187      <citerefentry>
188        <refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
189      </citerefentry>.
190    </para>
191  </refsect1>
192  <refsect1>
193    <title>BUGS</title>
194    <para>
195      RFC2133 fails to define what the nonzero return values of
196      <citerefentry>
197        <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
198      </citerefentry>
199      are.
200    </para>
201  </refsect1>
202</refentry><!--
203 - Local variables:
204 - mode: sgml
205 - End:
206-->