1ARES_GET_SERVERS(3)        Library Functions Manual        ARES_GET_SERVERS(3)
2
3
4

NAME

6       ares_get_servers,  ares_get_servers_ports  - Retrieve name servers from
7       an initialized ares_channel
8

SYNOPSIS

10       #include <ares.h>
11
12       int ares_get_servers(ares_channel channel,
13                            struct ares_addr_node **servers)
14
15       int ares_get_servers_ports(ares_channel channel,
16                                  struct ares_addr_port_node **servers)
17

DESCRIPTION

19       The ares_get_servers(3) function retrieves name  servers  configuration
20       from  the  channel  data  identified  by  channel,  as a linked list of
21       ares_addr_node structs storing a pointer to the first node at  the  ad‐
22       dress specified by servers.
23
24       The  ares_get_servers_ports(3)  function  also retrieves any per-server
25       port information that may have been previously configured, returning  a
26       linked list of ares_addr_port structures.
27
28       Function  caller  may traverse the returned name server linked list, or
29       may use it directly as suitable input  for  the  ares_set_servers(3)  /
30       ares_set_servers_ports(3) functions, but shall not shrink or extend the
31       list on its own.
32
33       Each node of the name server linked list is stored  in  memory  dynami‐
34       cally  allocated and managed by c-ares. It is the caller's responsibil‐
35       ity to free the resulting linked list, using ares_free_data(3)  ,  once
36       the caller does not need it any longer.
37
38       This  function  is  capable  of  handling IPv4 and IPv6 name server ad‐
39       dresses simultaneously,  rendering  ares_save_options(3)  with  optmask
40       ARES_OPT_SERVERS functionally obsolete except for IPv4-only name server
41       usage.
42
43

RETURN VALUES

45       This function may return any of the following values:
46
47       ARES_SUCCESS   The name  servers  configuration  was  successfully  re‐
48                      trieved
49
50       ARES_ENOMEM    The memory was exhausted
51
52       ARES_ENODATA   The channel data identified by channel was invalid.
53

SEE ALSO

55       ares_set_servers(3), ares_init_options(3), ares_save_options(3)
56

AVAILABILITY

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

AUTHOR

62       Implementation of this function and associated  library  internals  are
63       based  on code, comments and feedback provided in November and December
64       of 2008 by Daniel Stenberg, Gregor Jasny, Phil Blundell and  Yang  Tse,
65       December  2009  by Cedric Bail, February 2010 by Jakub Hrozek. On March
66       2010 Yang Tse shuffled all the bits and this function popped out.
67       Copyright 1998 by the Massachusetts Institute of Technology.
68       Copyright (C) 2008-2010 by Daniel Stenberg
69
70
71
72                                 5 March 2010              ARES_GET_SERVERS(3)