ares_get_servers(3)

ARES_GET_SERVERS(3)    C LIBRARY FUNCTIONS    ARES_GET_SERVERS(3)

NAME

     ares_get_servers,  ares_get_servers_ports  -  Retrieve  name
     servers from an initialized ares_channel

SYNOPSIS

     #include <ares.h>

     int ares_get_servers(ares_channel channel, struct ares_addr_node **servers)
     int ares_get_servers_ports(ares_channel channel, struct ares_addr_port_node **servers)

DESCRIPTION

     The ares_get_servers(3) function retrieves name servers con-
     figuration 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 struc-
     tures.

     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 function-
     ally 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  success-
                    fully 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)

                    Last change: 5 March 2010                   1

ARES_GET_SERVERS(3)    C LIBRARY FUNCTIONS    ARES_GET_SERVERS(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.

AUTHOR

     Implementation  of  this  function  and  associated  library
     internals  are based on code, comments and feedback provided
     in November and December of 2008 by Daniel Stenberg,  Gregor
     Jasny,  Phil  Blundell and Yang Tse, December 2009 by Cedric
     Bail, February 2010 by Jakub Hrozek. On March 2010 Yang  Tse
     shuffled all the bits and this function popped out.
     Copyright 1998 by the Massachusetts Institute of Technology.
     Copyright (C) 2008-2010 by Daniel Stenberg

                    Last change: 5 March 2010                   2