lwres_getaddrinfo.html revision 010a51c427bfb6ab658fc0056955a1a5b69810be
036f4a76ec5e5bdba8a7d2f7e77c188a8246bbacBob Halley - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley - Permission to use, copy, modify, and/or distribute this software for any
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff - purpose with or without fee is hereby granted, provided that the above
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley - copyright notice and this permission notice appear in all copies.
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
036f4a76ec5e5bdba8a7d2f7e77c188a8246bbacBob Halley - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley - PERFORMANCE OF THIS SOFTWARE.
12e425fa792ecc06603d8c61abcd0d0c5e9c2781Bob Halley<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_getaddrinfo">
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<a name="idp60896592"></a><div class="titlepage"></div>
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley lwres_getaddrinfo,
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff lwres_freeaddrinfo
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff — socket address structure to host and service name
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley<pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre>
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<td>const char *<var class="pdparam">hostname</var>, </td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<td>const char *<var class="pdparam">servname</var>, </td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<td>const struct addrinfo *<var class="pdparam">hints</var>, </td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<td>struct addrinfo **<var class="pdparam">res</var><code>)</code>;</td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<td>struct addrinfo *<var class="pdparam">ai</var><code>)</code>;</td>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff If the operating system does not provide a
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff the following structure is used:
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graffstruct addrinfo {
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff int ai_family; /* PF_xxx */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff int ai_socktype; /* SOCK_xxx */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff size_t ai_addrlen; /* length of ai_addr */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff char *ai_canonname; /* canonical name for hostname */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff struct sockaddr *ai_addr; /* binary address */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff struct addrinfo *ai_next; /* next structure in linked list */
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <p><code class="function">lwres_getaddrinfo()</code>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is used to get a list of IP addresses and port numbers for host
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>hostname</code></em> and service
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley <em class="parameter"><code>servname</code></em>.
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley The function is the lightweight resolver's implementation of
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley <code class="function">getaddrinfo()</code> as defined in RFC2133.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>hostname</code></em> and
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>servname</code></em> are pointers to null-terminated
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>hostname</code></em> is either a host name or a
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff numeric host address string: a dotted decimal IPv4 address or an
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff IPv6 address. <em class="parameter"><code>servname</code></em> is either a
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley decimal port number or a service name as listed in
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley is an optional pointer to a
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley This structure can be used to provide hints concerning the type of
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley that the caller supports or wishes to use.
5f38a3b14a20a62da2ff575b7ec2715bd49cf6a4Michael Graff The caller can supply the following structure elements in
3bc89b0c05ded11053ec3f8c1d24f05104bf3031David Lawrence <em class="parameter"><code>*hints</code></em>:
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<dt><span class="term"><code class="constant">ai_family</code></span></dt>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff The protocol family that should be used.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff it means the caller will accept any protocol family supported by
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff operating system.
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley<dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff denotes the type of socket —
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley — that is wanted.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is zero the caller will accept any socket type.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff indicates which transport protocol is wanted: IPPROTO_UDP or
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is zero the caller will accept any protocol.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<dt><span class="term"><code class="constant">ai_flags</code></span></dt>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff bit is set, a successful call to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <code class="function">lwres_getaddrinfo()</code>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff will return a null-terminated string containing the canonical
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff of the specified hostname in
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff structure returned.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff bit indicates that the returned socket address structure is
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff for used in a call to
90d3a7800b0bcced1486c3829ec9171d99b50353David Lawrence In this case, if the hostname argument is a
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley pointer, then the IP address portion of the socket
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff address structure will be set to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff for an IPv4 address or
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff for an IPv6 address.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff does not set the
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff bit, the returned socket address structure will be ready
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff for use in a call to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff for a connection-oriented protocol or
d71317b05cfdf4c3f993839d6d2f9e2e9858d3b9Andreas Gustafsson <span class="refentrytitle">sendmsg</span>(2)
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley if a connectionless protocol was chosen.
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley The IP address portion of the socket address structure will be
19de822a35b5d9594b1521b55f1c93b9b86964a5Bob Halley set to the loopback address if
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>hostname</code></em>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is not set in
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff it indicates that
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <em class="parameter"><code>hostname</code></em>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff should be treated as a numeric string defining an IPv4 or IPv6
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley and no name resolution should be attempted.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff All other elements of the <span class="type">struct addrinfo</span> passed
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff via <em class="parameter"><code>hints</code></em> must be zero.
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley treated as if
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley the caller provided a <span class="type">struct addrinfo</span> initialized to zero
63469b434a7726ce4b2700830721ecb1d1ad61a9Bob Halley with <code class="constant">ai_family</code>set to
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley After a successful call to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <code class="function">lwres_getaddrinfo()</code>,
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is a pointer to a linked list of one or more
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley in this list cn be processed by following
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley pointer, until a
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff pointer is encountered.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff The three members
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff structure contain the corresponding arguments for a call to
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley structure in the list, the
78fda31f2608ca863b1381798e680dd1cab2f209Bob Halley member points to a filled-in socket address structure of length
6017f424ee3c02d7f22132c77576ea38542fa949Andreas Gustafsson All of the information returned by
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley <code class="function">lwres_getaddrinfo()</code>
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is dynamically allocated: the addrinfo structures, and the socket
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley address structures and canonical host name strings pointed to by the
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley <code class="constant">addrinfo</code>structures.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff Memory allocated for the dynamically allocated structures created by
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff a successful call to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <code class="function">lwres_getaddrinfo()</code>
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley is released by
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <code class="function">lwres_freeaddrinfo()</code>.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff is a pointer to a
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff created by a call to
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <code class="function">lwres_getaddrinfo()</code>.
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <div class="refsection" title="RETURN VALUES">
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff<a name="idp61002960"></a><h2>RETURN VALUES</h2>
3da473e3e96d2d054331b43519426a9b5f83cf4cBob Halley <p><code class="function">lwres_getaddrinfo()</code>
e4c76dcbd1259d52345106778c5ad4d416f8a84dBob Halley returns zero on success or one of the error codes listed in
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <span class="refentrytitle">gai_strerror</span>(3)
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley if an error occurs. If both <em class="parameter"><code>hostname</code></em> and
d365d9a5551cc4a5de4b7b75d0c8eb7903d8eccdBob Halley <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
19de822a35b5d9594b1521b55f1c93b9b86964a5Bob Halley <code class="function">lwres_getaddrinfo()</code> returns
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <span class="refentrytitle">lwres_getaddrinfo</span>(3)
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <span class="refentrytitle">lwres_freeaddrinfo</span>(3)
d2eb1644065bdfdf7ffd29d1f922600be313e9a0Michael Graff <span class="refentrytitle">lwres_gai_strerror</span>(3)
e4c76dcbd1259d52345106778c5ad4d416f8a84dBob Halley <span class="refentrytitle">getservbyname</span>(3)