/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook
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 "—">]> 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 <lwres/netdb.h></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-->