lwres_getaddrinfo.3   [plain text]

.\"
.\" 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).