lwres_freeaddrinfo(3)

LWRES_GETADDRINFO(3)          BIND9          LWRES_GETADDRINFO(3)

NAME

     lwres_getaddrinfo, lwres_freeaddrinfo - socket address
     structure to host and service name

SYNOPSIS

     #include <lwres/netdb.h>

     int lwres_getaddrinfo(const char *hostname,
                           const char *servname,
                           const struct addrinfo *hints

     void lwres_freeaddrinfo(struct addrinfo *ai);

     If the operating system does not provide a struct addrinfo,
     the following structure is used:

     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 */
     };

DESCRIPTION

     lwres_getaddrinfo() is used to get a list of IP addresses
     and port numbers for host hostname and service servname. The
     function is the lightweight resolver's implementation of
     getaddrinfo() as defined in RFC2133.  hostname and servname
     are pointers to null-terminated strings or NULL.  hostname
     is either a host name or a numeric host address string: a
     dotted decimal IPv4 address or an IPv6 address.  servname is
     either a decimal port number or a service name as listed in
     /etc/services.

     hints is an optional pointer to a struct addrinfo. 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
     *hints:

     ai_family
         The protocol family that should be used. When ai_family
         is set to PF_UNSPEC, it means the caller will accept any
         protocol family supported by the operating system.

     ai_socktype
         denotes the type of socket - SOCK_STREAM, SOCK_DGRAM or

ISC                  Last change: 2007-06-18                    1

LWRES_GETADDRINFO(3)          BIND9          LWRES_GETADDRINFO(3)

         SOCK_RAW - that is wanted. When ai_socktype is zero the
         caller will accept any socket type.

     ai_protocol
         indicates which transport protocol is wanted:
         IPPROTO_UDP or IPPROTO_TCP. If ai_protocol is zero the
         caller will accept any protocol.

     ai_flags
         Flag bits. If the AI_CANONNAME bit is set, a successful
         call to lwres_getaddrinfo() will return a
         null-terminated string containing the canonical name of
         the specified hostname in ai_canonname of the first
         addrinfo structure returned. Setting the AI_PASSIVE bit
         indicates that the returned socket address structure is
         intended for used in a call to bind(2). In this case, if
         the hostname argument is a NULL pointer, then the IP
         address portion of the socket address structure will be
         set to INADDR_ANY for an IPv4 address or
         IN6ADDR_ANY_INIT for an IPv6 address.

         When ai_flags does not set the AI_PASSIVE bit, the
         returned socket address structure will be ready for use
         in a call to connect(2) for a connection-oriented
         protocol or connect(2), sendto(2), or sendmsg(2) if a
         connectionless protocol was chosen. The IP address
         portion of the socket address structure will be set to
         the loopback address if hostname is a NULL pointer and
         AI_PASSIVE is not set in ai_flags.

         If ai_flags is set to AI_NUMERICHOST it indicates that
         hostname should be treated as a numeric string defining
         an IPv4 or IPv6 address and no name resolution should be
         attempted.

     All other elements of the struct addrinfo passed via hints
     must be zero.

     A hints of NULL is treated as if the caller provided a
     struct addrinfo initialized to zero with ai_familyset to
     PF_UNSPEC.

     After a successful call to lwres_getaddrinfo(), *res is a
     pointer to a linked list of one or more addrinfo structures.
     Each struct addrinfo in this list cn be processed by
     following the ai_next pointer, until a NULL pointer is
     encountered. The three members ai_family, ai_socktype, and
     ai_protocol in each returned addrinfo structure contain the
     corresponding arguments for a call to socket(2). For each
     addrinfo structure in the list, the ai_addr member points to
     a filled-in socket address structure of length ai_addrlen.

ISC                  Last change: 2007-06-18                    2

LWRES_GETADDRINFO(3)          BIND9          LWRES_GETADDRINFO(3)

     All of the information returned by lwres_getaddrinfo() 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 lwres_getaddrinfo() is released by
     lwres_freeaddrinfo().  ai is a pointer to a struct addrinfo
     created by a call to lwres_getaddrinfo().

RETURN VALUES

     lwres_getaddrinfo() returns zero on success or one of the
     error codes listed in gai_strerror(3) if an error occurs. If
     both hostname and servname are NULLlwres_getaddrinfo()
     returns EAI_NONAME.

SEE ALSO

     lwres(3), lwres_getaddrinfo(3), lwres_freeaddrinfo(3),
     lwres_gai_strerror(3), RFC2133(), getservbyname(3), bind(2),
     connect(2), sendto(2), sendmsg(2), socket(2).

AUTHOR

     Internet Systems Consortium, Inc.

COPYRIGHT

     Copyright 8c9 2004, 2005, 2007, 2014-2016 Internet Systems
     Consortium, Inc. ("ISC")
     Copyright 8c9 2000, 2001, 2003 Internet Software Consortium.

ISC                  Last change: 2007-06-18                    3