diff options
| author | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
|---|---|---|
| committer | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
| commit | aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 (patch) | |
| tree | 95f3d0c8cb0d59d88900dbbd72110d7ab6e15b2a /lib/liblwres/man/lwres_getaddrinfo.html | |
| parent | 7c383bc22113b23718be89fe18eeb251942d7356 (diff) | |
| download | vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.tar.gz vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.zip | |
Import initial strongswan 2.7.0 version into SVN.
Diffstat (limited to 'lib/liblwres/man/lwres_getaddrinfo.html')
| -rw-r--r-- | lib/liblwres/man/lwres_getaddrinfo.html | 722 |
1 files changed, 722 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_getaddrinfo.html b/lib/liblwres/man/lwres_getaddrinfo.html new file mode 100644 index 000000000..d04ecc1a2 --- /dev/null +++ b/lib/liblwres/man/lwres_getaddrinfo.html @@ -0,0 +1,722 @@ +<!-- + - Copyright (C) 2000, 2001 Internet Software Consortium. + - + - Permission to use, copy, modify, and distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM + - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL + - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING + - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, + - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION + - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +--> +<HTML +><HEAD +><TITLE +>lwres_getaddrinfo</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><H1 +><A +NAME="AEN1" +>lwres_getaddrinfo</A +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8" +></A +><H2 +>Name</H2 +>lwres_getaddrinfo, lwres_freeaddrinfo -- socket address structure to host and service name</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN12" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><A +NAME="AEN13" +></A +><P +></P +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <lwres/netdb.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int +lwres_getaddrinfo</CODE +>(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);</CODE +></P +><P +><CODE +><CODE +CLASS="FUNCDEF" +>void +lwres_freeaddrinfo</CODE +>(struct addrinfo *ai);</CODE +></P +><P +></P +></DIV +><P +>If the operating system does not provide a +<SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +>, +the following structure is used: + +<PRE +CLASS="PROGRAMLISTING" +>struct addrinfo { + int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ + int ai_family; /* PF_xxx */ + int ai_socktype; /* SOCK_xxx */ + int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + size_t ai_addrlen; /* length of ai_addr */ + char *ai_canonname; /* canonical name for hostname */ + struct sockaddr *ai_addr; /* binary address */ + struct addrinfo *ai_next; /* next structure in linked list */ +};</PRE +></P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN29" +></A +><H2 +>DESCRIPTION</H2 +><P +><TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +is used to get a list of IP addresses and port numbers for host +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +and service +<TT +CLASS="PARAMETER" +><I +>servname</I +></TT +>. + +The function is the lightweight resolver's implementation of +<TT +CLASS="FUNCTION" +>getaddrinfo()</TT +> +as defined in RFC2133. +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>servname</I +></TT +> +are pointers to null-terminated +strings or +<SPAN +CLASS="TYPE" +>NULL</SPAN +>. + +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +is either a host name or a numeric host address string: a dotted decimal +IPv4 address or an IPv6 address. +<TT +CLASS="PARAMETER" +><I +>servname</I +></TT +> +is either a decimal port number or a service name as listed in +<TT +CLASS="FILENAME" +>/etc/services</TT +>.</P +><P +><TT +CLASS="PARAMETER" +><I +>hints</I +></TT +> +is an optional pointer to a +<SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +>. +This structure can be used to provide hints concerning the type of socket +that the caller supports or wishes to use. +The caller can supply the following structure elements in +<TT +CLASS="PARAMETER" +><I +>*hints</I +></TT +>: + +<P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><TT +CLASS="CONSTANT" +>ai_family</TT +></DT +><DD +><P +>The protocol family that should be used. +When +<TT +CLASS="CONSTANT" +>ai_family</TT +> +is set to +<SPAN +CLASS="TYPE" +>PF_UNSPEC</SPAN +>, +it means the caller will accept any protocol family supported by the +operating system.</P +></DD +><DT +><TT +CLASS="CONSTANT" +>ai_socktype</TT +></DT +><DD +><P +>denotes the type of socket — +<SPAN +CLASS="TYPE" +>SOCK_STREAM</SPAN +>, +<SPAN +CLASS="TYPE" +>SOCK_DGRAM</SPAN +> +or +<SPAN +CLASS="TYPE" +>SOCK_RAW</SPAN +> +— that is wanted. +When +<TT +CLASS="CONSTANT" +>ai_socktype</TT +> +is zero the caller will accept any socket type.</P +></DD +><DT +><TT +CLASS="CONSTANT" +>ai_protocol</TT +></DT +><DD +><P +>indicates which transport protocol is wanted: IPPROTO_UDP or +IPPROTO_TCP. +If +<TT +CLASS="CONSTANT" +>ai_protocol</TT +> +is zero the caller will accept any protocol.</P +></DD +><DT +><TT +CLASS="CONSTANT" +>ai_flags</TT +></DT +><DD +><P +>Flag bits. +If the +<SPAN +CLASS="TYPE" +>AI_CANONNAME</SPAN +> +bit is set, a successful call to +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +will return a a null-terminated string containing the canonical name +of the specified hostname in +<TT +CLASS="CONSTANT" +>ai_canonname</TT +> +of the first +<SPAN +CLASS="TYPE" +>addrinfo</SPAN +> +structure returned. +Setting the +<SPAN +CLASS="TYPE" +>AI_PASSIVE</SPAN +> +bit indicates that the returned socket address structure is intended +for used in a call to +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>bind</SPAN +>(2)</SPAN +>. + +In this case, if the hostname argument is a +<SPAN +CLASS="TYPE" +>NULL</SPAN +> +pointer, then the IP address portion of the socket +address structure will be set to +<SPAN +CLASS="TYPE" +>INADDR_ANY</SPAN +> +for an IPv4 address or +<SPAN +CLASS="TYPE" +>IN6ADDR_ANY_INIT</SPAN +> +for an IPv6 address.</P +><P +>When +<TT +CLASS="CONSTANT" +>ai_flags</TT +> +does not set the +<SPAN +CLASS="TYPE" +>AI_PASSIVE</SPAN +> +bit, the returned socket address structure will be ready +for use in a call to +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>connect</SPAN +>(2)</SPAN +> +for a connection-oriented protocol or +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>connect</SPAN +>(2)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>sendto</SPAN +>(2)</SPAN +>, + +or +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>sendmsg</SPAN +>(2)</SPAN +> +if a connectionless protocol was chosen. +The IP address portion of the socket address structure will be +set to the loopback address if +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +is a +<SPAN +CLASS="TYPE" +>NULL</SPAN +> +pointer and +<SPAN +CLASS="TYPE" +>AI_PASSIVE</SPAN +> +is not set in +<TT +CLASS="CONSTANT" +>ai_flags</TT +>.</P +><P +>If +<TT +CLASS="CONSTANT" +>ai_flags</TT +> +is set to +<SPAN +CLASS="TYPE" +>AI_NUMERICHOST</SPAN +> +it indicates that +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted.</P +></DD +></DL +></DIV +></P +><P +>All other elements of the <SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +> passed +via <TT +CLASS="PARAMETER" +><I +>hints</I +></TT +> must be zero.</P +><P +>A <TT +CLASS="PARAMETER" +><I +>hints</I +></TT +> of <SPAN +CLASS="TYPE" +>NULL</SPAN +> is treated as if +the caller provided a <SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +> initialized to zero +with <TT +CLASS="CONSTANT" +>ai_family</TT +>set to +<TT +CLASS="CONSTANT" +>PF_UNSPEC</TT +>.</P +><P +>After a successful call to +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +>, +<TT +CLASS="PARAMETER" +><I +>*res</I +></TT +> +is a pointer to a linked list of one or more +<SPAN +CLASS="TYPE" +>addrinfo</SPAN +> +structures. +Each +<SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +> +in this list cn be processed by following +the +<TT +CLASS="CONSTANT" +>ai_next</TT +> +pointer, until a +<SPAN +CLASS="TYPE" +>NULL</SPAN +> +pointer is encountered. +The three members +<TT +CLASS="CONSTANT" +>ai_family</TT +>, +<TT +CLASS="CONSTANT" +>ai_socktype</TT +>, +and +<TT +CLASS="CONSTANT" +>ai_protocol</TT +> +in each +returned +<SPAN +CLASS="TYPE" +>addrinfo</SPAN +> +structure contain the corresponding arguments for a call to +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>socket</SPAN +>(2)</SPAN +>. +For each +<SPAN +CLASS="TYPE" +>addrinfo</SPAN +> +structure in the list, the +<TT +CLASS="CONSTANT" +>ai_addr</TT +> +member points to a filled-in socket address structure of length +<TT +CLASS="CONSTANT" +>ai_addrlen</TT +>.</P +><P +>All of the information returned by +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +is dynamically allocated: the addrinfo structures, and the socket +address structures and canonical host name strings pointed to by the +<TT +CLASS="CONSTANT" +>addrinfo</TT +>structures. +Memory allocated for the dynamically allocated structures created by +a successful call to +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +is released by +<TT +CLASS="FUNCTION" +>lwres_freeaddrinfo()</TT +>. +<TT +CLASS="PARAMETER" +><I +>ai</I +></TT +> +is a pointer to a +<SPAN +CLASS="TYPE" +>struct addrinfo</SPAN +> +created by a call to +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN142" +></A +><H2 +>RETURN VALUES</H2 +><P +><TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +returns zero on success or one of the error codes listed in +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>gai_strerror</SPAN +>(3)</SPAN +> +if an error occurs. +If both +<TT +CLASS="PARAMETER" +><I +>hostname</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>servname</I +></TT +> +are +<SPAN +CLASS="TYPE" +>NULL</SPAN +> +<TT +CLASS="FUNCTION" +>lwres_getaddrinfo()</TT +> +returns +<SPAN +CLASS="ERRORCODE" +>EAI_NONAME</SPAN +>. </P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN154" +></A +><H2 +>SEE ALSO</H2 +><P +><SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_getaddrinfo</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_freeaddrinfo</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_gai_strerror</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC2133</SPAN +></SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>getservbyname</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>bind</SPAN +>(2)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>connect</SPAN +>(2)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>sendto</SPAN +>(2)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>sendmsg</SPAN +>(2)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>socket</SPAN +>(2)</SPAN +>.</P +></DIV +></BODY +></HTML +>
\ No newline at end of file |