mirror of
https://github.com/isc-projects/bind9.git
synced 2026-04-26 00:30:05 -04:00
248 lines
6.2 KiB
Groff
248 lines
6.2 KiB
Groff
.\"
|
|
.\" 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).
|