diff options
Diffstat (limited to 'docs/ares_get_servers.3')
| -rw-r--r-- | docs/ares_get_servers.3 | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/ares_get_servers.3 b/docs/ares_get_servers.3 new file mode 100644 index 0000000..d606428 --- /dev/null +++ b/docs/ares_get_servers.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2008-2010 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GET_SERVERS 3 "5 March 2010" +.SH NAME +ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initialized ares_channel +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_get_servers(ares_channel \fIchannel\fP, struct ares_addr_node **\fIservers\fP) +.B int ares_get_servers_ports(ares_channel \fIchannel\fP, struct ares_addr_port_node **\fIservers\fP) +.fi +.SH DESCRIPTION +The \fBares_get_servers(3)\fP function retrieves name servers configuration +from the +channel data identified by +.IR channel , +as a linked list of ares_addr_node structs storing a pointer to the first +node at the address specified by +.IR servers . + +The \fBares_get_servers_ports(3)\fP function also retrieves any per-server +port information that may have been previously configured, returning a linked +list of ares_addr_port structures. + +Function caller may traverse the returned name server linked list, or may use +it directly as suitable input for the \fBares_set_servers(3)\fP / +\fBares_set_servers_ports(3)\fP 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 \fBares_free_data(3)\fP , once the caller +does not need it any longer. + +This function is capable of handling IPv4 and IPv6 name server +addresses simultaneously, rendering \fBares_save_options(3)\fP with +optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for +IPv4-only name server usage. + +.SH RETURN VALUES +This function may return any of the following values: +.TP 15 +.B ARES_SUCCESS +The name servers configuration was successfully retrieved +.TP 15 +.B ARES_ENOMEM +The memory was exhausted +.TP 15 +.B ARES_ENODATA +The channel data identified by +.IR channel +was invalid. +.SH SEE ALSO +.BR ares_set_servers (3), +.BR ares_init_options (3), +.BR ares_save_options(3) +.SH AVAILABILITY +\fBares_get_servers(3)\fP was added in c-ares 1.7.1; +\fBares_get_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 +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. +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2008-2010 by Daniel Stenberg |