ares_library_cleanup(3)

ARES_LIBRARY_CLEANUP(3)C LIBRARY FUNCTIONSARES_LIBRARY_CLEANUP(3)

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,  pro-
     vided   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 (usu-
     ally 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

                    Last change: 19 May 2009                    1

ARES_LIBRARY_CLEANUP(3)C LIBRARY FUNCTIONSARES_LIBRARY_CLEANUP(3)

     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.

                    Last change: 19 May 2009                    2