blob: 4734f9264fbb8c4df15e1a3fb40aa695172b7155 [file] [log] [blame]
lh9ed821d2023-04-07 01:36:19 -07001.\"
2.\" Copyright 1998 by the Massachusetts Institute of Technology.
3.\" Copyright (C) 2004-2009 by Daniel Stenberg
4.\"
5.\" Permission to use, copy, modify, and distribute this
6.\" software and its documentation for any purpose and without
7.\" fee is hereby granted, provided that the above copyright
8.\" notice appear in all copies and that both that copyright
9.\" notice and this permission notice appear in supporting
10.\" documentation, and that the name of M.I.T. not be used in
11.\" advertising or publicity pertaining to distribution of the
12.\" software without specific, written prior permission.
13.\" M.I.T. makes no representations about the suitability of
14.\" this software for any purpose. It is provided "as is"
15.\" without express or implied warranty.
16.\"
17.TH ARES_LIBRARY_INIT 3 "19 May 2009"
18.SH NAME
19ares_library_init \- c-ares library initialization
20.SH SYNOPSIS
21.nf
22#include <ares.h>
23
24int ares_library_init(int \fIflags\fP)
25
26int ares_library_init_mem(int \fIflags\fP,
27 void *(*\fIamalloc\fP)(size_t),
28 void (*\fIafree\fP)(void *ptr),
29 void (*\fIarealloc\fP)(void *ptr, size_t size))
30.fi
31.SH DESCRIPTION
32.PP
33The
34.B ares_library_init
35function performs initializations internally required by the c-ares
36library that must take place before any other function provided by
37c-ares can be used in a program.
38.PP
39This function must be called at least once within the life of a program,
40before the program actually executes any other c-ares library function.
41Initializations done by this function remain effective until a number of
42calls to \fIares_library_cleanup(3)\fP equal to the number of calls to
43this function are performed.
44.PP
45Successive calls to this function do nothing further, only the first
46call done when c-ares is in an uninitialized state is actually
47effective.
48.PP
49The
50.I flags
51parameter is a bit pattern that tells c-ares exactly which features
52should be initialized, as described below. Set the desired bits by
53ORing the values together. In normal operation you should specify
54\fIARES_LIB_INIT_ALL\fP. Don't use any other value unless you are
55familiar with it and trying to control some internal c-ares feature.
56.PP
57The
58.B ares_library_init_mem
59function allows the caller to provide memory management functions that the
60c-ares library will be use instead of \fImalloc(3)\fP, \fIfree(3)\fP and
61\fIrealloc(3)\fP.
62.PP
63.B This function is not thread safe.
64You have to call it once the program has started, but this call must be done
65before the program starts any other thread. This is required to avoid
66potential race conditions in library initialization, and also due to the fact
67that \fIares_library_init(3)\fP might call functions from other libraries that
68are thread unsafe, and could conflict with any other thread that is already
69using these other libraries.
70.PP
71Win32/64 application DLLs shall not call \fIares_library_init(3)\fP from the
72DllMain function. Doing so will produce deadlocks and other problems.
73.SH FLAGS
74.TP 5
75.B ARES_LIB_INIT_ALL
76Initialize everything possible. This sets all known bits.
77.TP
78.B ARES_LIB_INIT_WIN32
79Initialize Win32/64 specific libraries.
80.TP
81.B ARES_LIB_INIT_NONE
82Initialize nothing extra. This sets no bit.
83.SH RETURN VALUE
84Upon successful completion, ares_library_init() will return 0. Otherwise, a
85non-zero error number will be returned to indicate the error. Except for
86\fIares_strerror(3)\fP, you shall not call any other c-ares function upon
87\fIares_library_init(3)\fP failure.
88.SH AVAILABILITY
89This function was first introduced in c-ares version 1.7.0 along with the
90definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP as an
91indication of the availability of this function. Its recursive behavior,
92which requires a matching number of calls to \fIares_library_cleanup()\fP
93in order to deinitialize the library, is present since c-ares version
941.10.0. Earlier versions would deinitialize the library on the first call
95to \fIares_library_cleanup()\fP.
96.PP
97Since the introduction of this function it is absolutely mandatory to
98call it for any Win32/64 program using c-ares.
99.PP
100Non-Win32/64 systems can still use c-ares version 1.7.0 without calling
101\fIares_library_init(3)\fP due to the fact that \fIcurrently\fP it is nearly
102a do-nothing function on non-Win32/64 platforms at this point.
103.SH SEE ALSO
104.BR ares_library_cleanup(3),
105.BR ares_strerror(3)
106.SH AUTHOR
107Yang Tse
108.PP
109Copyright 1998 by the Massachusetts Institute of Technology.
110.br
111Copyright (C) 2004-2009 by Daniel Stenberg.