1ARES_LIBRARY_CLEANUP(3)    Library Functions Manual    ARES_LIBRARY_CLEANUP(3)
2
3
4

NAME

6       ares_library_cleanup - c-ares library deinitialization
7

SYNOPSIS

9       #include <ares.h>
10
11       void ares_library_cleanup(void)
12

DESCRIPTION

14       The  ares_library_cleanup  function  uninitializes  the c-ares library,
15       freeing all resources previously acquired by ares_library_init(3)  when
16       the  library was initialized, provided there was only one single previ‐
17       ous call to ares_library_init(3). If there was more than  one  previous
18       call  to  ares_library_init(3),  this function uninitializes the c-ares
19       library   only   if   it   is   the   call   matching   the   call   to
20       ares_library_init(3)  which  initialized  the library (usually the very
21       first    call    to    ares_library_init(3)).     Other    calls     to
22       ares_library_cleanup(3)  have  no  effect  other  than  decrementing an
23       internal counter.
24
25       This function must be called when the  program  using  c-ares  will  no
26       longer   need   any  c-ares  function.  Once  the  program  has  called
27       ares_library_cleanup(3) sufficiently often such  that  the  library  is
28       uninitialised,  it  shall not make any further call to any c-ares func‐
29       tion.
30
31       This function does not cancel any pending c-ares  lookups  or  requests
32       previously done. Program  must use ares_cancel(3) for this purpose.
33
34       This function is not thread safe.  You have to call it once the program
35       is about to terminate, but this call must be done once the program  has
36       terminated  every  single  thread that it could have initiated. This is
37       required to avoid potential race conditions  in  library  deinitializa‐
38       tion,  and also due to the fact that ares_library_cleanup(3) might call
39       functions from other libraries that are thread unsafe, and  could  con‐
40       flict  with  any  other  thread  that  is  already  using  these  other
41       libraries.
42
43       Win32/64 application DLLs shall not call  ares_library_cleanup(3)  from
44       the  DllMain  function. Doing so will produce deadlocks and other prob‐
45       lems.
46

AVAILABILITY

48       This function was first introduced in c-ares version 1.7.0  along  with
49       the  definition  of preprocessor symbol CARES_HAVE_ARES_LIBRARY_CLEANUP
50       as an indication of the availability of this function. Reference count‐
51       ing  in  ares_library_init() and ares_library_cleanup(), which requires
52       calls to the former function to match calls to the latter,  is  present
53       since  c-ares  version 1.10.0.  Earlier versions would deinitialize the
54       library on the first call to ares_library_cleanup().
55
56       Since the introduction of this function, it is absolutely mandatory  to
57       call it for any Win32/64 program using c-ares.
58
59       Non-Win32/64 systems can still use c-ares version 1.7.0 without calling
60       ares_library_cleanup(3) due to the fact that currently it is  nearly  a
61       do-nothing function on non-Win32/64 platforms.
62

SEE ALSO

64       ares_library_init(3), ares_cancel(3)
65

AUTHOR

67       Yang Tse
68
69       Copyright 1998 by the Massachusetts Institute of Technology.
70       Copyright (C) 2004-2009 by Daniel Stenberg.
71
72
73
74                                  19 May 2009          ARES_LIBRARY_CLEANUP(3)
Impressum