oracular (3) ares_get_servers.3.gz

Provided by: libc-ares-dev_1.33.0-1_amd64 bug

NAME

       ares_get_servers,  ares_get_servers_ports  -  Retrieve  name  servers  from an initialized
       ares_channel (deprecated)

SYNOPSIS

       #include <ares.h>

       int ares_get_servers(const ares_channel_t *channel,
                            struct ares_addr_node **servers)

       int ares_get_servers_ports(const ares_channel_t *channel,
                                  struct ares_addr_port_node **servers)

DESCRIPTION

       The ares_get_servers(3) function retrieves name servers  configuration  from  the  channel
       data  identified  by channel, as a linked list of ares_addr_node structs storing a pointer
       to the first node at the address specified by servers.

       The ares_get_servers_ports(3) function also retrieves any per-server port information that
       may have been previously configured, returning a linked list of ares_addr_port structures.

       Function  caller may traverse the returned name server linked list, or may use it directly
       as suitable input for the ares_set_servers(3) / ares_set_servers_ports(3)  functions,  but
       shall not shrink or extend the list on its own.

       Each  node  of  the  name server linked list is stored in memory dynamically allocated and
       managed by c-ares. It is the caller's responsibility to free the  resulting  linked  list,
       using ares_free_data(3) , once the caller does not need it any longer.

       This  function  is capable of handling IPv4 and IPv6 name server addresses simultaneously,
       rendering ares_save_options(3) with optmask ARES_OPT_SERVERS functionally obsolete  except
       for IPv4-only name server usage.

RETURN VALUES

       This function may return any of the following values:

       ARES_SUCCESS   The name servers configuration was successfully retrieved

       ARES_ENOMEM    The memory was exhausted

       ARES_ENODATA   The channel data identified by channel was invalid.

SEE ALSO

       ares_set_servers(3), ares_init_options(3), ares_save_options(3)

AVAILABILITY

       ares_get_servers(3)  was  added in c-ares 1.7.1; ares_get_servers_ports(3) was added in c-
       ares 1.11.0.

NOTES

       As of c-ares 1.24, these functions are deprecated due to their lack of  ability  to  store
       the entire server configuration.  Use ares_get_servers_csv(3).

                                           5 March 2010                       ARES_GET_SERVERS(3)