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