lwres_getaddrinfo.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!ENTITY mdash "—">]>
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
6bdda696b3ea703c47e87fea61017ec655f91d92nd - Permission to use, copy, modify, and/or distribute this software for any
6bdda696b3ea703c47e87fea61017ec655f91d92nd - purpose with or without fee is hereby granted, provided that the above
6bdda696b3ea703c47e87fea61017ec655f91d92nd - copyright notice and this permission notice appear in all copies.
0662ed52e814f8f08ef0e09956413a792584eddffuankg - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
6bdda696b3ea703c47e87fea61017ec655f91d92nd - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
6bdda696b3ea703c47e87fea61017ec655f91d92nd - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
6bdda696b3ea703c47e87fea61017ec655f91d92nd - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
6bdda696b3ea703c47e87fea61017ec655f91d92nd - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
6bdda696b3ea703c47e87fea61017ec655f91d92nd - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
6bdda696b3ea703c47e87fea61017ec655f91d92nd - PERFORMANCE OF THIS SOFTWARE.
6bdda696b3ea703c47e87fea61017ec655f91d92nd<!-- Converted by db4-upgrade version 1.0 -->
6bdda696b3ea703c47e87fea61017ec655f91d92nd<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentryinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refentryinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refmeta>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </copyright>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </docinfo>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refnamediv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refpurpose>socket address structure to host and service name</refpurpose>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </refnamediv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refsynopsisdiv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <funcsynopsis>
6bdda696b3ea703c47e87fea61017ec655f91d92nd<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg<funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const char *<parameter>hostname</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const char *<parameter>servname</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd<funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </funcprototype>
6bdda696b3ea703c47e87fea61017ec655f91d92nd</funcsynopsis>
6bdda696b3ea703c47e87fea61017ec655f91d92nd If the operating system does not provide a
6bdda696b3ea703c47e87fea61017ec655f91d92nd the following structure is used:
6bdda696b3ea703c47e87fea61017ec655f91d92ndstruct addrinfo {
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_family; /* PF_xxx */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_socktype; /* SOCK_xxx */
6bdda696b3ea703c47e87fea61017ec655f91d92nd int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
6bdda696b3ea703c47e87fea61017ec655f91d92nd size_t ai_addrlen; /* length of ai_addr */
6bdda696b3ea703c47e87fea61017ec655f91d92nd char *ai_canonname; /* canonical name for hostname */
6bdda696b3ea703c47e87fea61017ec655f91d92nd struct sockaddr *ai_addr; /* binary address */
6bdda696b3ea703c47e87fea61017ec655f91d92nd struct addrinfo *ai_next; /* next structure in linked list */
6bdda696b3ea703c47e87fea61017ec655f91d92nd</programlisting>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </refsynopsisdiv>
6bdda696b3ea703c47e87fea61017ec655f91d92nd is used to get a list of IP addresses and port numbers for host
6bdda696b3ea703c47e87fea61017ec655f91d92nd The function is the lightweight resolver's implementation of
6bdda696b3ea703c47e87fea61017ec655f91d92nd <function>getaddrinfo()</function> as defined in RFC2133.
6bdda696b3ea703c47e87fea61017ec655f91d92nd <parameter>servname</parameter> are pointers to null-terminated
0662ed52e814f8f08ef0e09956413a792584eddffuankg <parameter>hostname</parameter> is either a host name or a
6bdda696b3ea703c47e87fea61017ec655f91d92nd numeric host address string: a dotted decimal IPv4 address or an
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg IPv6 address. <parameter>servname</parameter> is either a
6bdda696b3ea703c47e87fea61017ec655f91d92nd decimal port number or a service name as listed in
6bdda696b3ea703c47e87fea61017ec655f91d92nd is an optional pointer to a
6bdda696b3ea703c47e87fea61017ec655f91d92nd This structure can be used to provide hints concerning the type of
6bdda696b3ea703c47e87fea61017ec655f91d92nd that the caller supports or wishes to use.
0662ed52e814f8f08ef0e09956413a792584eddffuankg The caller can supply the following structure elements in
6bdda696b3ea703c47e87fea61017ec655f91d92nd <variablelist>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd The protocol family that should be used.
6bdda696b3ea703c47e87fea61017ec655f91d92nd it means the caller will accept any protocol family supported by
0662ed52e814f8f08ef0e09956413a792584eddffuankg operating system.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd denotes the type of socket —
6bdda696b3ea703c47e87fea61017ec655f91d92nd — that is wanted.
6bdda696b3ea703c47e87fea61017ec655f91d92nd is zero the caller will accept any socket type.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd indicates which transport protocol is wanted: IPPROTO_UDP or
6bdda696b3ea703c47e87fea61017ec655f91d92nd IPPROTO_TCP.
6bdda696b3ea703c47e87fea61017ec655f91d92nd is zero the caller will accept any protocol.
6bdda696b3ea703c47e87fea61017ec655f91d92nd </listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <varlistentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <listitem>
6bdda696b3ea703c47e87fea61017ec655f91d92nd Flag bits.
6bdda696b3ea703c47e87fea61017ec655f91d92nd bit is set, a successful call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd will return a null-terminated string containing the canonical
6bdda696b3ea703c47e87fea61017ec655f91d92nd of the specified hostname in
6bdda696b3ea703c47e87fea61017ec655f91d92nd of the first
6bdda696b3ea703c47e87fea61017ec655f91d92nd structure returned.
6bdda696b3ea703c47e87fea61017ec655f91d92nd Setting the
6bdda696b3ea703c47e87fea61017ec655f91d92nd bit indicates that the returned socket address structure is
6bdda696b3ea703c47e87fea61017ec655f91d92nd for used in a call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>.
6bdda696b3ea703c47e87fea61017ec655f91d92nd In this case, if the hostname argument is a
6bdda696b3ea703c47e87fea61017ec655f91d92nd pointer, then the IP address portion of the socket
6bdda696b3ea703c47e87fea61017ec655f91d92nd address structure will be set to
6bdda696b3ea703c47e87fea61017ec655f91d92nd for an IPv4 address or
6bdda696b3ea703c47e87fea61017ec655f91d92nd for an IPv6 address.
6bdda696b3ea703c47e87fea61017ec655f91d92nd does not set the
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg bit, the returned socket address structure will be ready
6bdda696b3ea703c47e87fea61017ec655f91d92nd for use in a call to
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd for a connection-oriented protocol or
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <citerefentry>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
ac7985784d08a3655291f24f711812b4d8b1cbcffuankg </citerefentry>,
6bdda696b3ea703c47e87fea61017ec655f91d92nd <citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
6bdda696b3ea703c47e87fea61017ec655f91d92nd </citerefentry>
6bdda696b3ea703c47e87fea61017ec655f91d92nd if a connectionless protocol was chosen.
6bdda696b3ea703c47e87fea61017ec655f91d92nd The IP address portion of the socket address structure will be
6bdda696b3ea703c47e87fea61017ec655f91d92nd set to the loopback address if
0662ed52e814f8f08ef0e09956413a792584eddffuankg pointer and
6bdda696b3ea703c47e87fea61017ec655f91d92nd is not set in
6bdda696b3ea703c47e87fea61017ec655f91d92nd it indicates that
6bdda696b3ea703c47e87fea61017ec655f91d92nd should be treated as a numeric string defining an IPv4 or IPv6
6bdda696b3ea703c47e87fea61017ec655f91d92nd and no name resolution should be attempted.