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>
133