.\" Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016, 2018-2020 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
.\" 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
.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-2020 Internet Systems Consortium, Inc. ("ISC")
.br