ares_set_servers.3 (3041B)
1 .\" 2 .\" Copyright 2010 by Ben Greear <greearb@candelatech.com> 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_SET_SERVERS 3 "5 March 2010" 6 .SH NAME 7 ares_set_servers, ares_set_servers_ports \- Initialize name server configuration 8 for an ares channel. (deprecated) 9 .SH SYNOPSIS 10 .nf 11 #include <ares.h> 12 13 int ares_set_servers(ares_channel_t *\fIchannel\fP, 14 const struct ares_addr_node *\fIservers\fP) 15 16 int ares_set_servers_ports(ares_channel_t *\fIchannel\fP, 17 const struct ares_addr_port_node *\fIservers\fP) 18 .fi 19 .SH DESCRIPTION 20 The \fBares_set_servers(3)\fP function initializes name servers configuration 21 for the channel data identified by 22 .IR channel , 23 from a 24 .IR servers 25 pointer to a linked list of ares_addr_node structs holding name servers 26 address data. 27 .PP 28 The name server linked list pointer argument may be the result of a previous 29 call to \fBares_get_servers(3)\fP or a linked list of \fBares_addr_node\fP structs 30 set up by other means. 31 .PP 32 The \fBares_set_servers_ports(3)\fP function also allows the specification of UDP and 33 TCP ports to be used for communication on a per-server basis. The provided 34 linked list argument may be the result of a previous call to 35 \fBares_get_servers_ports(3)\fP or a linked list of \fBares_addr_port_node\fP structs 36 set up by other means. 37 .PP 38 This function replaces any potentially previously configured name servers 39 with the ones given in the linked list. So, in order to configure a channel 40 with more than one name server all the desired ones must be specified in a 41 single list. Though not recommended, passing NULL will clear all configured 42 servers and make an inoperable channel, this may be advantageous for test 43 simulation but unlikely to be useful in production. 44 .PP 45 The function does not take ownership of the linked list argument. 46 The caller is responsible for freeing the linked list when no longer needed. 47 .PP 48 This function is capable of handling IPv4 and IPv6 name server 49 addresses simultaneously, rendering \fBares_init_options(3)\fP with 50 optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for 51 IPv4-only name server usage. 52 .PP 53 As of v1.22.0 this function can 54 be called on an active channel with running queries, previously it would return 55 ARES_ENOTIMP. 56 57 .SH RETURN VALUES 58 .B ares_set_servers(3) 59 may return any of the following values: 60 .TP 15 61 .B ARES_SUCCESS 62 The name servers configuration was successfully initialized. 63 .TP 15 64 .B ARES_ENOMEM 65 The process's available memory was exhausted. 66 .TP 15 67 .B ARES_ENODATA 68 The channel data identified by 69 .IR channel 70 was invalid. 71 .TP 15 72 .B ARES_ENOTINITIALIZED 73 c-ares library initialization not yet performed. 74 .SH SEE ALSO 75 .BR ares_set_servers_csv (3), 76 .BR ares_get_servers (3), 77 .BR ares_init_options (3), 78 .BR ares_dup (3) 79 80 .SH NOTES 81 Deprecated functions as of c-ares 1.24.0 due to inability to set all available 82 server options. Use \fBares_set_servers_csv(3)\fP. 83 84 .SH AVAILABILITY 85 \fBares_set_servers(3)\fP was added in c-ares 1.7.1; 86 \fBares_set_servers_ports(3)\fP was added in c-ares 1.11.0.