lwres_getaddrinfo.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!ENTITY mdash "—">]>
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getaddrinfo</refentrytitle>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>socket address structure to host and service name</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrinfo</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const char *<parameter>hostname</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const char *<parameter>servname</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_freeaddrinfo</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If the operating system does not provide a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the following structure is used:
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafssonstruct addrinfo {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_family; /* PF_xxx */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_socktype; /* SOCK_xxx */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t ai_addrlen; /* length of ai_addr */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *ai_canonname; /* canonical name for hostname */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson struct sockaddr *ai_addr; /* binary address */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson struct addrinfo *ai_next; /* next structure in linked list */
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is used to get a list of IP addresses and port numbers for host
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The function is the lightweight resolver's implementation of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>getaddrinfo()</function> as defined in RFC2133.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>servname</parameter> are pointers to null-terminated
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>hostname</parameter> is either a host name or a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein numeric host address string: a dotted decimal IPv4 address or an
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein IPv6 address. <parameter>servname</parameter> is either a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein decimal port number or a service name as listed in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is an optional pointer to a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This structure can be used to provide hints concerning the type of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein that the caller supports or wishes to use.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The caller can supply the following structure elements in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The protocol family that should be used.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein it means the caller will accept any protocol family supported by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein operating system.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein denotes the type of socket —
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein — that is wanted.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is zero the caller will accept any socket type.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein indicates which transport protocol is wanted: IPPROTO_UDP or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein IPPROTO_TCP.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is zero the caller will accept any protocol.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bit is set, a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein will return a null-terminated string containing the canonical
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of the specified hostname in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of the first
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein structure returned.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bit indicates that the returned socket address structure is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for used in a call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein In this case, if the hostname argument is a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein pointer, then the IP address portion of the socket
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein address structure will be set to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for an IPv4 address or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for an IPv6 address.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein does not set the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein bit, the returned socket address structure will be ready
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for use in a call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for a connection-oriented protocol or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if a connectionless protocol was chosen.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The IP address portion of the socket address structure will be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein set to the loopback address if
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is not set in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein it indicates that
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein should be treated as a numeric string defining an IPv4 or IPv6
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and no name resolution should be attempted.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein All other elements of the <type>struct addrinfo</type> passed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein A <parameter>hints</parameter> of <type>NULL</type> is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein treated as if
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the caller provided a <type>struct addrinfo</type> initialized to zero
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein After a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is a pointer to a linked list of one or more
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in this list cn be processed by following
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein pointer, until a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein pointer is encountered.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The three members
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein structure contain the corresponding arguments for a call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein structure in the list, the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein member points to a filled-in socket address structure of length
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein All of the information returned by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is dynamically allocated: the addrinfo structures, and the socket
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein address structures and canonical host name strings pointed to by the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Memory allocated for the dynamically allocated structures created by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is released by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is a pointer to a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein created by a call to
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns zero on success or one of the error codes listed in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if an error occurs. If both <parameter>hostname</parameter> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>servname</parameter> are <type>NULL</type>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_getaddrinfo()</function> returns
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>