diff options
Diffstat (limited to 'lib/liblwres/man/lwres_getipnode.docbook')
| -rw-r--r-- | lib/liblwres/man/lwres_getipnode.docbook | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_getipnode.docbook b/lib/liblwres/man/lwres_getipnode.docbook new file mode 100644 index 000000000..3d4fa7f15 --- /dev/null +++ b/lib/liblwres/man/lwres_getipnode.docbook @@ -0,0 +1,307 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- + - Copyright (C) 2001 Internet Software Consortium. + - + - Permission to use, copy, modify, and distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM + - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL + - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION + - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +--> + +<!-- $Id: lwres_getipnode.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ --> + +<refentry> + +<refentryinfo> +<date>Jun 30, 2000</date> +</refentryinfo> + +<refmeta> +<refentrytitle>lwres_getipnode</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo>BIND9</refmiscinfo> +</refmeta> + +<refnamediv> +<refname>lwres_getipnodebyname</refname> +<refname>lwres_getipnodebyaddr</refname> +<refname>lwres_freehostent</refname> +<refpurpose>lightweight resolver nodename / address translation API</refpurpose> +</refnamediv> +<refsynopsisdiv> +<funcsynopsis> +<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> +<funcprototype> +<funcdef> +struct hostent * +<function>lwres_getipnodebyname</function></funcdef> +<paramdef>const char *name</paramdef> +<paramdef>int af</paramdef> +<paramdef>int flags</paramdef> +<paramdef>int *error_num</paramdef> +</funcprototype> +<funcprototype> +<funcdef> +struct hostent * +<function>lwres_getipnodebyaddr</function></funcdef> +<paramdef>const void *src</paramdef> +<paramdef>size_t len</paramdef> +<paramdef>int af</paramdef> +<paramdef>int *error_num</paramdef> +</funcprototype> +<funcprototype> +<funcdef> +void +<function>lwres_freehostent</function></funcdef> +<paramdef>struct hostent *he</paramdef> +</funcprototype> +</funcsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>DESCRIPTION</title> + +<para> +These functions perform thread safe, protocol independent +nodename-to-address and address-to-nodename +translation as defined in RFC2553. +</para> + +<para> +They use a +<type>struct hostent</type> +which is defined in +<filename>namedb.h</filename>: +<programlisting> +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +</programlisting> +</para> + +<para> +The members of this structure are: +<variablelist> +<varlistentry><term><constant>h_name</constant></term> +<listitem> +<para> +The official (canonical) name of the host. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>h_aliases</constant></term> +<listitem> +<para> +A NULL-terminated array of alternate names (nicknames) for the host. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>h_addrtype</constant></term> +<listitem> +<para> +The type of address being returned - usually +<type>PF_INET</type> +or +<type>PF_INET6</type>. + +</para> +</listitem></varlistentry> +<varlistentry><term><constant>h_length</constant></term> +<listitem> +<para> +The length of the address in bytes. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>h_addr_list</constant></term> +<listitem> +<para> +A +<type>NULL</type> +terminated array of network addresses for the host. +Host addresses are returned in network byte order. +</para> +</listitem></varlistentry> +</variablelist> +</para> +<para> +<function>lwres_getipnodebyname()</function> +looks up addresses of protocol family +<parameter>af</parameter> + +for the hostname +<parameter>name</parameter>. + +The +<parameter>flags</parameter> +parameter contains ORed flag bits to +specify the types of addresses that are searched +for, and the types of addresses that are returned. +The flag bits are: +<variablelist> +<varlistentry><term><constant>AI_V4MAPPED</constant></term> +<listitem> +<para> +This is used with an +<parameter>af</parameter> +of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped +IPv6 addresses. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>AI_ALL</constant></term> +<listitem> +<para> +This is used with an +<parameter>af</parameter> +of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. +If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped +IPv6 addresses. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>AI_ADDRCONFIG</constant></term> +<listitem> +<para> +Only return an IPv6 or IPv4 address if here is an active network +interface of that type. This is not currently implemented +in the BIND 9 lightweight resolver, and the flag is ignored. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>AI_DEFAULT</constant></term> +<listitem> +<para> +This default sets the +<constant>AI_V4MAPPED</constant> +and +<constant>AI_ADDRCONFIG</constant> +flag bits. +</para> +</listitem></varlistentry> +</variablelist> +</para> +<para> +<function>lwres_getipnodebyaddr()</function> +performs a reverse lookup +of address +<parameter>src</parameter> +which is +<parameter>len</parameter> +bytes long. +<parameter>af</parameter> +denotes the protocol family, typically +<type>PF_INET</type> +or +<type>PF_INET6</type>. + +</para> +<para> +<function>lwres_freehostent()</function> +releases all the memory associated with +the +<type>struct hostent</type> +pointer +<parameter>he</parameter>. + +Any memory allocated for the +<constant>h_name</constant>, + +<constant>h_addr_list</constant> +and +<constant>h_aliases</constant> +is freed, as is the memory for the +<type>hostent</type> +structure itself. +</para> +</refsect1> +<refsect1> +<title>RETURN VALUES</title> +<para> +If an error occurs, +<function>lwres_getipnodebyname()</function> +and +<function>lwres_getipnodebyaddr()</function> +set +<parameter>*error_num</parameter> +to an approriate error code and the function returns a +<type>NULL</type> +pointer. +The error codes and their meanings are defined in +<filename><lwres/netdb.h></filename>: +<variablelist> +<varlistentry><term><constant>HOST_NOT_FOUND</constant></term> +<listitem> +<para> +No such host is known. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>NO_ADDRESS</constant></term> +<listitem> +<para> +The server recognised the request and the name but no address is +available. Another type of request to the name server for the +domain might return an answer. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>TRY_AGAIN</constant></term> +<listitem> +<para> +A temporary and possibly transient error occurred, such as a +failure of a server to respond. The request may succeed if +retried. +</para> +</listitem></varlistentry> +<varlistentry><term><constant>NO_RECOVERY</constant></term> +<listitem> +<para> +An unexpected failure occurred, and retrying the request +is pointless. +</para> +</listitem></varlistentry> +</variablelist> +</para> +<para> +<citerefentry> +<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 +</manvolnum> +</citerefentry> +translates these error codes to suitable error messages. +</para> +</refsect1> +<refsect1> +<title>SEE ALSO</title> +<para> +<citerefentry> +<refentrytitle>RFC2553</refentrytitle> +</citerefentry>, + +<citerefentry> +<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>, + +<citerefentry> +<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>, + +<citerefentry> +<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>, + +<citerefentry> +<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>, + +<citerefentry> +<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> +</citerefentry>. +</para> +</refsect1> +</refentry> |