ares_library_cleanup.3 (2982B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" Copyright (C) 2004-2009 by Daniel Stenberg 4 .\" SPDX-License-Identifier: MIT 5 .\" 6 .TH ARES_LIBRARY_CLEANUP 3 "19 May 2009" 7 .SH NAME 8 ares_library_cleanup \- c-ares library deinitialization 9 .SH SYNOPSIS 10 .nf 11 #include <ares.h> 12 13 void ares_library_cleanup(void) 14 .fi 15 .SH DESCRIPTION 16 .PP 17 The 18 .B ares_library_cleanup 19 function uninitializes the c-ares library, freeing all resources 20 previously acquired by \fIares_library_init(3)\fP when the library 21 was initialized, provided there was only one single previous call to 22 \fIares_library_init(3)\fP. If there was more than one previous call to 23 \fIares_library_init(3)\fP, this function uninitializes the c-ares 24 library only if it is the call matching the call to 25 \fIares_library_init(3)\fP which initialized the library 26 (usually the very first call to \fIares_library_init(3)\fP). 27 Other calls to \fIares_library_cleanup(3)\fP have no effect other than 28 decrementing an internal counter. 29 .PP 30 This function must be called when the program using c-ares will 31 no longer need any c-ares function. Once the program has called 32 \fIares_library_cleanup(3)\fP sufficiently often such that the 33 library is uninitialised, it shall not make any further call to any 34 c-ares function. 35 .PP 36 This function does not cancel any pending c-ares lookups or requests 37 previously done. Program must use \fIares_cancel(3)\fP for this purpose. 38 .PP 39 .B This function is not thread safe. 40 You have to call it once the program is about to terminate, but this call must 41 be done once the program has terminated every single thread that it could have 42 initiated. This is required to avoid potential race conditions in library 43 deinitialization, and also due to the fact that \fIares_library_cleanup(3)\fP 44 might call functions from other libraries that are thread unsafe, and could 45 conflict with any other thread that is already using these other libraries. 46 .PP 47 Win32/64 application DLLs shall not call \fIares_library_cleanup(3)\fP from 48 the DllMain function. Doing so will produce deadlocks and other problems. 49 .SH AVAILABILITY 50 This function was first introduced in c-ares version 1.7.0 along with the 51 definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an 52 indication of the availability of this function. Reference counting in 53 \fIares_library_init(3)\fP and \fIares_library_cleanup(3)\fP, which requires 54 calls to the former function to match calls to the latter, is present since 55 c-ares version 1.10.0. Earlier versions would deinitialize the library on the 56 first call to \fIares_library_cleanup(3)\fP. 57 .PP 58 Since the introduction of this function, it is absolutely mandatory to call it 59 for any Win32/64 program using c-ares. 60 .PP 61 Non-Win32/64 systems can still use c-ares version 1.7.0 without calling 62 \fIares_library_cleanup(3)\fP due to the fact that \fIcurrently\fP it is nearly 63 a do-nothing function on non-Win32/64 platforms. 64 .SH SEE ALSO 65 .BR ares_library_init (3), 66 .BR ares_cancel (3)