jpayne@68: .\"
jpayne@68: .\" Copyright 2023 by the c-ares project and its contributors
jpayne@68: .\" SPDX-License-Identifier: MIT
jpayne@68: .\"
jpayne@68: .TH ARES_REINIT 3 "12 November 2023"
jpayne@68: .SH NAME
jpayne@68: ares_reinit \- ReInitialize a resolver channel from system configuration.
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: #include <ares.h>
jpayne@68: 
jpayne@68: int ares_reinit(ares_channel_t *\fIchannel\fP)
jpayne@68: .fi
jpayne@68: .SH DESCRIPTION
jpayne@68: The \fBares_reinit(3)\fP function re-reads the system configuration and safely
jpayne@68: applies the configuration to the existing channel.  System configuration will
jpayne@68: never override user-provided settings such as provided via
jpayne@68: \fBares_init_options(3)\fP or \fBares_set_servers(3)\fP.
jpayne@68: 
jpayne@68: Any existing queries will be automatically requeued if the server they are
jpayne@68: currently assigned to is removed from the system configuration.
jpayne@68: 
jpayne@68: This function may cause additional file descriptors to be created, and existing
jpayne@68: ones to be destroyed if server configuration has changed.
jpayne@68: 
jpayne@68: \Bares_reinit(3)\fP, when compiled with thread safety, will spawn a background
jpayne@68: thread to read the configuration and apply it.  It is crucial that developers
jpayne@68: use the \fBARES_OPT_SOCK_STATE_CB\fP or \fBARES_OPT_EVENT_THREAD\fP so that
jpayne@68: notifications of changes are alerted.  If using \fBares_getsock(3)\fP or
jpayne@68: \fBares_fds(3)\fP, no notification is possible which could cause a stall.
jpayne@68: 
jpayne@68: .SH RETURN VALUES
jpayne@68: \fIares_reinit(3)\fP can return any of the following values:
jpayne@68: .TP 14
jpayne@68: .B ARES_SUCCESS
jpayne@68: Initialization succeeded.
jpayne@68: .TP 14
jpayne@68: .B ARES_EFILE
jpayne@68: A configuration file could not be read.
jpayne@68: .TP 14
jpayne@68: .B ARES_ENOMEM
jpayne@68: The process's available memory was exhausted.
jpayne@68: 
jpayne@68: .SH AVAILABILITY
jpayne@68: This function was first introduced in c-ares version 1.22.0.
jpayne@68: .SH SEE ALSO
jpayne@68: .BR ares_init (3),
jpayne@68: .BR ares_init_options (3),
jpayne@68: .BR ares_destroy (3),
jpayne@68: .BR ares_dup (3),
jpayne@68: .BR ares_library_init (3),
jpayne@68: .BR ares_set_servers (3),
jpayne@68: .BR ares_threadsafety (3)