diff options
| -rw-r--r-- | ares_library_cleanup.3 | 19 | ||||
| -rw-r--r-- | ares_library_init.3 | 18 |
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. |