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