NAME

       ares_library_cleanup - c-ares library deinitialization

SYNOPSIS

       #include <ares.h>

       void ares_library_cleanup(void)

DESCRIPTION

       The  ares_library_cleanup function uninitializes the c-ares library, freeing all resources
       previously acquired by ares_library_init(3) when the  library  was  initialized,  provided
       there  was  only  one single previous call to ares_library_init(3). If there was more than
       one previous call to ares_library_init(3), this function uninitializes the c-ares  library
       only  if  it  is  the call matching the call to ares_library_init(3) which initialized the
       library  (usually  the  very  first  call  to  ares_library_init(3)).   Other   calls   to
       ares_library_cleanup(3) have no effect other than decrementing an internal counter.

       This  function must be called when the program using c-ares will no longer need any c-ares
       function. Once the program has called ares_library_cleanup(3) sufficiently often such that
       the library is uninitialised, it shall not make any further call to any c-ares function.

       This  function  does  not  cancel  any pending c-ares lookups or requests previously done.
       Program  must use ares_cancel(3) for this purpose.

       This function is not thread safe.  You have to call  it  once  the  program  is  about  to
       terminate,  but this call must be done once the program has terminated every single thread
       that it could have initiated. This is required  to  avoid  potential  race  conditions  in
       library deinitialization, and also due to the fact that ares_library_cleanup(3) might call
       functions from other libraries that are thread unsafe, and could conflict with  any  other
       thread that is already using these other libraries.

       Win32/64  application  DLLs  shall  not  call  ares_library_cleanup(3)  from  the  DllMain
       function. Doing so will produce deadlocks and other problems.

AVAILABILITY

       This function was first introduced in c-ares version 1.7.0 along with  the  definition  of
       preprocessor  symbol  CARES_HAVE_ARES_LIBRARY_CLEANUP as an indication of the availability
       of this function. Reference counting in  ares_library_init()  and  ares_library_cleanup(),
       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 ares_library_cleanup().

       Since  the  introduction  of  this function, it is absolutely mandatory to call it for any
       Win32/64 program using c-ares.

       Non-Win32/64   systems   can   still   use   c-ares   version   1.7.0   without    calling
       ares_library_cleanup(3)  due to the fact that currently it is nearly a do-nothing function
       on non-Win32/64 platforms.

SEE ALSO

       ares_library_init(3), ares_cancel(3)

AUTHOR

       Yang Tse

       Copyright 1998 by the Massachusetts Institute of Technology.
       Copyright (C) 2004-2009 by Daniel Stenberg.

                                           19 May 2009                    ARES_LIBRARY_CLEANUP(3)