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(3) and ares_library_cleanup(3), 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(3).

       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)