getaddrinfo

Jump to: navigation, search

Table of Contents >> Application Reference >> DNS Resolver


#include <trsocket.h>


int getaddrinfo (
const char * nodeName,
const char * serviceName,
const struct addrinfo * hintsPtr,
struct addrinfo ** resPtrPtr
);


Function Description

Return a dynamically allocated list of IP addresses and port numbers for nodeName and serviceName, as supplied by the primary or secondary DNS server (see tfNgDnsSetServer()). You must call freeaddrinfo() to release the storage after use. IPv4 and IPv6 addresses are supported. Judicious use of the hintsPtr information will yield address information in resPtrPtr that can be used as input to socket functions socket(), bind(), connect(), sendto(), etc.

Parameter nodeName can be either be the NULL pointer, a fully qualified domain name (e.g. "www.treck.com"), a partial domain name (e.g. "www"), or the string representation of a numeric IPv4 or IPv6 address (e.g. "10.1.2.3" or "2003:db8::17"). Partial domain names are supported only if compile time macro TM_USE_DNS_DOMAIN_SEARCH is uncommented in trsystem.h. Non-global, numeric IPv6 addresses may include interface scope information as defined in RFC 4007, section 11. The scope information may be the name of the interface as specified in your tfAddInterface() call (e.g. "fe80::23%eth0"), or the numeric index that the interface name would return by calling if_nametoindex() (e.g. "fe80::23%2"). (The scope information is often required if you are sending or connecting to a remote host via its link-local IPv6 address.)

Currently, serviceName must either be the NULL pointer or a NUL-terminated string of decimal digits. The number provided is returned as the port number in all resPtrPtr results. If this parameter is NULL, nodeName must not be NULL and vice versa.

Parameter hintsPtr must either be the NULL pointer or a pointer to an address information structure that provides filtering rules for the resPtrPtr results. If hintsPtr is NULL, ai_flags defaults to the combination of flags AI_V4MAPPED and AI_ADDRCONFIG (see description below). By default, both IPv4 and IPv6 addresses are returned (ai_family == AF_UNSPEC). Use ai_family to restrict the results for dual IP systems to IPv4 (AF_INET) or IPv6 (AF_INET6) only.

Note Note: The list returned in resPtrPtr is dynamically allocated. Call freeaddrinfo() to release the storage when no longer needed.

ai_flags

  • AI_ALL
    Return all IPv4 and IPv6 addresses found.
  • AI_V4MAPPED
    Only return IPv4 addresses if no native IPv6 addresses are found. IPv4 addresses will be represented as IPv4-mapped IPv6 addresses.
  • AI_ADDRCONFIG
    Return IPv4 addresses only if IPv4 is configured on this device; return IPv6 only if IPv6 is configured on this device.
  • AI_CANONNAME
    Requests the canonical name of the given host name. When set, the canonical name is returned in the ai_canonname field of the first returned addrinfo structure.
  • AI_NUMERICHOST
    Don't use name resolution. This flag can be set when passing the ASCII representation of an address to getaddrinfo, which causes it to behave like inet_pton().
  • AI_NUMERICSERV
    Don't use service resolution. This flag can be set when passing the service name as a port number in decimal string form to getaddrinfo.
  • AI_PASSIVE
    If this flag is not set, the results returned can be used with connect() or sendto() (sin_addr or sin6_addr will be set to the address of the remote host, depending on the address family). If this flag is set, the results returned can be used with bind() to receive from all remote hosts (for IPv4, sin_addr will be set to INADDR_ANY; for IPv6, sin6_addr will be set to in6addr_any).

Example

These flags allow quite a bit of versatility, but here are some common settings for ai_flags and ai_family
Only IPv4 addresses:
      ai_flags = 0;
      ai_family = AF_INET;
Only IPv6 addresses:
      ai_flags = 0;
      ai_family = AF_INET6;
