lwres_getaddrinfo.docbook revision f5d30e2864e048a42c4dc1134993ae7efdb5d6c3
bcb4e51a409d94ae670de96afb8483a4f7855294Stephan Bosch<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen [<!ENTITY mdash "—">]>
6789ed17e7ca4021713507baf0dcf6979bb42e0cTimo Sirainen - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
7a54d58280aad8a64f266c61273ea1e8dff511a3Timo Sirainen - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen - Permission to use, copy, modify, and distribute this software for any
b7f14c9568e7edc75d1d7fd86751c02bc97cde3eTimo Sirainen - purpose with or without fee is hereby granted, provided that the above
436adac819e7cbeef04af08dcc6a4f3ecd4a1d9eMartti Rannanjärvi - copyright notice and this permission notice appear in all copies.
57e3b63a75335f45cf6cf9cd89317e2e6cec249dStephan Bosch - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
52fbebc87d7ae4fc4585863d38cb87f166a6521aTimo Sirainen - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
6789ed17e7ca4021713507baf0dcf6979bb42e0cTimo Sirainen - PERFORMANCE OF THIS SOFTWARE.
7c3f90095b4168d89a268ac1ec820c5925d48fd3Timo Sirainen<!-- $Id: lwres_getaddrinfo.docbook,v 1.10 2005/05/13 01:35:46 marka Exp $ -->
e15b305e90c9834734ccf35ed78f0ad29d570ee9Timo Sirainen <refentryinfo>
52fbebc87d7ae4fc4585863d38cb87f166a6521aTimo Sirainen </refentryinfo>
31be5ed1551c98cddeb2295a594f010aaf4b76bcTimo Sirainen <refentrytitle>lwres_getaddrinfo</refentrytitle>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <holder>Internet Software Consortium.</holder>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <refpurpose>socket address structure to host and service name</refpurpose>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen </refnamediv>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <refsynopsisdiv>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <funcsynopsis>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
147a788fea2a88f7125b27226451271d55cf5b01Timo Sirainen<funcprototype>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen<function>lwres_getaddrinfo</function></funcdef>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <paramdef>const char *<parameter>hostname</parameter></paramdef>
5df33e9ee65eec194105b338c55dedbf8422f695Timo Sirainen <paramdef>const char *<parameter>servname</parameter></paramdef>
6e8f0036cad59d1d6bcd9ef69bfe712d01656ca3Timo Sirainen <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
6e8f0036cad59d1d6bcd9ef69bfe712d01656ca3Timo Sirainen <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
52fbebc87d7ae4fc4585863d38cb87f166a6521aTimo Sirainen </funcprototype>
52fbebc87d7ae4fc4585863d38cb87f166a6521aTimo Sirainen<funcprototype>
4cce36128569c68a999e98c9034bfb1bc177f1ffTimo Sirainen<function>lwres_freeaddrinfo</function></funcdef>
4cce36128569c68a999e98c9034bfb1bc177f1ffTimo Sirainen <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
e015e2f7e7f48874495f9df8b0dd192b7ffcb5ccTimo Sirainen </funcprototype>
e015e2f7e7f48874495f9df8b0dd192b7ffcb5ccTimo Sirainen</funcsynopsis>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen If the operating system does not provide a
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen the following structure is used:
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainenstruct addrinfo {
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainen int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainen int ai_family; /* PF_xxx */
c04f9a724a7b3cc649485a61b0a540868d25d71bTimo Sirainen int ai_socktype; /* SOCK_xxx */
c04f9a724a7b3cc649485a61b0a540868d25d71bTimo Sirainen int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainen size_t ai_addrlen; /* length of ai_addr */
2d01cc1880cf2afd4fb1c8ad7fa6ce78e562e71eTimo Sirainen char *ai_canonname; /* canonical name for hostname */
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainen struct sockaddr *ai_addr; /* binary address */
b0a901f1dbe9e05ac1c92a0974af6bce0274f31aTimo Sirainen struct addrinfo *ai_next; /* next structure in linked list */
46114180b41dc7cac5e7b0242ad347b4acdbaa5aTimo Sirainen</programlisting>
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen </refsynopsisdiv>
46114180b41dc7cac5e7b0242ad347b4acdbaa5aTimo Sirainen <para><function>lwres_getaddrinfo()</function>
46114180b41dc7cac5e7b0242ad347b4acdbaa5aTimo Sirainen is used to get a list of IP addresses and port numbers for host
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen The function is the lightweight resolver's implementation of
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen <function>getaddrinfo()</function> as defined in RFC2133.
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen <parameter>servname</parameter> are pointers to null-terminated
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen <parameter>hostname</parameter> is either a host name or a
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen numeric host address string: a dotted decimal IPv4 address or an
7522446d6514e5593c9d4d7e4beacd328301cb23Aki Tuomi IPv6 address. <parameter>servname</parameter> is either a
46114180b41dc7cac5e7b0242ad347b4acdbaa5aTimo Sirainen decimal port number or a service name as listed in
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen is an optional pointer to a
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen This structure can be used to provide hints concerning the type of
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen that the caller supports or wishes to use.
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen The caller can supply the following structure elements in
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen <variablelist>
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen <varlistentry>
884228e5496378bada39a932db67aa3d9478198fTimo Sirainen The protocol family that should be used.
19e8adccba16ff419f5675b1575358c2956dce83Timo Sirainen it means the caller will accept any protocol family supported by
19e8adccba16ff419f5675b1575358c2956dce83Timo Sirainen operating system.
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen </varlistentry>
6e0054c2e5efc526df6287da368335680a856714Timo Sirainen <varlistentry>
6e0054c2e5efc526df6287da368335680a856714Timo Sirainen denotes the type of socket —
1b4441e3e6f9e78ebeae8218de971959cd55bf60Timo Sirainen — that is wanted.
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen is zero the caller will accept any socket type.
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen </varlistentry>
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen <varlistentry>
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen indicates which transport protocol is wanted: IPPROTO_UDP or
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen is zero the caller will accept any protocol.
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen </varlistentry>
489301ee88b2174e3171875e979e667de2c4a174Timo Sirainen <varlistentry>
d9a7e950a9cd21f2b4a90ec7759fca9e8fcc7995Timo Sirainen bit is set, a successful call to
3281669db44d09a087a203201248abbc81b3cc1aTimo Sirainen will return a null-terminated string containing the canonical
8e361d2906b0e44f7175a20981f8d2280645b58bTimo Sirainen of the specified hostname in
8e361d2906b0e44f7175a20981f8d2280645b58bTimo Sirainen structure returned.
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen bit indicates that the returned socket address structure is
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen for used in a call to
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen <citerefentry>
a39292e6410a30805b020acf4fc916210ae54e86Timo Sirainen <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen </citerefentry>.
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen In this case, if the hostname argument is a
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen pointer, then the IP address portion of the socket
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen address structure will be set to
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen for an IPv4 address or
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen for an IPv6 address.
0737a4fe0b83a05f335a8ad02e833b62565a36daTimo Sirainen does not set the
0737a4fe0b83a05f335a8ad02e833b62565a36daTimo Sirainen bit, the returned socket address structure will be ready
0737a4fe0b83a05f335a8ad02e833b62565a36daTimo Sirainen for use in a call to
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <citerefentry>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen </citerefentry>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen for a connection-oriented protocol or
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <citerefentry>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen </citerefentry>,
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <citerefentry>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen </citerefentry>,
3fe9483b2b412a14493e3120751b0e99ecfe9388Timo Sirainen <citerefentry>
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
3fe9483b2b412a14493e3120751b0e99ecfe9388Timo Sirainen </citerefentry>
3fe9483b2b412a14493e3120751b0e99ecfe9388Timo Sirainen if a connectionless protocol was chosen.
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen The IP address portion of the socket address structure will be
817d027593510c3ba70ad542ce0011f5f6916d1eTimo Sirainen set to the loopback address if
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen is not set in
a2f250a332dfc1e6cd4ffd196c621eb9dbf7b8a1Timo Sirainen it indicates that
87490012895b4f371635ded00add04c9107dcfefJosef 'Jeff' Sipek should be treated as a numeric string defining an IPv4 or IPv6
a2f250a332dfc1e6cd4ffd196c621eb9dbf7b8a1Timo Sirainen and no name resolution should be attempted.
ca98d6a1bbe73499da758a36bfab2963375c8d06Timo Sirainen </varlistentry>
a2f250a332dfc1e6cd4ffd196c621eb9dbf7b8a1Timo Sirainen </variablelist>
a2f250a332dfc1e6cd4ffd196c621eb9dbf7b8a1Timo Sirainen All other elements of the <type>struct addrinfo</type> passed
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen via <parameter>hints</parameter> must be zero.
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen A <parameter>hints</parameter> of <type>NULL</type> is
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen treated as if
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen the caller provided a <type>struct addrinfo</type> initialized to zero
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen After a successful call to
f46885a5b78b15a8d2419f6e5d13b643bd85e41fTimo Sirainen is a pointer to a linked list of one or more
87490012895b4f371635ded00add04c9107dcfefJosef 'Jeff' Sipek in this list cn be processed by following
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen pointer, until a
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen pointer is encountered.
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen The three members
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen structure contain the corresponding arguments for a call to
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen <citerefentry>
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen </citerefentry>.
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen structure in the list, the
bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen member points to a filled-in socket address structure of length
a757f31393b9d6fc7760a9dec8363404ab3ae576Timo Sirainen All of the information returned by
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen is dynamically allocated: the addrinfo structures, and the socket
87490012895b4f371635ded00add04c9107dcfefJosef 'Jeff' Sipek address structures and canonical host name strings pointed to by the
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen Memory allocated for the dynamically allocated structures created by
a757f31393b9d6fc7760a9dec8363404ab3ae576Timo Sirainen a successful call to
cd83124e5d070a016c590bb0b1096d7828c7b6adTimo Sirainen is released by
a757f31393b9d6fc7760a9dec8363404ab3ae576Timo Sirainen is a pointer to a
eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen created by a call to
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <para><function>lwres_getaddrinfo()</function>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen returns zero on success or one of the error codes listed in
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <citerefentry>
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
96541d31299bb40b5a6efdbf9b4cb3d4f4b4a069Timo Sirainen </citerefentry>
02b78558dc03daa2e7da2010b63f247b49936a38Timo Sirainen if an error occurs. If both <parameter>hostname</parameter> and
02b78558dc03daa2e7da2010b63f247b49936a38Timo Sirainen <parameter>servname</parameter> are <type>NULL</type>
02b78558dc03daa2e7da2010b63f247b49936a38Timo Sirainen <function>lwres_getaddrinfo()</function> returns
49f65b7c797515d787bcbc9cbeb78f0c21b1b282Timo Sirainen <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
49f65b7c797515d787bcbc9cbeb78f0c21b1b282Timo Sirainen </citerefentry>,
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen <citerefentry>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen </citerefentry>,
e8a59a1671127f87e2d22f42e84c572f28299d81Timo Sirainen <citerefentry>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen </citerefentry>,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen <citerefentry>
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
ae1b268ffff743ad9927c304a1344c5cbd7f909dTimo Sirainen </citerefentry>,
e192a3b1ca8ae857e7d87298ea507d32977ba570Timo Sirainen <citerefentry>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen </citerefentry>,
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <citerefentry>
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen </citerefentry>,
ae1b268ffff743ad9927c304a1344c5cbd7f909dTimo Sirainen <citerefentry>
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen </citerefentry>,
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen <citerefentry>
87490012895b4f371635ded00add04c9107dcfefJosef 'Jeff' Sipek <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen </citerefentry>,
ae1b268ffff743ad9927c304a1344c5cbd7f909dTimo Sirainen <citerefentry>
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
e192a3b1ca8ae857e7d87298ea507d32977ba570Timo Sirainen </citerefentry>,
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <citerefentry>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen </citerefentry>,
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen <citerefentry>
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
ae1b268ffff743ad9927c304a1344c5cbd7f909dTimo Sirainen </citerefentry>.
7a54d58280aad8a64f266c61273ea1e8dff511a3Timo Sirainen - Local variables: