lwres_getaddrinfo.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg<!ENTITY mdash "—">]>
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and/or distribute this software for any
4da61833a1cbbca94094f9653fd970582b97a72etrawick - purpose with or without fee is hereby granted, provided that the above
4da61833a1cbbca94094f9653fd970582b97a72etrawick - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
4da61833a1cbbca94094f9653fd970582b97a72etrawick - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
4789804be088bcd86ae637a29cdb7fda25169521jailletc - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
4789804be088bcd86ae637a29cdb7fda25169521jailletc - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
4789804be088bcd86ae637a29cdb7fda25169521jailletc - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
e50c3026198fd496f183cda4c32a202925476778covener - PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- Converted by db4-upgrade version 1.0 -->
5b88c8507d5ef6d0c4cfbc78230294968175b638minfrin<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic <refentryinfo>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic </refentryinfo>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza <copyright>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf </copyright>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf <copyright>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic </copyright>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic <refnamediv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <refpurpose>socket address structure to host and service name</refpurpose>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic </refnamediv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <refsynopsisdiv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <funcsynopsis>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener<funcprototype>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>const char *<parameter>hostname</parameter></paramdef>
44ff304057225e944e220e981d434a046d14cf06covener <paramdef>const char *<parameter>servname</parameter></paramdef>
44ff304057225e944e220e981d434a046d14cf06covener <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
44ff304057225e944e220e981d434a046d14cf06covener <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
44ff304057225e944e220e981d434a046d14cf06covener </funcprototype>
5d1ba75b8794925e67591c209085a49279791de9covener<funcprototype>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand </funcprototype>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand</funcsynopsis>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic If the operating system does not provide a
45a10d38e6051fd7bdf9d742aaae633d97ff02abjailletc the following structure is used:
2165214331e4afafca4048f66f303d0253d7b001covenerstruct addrinfo {
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem int ai_family; /* PF_xxx */
1e2d421a36999d292042a5539971070d54aa6c63ylavic int ai_socktype; /* SOCK_xxx */
1e2d421a36999d292042a5539971070d54aa6c63ylavic int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
1e2d421a36999d292042a5539971070d54aa6c63ylavic size_t ai_addrlen; /* length of ai_addr */
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh char *ai_canonname; /* canonical name for hostname */
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh struct sockaddr *ai_addr; /* binary address */
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh struct addrinfo *ai_next; /* next structure in linked list */
0b67eb8568cd58bb77082703951679b42cf098actrawick</programlisting>
5ef3c61605a3a021ff71f488983cb0065f8e1a79covener </refsynopsisdiv>
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic is used to get a list of IP addresses and port numbers for host
e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletc The function is the lightweight resolver's implementation of
e466c40e1801982602ee0200c9e8b61cc148742djailletc <function>getaddrinfo()</function> as defined in RFC2133.
457468b82e59d01eba00dd9d0817309c8f5e414ejim <parameter>servname</parameter> are pointers to null-terminated
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton <parameter>hostname</parameter> is either a host name or a
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton numeric host address string: a dotted decimal IPv4 address or an
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem IPv6 address. <parameter>servname</parameter> is either a
15660979a30d251681463de2e0584853890082accovener decimal port number or a service name as listed in
cfd9415521847b2f9394fad04fb701cfb955f503rjung is an optional pointer to a
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe This structure can be used to provide hints concerning the type of
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe that the caller supports or wishes to use.
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe The caller can supply the following structure elements in
63b9f1f5880391261705f696d7d65507bbe9ace3covener <variablelist>
63b9f1f5880391261705f696d7d65507bbe9ace3covener <varlistentry>
49dacedb6c387b786b7911082ff35121a45f414bcovener The protocol family that should be used.
3c990331fc6702119e4f5b8ba9eae3021aea5265jim it means the caller will accept any protocol family supported by
fc42512879dd0504532f52fe5d0d0383dda96a1eniq operating system.
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq </listitem>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq </varlistentry>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq <varlistentry>
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc denotes the type of socket —
259878293a997ff49f5ddfc53d3739cbdc25444ecovener — that is wanted.
259878293a997ff49f5ddfc53d3739cbdc25444ecovener is zero the caller will accept any socket type.
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin </listitem>
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin </varlistentry>
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin <varlistentry>
65967d05f839dbf27cf91d91fa79585eeae19660minfrin indicates which transport protocol is wanted: IPPROTO_UDP or
8152945ae46857b170cb227e79bb799f4fc7710dminfrin IPPROTO_TCP.
8152945ae46857b170cb227e79bb799f4fc7710dminfrin is zero the caller will accept any protocol.
75f5c2db254c0167a0e396254460de09b775d203trawick </listitem>
75f5c2db254c0167a0e396254460de09b775d203trawick </varlistentry>
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph <varlistentry>
54d750a84a175d8e338880514d440773eb986b50covener bit is set, a successful call to
54d750a84a175d8e338880514d440773eb986b50covener will return a null-terminated string containing the canonical
54d750a84a175d8e338880514d440773eb986b50covener of the specified hostname in
54d750a84a175d8e338880514d440773eb986b50covener of the first
7a3aa12f0eda24793ee26d6a179bd53132e9dae8covener structure returned.
54d750a84a175d8e338880514d440773eb986b50covener Setting the
83b50288fa7d306324bba68832011ea08f5c7832covener bit indicates that the returned socket address structure is
83b50288fa7d306324bba68832011ea08f5c7832covener for used in a call to
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick <citerefentry>
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick </citerefentry>.
2e15620d724fb8e3a5be183b917359a2fd6e9468covener In this case, if the hostname argument is a
2e15620d724fb8e3a5be183b917359a2fd6e9468covener pointer, then the IP address portion of the socket
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener address structure will be set to
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener for an IPv4 address or
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener for an IPv6 address.
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd does not set the
179565be4043d7e5f9161aa75271fa0a001866d9covener bit, the returned socket address structure will be ready
179565be4043d7e5f9161aa75271fa0a001866d9covener for use in a call to
111436a32ba1254291e4883292fb116d15fe8f64covener <citerefentry>
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener </citerefentry>
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener for a connection-oriented protocol or
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener <citerefentry>
7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick </citerefentry>,
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz <citerefentry>
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz </citerefentry>,
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <citerefentry>
efe780dcf13b2b95effabf897d694d8f23feac74trawick <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin </citerefentry>
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin if a connectionless protocol was chosen.
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin The IP address portion of the socket address structure will be
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza set to the loopback address if
ba050a6f942b9fa0e81ed73437588005c569655ccovener pointer and
ba050a6f942b9fa0e81ed73437588005c569655ccovener is not set in
793214f67dede32edfd9ee96c664ead04d175cbbjfclere it indicates that
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener should be treated as a numeric string defining an IPv4 or IPv6
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener and no name resolution should be attempted.
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </listitem>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </varlistentry>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </variablelist>
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc All other elements of the <type>struct addrinfo</type> passed
f87299dab99bc04b51a6b8cad51b6795db862c0atrawick A <parameter>hints</parameter> of <type>NULL</type> is
f87299dab99bc04b51a6b8cad51b6795db862c0atrawick treated as if
4d12805e6c18253040223ea637acd6b3b3c18f60jorton the caller provided a <type>struct addrinfo</type> initialized to zero
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener After a successful call to
cb666b29f81df1d11d65002250153353568021fccovener is a pointer to a linked list of one or more
cb666b29f81df1d11d65002250153353568021fccovener structures.
6a80c3c6f4b8ea7ba5e89402b8b779b09ce020e0covener in this list cn be processed by following
75a230a728338d84dcfe81edd375352f34de22d0covener pointer, until a
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener pointer is encountered.
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener The three members
65a4e663b82f8bce28ac22ab2edfd7502de36998sf structure contain the corresponding arguments for a call to
c7de1955eb0eaeabf7042902476397692672d549sf <citerefentry>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin </citerefentry>.
a511a29faf2ff7ead3b67680154a624effb31aafminfrin structure in the list, the
a511a29faf2ff7ead3b67680154a624effb31aafminfrin member points to a filled-in socket address structure of length
63921358ef93fcb41bc71d9894221ba3d7fbb87bminfrin All of the information returned by
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin is dynamically allocated: the addrinfo structures, and the socket
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin address structures and canonical host name strings pointed to by the
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin Memory allocated for the dynamically allocated structures created by
684e0cfc200f66287a93bbd1708d1dd8a92a7eefcovener a successful call to
5c43d2fb853f84497b5ece2d414ef9484aa87e5fsf is released by
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq is a pointer to a
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq created by a call to
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq </refsection>
413ee814748f37be168ff12407fa6dba0ceeabe6trawick <refsection><info><title>RETURN VALUES</title></info>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf returns zero on success or one of the error codes listed in
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf <citerefentry>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf </citerefentry>
d7ffd2da16d58b1a0de212e4d56f7aebb72bef26sf if an error occurs. If both <parameter>hostname</parameter> and
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf </refsection>
88fac54d9d64f85bbdab5d7010816f4377f95bd7rjung <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
88fac54d9d64f85bbdab5d7010816f4377f95bd7rjung </citerefentry>,
bd3f5647b96d378d9c75c954e3f13582af32c643sf <citerefentry>
bd3f5647b96d378d9c75c954e3f13582af32c643sf <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
bd3f5647b96d378d9c75c954e3f13582af32c643sf </citerefentry>,
2a7beea91d46beb41f043a84eaad060047ee04aafabien <citerefentry>
2a7beea91d46beb41f043a84eaad060047ee04aafabien <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
2a7beea91d46beb41f043a84eaad060047ee04aafabien </citerefentry>,
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf <citerefentry>
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf </citerefentry>,
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf <citerefentry>
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf </citerefentry>,
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf <citerefentry>
132ee6ac1c26d6e8953836316ba50734eefab47bsf <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
132ee6ac1c26d6e8953836316ba50734eefab47bsf </citerefentry>,
85eacfc96a04547ef25aabbc06440039715084c2jorton <citerefentry>
85eacfc96a04547ef25aabbc06440039715084c2jorton <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
85eacfc96a04547ef25aabbc06440039715084c2jorton </citerefentry>,
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick <citerefentry>
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick </citerefentry>,
79c5787b92ac5f0e1cc82393816c77a006399316trawick <citerefentry>
79c5787b92ac5f0e1cc82393816c77a006399316trawick <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
79c5787b92ac5f0e1cc82393816c77a006399316trawick </citerefentry>,
79c5787b92ac5f0e1cc82393816c77a006399316trawick <citerefentry>
79c5787b92ac5f0e1cc82393816c77a006399316trawick <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
79c5787b92ac5f0e1cc82393816c77a006399316trawick </citerefentry>,
79c5787b92ac5f0e1cc82393816c77a006399316trawick <citerefentry>
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton </citerefentry>.
536e48c08d674acac5d44929318f2ad928edc361jorton </refsection>