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, struct ares_addr_node **servers)
13       int ares_get_servers_ports(ares_channel channel, struct ares_addr_port_node **servers)
14

DESCRIPTION

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

RETURN VALUES

42       This function may return any of the following values:
43
44       ARES_SUCCESS   The  name   servers   configuration   was   successfully
45                      retrieved
46
47       ARES_ENOMEM    The memory was exhausted
48
49       ARES_ENODATA   The channel data identified by channel was invalid.
50

SEE ALSO

52       ares_set_servers(3), ares_init_options(3), ares_save_options(3)
53

AVAILABILITY

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

AUTHOR

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