1NE_SOCK_INIT(3)               neon API reference               NE_SOCK_INIT(3)
2
3
4

NAME

6       ne_sock_init, ne_sock_exit - perform library initialization
7

SYNOPSIS

9       #include <ne_socket.h>
10
11       int ne_sock_init(void);
12
13       void ne_sock_exit(void);
14

DESCRIPTION

16       In some platforms and configurations, neon may be using some socket or
17       SSL libraries which require global initialization before use. To
18       perform this initialization, the ne_sock_init function must be called
19       before any other library functions are used.
20
21       Once all use of neon is complete, ne_sock_exit can be called to perform
22       de-initialization of socket or SSL libraries, if necessary. Uses of
23       ne_sock_init and ne_sock_exit are "reference counted"; if N calls to
24       ne_sock_init are made, only the Nth call to ne_sock_exit will have
25       effect.
26
27       ne_sock_init will set the disposition of the SIGPIPE signal to ignored.
28       No change is made to the SIGPIPE disposition by ne_sock_exit.
29
30       Both the SSL libraries supported by neon — OpenSSL and GnuTLS — require
31       callbacks to be registered to allow thread-safe use of SSL. These
32       callbacks are stored as global variables and so their state persists
33       for as long as the library in question is loaded into the process. If
34       multiple users of the SSL library exist within the process, this can be
35       problematic, particularly if one is dynamically loaded (and may
36       subsequently be unloaded).
37
38       If neon is configured using the --enable-threadsafe-ssl flag,
39       thread-safe SSL support will be enabled automatically, as covered in
40       the following section. Otherwise, it is not safe to use neon with SSL
41       in a multi-threaded process. The ne_has_support function can be used to
42       determine whether neon is built to enable thread-safety support in the
43       SSL library.
44
45   Thread-safe SSL with OpenSSL
46       neon follows two simple rules when dealing with the OpenSSL locking
47       callbacks:
48
49       ·   ne_sock_init will set thread-safety locking callbacks if and only
50           if no locking callbacks are already registered.
51
52       ·   ne_sock_exit will unset the thread-safety locking callbacks if and
53           only if the locking callbacks registered are those registered by
54           ne_sock_init.
55
56       Applications and libraries should be able to co-operate to ensure that
57       SSL use is always thread-safe if similar rules are always followed.
58
59   Thread-safe SSL with GnuTLS
60       The cryptography library used by GnuTLS, libgcrypt, only supports an
61       initialization operation to register thread-safety callbacks.
62       ne_sock_init will register the thread-safe locking callbacks on first
63       use; ne_sock_exit cannot unregister them. If multiple users of GnuTLS
64       are present within the process, it is unsafe to dynamically unload neon
65       from the process if neon is configured with thread-safe SSL support
66       enabled (since the callbacks would be left pointing at unmapped memory
67       once neon is unloaded).
68

RETURN VALUE

70       ne_sock_init returns zero on success, or non-zero on error. If an error
71       occurs, no further use of the neon library should be attempted.
72

SEE ALSO

74       neon(3), ne_has_support(3)
75

AUTHOR

77       Joe Orton <neon@lists.manyfish.co.uk>
78           Author.
79

81neon 0.29.3                     11 January 2010                NE_SOCK_INIT(3)
Impressum