summaryrefslogtreecommitdiff
path: root/ares_library_cleanup.3
diff options
context:
space:
mode:
authorAlexander Klauer <Alexander.Klauer@itwm.fraunhofer.de>2013-03-18 08:23:30 (GMT)
committerDaniel Stenberg <daniel@haxx.se>2013-04-22 21:26:01 (GMT)
commit9a92b80191af997c910fca973307bef339e7b767 (patch)
tree81664cda97a37da1c4f9205a9c0b2a1d8b4cf4f2 /ares_library_cleanup.3
parent2e0c3076e592d0d8ec4878aa800f24601f0a7321 (diff)
downloadc-ares-9a92b80191af997c910fca973307bef339e7b767.zip
c-ares-9a92b80191af997c910fca973307bef339e7b767.tar.gz
c-ares-9a92b80191af997c910fca973307bef339e7b767.tar.bz2
library init: documentation update
This commit updates the documentation of ares_library_init() and ares_library_cleanup() with regard to the newly introduced reference counting of initializations and deinitializations.
Diffstat (limited to 'ares_library_cleanup.3')
-rw-r--r--ares_library_cleanup.319
1 files changed, 16 insertions, 3 deletions
diff --git a/ares_library_cleanup.3 b/ares_library_cleanup.3
index 9fcf896..d60c378 100644
--- a/ares_library_cleanup.3
+++ b/ares_library_cleanup.3
@@ -31,11 +31,19 @@ The
.B ares_library_cleanup
function uninitializes the c-ares library, freeing all resources
previously acquired by \fIares_library_init(3)\fP when the library
-was initialized.
+was initialized, provided there was only one single previous call to
+\fIares_library_init(3)\fP. If there was more than one previous call to
+\fIares_library_init(3)\fP, this function uninitializes the c-ares
+library only if it is the call matching the call to
+\fIares_library_init(3)\fP which initialized the library
+(usually the very first call to \fIares_library_init(3)\fP).
+Other calls to \fIares_library_cleanup(3)\fP have no effect other than
+decrementing an internal counter.
.PP
This function must be called when the program using c-ares will
no longer need any c-ares function. Once the program has called
-\fIares_library_cleanup(3)\fP it shall not make any further call to any
+\fIares_library_cleanup(3)\fP sufficiently often such that the
+library is uninitialised, it shall not make any further call to any
c-ares function.
.PP
This function does not cancel any pending c-ares lookups or requests
@@ -54,7 +62,12 @@ the DllMain function. Doing so will produce deadlocks and other problems.
.SH AVAILABILITY
This function was first introduced in c-ares version 1.7.0 along with the
definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an
-indication of the availability of this function.
+indication of the availability of this function. Reference counting in
+\fIares_library_init()\fP and \fIares_library_cleanup()\fP, which requires
+calls to the former function to match calls to the latter, is present since
+c-ares version 1.10.0.
+Earlier versions would deinitialize the library on the first call
+to \fIares_library_cleanup()\fP.
.PP
Since the introduction of this function, it is absolutely mandatory to call it
for any Win32/64 program using c-ares.