lwres_getaddrinfo.docbook revision 86b0285d7e65601645db4090d62ee6cb63abad6c
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem - Copyright (C) 2001 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and distribute this software for any
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - purpose with or without fee is hereby granted, provided that the above
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
4da61833a1cbbca94094f9653fd970582b97a72etrawick - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
4789804be088bcd86ae637a29cdb7fda25169521jailletc - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
4789804be088bcd86ae637a29cdb7fda25169521jailletc - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- $Id: lwres_getaddrinfo.docbook,v 1.5 2001/06/18 22:06:53 gson Exp $ -->
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<refentryinfo>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic</refentryinfo>
69301145375a889e7e37caf7cc7321ac0f91801erpluem<refnamediv>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza<refpurpose>socket address structure to host and service name</refpurpose>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza</refnamediv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<refsynopsisdiv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsis>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf<funcprototype>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic</funcprototype>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic<funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcsynopsis>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covenerIf the operating system does not provide a
d7205b1a86c51c27b71a2c458dc453fd53a261c1covenerthe following structure is used:
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener<programlisting>
44ff304057225e944e220e981d434a046d14cf06covenerstruct addrinfo {
44ff304057225e944e220e981d434a046d14cf06covener int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
44ff304057225e944e220e981d434a046d14cf06covener int ai_family; /* PF_xxx */
44ff304057225e944e220e981d434a046d14cf06covener int ai_socktype; /* SOCK_xxx */
5d1ba75b8794925e67591c209085a49279791de9covener int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
5d1ba75b8794925e67591c209085a49279791de9covener size_t ai_addrlen; /* length of ai_addr */
5d1ba75b8794925e67591c209085a49279791de9covener char *ai_canonname; /* canonical name for hostname */
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand struct sockaddr *ai_addr; /* binary address */
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand struct addrinfo *ai_next; /* next structure in linked list */
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand</programlisting>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic</refsynopsisdiv>
a34684a59b60a4173c25035d0c627ef17e6dc215rpluemis used to get a list of IP addresses and port numbers for host
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedoohThe function is the lightweight resolver's implementation of
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedoohas defined in RFC2133.
0b67eb8568cd58bb77082703951679b42cf098actrawickare pointers to null-terminated
6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavicis either a host name or a numeric host address string: a dotted decimal
3060ce7f798fbda7999cd4ddf89b525d2b294185covenerIPv4 address or an IPv6 address.
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavicis either a decimal port number or a service name as listed in
457468b82e59d01eba00dd9d0817309c8f5e414ejimis an optional pointer to a
457468b82e59d01eba00dd9d0817309c8f5e414ejimThis structure can be used to provide hints concerning the type of socket
04983e3bd1754764eec7d6bb772fe3b0bf391771jortonthat the caller supports or wishes to use.
04983e3bd1754764eec7d6bb772fe3b0bf391771jortonThe caller can supply the following structure elements in
15660979a30d251681463de2e0584853890082accovener<variablelist>
49dacedb6c387b786b7911082ff35121a45f414bcovener<varlistentry><term><constant>ai_family</constant></term>
cfd9415521847b2f9394fad04fb701cfb955f503rjung<para>The protocol family that should be used.
28c31fb73c1264bd1d0ff932573677030b024c7dwroweit means the caller will accept any protocol family supported by the
28c31fb73c1264bd1d0ff932573677030b024c7dwroweoperating system.
8491e0600f69b0405e156ea8a419653c065c645bcovener<varlistentry><term><constant>ai_socktype</constant></term>
63b9f1f5880391261705f696d7d65507bbe9ace3covenerdenotes the type of socket —
3c990331fc6702119e4f5b8ba9eae3021aea5265jim— that is wanted.
3c990331fc6702119e4f5b8ba9eae3021aea5265jimis zero the caller will accept any socket type.
fc42512879dd0504532f52fe5d0d0383dda96a1eniq</listitem>
fc42512879dd0504532f52fe5d0d0383dda96a1eniq</varlistentry>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq<varlistentry><term><constant>ai_protocol</constant></term>
da0442c0440caef34706e2c2f3af05cb65921cc0jailletcindicates which transport protocol is wanted: IPPROTO_UDP or
983528026996668ea295be95aedb9c7a346af470ylavicIPPROTO_TCP.
06b8f183140c8e02e0974e938a05078b511d1603coveneris zero the caller will accept any protocol.
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem</varlistentry>
259878293a997ff49f5ddfc53d3739cbdc25444ecovener<varlistentry><term><constant>ai_flags</constant></term>
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrinbit is set, a successful call to
65967d05f839dbf27cf91d91fa79585eeae19660minfrinwill return a a null-terminated string containing the canonical name
65967d05f839dbf27cf91d91fa79585eeae19660minfrinof the specified hostname in
65967d05f839dbf27cf91d91fa79585eeae19660minfrinof the first
8152945ae46857b170cb227e79bb799f4fc7710dminfrinstructure returned.
75f5c2db254c0167a0e396254460de09b775d203trawickbit indicates that the returned socket address structure is intended
75f5c2db254c0167a0e396254460de09b775d203trawickfor used in a call to
75f5c2db254c0167a0e396254460de09b775d203trawick<citerefentry>
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph</citerefentry>.
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawickIn this case, if the hostname argument is a
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawickpointer, then the IP address portion of the socket
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawickaddress structure will be set to
54d750a84a175d8e338880514d440773eb986b50covenerfor an IPv4 address or
54d750a84a175d8e338880514d440773eb986b50covenerfor an IPv6 address.
7a3aa12f0eda24793ee26d6a179bd53132e9dae8covenerdoes not set the
54d750a84a175d8e338880514d440773eb986b50covenerbit, the returned socket address structure will be ready
83b50288fa7d306324bba68832011ea08f5c7832covenerfor use in a call to
4e30ef014533a7e93c92d88306291f5e49c9692ftrawick<citerefentry>
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick</manvolnum>
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick</citerefentry>
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawickfor a connection-oriented protocol or
2e15620d724fb8e3a5be183b917359a2fd6e9468covener<citerefentry>
2e15620d724fb8e3a5be183b917359a2fd6e9468covener<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
2e15620d724fb8e3a5be183b917359a2fd6e9468covener</citerefentry>,
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener<citerefentry>
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener</citerefentry>,
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener<citerefentry>
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd</manvolnum>
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd</citerefentry>
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisdif a connectionless protocol was chosen.
179565be4043d7e5f9161aa75271fa0a001866d9covenerThe IP address portion of the socket address structure will be
179565be4043d7e5f9161aa75271fa0a001866d9covenerset to the loopback address if
fce4949fb0b309a5744afcd503c6ed2d35621ee2coveneris not set in
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluzait indicates that
efe780dcf13b2b95effabf897d694d8f23feac74trawickshould be treated as a numeric string defining an IPv4 or IPv6 address
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrinand no name resolution should be attempted.
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza</varlistentry>
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza</variablelist>
ba050a6f942b9fa0e81ed73437588005c569655ccovenerAll other elements of the <type>struct addrinfo</type> passed
001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedoohA <parameter>hints</parameter> of <type>NULL</type> is treated as if
001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedoohthe caller provided a <type>struct addrinfo</type> initialized to zero
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovenerAfter a successful call to
249d09d51808cb7981af99762c3b3736ca126cd5jkaluzais a pointer to a linked list of one or more
56589be3d7a3e9343370df240010c6928cc78b39jkaluzain this list cn be processed by following
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletcpointer, until a
f87299dab99bc04b51a6b8cad51b6795db862c0atrawickpointer is encountered.
f87299dab99bc04b51a6b8cad51b6795db862c0atrawickThe three members
a4df2cd1e1391575a327c2a90ba4315f805a0a78covenerstructure contain the corresponding arguments for a call to
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener<citerefentry>
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
cb666b29f81df1d11d65002250153353568021fccovener</citerefentry>.
6a80c3c6f4b8ea7ba5e89402b8b779b09ce020e0covenerstructure in the list, the
6a80c3c6f4b8ea7ba5e89402b8b779b09ce020e0covenermember points to a filled-in socket address structure of length
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covenerAll of the information returned by
63a5ea80bddcc84a462e40f402b4f330e0e05411coveneris dynamically allocated: the addrinfo structures, and the socket
63a5ea80bddcc84a462e40f402b4f330e0e05411coveneraddress structures and canonical host name strings pointed to by the
63a5ea80bddcc84a462e40f402b4f330e0e05411covenerMemory allocated for the dynamically allocated structures created by
65a4e663b82f8bce28ac22ab2edfd7502de36998sfa successful call to
65a4e663b82f8bce28ac22ab2edfd7502de36998sfis released by
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrinis a pointer to a
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrincreated by a call to
deec48c67d4786bc77112ffbf3a4e70b931097edminfrinreturns zero on success or one of the error codes listed in
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin<citerefentry>
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin<refentrytitle>gai_strerror</refentrytitle><manvolnum>3
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin</manvolnum>
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin</citerefentry>
684e0cfc200f66287a93bbd1708d1dd8a92a7eefcovenerif an error occurs.
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq</refsect1>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf<citerefentry>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf</citerefentry>,
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf<citerefentry>
d7ffd2da16d58b1a0de212e4d56f7aebb72bef26sf<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
d7ffd2da16d58b1a0de212e4d56f7aebb72bef26sf</citerefentry>,
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf<citerefentry>
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf</citerefentry>,
9811aed12bbc71783d2e544ccb5fecd193843eadsf<citerefentry>
9811aed12bbc71783d2e544ccb5fecd193843eadsf<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
88fac54d9d64f85bbdab5d7010816f4377f95bd7rjung</citerefentry>,
bd3f5647b96d378d9c75c954e3f13582af32c643sf<citerefentry>
bd3f5647b96d378d9c75c954e3f13582af32c643sf</citerefentry>,
bd3f5647b96d378d9c75c954e3f13582af32c643sf<citerefentry>
2a7beea91d46beb41f043a84eaad060047ee04aafabien<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
2a7beea91d46beb41f043a84eaad060047ee04aafabien</citerefentry>,
2a7beea91d46beb41f043a84eaad060047ee04aafabien<citerefentry>
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf</citerefentry>,
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf<citerefentry>
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf</citerefentry>,
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf<citerefentry>
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
132ee6ac1c26d6e8953836316ba50734eefab47bsf</citerefentry>,
132ee6ac1c26d6e8953836316ba50734eefab47bsf<citerefentry>
85eacfc96a04547ef25aabbc06440039715084c2jorton<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
85eacfc96a04547ef25aabbc06440039715084c2jorton</citerefentry>,
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick<citerefentry>
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick</citerefentry>.