lwres_gethostent.docbook revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync<!ENTITY mdash "—">]>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync - Copyright (C) 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync - This Source Code Form is subject to the terms of the Mozilla Public
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync - License, v. 2.0. If a copy of the MPL was not distributed with this
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync - file, You can obtain one at http://mozilla.org/MPL/2.0/.
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync<!-- Converted by db4-upgrade version 1.0 -->
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refentryinfo>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync </refentryinfo>
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync <copyright>
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync </copyright>
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync <copyright>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync </copyright>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync <refnamediv>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refpurpose>lightweight resolver get network host entry</refpurpose>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </refnamediv>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsync <refsynopsisdiv>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync <funcsynopsis>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync<funcprototype>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsyncstruct hostent *
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <paramdef>const char *<parameter>name</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync<funcprototype>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsyncstruct hostent *
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>const char *<parameter>name</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsyncstruct hostent *
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>const char *<parameter>addr</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>len</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>type</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsyncstruct hostent *
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>stayopen</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
64836f6a22eea42b83b0ec64abcb3aa7ccc27f25vboxsyncstruct hostent *
01b2e367e947049139a5d5813ccc1fa162b11f76vboxsync<function>lwres_gethostbyname_r</function></funcdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>const char *<parameter>name</parameter></paramdef>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
71e8510a26b72d539cf6d7d7157bd87a53de8cf4vboxsync <paramdef>char *<parameter>buf</parameter></paramdef>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <paramdef>int <parameter>buflen</parameter></paramdef>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsync <paramdef>int *<parameter>error</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsyncstruct hostent *
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<function>lwres_gethostbyaddr_r</function></funcdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>const char *<parameter>addr</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>len</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>type</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>char *<parameter>buf</parameter></paramdef>
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync <paramdef>int <parameter>buflen</parameter></paramdef>
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync <paramdef>int *<parameter>error</parameter></paramdef>
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync </funcprototype>
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsyncstruct hostent *
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>char *<parameter>buf</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>buflen</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int *<parameter>error</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
64836f6a22eea42b83b0ec64abcb3aa7ccc27f25vboxsync<funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <paramdef>int <parameter>stayopen</parameter></paramdef>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </funcprototype>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync<funcprototype>
b099c6398b85f527d7343cb1da573e1e95f9fd10vboxsync </funcprototype>
b099c6398b85f527d7343cb1da573e1e95f9fd10vboxsync</funcsynopsis>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </refsynopsisdiv>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <refsection><info><title>DESCRIPTION</title></info>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync These functions provide hostname-to-address and
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync address-to-hostname lookups by means of the lightweight resolver.
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync They are similar to the standard
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <citerefentry>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </citerefentry>
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync functions provided by most operating systems.
71626c00d9eb0b73ed7254794a6dfb000f4bb65cvboxsync which is usually defined in
c09430453634ebc72695a69d12366a8fb57132e3vboxsyncstruct hostent {
c09430453634ebc72695a69d12366a8fb57132e3vboxsync char *h_name; /* official name of host */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync char **h_aliases; /* alias list */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync int h_addrtype; /* host address type */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync int h_length; /* length of address */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync char **h_addr_list; /* list of addresses from name server */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync#define h_addr h_addr_list[0] /* address, for backward compatibility */
c09430453634ebc72695a69d12366a8fb57132e3vboxsync</programlisting>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync The members of this structure are:
c09430453634ebc72695a69d12366a8fb57132e3vboxsync <variablelist>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync <varlistentry>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync The official (canonical) name of the host.
c09430453634ebc72695a69d12366a8fb57132e3vboxsync </listitem>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync </varlistentry>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync <varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync A NULL-terminated array of alternate names (nicknames) for the
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </listitem>
358a99c385080f7f31166943f3ac3a2aea6b5263vboxsync </varlistentry>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsync <varlistentry>
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync The type of address being returned —
1d9143584d5616e94efe0ff5ce57e04708529775vboxsync </listitem>
1d9143584d5616e94efe0ff5ce57e04708529775vboxsync </varlistentry>
1d9143584d5616e94efe0ff5ce57e04708529775vboxsync <varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync The length of the address in bytes.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </listitem>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsync </varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync terminated array of network addresses for the host.
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync Host addresses are returned in network byte order.
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </listitem>
c09430453634ebc72695a69d12366a8fb57132e3vboxsync </varlistentry>
e33247bff4fddfdba92538374bcc9e2753044a38vboxsync </variablelist>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync For backward compatibility with very old software,
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync is the first address in
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync provide iteration over the known host entries on systems that
d46ee884c41b808b239563b1978468aae12e33a2vboxsync provide such functionality through facilities like
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync or NIS. The lightweight resolver does not currently implement
d46ee884c41b808b239563b1978468aae12e33a2vboxsync these functions; it only provides them as stub functions that always
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync return failure.
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync and <function>lwres_gethostbyname2()</function> look up the
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync <function>lwres_gethostbyname()</function> always looks for an
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync IPv4 address while <function>lwres_gethostbyname2()</function>
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync looks for an address of protocol family
358a99c385080f7f31166943f3ac3a2aea6b5263vboxsync <parameter>af</parameter>: either <type>PF_INET</type> or
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>PF_INET6</type> — IPv4 or IPV6 addresses
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync respectively. Successful calls of the functions return a
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>struct hostent</type>for the name that was looked up.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync Reverse lookups of addresses are performed by
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <parameter>addr</parameter> is an address of length
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <parameter>len</parameter> bytes and protocol family
3933885bc0c2c93436d858a14564c6179ec72872vboxsync <parameter>type</parameter> — <type>PF_INET</type> or
2a958663078b64bbcd23ff5ca77acbd42c541455vboxsync thread-safe function
3a8a18c52fd339275dcd738e571005ab6f7432acvboxsync for forward lookups. If an error occurs, an error code is returned in
fd0cf98cb3eafc5c96b7e95d934b01c5df4785fbvboxsync <type>struct hostent</type> which is initialised by a successful call to
358a99c385080f7f31166943f3ac3a2aea6b5263vboxsync <parameter>len</parameter> bytes which is used to store the
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <constant>h_name</constant>, <constant>h_aliases</constant>, and
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync Successful calls to <function>lwres_gethostbyname_r()</function>
d46ee884c41b808b239563b1978468aae12e33a2vboxsync which is a pointer to the <type>struct hostent</type> it created.
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync is a thread-safe function
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync that performs a reverse lookup of address <parameter>addr</parameter>
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync which is <parameter>len</parameter> bytes long and is of
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync family <parameter>type</parameter> — <type>PF_INET</type> or
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>PF_INET6</type>. If an error occurs, the error code is returned
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync in <parameter>*error</parameter>. The other function
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync parameters are
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync identical to those in <function>lwres_gethostbyname_r()</function>.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>struct hostent</type> which is initialised by a successful call to
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <parameter>len</parameter> bytes which is used to store the
71626c00d9eb0b73ed7254794a6dfb000f4bb65cvboxsync <constant>h_name</constant>, <constant>h_aliases</constant>, and
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <type>struct hostent</type> returned in <parameter>resbuf</parameter>.
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync Successful calls to <function>lwres_gethostbyaddr_r()</function> return
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <parameter>resbuf</parameter>, which is a pointer to the
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync </refsection>
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <refsection><info><title>RETURN VALUES</title></info>
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync The functions
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync return NULL to indicate an error. In this case the global variable
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync will contain one of the following error codes defined in
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <variablelist>
75fb03f8c1ac60d0449d333b78ec1ef08fcc9868vboxsync <varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync The host or address was not found.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </listitem>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync A recoverable error occurred, e.g., a timeout.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync Retrying the lookup may succeed.
d8523ff7d948462e328eec88b602effe2e7f7080vboxsync </listitem>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <varlistentry>
5ff3fa0492332325f57e80636321619e2224027evboxsync A non-recoverable error occurred.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </listitem>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </varlistentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <varlistentry>
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync The name exists, but has no address information
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync associated with it (or vice versa in the case
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync of a reverse lookup). The code NO_ADDRESS
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync is accepted as a synonym for NO_DATA for backwards
3933885bc0c2c93436d858a14564c6179ec72872vboxsync compatibility.
3933885bc0c2c93436d858a14564c6179ec72872vboxsync </listitem>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </varlistentry>
3933885bc0c2c93436d858a14564c6179ec72872vboxsync </variablelist>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </citerefentry>
3933885bc0c2c93436d858a14564c6179ec72872vboxsync translates these error codes to suitable error messages.
fc60d7c6501c5e676e41b11c042d4358d9faa81dvboxsync Successful calls to <function>lwres_gethostbyname_r()</function> and
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <function>lwres_gethostbyaddr_r()</function> return
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync <type>struct hostent</type> that was initialised by these functions. They return
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync <type>NULL</type> if the lookups fail or if <parameter>buf</parameter>
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync was too small to hold the list of addresses and names referenced by
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync the <constant>h_name</constant>, <constant>h_aliases</constant>, and
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <function>lwres_gethostbyaddr_r()</function> set the global
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <type>errno</type> to <errorcode>ERANGE</errorcode>.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </refsection>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync </citerefentry>,
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <citerefentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </citerefentry>,
fd0cf98cb3eafc5c96b7e95d934b01c5df4785fbvboxsync <citerefentry>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync </citerefentry>
10153a147e7cb38821b5e7404bd2ef6b9af5be4avboxsync </refsection>
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync are not thread safe; they return pointers to static data and
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync provide error codes through a global variable.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync Thread-safe versions for name and address lookup are provided by
8cd393943ea52545c4d063f5a94436639f0f80b6vboxsync respectively.
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync The resolver daemon does not currently support any non-DNS
fe06619ae576367ff3568e6abd99fb8ad28cc73avboxsync name services such as
cebc93936b5bb4d867e1c086dd1b206db33c31dcvboxsync consequently the above functions don't, either.
6063286f0f0d78e627c9ef48073f5753da93ba10vboxsync </refsection>