lwres_getaddrinfo

## 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,
| struct addrinfo ** | res`)`;

`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 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_family`set 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`.

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 `addrinfo`structures. 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 NULL `lwres_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).