1=pod
2
3=head1 NAME
4
5CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback,
6CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy,
7CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks,
8CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
9CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
10CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
11
12=head1 SYNOPSIS
13
14 #include <openssl/crypto.h>
15
16 /* Don't use this structure directly. */
17 typedef struct crypto_threadid_st
18         {
19         void *ptr;
20         unsigned long val;
21         } CRYPTO_THREADID;
22 /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */
23 void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val);
24 void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr);
25 int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *));
26 void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *);
27 void CRYPTO_THREADID_current(CRYPTO_THREADID *id);
28 int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a,
29                         const CRYPTO_THREADID *b);
30 void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest,
31                          const CRYPTO_THREADID *src);
32 unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id);
33
34 int CRYPTO_num_locks(void);
35
36 /* struct CRYPTO_dynlock_value needs to be defined by the user */
37 struct CRYPTO_dynlock_value;
38
39 void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
40	(*dyn_create_function)(char *file, int line));
41 void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
42	(int mode, struct CRYPTO_dynlock_value *l,
43	const char *file, int line));
44 void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
45	(struct CRYPTO_dynlock_value *l, const char *file, int line));
46
47 int CRYPTO_get_new_dynlockid(void);
48
49 void CRYPTO_destroy_dynlockid(int i);
50
51 void CRYPTO_lock(int mode, int n, const char *file, int line);
52
53 #define CRYPTO_w_lock(type)	\
54	CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
55 #define CRYPTO_w_unlock(type)	\
56	CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
57 #define CRYPTO_r_lock(type)	\
58	CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
59 #define CRYPTO_r_unlock(type)	\
60	CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
61 #define CRYPTO_add(addr,amount,type)	\
62	CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
63
64=head1 DESCRIPTION
65
66OpenSSL can safely be used in multi-threaded applications provided
67that at least two callback functions are set, locking_function and
68threadid_func.
69
70locking_function(int mode, int n, const char *file, int line) is
71needed to perform locking on shared data structures. 
72(Note that OpenSSL uses a number of global data structures that
73will be implicitly shared whenever multiple threads use OpenSSL.)
74Multi-threaded applications will crash at random if it is not set.
75
76locking_function() must be able to handle up to CRYPTO_num_locks()
77different mutex locks. It sets the B<n>-th lock if B<mode> &
78B<CRYPTO_LOCK>, and releases it otherwise.
79
80B<file> and B<line> are the file number of the function setting the
81lock. They can be useful for debugging.
82
83threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing
84thread's identifier into B<id>. The implementation of this callback should not
85fill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread
86IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based.
87If the application does not register such a callback using
88CRYPTO_THREADID_set_callback(), then a default implementation is used - on
89Windows and BeOS this uses the system's default thread identifying APIs, and on
90all other platforms it uses the address of B<errno>. The latter is satisfactory
91for thread-safety if and only if the platform has a thread-local error number
92facility.
93
94Once threadid_func() is registered, or if the built-in default implementation is
95to be used;
96
97=over 4
98
99=item *
100CRYPTO_THREADID_current() records the currently-executing thread ID into the
101given B<id> object.
102
103=item *
104CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie.
105the same semantics as memcmp()).
106
107=item *
108CRYPTO_THREADID_cpy() duplicates a thread ID value,
109
110=item *
111CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This
112is usually the exact numeric or pointer-based thread ID used internally, however
113this also handles the unusual case where pointers are larger than 'long'
114variables and the platform's thread IDs are pointer-based - in this case, mixing
115is done to attempt to produce a unique numeric value even though it is not as
116wide as the platform's true thread IDs.
117
118=back
119
120Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
121of OpenSSL need it for better performance.  To enable this, the following
122is required:
123
124=over 4
125
126=item *
127Three additional callback function, dyn_create_function, dyn_lock_function
128and dyn_destroy_function.
129
130=item *
131A structure defined with the data that each lock needs to handle.
132
133=back
134
135struct CRYPTO_dynlock_value has to be defined to contain whatever structure
136is needed to handle locks.
137
138dyn_create_function(const char *file, int line) is needed to create a
139lock.  Multi-threaded applications might crash at random if it is not set.
140
141dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line)
142is needed to perform locking off dynamic lock numbered n. Multi-threaded
143applications might crash at random if it is not set.
144
145dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
146needed to destroy the lock l. Multi-threaded applications might crash at
147random if it is not set.
148
149CRYPTO_get_new_dynlockid() is used to create locks.  It will call
150dyn_create_function for the actual creation.
151
152CRYPTO_destroy_dynlockid() is used to destroy locks.  It will call
153dyn_destroy_function for the actual destruction.
154
155CRYPTO_lock() is used to lock and unlock the locks.  mode is a bitfield
156describing what should be done with the lock.  n is the number of the
157lock as returned from CRYPTO_get_new_dynlockid().  mode can be combined
158from the following values.  These values are pairwise exclusive, with
159undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE
160should not be used together):
161
162	CRYPTO_LOCK	0x01
163	CRYPTO_UNLOCK	0x02
164	CRYPTO_READ	0x04
165	CRYPTO_WRITE	0x08
166
167=head1 RETURN VALUES
168
169CRYPTO_num_locks() returns the required number of locks.
170
171CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
172
173The other functions return no values.
174
175=head1 NOTES
176
177You can find out if OpenSSL was configured with thread support:
178
179 #define OPENSSL_THREAD_DEFINES
180 #include <openssl/opensslconf.h>
181 #if defined(OPENSSL_THREADS)
182   // thread support enabled
183 #else
184   // no thread support
185 #endif
186
187Also, dynamic locks are currently not used internally by OpenSSL, but
188may do so in the future.
189
190=head1 EXAMPLES
191
192B<crypto/threads/mttest.c> shows examples of the callback functions on
193Solaris, Irix and Win32.
194
195=head1 HISTORY
196
197CRYPTO_set_locking_callback() is
198available in all versions of SSLeay and OpenSSL.
199CRYPTO_num_locks() was added in OpenSSL 0.9.4.
200All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
201B<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0
202to replace (actually, deprecate) the previous CRYPTO_set_id_callback(),
203CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed
204thread IDs to always be represented by 'unsigned long'.
205
206=head1 SEE ALSO
207
208L<crypto(3)|crypto(3)>
209
210=cut
211