ares_get_servers.3 (2444B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" Copyright (C) 2008-2010 by Daniel Stenberg 4 .\" SPDX-License-Identifier: MIT 5 .\" 6 .TH ARES_GET_SERVERS 3 "5 March 2010" 7 .SH NAME 8 ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initialized ares_channel (deprecated) 9 .SH SYNOPSIS 10 .nf 11 #include <ares.h> 12 13 int ares_get_servers(const ares_channel_t *\fIchannel\fP, 14 struct ares_addr_node **\fIservers\fP) 15 16 int ares_get_servers_ports(const ares_channel_t *\fIchannel\fP, 17 struct ares_addr_port_node **\fIservers\fP) 18 .fi 19 .SH DESCRIPTION 20 The \fBares_get_servers(3)\fP function retrieves name servers configuration 21 from the 22 channel data identified by 23 .IR channel , 24 as a linked list of ares_addr_node structs storing a pointer to the first 25 node at the address specified by 26 .IR servers . 27 28 The \fBares_get_servers_ports(3)\fP function also retrieves any per-server 29 port information that may have been previously configured, returning a linked 30 list of ares_addr_port structures. 31 32 Function caller may traverse the returned name server linked list, or may use 33 it directly as suitable input for the \fBares_set_servers(3)\fP / 34 \fBares_set_servers_ports(3)\fP functions, but 35 shall not shrink or extend the list on its own. 36 37 Each node of the name server linked list is stored in memory dynamically 38 allocated and managed by c-ares. It is the caller's responsibility to free 39 the resulting linked list, using \fBares_free_data(3)\fP , once the caller 40 does not need it any longer. 41 42 This function is capable of handling IPv4 and IPv6 name server 43 addresses simultaneously, rendering \fBares_save_options(3)\fP with 44 optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for 45 IPv4-only name server usage. 46 47 .SH RETURN VALUES 48 This function may return any of the following values: 49 .TP 15 50 .B ARES_SUCCESS 51 The name servers configuration was successfully retrieved 52 .TP 15 53 .B ARES_ENOMEM 54 The memory was exhausted 55 .TP 15 56 .B ARES_ENODATA 57 The channel data identified by 58 .IR channel 59 was invalid. 60 .SH SEE ALSO 61 .BR ares_set_servers (3), 62 .BR ares_init_options (3), 63 .BR ares_save_options(3) 64 .SH AVAILABILITY 65 \fBares_get_servers(3)\fP was added in c-ares 1.7.1; 66 \fBares_get_servers_ports(3)\fP was added in c-ares 1.11.0. 67 .SH NOTES 68 As of c-ares 1.24, these functions are deprecated due to their lack of ability 69 to store the entire server configuration. Use \fBares_get_servers_csv(3)\fP.