Spaces:
Running
Running
| .\" | |
| .\" 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 | |
| #include <ares.h> | |
| int ares_get_servers(ares_channel \fIchannel\fP, | |
| struct ares_addr_node **\fIservers\fP) | |
| 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 | |