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