ares_set_servers(3)

ARES_SET_SERVERS(3)    C LIBRARY FUNCTIONS    ARES_SET_SERVERS(3)

NAME

     ares_set_servers,  ares_set_servers_ports  -  Initialize  an
     ares_channel name servers configuration

SYNOPSIS

     #include <ares.h>

     int ares_set_servers(ares_channel channel, struct ares_addr_node *servers)
     int ares_set_servers_ports(ares_channel channel, struct ares_addr_port_node *servers)

DESCRIPTION

     The ares_set_servers(3) function  initializes  name  servers
     configuration  for  the  channel data identified by channel,
     from a servers pointer to a linked  list  of  ares_addr_node
     structs holding name servers address data.

     The name server linked list  pointer  argument  may  be  the
     result of a previous call to ares_get_servers(3) or a linked
     list of ares_addr_node structs set up by other means.

     The ares_set_servers(3) function also allows the  specifica-
     tion  of UDP and TCP ports to be used for communication on a
     per-server basis.  The provided linked list argument may  be
     the  result  of a previous call to ares_get_servers_ports(3)
     or a linked list of ares_addr_port_node structs  set  up  by
     other means.

     This function replaces any potentially previously configured
     name  servers with the ones given in the linked list. So, in
     order to configure a channel with more than one name  server
     all the desired ones must be specified in a single list.

     The function does not take  ownership  of  the  linked  list
     argument.   The caller is responsible for freeing the linked
     list when no longer needed.

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

RETURN VALUES

     ares_set_servers(3) may return any of the following values:

     ARES_SUCCESS   The name servers configuration  was  success-
                    fully initialized.

     ARES_ENOMEM    The process's available memory was exhausted.

     ARES_ENODATA   The channel data identified  by  channel  was
                    invalid.

                    Last change: 5 March 2010                   1

ARES_SET_SERVERS(3)    C LIBRARY FUNCTIONS    ARES_SET_SERVERS(3)

     ARES_ENOTINITIALIZED
                    c-ares library initialization  not  yet  per-
                    formed.

SEE ALSO

     ares_set_servers_csv(3),                ares_get_servers(3),
     ares_init_options(3), ares_dup(3)

AVAILABILITY

     ares_set_servers(3)   was    added    in    c-ares    1.7.1;
     ares_set_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