| 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 <ne_socket.h></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; — OpenSSL |
| 58 |
and GnuTLS — 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> |