'\" t
.\"     Title: ne_sock_init
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
.\"      Date: 13 September 2009
.\"    Manual: neon API reference
.\"    Source: neon 0.29.0
.\"  Language: English
.\"
.TH "NE_SOCK_INIT" "3" "13 September 2009" "neon 0.29.0" "neon API reference"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ne_sock_init, ne_sock_exit \- perform library initialization
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <ne_socket\&.h>
.fi
.ft
.HP \w'int\ ne_sock_init('u
.BI "int ne_sock_init(void);"
.HP \w'void\ ne_sock_exit('u
.BI "void ne_sock_exit(void);"
.SH "DESCRIPTION"
.PP
In some platforms and configurations, neon may be using some socket or SSL libraries which require global initialization before use\&. To perform this initialization, the
\fBne_sock_init\fR
function must be called before any other library functions are used\&.
.PP
Once all use of neon is complete,
\fBne_sock_exit\fR
can be called to perform de\-initialization of socket or SSL libraries, if necessary\&. Uses of
\fBne_sock_init\fR
and
\fBne_sock_exit\fR
are "reference counted"; if N calls to
\fBne_sock_init\fR
are made, only the Nth call to
\fBne_sock_exit\fR
will have effect\&.
.PP
\fBne_sock_init\fR
will set the disposition of the
SIGPIPE
signal to
\fIignored\fR\&. No change is made to the
SIGPIPE
disposition by
\fBne_sock_exit\fR\&.
.PP
Both the SSL libraries supported by neon \(em OpenSSL and GnuTLS \(em require callbacks to be registered to allow thread\-safe use of SSL\&. These callbacks are stored as global variables and so their state persists for as long as the library in question is loaded into the process\&. If multiple users of the SSL library exist within the process, this can be problematic, particularly if one is dynamically loaded (and may subsequently be unloaded)\&.
.PP
If neon is configured using the
\-\-enable\-threadsafe\-ssl
flag, thread\-safe SSL support will be enabled automatically, as covered in the following section\&. Otherwise, it is not safe to use neon with SSL in a multi\-threaded process\&. The
ne_has_support
function can be used to determine whether neon is built to enable thread\-safety support in the SSL library\&.
.SS "Thread\-safe SSL with OpenSSL"
.PP
neon follows two simple rules when dealing with the OpenSSL locking callbacks:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBne_sock_init\fR
will set thread\-safety locking callbacks if and only if no locking callbacks are already registered\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBne_sock_exit\fR
will unset the thread\-safety locking callbacks if and only if the locking callbacks registered are those registered by
\fBne_sock_init\fR\&.
.RE
.sp
.RE
Applications and libraries should be able to co\-operate to ensure that SSL use is always thread\-safe if similar rules are always followed\&.
.SS "Thread\-safe SSL with GnuTLS"
.PP
The cryptography library used by GnuTLS, libgcrypt, only supports an initialization operation to register thread\-safety callbacks\&.
\fBne_sock_init\fR
will register the thread\-safe locking callbacks on first use;
\fBne_sock_exit\fR
cannot unregister them\&. If multiple users of GnuTLS are present within the process, it is unsafe to dynamically unload neon from the process if neon is configured with thread\-safe SSL support enabled (since the callbacks would be left pointing at unmapped memory once neon is unloaded)\&.
.SH "RETURN VALUE"
.PP
\fBne_sock_init\fR
returns zero on success, or non\-zero on error\&. If an error occurs, no further use of the neon library should be attempted\&.
.SH "SEE ALSO"
.PP
neon(3),
ne_has_support(3)
.SH "AUTHOR"
.PP
\fBJoe Orton\fR <\&neon@lists.manyfish.co.uk\&>
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br