Update man page

ares/ares_library_init.3

@@ -23,38 +23,41 @@ ares_library_init \- c-ares library initialization
 .B #include <ares.h>
 .PP
 .B int ares_library_init(int \fIflags\fP)
+.PP
+.B cc file.c -lcares
 .fi
 .SH DESCRIPTION
 .PP
 The
 .B ares_library_init
 function performs initializations internally required by the c-ares
-library that must take place before any other c-ares function can be
-used.
+library that must take place before any other function provided by
+c-ares can be used in a program.
 .PP
-This function must be called one time within the life of a program
-before the program actually executes any other c-ares library function
-call. Initializations done by this function remain effective until a
+This function must be called one time within the life of a program,
+before the program actually executes any other c-ares library function.
+Initializations done by this function remain effective until a
 call to \fIares_library_cleanup(3)\fP is performed.
 .PP
-Successive calls to this function are ignored, only the first one with
-c-ares in an uninitialized state is effective.
+Successive calls to this function do nothing, only the first call done
+when c-ares is in an uninitialized state is actually effective.
 .PP
 The
 .I flags
 parameter is a bit pattern that tells c-ares exactly which features
 should be initialized, as described below. Set the desired bits by
-ORing the values together. In normal operation, you must specify
-.I ARES_LIB_INIT_ALL.
-Don't use any other value unless you are familiar with it and trying
-to control some internal c-ares features.
+ORing the values together. In normal operation you should specify
+\fIARES_LIB_INIT_ALL\fP. Don't use any other value unless you are
+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 must be called before the program starts any other thread.
-Due to the fact that ares_library_init() might call functions from other
-libraries that are thread unsafe, it could conflict with any other thread
-that uses these other libraries.
+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.
 .SH FLAGS
 .TP 5
 .B ARES_LIB_INIT_ALL
@@ -66,13 +69,27 @@ Initialize Win32 specific libraries.
 .B ARES_LIB_INIT_NONE
 Initialize nothing extra. This sets no bit.
 .SH RETURN VALUE
-If this function returns non-zero, something went wrong and you cannot
-use the other c-ares functions.
+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 CARES_HAVE_ARES_LIBRARY_INIT
+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.
+.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.
 .SH SEE ALSO
-.BR ares_library_cleanup (3)
+.BR ares_library_cleanup(3),
+.BR ares_strerror(3)
 .SH AUTHOR
 Yang Tse
+.PP
+Copyright 1998 by the Massachusetts Institute of Technology.
+.br
+Copyright (C) 2004-2009 by Daniel Stenberg.