Debian Codegraph @

deps/libneon/doc/man/ne_sock_init.3

raw
1 '\" t
2 .\" Title: ne_sock_init
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_SOCK_INIT" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_sock_init, ne_sock_exit \- perform library initialization
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_socket\&.h>
37 .fi
38 .ft
39 .HP \w'int\ ne_sock_init('u
40 .BI "int ne_sock_init(void);"
41 .HP \w'void\ ne_sock_exit('u
42 .BI "void ne_sock_exit(void);"
43 .SH "DESCRIPTION"
44 .PP
45 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
46 \fBne_sock_init\fR
47 function must be called before any other library functions are used\&.
48 .PP
49 Once all use of neon is complete,
50 \fBne_sock_exit\fR
51 can be called to perform de\-initialization of socket or SSL libraries, if necessary\&. Uses of
52 \fBne_sock_init\fR
53 and
54 \fBne_sock_exit\fR
55 are "reference counted"; if N calls to
56 \fBne_sock_init\fR
57 are made, only the Nth call to
58 \fBne_sock_exit\fR
59 will have effect\&.
60 .PP
61 \fBne_sock_init\fR
62 will set the disposition of the
63 SIGPIPE
64 signal to
65 \fIignored\fR\&. No change is made to the
66 SIGPIPE
67 disposition by
68 \fBne_sock_exit\fR\&.
69 .PP
70 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)\&.
71 .PP
72 If neon is configured using the
73 \-\-enable\-threadsafe\-ssl
74 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
75 ne_has_support
76 function can be used to determine whether neon is built to enable thread\-safety support in the SSL library\&.
77 .SS "Thread\-safe SSL with OpenSSL"
78 .PP
79 neon follows two simple rules when dealing with the OpenSSL locking callbacks:
80 .sp
81 .RS 4
82 .ie n \{\
83 \h'-04'\(bu\h'+03'\c
84 .\}
85 .el \{\
86 .sp -1
87 .IP \(bu 2.3
88 .\}
89 \fBne_sock_init\fR
90 will set thread\-safety locking callbacks if and only if no locking callbacks are already registered\&.
91 .RE
92 .sp
93 .RS 4
94 .ie n \{\
95 \h'-04'\(bu\h'+03'\c
96 .\}
97 .el \{\
98 .sp -1
99 .IP \(bu 2.3
100 .\}
101 \fBne_sock_exit\fR
102 will unset the thread\-safety locking callbacks if and only if the locking callbacks registered are those registered by
103 \fBne_sock_init\fR\&.
104 .RE
105 .sp
106 Applications and libraries should be able to co\-operate to ensure that SSL use is always thread\-safe if similar rules are always followed\&.
107 .SS "Thread\-safe SSL with GnuTLS"
108 .PP
109 The cryptography library used by GnuTLS, libgcrypt, only supports an initialization operation to register thread\-safety callbacks\&.
110 \fBne_sock_init\fR
111 will register the thread\-safe locking callbacks on first use;
112 \fBne_sock_exit\fR
113 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)\&.
114 .SH "RETURN VALUE"
115 .PP
116 \fBne_sock_init\fR
117 returns zero on success, or non\-zero on error\&. If an error occurs, no further use of the neon library should be attempted\&.
118 .SH "SEE ALSO"
119 .PP
120 neon(3),
121 ne_has_support(3)
122 .SH "AUTHOR"
123 .PP
124 \fBJoe Orton\fR <\&[email protected]\&>
125 .RS 4
126 Author.
127 .RE
128 .SH "COPYRIGHT"
129 .br