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.

2 files changed, 28 insertions, 9 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.
diff --git a/ares_library_init.3 b/ares_library_init.3
index b3efc18..797476b 100644
--- a/ares_library_init.3
+++ b/ares_library_init.3
@@ -33,13 +33,15 @@ function performs initializations internally required by the c-ares
 library that must take place before any other function provided by
 c-ares can be used in a program.
 .PP
-This function must be called one time within the life of a program,
+This function must be called at least once within the life of a program,
 before the program actually executes any other c-ares library function.
-Initializations done by this function remain effective until a
-call to \fIares_library_cleanup(3)\fP is performed.
+Initializations done by this function remain effective until a number of
+calls to \fIares_library_cleanup(3)\fP equal to the number of calls to
+this function are performed.
 .PP
-Successive calls to this function do nothing, only the first call done
-when c-ares is in an uninitialized state is actually effective.
+Successive calls to this function do nothing further, only the first
+call done when c-ares is in an uninitialized state is actually
+effective.
 .PP
 The
 .I flags
@@ -77,7 +79,11 @@ non-zero error number will be returned to indicate the error. Except for
 .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_INIT\fP as an
-indication of the availability of this function.
+indication of the availability of this function. Its recursive behavior,
+which requires a matching number of calls to \fIares_library_cleanup()\fP
+in order to deinitialize the library, 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.