diff options
Diffstat (limited to 'lib/liblwres/man/lwres_getaddrinfo.3')
| -rw-r--r-- | lib/liblwres/man/lwres_getaddrinfo.3 | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_getaddrinfo.3 b/lib/liblwres/man/lwres_getaddrinfo.3 new file mode 100644 index 000000000..b7ea46128 --- /dev/null +++ b/lib/liblwres/man/lwres_getaddrinfo.3 @@ -0,0 +1,247 @@ +.\" +.\" 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. +.\" +.TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" "" +.SH NAME +lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name +.SH SYNOPSIS +\fB#include <lwres/netdb.h> +.sp +.na +int +lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res); +.ad +.sp +.na +void +lwres_freeaddrinfo(struct addrinfo *ai); +.ad +\fR.PP +If the operating system does not provide a +\fBstruct addrinfo\fR, +the following structure is used: +.sp +.nf +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 */ +}; +.sp +.fi +.SH "DESCRIPTION" +.PP +\fBlwres_getaddrinfo()\fR +is used to get a list of IP addresses and port numbers for host +\fIhostname\fR +and service +\fIservname\fR. +The function is the lightweight resolver's implementation of +\fBgetaddrinfo()\fR +as defined in RFC2133. +\fIhostname\fR +and +\fIservname\fR +are pointers to null-terminated +strings or +\fBNULL\fR. +\fIhostname\fR +is either a host name or a numeric host address string: a dotted decimal +IPv4 address or an IPv6 address. +\fIservname\fR +is either a decimal port number or a service name as listed in +\fI/etc/services\fR. +.PP +\fIhints\fR +is an optional pointer to a +\fBstruct addrinfo\fR. +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 +\fI*hints\fR: +.TP +\fBai_family\fR +The protocol family that should be used. +When +ai_family +is set to +\fBPF_UNSPEC\fR, +it means the caller will accept any protocol family supported by the +operating system. +.TP +\fBai_socktype\fR +denotes the type of socket \(em +\fBSOCK_STREAM\fR, +\fBSOCK_DGRAM\fR +or +\fBSOCK_RAW\fR +\(em that is wanted. +When +ai_socktype +is zero the caller will accept any socket type. +.TP +\fBai_protocol\fR +indicates which transport protocol is wanted: IPPROTO_UDP or +IPPROTO_TCP. +If +ai_protocol +is zero the caller will accept any protocol. +.TP +\fBai_flags\fR +Flag bits. +If the +\fBAI_CANONNAME\fR +bit is set, a successful call to +\fBlwres_getaddrinfo()\fR +will return a a null-terminated string containing the canonical name +of the specified hostname in +ai_canonname +of the first +\fBaddrinfo\fR +structure returned. +Setting the +\fBAI_PASSIVE\fR +bit indicates that the returned socket address structure is intended +for used in a call to +\fBbind\fR(2). +In this case, if the hostname argument is a +\fBNULL\fR +pointer, then the IP address portion of the socket +address structure will be set to +\fBINADDR_ANY\fR +for an IPv4 address or +\fBIN6ADDR_ANY_INIT\fR +for an IPv6 address. + +When +ai_flags +does not set the +\fBAI_PASSIVE\fR +bit, the returned socket address structure will be ready +for use in a call to +\fBconnect\fR(2) +for a connection-oriented protocol or +\fBconnect\fR(2), +\fBsendto\fR(2), +or +\fBsendmsg\fR(2) +if a connectionless protocol was chosen. +The IP address portion of the socket address structure will be +set to the loopback address if +\fIhostname\fR +is a +\fBNULL\fR +pointer and +\fBAI_PASSIVE\fR +is not set in +ai_flags. + +If +ai_flags +is set to +\fBAI_NUMERICHOST\fR +it indicates that +\fIhostname\fR +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted. +.PP +All other elements of the \fBstruct addrinfo\fR passed +via \fIhints\fR must be zero. +.PP +A \fIhints\fR of \fBNULL\fR is treated as if +the caller provided a \fBstruct addrinfo\fR initialized to zero +with ai_familyset to +PF_UNSPEC. +.PP +After a successful call to +\fBlwres_getaddrinfo()\fR, +\fI*res\fR +is a pointer to a linked list of one or more +\fBaddrinfo\fR +structures. +Each +\fBstruct addrinfo\fR +in this list cn be processed by following +the +ai_next +pointer, until a +\fBNULL\fR +pointer is encountered. +The three members +ai_family, +ai_socktype, +and +ai_protocol +in each +returned +\fBaddrinfo\fR +structure contain the corresponding arguments for a call to +\fBsocket\fR(2). +For each +\fBaddrinfo\fR +structure in the list, the +ai_addr +member points to a filled-in socket address structure of length +ai_addrlen. +.PP +All of the information returned by +\fBlwres_getaddrinfo()\fR +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 +\fBlwres_getaddrinfo()\fR +is released by +\fBlwres_freeaddrinfo()\fR. +\fIai\fR +is a pointer to a +\fBstruct addrinfo\fR +created by a call to +\fBlwres_getaddrinfo()\fR. +.SH "RETURN VALUES" +.PP +\fBlwres_getaddrinfo()\fR +returns zero on success or one of the error codes listed in +\fBgai_strerror\fR(3) +if an error occurs. +If both +\fIhostname\fR +and +\fIservname\fR +are +\fBNULL\fR +\fBlwres_getaddrinfo()\fR +returns +EAI_NONAME. +.SH "SEE ALSO" +.PP +\fBlwres\fR(3), +\fBlwres_getaddrinfo\fR(3), +\fBlwres_freeaddrinfo\fR(3), +\fBlwres_gai_strerror\fR(3), +\fBRFC2133\fR, +\fBgetservbyname\fR(3), +\fBbind\fR(2), +\fBconnect\fR(2), +\fBsendto\fR(2), +\fBsendmsg\fR(2), +\fBsocket\fR(2). |