Debian Codegraph @

deps/libneon/doc/ref/init.xml

raw
1 <refentry id="refsockinit">
2
3 <refmeta>
4 <refentrytitle>ne_sock_init</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname id="ne_sock_init">ne_sock_init</refname>
10 <refname id="ne_sock_exit">ne_sock_exit</refname>
11 <refpurpose>perform library initialization</refpurpose>
12 </refnamediv>
13
14 <refsynopsisdiv>
15
16 <funcsynopsis>
17
18 <funcsynopsisinfo>#include &lt;ne_socket.h&gt;</funcsynopsisinfo>
19
20 <funcprototype>
21 <funcdef>int <function>ne_sock_init</function></funcdef>
22 <void/>
23 </funcprototype>
24
25 <funcprototype>
26 <funcdef>void <function>ne_sock_exit</function></funcdef>
27 <void/>
28 </funcprototype>
29
30 </funcsynopsis>
31
32 </refsynopsisdiv>
33
34 <refsect1>
35 <title>Description</title>
36
37 <para>In some platforms and configurations, &neon; may be using
38 some socket or SSL libraries which require global initialization
39 before use. To perform this initialization, the
40 <function>ne_sock_init</function> function must be called before
41 any other library functions are used.</para>
42
43 <para>Once all use of &neon; is complete,
44 <function>ne_sock_exit</function> can be called to perform
45 de-initialization of socket or SSL libraries, if necessary. Uses
46 of <function>ne_sock_init</function> and
47 <function>ne_sock_exit</function> are "reference counted"; if N
48 calls to <function>ne_sock_init</function> are made, only the Nth
49 call to <function>ne_sock_exit</function> will have effect.</para>
50
51 <para><function>ne_sock_init</function> will set the disposition
52 of the <literal>SIGPIPE</literal> signal to
53 <emphasis>ignored</emphasis>. No change is made to the
54 <literal>SIGPIPE</literal> disposition by
55 <function>ne_sock_exit</function>.</para>
56
57 <para>Both the SSL libraries supported by &neon; &mdash; OpenSSL
58 and GnuTLS &mdash; require callbacks to be registered to allow
59 thread-safe use of SSL. These callbacks are stored as global
60 variables and so their state persists for as long as the library
61 in question is loaded into the process. If multiple users of the
62 SSL library exist within the process, this can be problematic,
63 particularly if one is dynamically loaded (and may subsequently be
64 unloaded).</para>
65
66 <para>If &neon; is configured using the
67 <literal>--enable-threadsafe-ssl</literal> flag, thread-safe SSL
68 support will be enabled automatically, as covered in the following
69 section. Otherwise, it is not safe to use &neon; with SSL in a
70 multi-threaded process. The <xref linkend="ne_has_support"/>
71 function can be used to determine whether &neon; is built to
72 enable thread-safety support in the SSL library.</para>
73
74 <refsect2>
75 <title>Thread-safe SSL with OpenSSL</title>
76
77 <para>&neon; follows two simple rules when dealing with the
78 OpenSSL locking callbacks:
79
80 <itemizedlist>
81
82 <listitem><simpara><function>ne_sock_init</function> will set
83 thread-safety locking callbacks if and only if no locking
84 callbacks are already registered.</simpara></listitem>
85
86 <listitem><simpara><function>ne_sock_exit</function> will
87 unset the thread-safety locking callbacks if and only if the
88 locking callbacks registered are those registered by
89 <function>ne_sock_init</function>.</simpara></listitem>
90
91 </itemizedlist>
92
93 Applications and libraries should be able to co-operate to
94 ensure that SSL use is always thread-safe if similar rules are
95 always followed.</para>
96
97 </refsect2>
98
99 <refsect2>
100 <title>Thread-safe SSL with GnuTLS</title>
101
102 <para>The cryptography library used by GnuTLS, libgcrypt, only
103 supports an initialization operation to register thread-safety
104 callbacks. <function>ne_sock_init</function> will register the
105 thread-safe locking callbacks on first use;
106 <function>ne_sock_exit</function> cannot unregister them. If
107 multiple users of GnuTLS are present within the process, it is
108 unsafe to dynamically unload &neon; from the process if &neon;
109 is configured with thread-safe SSL support enabled (since the
110 callbacks would be left pointing at unmapped memory once &neon;
111 is unloaded).</para>
112
113 </refsect2>
114
115 </refsect1>
116
117 <refsect1>
118 <title>Return value</title>
119
120 <para><function>ne_sock_init</function> returns zero on success,
121 or non-zero on error. If an error occurs, no further use of the
122 &neon; library should be attempted.</para>
123
124 </refsect1>
125
126 <refsect1>
127 <title>See also</title>
128
129 <para><xref linkend="refneon"/>, <xref linkend="reffeat"/></para>
130 </refsect1>
131
132 </refentry>