diff options
Diffstat (limited to 'lib/lwres/man/lwres_getaddrinfo.3')
| -rw-r--r-- | lib/lwres/man/lwres_getaddrinfo.3 | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_getaddrinfo.3 b/lib/lwres/man/lwres_getaddrinfo.3 new file mode 100644 index 0000000..581ea5c --- /dev/null +++ b/lib/lwres/man/lwres_getaddrinfo.3 @@ -0,0 +1,254 @@ +.\" Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" This Source Code Form is subject to the terms of the Mozilla Public +.\" License, v. 2.0. If a copy of the MPL was not distributed with this +.\" file, You can obtain one at http://mozilla.org/MPL/2.0/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: lwres_getaddrinfo +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "LWRES_GETADDRINFO" "3" "2007\-06\-18" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <lwres/netdb\&.h> +.fi +.ft +.HP \w'int\ lwres_getaddrinfo('u +.BI "int lwres_getaddrinfo(const\ char\ *" "hostname" ", const\ char\ *" "servname" ", const\ struct\ addrinfo\ *" "hints" ", struct\ addrinfo\ **" "res" ");" +.HP \w'void\ lwres_freeaddrinfo('u +.BI "void lwres_freeaddrinfo(struct\ addrinfo\ *" "ai" ");" +.PP +If the operating system does not provide a +\fBstruct addrinfo\fR, the following structure is used: +.PP +.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 */ +}; +.fi +.sp +.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\*(Aqs 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 +/etc/services\&. +.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: +.PP +\fBai_family\fR +.RS 4 +The protocol family that should be used\&. When +\fBai_family\fR +is set to +\fBPF_UNSPEC\fR, it means the caller will accept any protocol family supported by the operating system\&. +.RE +.PP +\fBai_socktype\fR +.RS 4 +denotes the type of socket \(em +\fBSOCK_STREAM\fR, +\fBSOCK_DGRAM\fR +or +\fBSOCK_RAW\fR +\(em that is wanted\&. When +\fBai_socktype\fR +is zero the caller will accept any socket type\&. +.RE +.PP +\fBai_protocol\fR +.RS 4 +indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP\&. If +\fBai_protocol\fR +is zero the caller will accept any protocol\&. +.RE +.PP +\fBai_flags\fR +.RS 4 +Flag bits\&. If the +\fBAI_CANONNAME\fR +bit is set, a successful call to +\fBlwres_getaddrinfo()\fR +will return a null\-terminated string containing the canonical name of the specified hostname in +\fBai_canonname\fR +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\&. +.sp +When +\fBai_flags\fR +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 +\fBai_flags\fR\&. +.sp +If +\fBai_flags\fR +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\&. +.RE +.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 +\fBai_family\fRset to +\fBPF_UNSPEC\fR\&. +.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 +\fBai_next\fR +pointer, until a +\fBNULL\fR +pointer is encountered\&. The three members +\fBai_family\fR, +\fBai_socktype\fR, and +\fBai_protocol\fR +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 +\fBai_addr\fR +member points to a filled\-in socket address structure of length +\fBai_addrlen\fR\&. +.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 +\fBaddrinfo\fRstructures\&. 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 +\fBEAI_NONAME\fR\&. +.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)\&. +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2000, 2001, 2003-2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.br |