.\" 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 <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-2020 Internet Systems Consortium, Inc. ("ISC")

.br