From aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Mon, 22 May 2006 05:12:18 +0000 Subject: Import initial strongswan 2.7.0 version into SVN. --- lib/liblwres/man/lwres_getaddrinfo.docbook | 372 +++++++++++++++++++++++++++++ 1 file changed, 372 insertions(+) create mode 100644 lib/liblwres/man/lwres_getaddrinfo.docbook (limited to 'lib/liblwres/man/lwres_getaddrinfo.docbook') diff --git a/lib/liblwres/man/lwres_getaddrinfo.docbook b/lib/liblwres/man/lwres_getaddrinfo.docbook new file mode 100644 index 000000000..f89107304 --- /dev/null +++ b/lib/liblwres/man/lwres_getaddrinfo.docbook @@ -0,0 +1,372 @@ + + + + + + + + +Jun 30, 2000 + + + +lwres_getaddrinfo +3 +BIND9 + + + +lwres_getaddrinfo +lwres_freeaddrinfo +socket address structure to host and service name + + + +#include <lwres/netdb.h> + + +int +lwres_getaddrinfo +const char *hostname +const char *servname +const struct addrinfo *hints +struct addrinfo **res + + + +void +lwres_freeaddrinfo +struct addrinfo *ai + + + + +If the operating system does not provide a +struct addrinfo, +the following structure is used: + + +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 */ +}; + + + + + + +DESCRIPTION + +lwres_getaddrinfo() +is used to get a list of IP addresses and port numbers for host +hostname +and service +servname. + +The function is the lightweight resolver's implementation of +getaddrinfo() +as defined in RFC2133. +hostname +and +servname +are pointers to null-terminated +strings or +NULL. + +hostname +is either a host name or a numeric host address string: a dotted decimal +IPv4 address or an IPv6 address. +servname +is either a decimal port number or a service name as listed in +/etc/services. + + + +hints +is an optional pointer to a +struct addrinfo. +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 +*hints: + + +ai_family + +The protocol family that should be used. +When +ai_family +is set to +PF_UNSPEC, +it means the caller will accept any protocol family supported by the +operating system. + +ai_socktype + + +denotes the type of socket — +SOCK_STREAM, +SOCK_DGRAM +or +SOCK_RAW +— that is wanted. +When +ai_socktype +is zero the caller will accept any socket type. + + + +ai_protocol + + +indicates which transport protocol is wanted: IPPROTO_UDP or +IPPROTO_TCP. +If +ai_protocol +is zero the caller will accept any protocol. + + + +ai_flags + + +Flag bits. +If the +AI_CANONNAME +bit is set, a successful call to +lwres_getaddrinfo() +will return a a null-terminated string containing the canonical name +of the specified hostname in +ai_canonname +of the first +addrinfo +structure returned. +Setting the +AI_PASSIVE +bit indicates that the returned socket address structure is intended +for used in a call to + +bind2 +. + +In this case, if the hostname argument is a +NULL +pointer, then the IP address portion of the socket +address structure will be set to +INADDR_ANY +for an IPv4 address or +IN6ADDR_ANY_INIT +for an IPv6 address. + + +When +ai_flags +does not set the +AI_PASSIVE +bit, the returned socket address structure will be ready +for use in a call to + +connect2 + + +for a connection-oriented protocol or + +connect2 +, + + +sendto2 +, + +or + +sendmsg2 + + +if a connectionless protocol was chosen. +The IP address portion of the socket address structure will be +set to the loopback address if +hostname +is a +NULL +pointer and +AI_PASSIVE +is not set in +ai_flags. + + +If +ai_flags +is set to +AI_NUMERICHOST +it indicates that +hostname +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted. + + + + + + + +All other elements of the struct addrinfo passed +via hints must be zero. + + + +A hints of NULL is treated as if +the caller provided a struct addrinfo initialized to zero +with ai_familyset to +PF_UNSPEC. + + + +After a successful call to +lwres_getaddrinfo(), +*res +is a pointer to a linked list of one or more +addrinfo +structures. +Each +struct addrinfo +in this list cn be processed by following +the +ai_next +pointer, until a +NULL +pointer is encountered. +The three members +ai_family, +ai_socktype, +and +ai_protocol +in each +returned +addrinfo +structure contain the corresponding arguments for a call to + +socket2 +. +For each +addrinfo +structure in the list, the +ai_addr +member points to a filled-in socket address structure of length +ai_addrlen. + + + +All of the information returned by +lwres_getaddrinfo() +is dynamically allocated: the addrinfo structures, and the socket +address structures and canonical host name strings pointed to by the +addrinfostructures. +Memory allocated for the dynamically allocated structures created by +a successful call to +lwres_getaddrinfo() +is released by +lwres_freeaddrinfo(). +ai +is a pointer to a +struct addrinfo +created by a call to +lwres_getaddrinfo(). + + + + + +RETURN VALUES + +lwres_getaddrinfo() +returns zero on success or one of the error codes listed in + +gai_strerror3 + + +if an error occurs. +If both +hostname +and +servname +are +NULL +lwres_getaddrinfo() +returns +EAI_NONAME. + + + + +SEE ALSO + + +lwres3 +, + + +lwres_getaddrinfo3 +, + + +lwres_freeaddrinfo3 +, + + +lwres_gai_strerror3 +, + + +RFC2133 +, + + +getservbyname3 +, + + +bind2 +, + + +connect2 +, + + +sendto2 +, + + +sendmsg2 +, + + +socket2 +. + + + + -- cgit v1.2.3