library init: be recursive

[platform/upstream/c-ares.git] / ares_library_init.3

diff --git a/ares_library_init.3 b/ares_library_init.3
index 2a69b14..b3efc18 100644 (file)
--- a/ares_library_init.3
+++ b/ares_library_init.3
@@ -1,4 +1,3 @@
-.\" $Id$
 .\"
 .\" Copyright 1998 by the Massachusetts Institute of Technology.
 .\" Copyright (C) 2004-2009 by Daniel Stenberg
@@ -51,39 +50,41 @@ ORing the values together. In normal operation you should specify
 familiar with it and trying to control some internal c-ares feature.
 .PP
 .B This function is not thread safe.
-You have to call it once the program
-has started, but this call must be done before the program starts any
-other thread. This is required to avoid potential race conditions in
-library initialization, and also due to the fact that ares_library_init()
-might call functions from other libraries that are thread unsafe, and
-could conflict with any other thread that is already using these other
-libraries.
+You have to call it once the program has started, but this call must be done
+before the program starts any other thread. This is required to avoid
+potential race conditions in library initialization, and also due to the fact
+that \fIares_library_init(3)\fP might call functions from other libraries that
+are thread unsafe, and could conflict with any other thread that is already
+using these other libraries.
+.PP
+Win32/64 application DLLs shall not call \fIares_library_init(3)\fP from the
+DllMain function. Doing so will produce deadlocks and other problems.
 .SH FLAGS
 .TP 5
 .B ARES_LIB_INIT_ALL
 Initialize everything possible. This sets all known bits.
 .TP
 .B ARES_LIB_INIT_WIN32
-Initialize Win32 specific libraries.
+Initialize Win32/64 specific libraries.
 .TP
 .B ARES_LIB_INIT_NONE
 Initialize nothing extra. This sets no bit.
 .SH RETURN VALUE
-Upon successful completion, ares_library_init() will return 0.
-Otherwise, a non-zero error number will be returned to indicate
-the error. Except for \fIares_strerror(3)\fP, you shall not call any
-other c-ares function upon ares_library_init() failure.
-.SH NOTES
-This function was first introduced in c-ares version 1.6.1 along with
-the definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP
-as an indication of the availability of this function.
+Upon successful completion, ares_library_init() will return 0.  Otherwise, a
+non-zero error number will be returned to indicate the error. Except for
+\fIares_strerror(3)\fP, you shall not call any other c-ares function upon
+\fIares_library_init(3)\fP failure.
+.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.
 .PP
 Since the introduction of this function it is absolutely mandatory to
-call it for any Win32 program using c-ares.
+call it for any Win32/64 program using c-ares.
 .PP
-Non-Win32 systems can still use c-ares version 1.6.1 without calling
-ares_library_init() due to the fact that it is nearly a do-nothing
-function on non-Win32 platforms.
+Non-Win32/64 systems can still use c-ares version 1.7.0 without calling
+\fIares_library_init(3)\fP due to the fact that \fIcurrently\fP it is nearly
+a do-nothing function on non-Win32/64 platforms at this point.
 .SH SEE ALSO
 .BR ares_library_cleanup(3),
 .BR ares_strerror(3)