Chiebot-Mirror
/
c-ares
mirror of https://github.com/c-ares/c-ares.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity
A C library for asynchronous DNS requests (grpc依赖)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
811 Commits
14 Branches
96 Tags
22 MiB
Tag: Branch: Tree: coverity_scan
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'coverity_scan'
${ noResults }
c-ares/docs/ares_reinit.3

54 lines
1.7 KiB
Raw Permalink Normal View History Unescape

Implement ares_reinit() to reload system configuration into existing channel (#614) This PR implements ares_reinit() to safely reload a channel's configuration even if there are existing queries. This function can be called when system configuration is detected to be changed, however since c-ares isn't thread aware, care must be taken to ensure no other c-ares calls are in progress at the time this function is called. Also, this function may update the open file descriptor list so care must also be taken to wake any event loops and reprocess the list of file descriptors. Fixes Bug #301 Fix By: Brad House (@bradh352)
1 year ago
.\"
add missing copyrights
7 months ago
.\" Copyright 2023 by the c-ares project and its contributors
Implement ares_reinit() to reload system configuration into existing channel (#614) This PR implements ares_reinit() to safely reload a channel's configuration even if there are existing queries. This function can be called when system configuration is detected to be changed, however since c-ares isn't thread aware, care must be taken to ensure no other c-ares calls are in progress at the time this function is called. Also, this function may update the open file descriptor list so care must also be taken to wake any event loops and reprocess the list of file descriptors. Fixes Bug #301 Fix By: Brad House (@bradh352)
1 year ago
.\" SPDX-License-Identifier: MIT
.\"
.TH ARES_REINIT 3 "12 November 2023"
.SH NAME
ares_reinit \- ReInitialize a resolver channel from system configuration.
.SH SYNOPSIS
.nf
#include <ares.h>
int ares_reinit(ares_channel_t *\fIchannel\fP)
.fi
.SH DESCRIPTION
The \fBares_reinit(3)\fP function re-reads the system configuration and safely
applies the configuration to the existing channel. System configuration will
never override user-provided settings such as provided via
\fBares_init_options(3)\fP or \fBares_set_servers(3)\fP.
Any existing queries will be automatically requeued if the server they are
currently assigned to is removed from the system configuration.
Basic Thread Safety (#636) c-ares does not have any concept of thread-safety. It has always been 100% up to the implementor to ensure they never call c-ares from more than one thread at a time. This patch adds basic thread-safety support, which can be disabled at compile time if not desired. It uses a single recursive mutex per channel, which should be extremely quick when uncontested so overhead should be minimal. Fixes Bug: #610 Also sets the stage to implement #611 Fix By: Brad House (@bradh352)
1 year ago
This function may cause additional file descriptors to be created, and existing
Auto reload config on changes (requires EventThread) (#759) Automatically detect configuration changes and reload. On systems which provide notification mechanisms, use those, otherwise fallback to polling. When a system configuration change is detected, it asynchronously applies the configuration in order to ensure it is a non-blocking operation for any queries which may still be being processed. On Windows, however, changes aren't detected if a user manually sets/changes the DNS servers on an interface, it doesn't appear there is any mechanism capable of this. We are relying on `NotifyIpInterfaceChange()` for notifications. Fixes Issue: #613 Fix By: Brad House (@bradh352)
6 months ago
ones to be destroyed if server configuration has changed.
\Bares_reinit(3)\fP, when compiled with thread safety, will spawn a background
thread to read the configuration and apply it. It is crucial that developers
use the \fBARES_OPT_SOCK_STATE_CB\fP or \fBARES_OPT_EVENT_THREAD\fP so that
notifications of changes are alerted. If using \fBares_getsock(3)\fP or
\fBares_fds(3)\fP, no notification is possible which could cause a stall.
Implement ares_reinit() to reload system configuration into existing channel (#614) This PR implements ares_reinit() to safely reload a channel's configuration even if there are existing queries. This function can be called when system configuration is detected to be changed, however since c-ares isn't thread aware, care must be taken to ensure no other c-ares calls are in progress at the time this function is called. Also, this function may update the open file descriptor list so care must also be taken to wake any event loops and reprocess the list of file descriptors. Fixes Bug #301 Fix By: Brad House (@bradh352)
1 year ago
.SH RETURN VALUES
\fIares_reinit(3)\fP can return any of the following values:
.TP 14
.B ARES_SUCCESS
Initialization succeeded.
.TP 14
.B ARES_EFILE
A configuration file could not be read.
.TP 14
.B ARES_ENOMEM
The process's available memory was exhausted.
Add DNS record manpages (#615) The new DNS record parser and writer needs manpages. This PR implements those. Fix By: Brad House (@bradh352)
1 year ago
.SH AVAILABILITY
This function was first introduced in c-ares version 1.22.0.
Implement ares_reinit() to reload system configuration into existing channel (#614) This PR implements ares_reinit() to safely reload a channel's configuration even if there are existing queries. This function can be called when system configuration is detected to be changed, however since c-ares isn't thread aware, care must be taken to ensure no other c-ares calls are in progress at the time this function is called. Also, this function may update the open file descriptor list so care must also be taken to wake any event loops and reprocess the list of file descriptors. Fixes Bug #301 Fix By: Brad House (@bradh352)
1 year ago
.SH SEE ALSO
.BR ares_init (3),
.BR ares_init_options (3),
.BR ares_destroy (3),
.BR ares_dup (3),
.BR ares_library_init (3),
Basic Thread Safety (#636) c-ares does not have any concept of thread-safety. It has always been 100% up to the implementor to ensure they never call c-ares from more than one thread at a time. This patch adds basic thread-safety support, which can be disabled at compile time if not desired. It uses a single recursive mutex per channel, which should be extremely quick when uncontested so overhead should be minimal. Fixes Bug: #610 Also sets the stage to implement #611 Fix By: Brad House (@bradh352)
1 year ago
.BR ares_set_servers (3),
.BR ares_threadsafety (3)