diff options
Diffstat (limited to 'ares/ares_library_init.3')
| -rw-r--r-- | ares/ares_library_init.3 | 55 |
1 files changed, 36 insertions, 19 deletions
diff --git a/ares/ares_library_init.3 b/ares/ares_library_init.3 index a505750ac..2a69b1471 100644 --- a/ares/ares_library_init.3 +++ b/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. |