All addresses (IPv4 and IPv6). IPv4 addresses will be represented as IPv4-mapped IPv6 addresses:
      ai_flags = AI_ALL;
      ai_family = AF_INET6;
Only return IPv4 addresses if no IPv6 addresses are available. IPv4 addresses will be represented as IPv4-mapped IPv6 addresses:
      ai_flags = AI_V4MAPPED;
      ai_flags = AF_INET6;

Non-blocking Mode

Like all of the other DNS functions, getaddrinfo() can be used in non-blocking mode by specifying TM_BLOCKING_OFF when tfDnsInit() is called. In non-blocking mode, getaddrinfo() may return TM_EWOULDBLOCK. This indicates that the operation is in progress. Continue to call getaddrinfo() until a value other than TM_EWOULDBLOCK is returned, which indicates that the operation is complete. For example code using getaddrinfo() please see the <examples/txdns.c>.


Parameters

  • nodeName
    String containing nodename to translate. This may be a fully qualified domain name (e.g. "www.treck.com"), a partial domain name (only if compile time macro TM_USE_DNS_DOMAIN_SEARCH is uncommented in trsystem.h), or a numeric IPv4 or IPv6 address. This may be NULL if serviceName is not NULL.
  • serviceName
    String containing the port number of the service, in decimal form (e.g. "80" for HTTP). This may be NULL if nodeName is not NULL.
  • hintsPtr
    Pointer to structure indicating which types of addresses the caller is interested in.
  • resPtrPtr
    Set to a pointer to one or more addrinfo structures containing address information about the specified nodename.


Returns

  • TM_ENOERROR
    Address information successfully retrieved. Call freeaddrinfo() to free the list after use.
  • TM_EOPNOTSUPP
    Specifying a service name is not supported.
  • TM_ETIMEDOUT
    DNS request failed – requests to DNS server timed out.
  • TM_EHOSTUNREACH
    No route to DNS server.
  • TM_EWOULDBLOCK
    Indicates that an operation is currently in progress and has not yet completed. Only returned in non-blocking mode. (see above)
  • EAI_NONAME
    AI_NUMERICHOST was specified but nodeName was not a valid numeric address for the given family type.
  • EAI_BADFLAGS
    Invalid flags specified in hint structure.
  • EAI_FAMILY
    Invalid protocol family (not PF_INET,PF_INET6 or PF_UNSPEC) in hint structure.
  • EAI_NODATA
    No addresses (of the given address family) associated with the nodename.
  • EAI_MEMORY
    Not enough memory to allocate addrinfo structure(s) to be returned.
  • TM_DNS_EFORMAT
    Error from DNS server: Format error. The name server was unable to interpret the query.
  • TM_DNS_ESERVER
    Error from DNS server: Server failure. The name server was unable to process this query due to a problem with the name server.
  • TM_DNS_ENAME_ERROR
    Error from DNS server: Name error. Meaningful only for responses from an authoritative name server, this code signifies that the domain name referenced in the query does not exist.
  • TM_DNS_ENOT_IMPLEM
    Error from DNS server: Not implemented. The name server does not support the requested kind of query.
  • TM_DNS_EREFUSED
    Error from DNS server: Refused. The name server refuses to perform the specified operation for policy reasons. For example, a name server may not wish to provide the information to the particular requester, or a name server may not wish to perform a particular operation (e.g., zone transfer) for particular data.
  • TM_DNS_EANSWER
    No answer received from name server (i.e., response packet received, but it did not contain the answer to our query).
  • TM_EFILE
    Treck was unable to successfully allocate a socket for the DNS request. This could indicate Treck did not have the resources to allocate another socket. It could also be due to Treck hitting the limit of sockets set by TM_DNS_MAX_SOCKETS_ALLOWED or the tfDnsSetOption() option: TM_DNS_OPTION_MAX_SOCKETS_ALLOWED.


Table of Contents >> Application Reference >> DNS Resolver

Retrieved from "https://wiki.treck.com/index.php?title=getaddrinfo&oldid=5923"