rainlance/c-ares
1
0
Fork 0
mirror of https://frontier.innolan.net/rainlance/c-ares.git synced 2025-11-22 00:51:06 +00:00
Code Releases Activity

api: Add entrypoints to allow use of per-server ports

Browse Source 
Add user-visible entrypoints ares_{get,set}_servers_ports(3), which
take struct ares_addr_port_node rather than struct ares_addr_node.
This structure includes a UDP and TCP port number; if this is set
to zero, the channel-wide port values are used as before.

Similarly, add a new ares_set_servers_ports_csv(3) entrypoint, which
is analogous to ares_set_servers(3) except it doesn't ignore any
specified port information; instead, any per-server specified port
is used as both the UDP and TCP port for that server.

The internal struct ares_addr is extended to hold the UDP/TCP ports,
stored in network order, with the convention that a value of zero
indicates that the channel-wide UDP/TCP port should be used.

For the internal implementation of ares_dup(3), shift to use the
_ports() version of the get/set functions, so port information is
transferred correctly to the new channel.

Update manpages, and add missing ares_set_servers_csv to the lists
while we're at it
This commit is contained in:
David Drysdale
2015-12-28 11:09:52 +00:00
parent 06d0f72e54
commit 7972adc5d7
14 changed files with 269 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
ares_set_servers.3
View File

@ -15,12 +15,13 @@
.\"
.TH ARES_SET_SERVERS 3 "5 March 2010"
.SH NAME
ares_set_servers \- Initialize an ares_channel name servers configuration
ares_set_servers, ares_set_servers_ports \- Initialize an ares_channel name servers configuration
.SH SYNOPSIS
.nf
.B #include <ares.h>
.PP
.B int ares_set_servers(ares_channel \fIchannel\fP, struct ares_addr_node *\fIservers\fP)
.B int ares_set_servers_ports(ares_channel \fIchannel\fP, struct ares_addr_port_node *\fIservers\fP)
.fi
.SH DESCRIPTION
The \fBares_set_servers(3)\fP function initializes name servers configuration
@ -30,19 +31,25 @@ from a
.IR servers
pointer to a linked list of ares_addr_node structs holding name servers
address data.
.PP
The name server linked list pointer argument may be the result of a previous
call to \fBares_get_servers(3)\fP or a linked list of ares_addr_node structs
setup by other means.
call to \fBares_get_servers(3)\fP or a linked list of \fBares_addr_node\fP structs
set up by other means.
.PP
The \fBares_set_servers(3)\fP function also allows the specification 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
\fBares_get_servers_ports(3)\fP or a linked list of \fBares_addr_port_node\fP structs
set up by other means.
.PP
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
with more than one name server all the desired ones must be specified in a
single list.
\fBares_set_servers(3)\fP does not take ownership of the linked list argument.
.PP
The function does not take ownership of the linked list argument.
The caller is responsible for freeing the linked list when no longer needed.
.PP
This function is capable of handling IPv4 and IPv6 name server
addresses simultaneously, rendering \fBares_init_options(3)\fP with
optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for
@ -71,7 +78,8 @@ c-ares library initialization not yet performed.
.BR ares_init_options (3),
.BR ares_dup(3)
.SH AVAILABILITY
ares_set_servers(3) was added in c-ares 1.7.1
\fBares_set_servers(3)\fP was added in c-ares 1.7.1;
\fBares_set_servers_ports(3)\fP was added in c-ares 1.11.0.
.SH AUTHOR
Implementation of this function and associated library internals are based
on code, comments and feedback provided in November and December of 2008 by