Home Explore Help
Register Sign In
Apq
/
winscp
mirror of https://github.com/winscp/winscp.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: f2590f90ac
Branches Tags
winscp
/
libs
/
neon
/
doc
/
html
/
refsockinit.html

refsockinit.html 6.6 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051 
  1. <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_sock_init</title><link rel="stylesheet" type="text/css" href="../manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refshave.html" title="ne_shave"><link rel="next" href="refcert.html" title="ne_ssl_cert_identity"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ne_sock_init</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refshave.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refcert.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="refsockinit"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_sock_init, ne_sock_exit — perform library initialization</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;ne_socket.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">ne_sock_init</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">ne_sock_exit</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm139901958915120"></a><h2>Description</h2><p>In some platforms and configurations, neon may be using
    2. 

  2.     some socket or SSL libraries which require global initialization
    3. 

  3.     before use.  To perform this initialization, the
    4. 

  4.     <code class="function">ne_sock_init</code> function must be called before
    5. 

  5.     any other library functions are used.</p><p>Once all use of neon is complete,
    6. 

  6.     <code class="function">ne_sock_exit</code> can be called to perform
    7. 

  7.     de-initialization of socket or SSL libraries, if necessary.  Uses
    8. 

  8.     of <code class="function">ne_sock_init</code> and
    9. 

  9.     <code class="function">ne_sock_exit</code> are "reference counted"; if N
    10. 

  10.     calls to <code class="function">ne_sock_init</code> are made, only the Nth
    11. 

  11.     call to <code class="function">ne_sock_exit</code> will have effect.</p><p><code class="function">ne_sock_init</code> will set the disposition
    12. 

  12.     of the <code class="literal">SIGPIPE</code> signal to
    13. 

  13.     <span class="emphasis"><em>ignored</em></span>.  No change is made to the
    14. 

  14.     <code class="literal">SIGPIPE</code> disposition by
    15. 

  15.     <code class="function">ne_sock_exit</code>.</p><p>Both the SSL libraries supported by neon — OpenSSL
    16. 

  16.     and GnuTLS — require callbacks to be registered to allow
    17. 

  17.     thread-safe use of SSL.  These callbacks are stored as global
    18. 

  18.     variables and so their state persists for as long as the library
    19. 

  19.     in question is loaded into the process.  If multiple users of the
    20. 

  20.     SSL library exist within the process, this can be problematic,
    21. 

  21.     particularly if one is dynamically loaded (and may subsequently be
    22. 

  22.     unloaded).</p><p>If neon is configured using the
    23. 

  23.     <code class="literal">--enable-threadsafe-ssl</code> flag, thread-safe SSL
    24. 

  24.     support will be enabled automatically, as covered in the following
    25. 

  25.     section.  Otherwise, it is not safe to use neon with SSL in a
    26. 

  26.     multi-threaded process.  The <a class="xref" href="reffeat.html#ne_has_support">ne_has_support</a>
    27. 

  27.     function can be used to determine whether neon is built to
    28. 

  28.     enable thread-safety support in the SSL library.</p><div class="refsect2"><a name="idm139901958903760"></a><h3>Thread-safe SSL with OpenSSL</h3><p>neon follows two simple rules when dealing with the
    29. 

  29.       OpenSSL locking callbacks:
    30. 

  30. 

  31.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="function">ne_sock_init</code> will set
    32. 

  32.         thread-safety locking callbacks if and only if no locking
    33. 

  33.         callbacks are already registered.</li><li class="listitem"><code class="function">ne_sock_exit</code> will
    34. 

  34.         unset the thread-safety locking callbacks if and only if the
    35. 

  35.         locking callbacks registered are those registered by
    36. 

  36.         <code class="function">ne_sock_init</code>.</li></ul></div><p>
    37. 

  37. 

  38.       Applications and libraries should be able to co-operate to
    39. 

  39.       ensure that SSL use is always thread-safe if similar rules are
    40. 

  40.       always followed.</p></div><div class="refsect2"><a name="idm139901958899008"></a><h3>Thread-safe SSL with GnuTLS</h3><p>The cryptography library used by GnuTLS, libgcrypt, only
    41. 

  41.       supports an initialization operation to register thread-safety
    42. 

  42.       callbacks.  <code class="function">ne_sock_init</code> will register the
    43. 

  43.       thread-safe locking callbacks on first use;
    44. 

  44.       <code class="function">ne_sock_exit</code> cannot unregister them.  If
    45. 

  45.       multiple users of GnuTLS are present within the process, it is
    46. 

  46.       unsafe to dynamically unload neon from the process if neon
    47. 

  47.       is configured with thread-safe SSL support enabled (since the
    48. 

  48.       callbacks would be left pointing at unmapped memory once neon
    49. 

  49.       is unloaded).</p></div></div><div class="refsect1"><a name="idm139901958895872"></a><h2>Return value</h2><p><code class="function">ne_sock_init</code> returns zero on success,
    50. 

  50.     or non-zero on error.  If an error occurs, no further use of the
    51. 

  51.     neon library should be attempted.</p></div><div class="refsect1"><a name="idm139901958893968"></a><h2>See also</h2><p><a class="xref" href="refneon.html" title="neon"><span class="refentrytitle">neon</span></a>, <a class="xref" href="reffeat.html" title="ne_has_support"><span class="refentrytitle">ne_has_support</span></a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refshave.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="refcert.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_shave </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_cert_identity</td></tr></table></div></body></html>
    52.