mirror of https://github.com/c-ares/c-ares.git
Yang Tse
15 years ago
parent
249fc61b8c
commit
8fe746fcf2
27 changed files with 781 additions and 196 deletions
@ -0,0 +1,78 @@ |
||||
.\" $Id$ |
||||
.\" |
||||
.\" 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 \- 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) |
||||
.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 . |
||||
|
||||
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 function, 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 |
||||
.B ares_get_servers(3) |
||||
may return any of the following values: |
||||
.TP 15 |
||||
.B ARES_SUCCESS |
||||
The name servers configuration was successfuly 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 |
||||
ares_get_servers(3) was added in c-ares 1.7.1 |
||||
.SH AUTHOR |
||||
Implementation of this function and associated library internals are based |
||||
on code, comments and feedback provided 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. |
||||
Copyright (C) 2008-2010 by Daniel Stenberg |
||||
@ -0,0 +1,128 @@ |
||||
/* $Id$ */ |
||||
|
||||
/* 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. |
||||
*/ |
||||
|
||||
|
||||
#include "ares_setup.h" |
||||
|
||||
#include "ares.h" |
||||
#include "ares_data.h" |
||||
#include "ares_private.h" |
||||
|
||||
|
||||
int ares_get_servers(ares_channel channel, |
||||
struct ares_addr_node **servers) |
||||
{ |
||||
struct ares_addr_node *srvr_head = NULL; |
||||
struct ares_addr_node *srvr_last = NULL; |
||||
struct ares_addr_node *srvr_curr; |
||||
int status = ARES_SUCCESS; |
||||
int i; |
||||
|
||||
if (!channel) |
||||
return ARES_ENODATA; |
||||
|
||||
for (i = 0; i < channel->nservers; i++) |
||||
{ |
||||
/* Allocate storage for this server node appending it to the list */ |
||||
srvr_curr = ares_malloc_data(ARES_DATATYPE_ADDR_NODE); |
||||
if (!srvr_curr) |
||||
{ |
||||
status = ARES_ENOMEM; |
||||
break; |
||||
} |
||||
if (srvr_last) |
||||
{ |
||||
srvr_last->next = srvr_curr; |
||||
} |
||||
else |
||||
{ |
||||
srvr_head = srvr_curr; |
||||
} |
||||
srvr_last = srvr_curr; |
||||
|
||||
/* Fill this server node data */ |
||||
srvr_curr->family = channel->servers[i].addr.family; |
||||
if (srvr_curr->family == AF_INET) |
||||
memcpy(&srvr_curr->addrV4, &channel->servers[i].addr.addrV4, |
||||
sizeof(srvr_curr->addrV4)); |
||||
else |
||||
memcpy(&srvr_curr->addrV6, &channel->servers[i].addr.addrV6, |
||||
sizeof(srvr_curr->addrV6)); |
||||
} |
||||
|
||||
if (status != ARES_SUCCESS) |
||||
{ |
||||
if (srvr_head) |
||||
{ |
||||
ares_free_data(srvr_head); |
||||
srvr_head = NULL; |
||||
} |
||||
} |
||||
|
||||
*servers = srvr_head; |
||||
|
||||
return status; |
||||
} |
||||
|
||||
|
||||
int ares_set_servers(ares_channel channel, |
||||
struct ares_addr_node *servers) |
||||
{ |
||||
struct ares_addr_node *srvr; |
||||
int num_srvrs = 0; |
||||
int i; |
||||
|
||||
if (ares_library_initialized() != ARES_SUCCESS) |
||||
return ARES_ENOTINITIALIZED; |
||||
|
||||
if (!channel) |
||||
return ARES_ENODATA; |
||||
|
||||
ares__destroy_servers_state(channel); |
||||
|
||||
for (srvr = servers; srvr; srvr = srvr->next) |
||||
{ |
||||
num_srvrs++; |
||||
} |
||||
|
||||
if (num_srvrs > 0) |
||||
{ |
||||
/* Allocate storage for servers state */ |
||||
channel->servers = malloc(num_srvrs * sizeof(struct server_state)); |
||||
if (!channel->servers) |
||||
{ |
||||
return ARES_ENOMEM; |
||||
} |
||||
channel->nservers = num_srvrs; |
||||
/* Fill servers state address data */ |
||||
for (i = 0, srvr = servers; srvr; i++, srvr = srvr->next) |
||||
{ |
||||
channel->servers[i].addr.family = srvr->family; |
||||
if (srvr->family == AF_INET) |
||||
memcpy(&channel->servers[i].addr.addrV4, &srvr->addrV4, |
||||
sizeof(srvr->addrV4)); |
||||
else |
||||
memcpy(&channel->servers[i].addr.addrV6, &srvr->addrV6, |
||||
sizeof(srvr->addrV6)); |
||||
} |
||||
/* Initialize servers state remaining data */ |
||||
ares__init_servers_state(channel); |
||||
} |
||||
|
||||
return ARES_SUCCESS; |
||||
} |
||||
@ -0,0 +1,84 @@ |
||||
.\" $Id$ |
||||
.\" |
||||
.\" 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_SET_SERVERS 3 "5 March 2010" |
||||
.SH NAME |
||||
ares_set_servers \- 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) |
||||
.fi |
||||
.SH DESCRIPTION |
||||
The \fBares_set_servers(3)\fP function initializes name servers configuration |
||||
for the channel data identified by |
||||
.IR channel , |
||||
from a |
||||
.IR servers |
||||
pointer to a linked list of ares_addr_node structs holding name servers |
||||
address data. |
||||
|
||||
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. |
||||
|
||||
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 |
||||
single list. |
||||
|
||||
\fBares_set_servers(3)\fP does not take ownership of the linked list argument. |
||||
The caller is responsible to free the linked list when no longer needed. |
||||
|
||||
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 |
||||
IPv4-only name server usage. |
||||
|
||||
.SH RETURN VALUES |
||||
.B ares_set_servers(3) |
||||
may return any of the following values: |
||||
.TP 15 |
||||
.B ARES_SUCCESS |
||||
The name servers configuration was successfuly initialized. |
||||
.TP 15 |
||||
.B ARES_ENOMEM |
||||
The process's available memory was exhausted. |
||||
.TP 15 |
||||
.B ARES_ENODATA |
||||
The channel data identified by |
||||
.IR channel |
||||
was invalid. |
||||
.TP 15 |
||||
.B ARES_ENOTINITIALIZED |
||||
c-ares library initialization not yet performed. |
||||
.SH SEE ALSO |
||||
.BR ares_get_servers (3), |
||||
.BR ares_init_options (3), |
||||
.BR ares_dup(3) |
||||
.SH AVAILABILITY |
||||
ares_set_servers(3) was added in c-ares 1.7.1 |
||||
.SH AUTHOR |
||||
Implementation of this function and associated library internals are based |
||||
on code, comments and feedback provided 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. |
||||
Copyright (C) 2008-2010 by Daniel Stenberg |
||||
Loading…
Reference in new issue