Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / threads.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH threads 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
192CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
193CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
194CRYPTO_destroy_dynlockid, CRYPTO_lock \- OpenSSL thread support
195.SH "SYNOPSIS"
74dab6c2 196.PP
984263bc
MD
197.Vb 1
198\& #include <openssl/crypto.h>
199.Ve
200.Vb 2
201\& void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
202\& int n, const char *file, int line));
203.Ve
204.Vb 1
205\& void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
206.Ve
207.Vb 1
208\& int CRYPTO_num_locks(void);
209.Ve
210.Vb 2
211\& /* struct CRYPTO_dynlock_value needs to be defined by the user */
212\& struct CRYPTO_dynlock_value;
213.Ve
214.Vb 7
215\& void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
216\& (*dyn_create_function)(char *file, int line));
217\& void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
218\& (int mode, struct CRYPTO_dynlock_value *l,
219\& const char *file, int line));
220\& void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
221\& (struct CRYPTO_dynlock_value *l, const char *file, int line));
222.Ve
223.Vb 1
224\& int CRYPTO_get_new_dynlockid(void);
225.Ve
226.Vb 1
227\& void CRYPTO_destroy_dynlockid(int i);
228.Ve
229.Vb 1
230\& void CRYPTO_lock(int mode, int n, const char *file, int line);
231.Ve
232.Vb 10
233\& #define CRYPTO_w_lock(type) \e
234\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
235\& #define CRYPTO_w_unlock(type) \e
236\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
237\& #define CRYPTO_r_lock(type) \e
238\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
239\& #define CRYPTO_r_unlock(type) \e
240\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
241\& #define CRYPTO_add(addr,amount,type) \e
242\& CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
243.Ve
244.SH "DESCRIPTION"
984263bc
MD
245OpenSSL can safely be used in multi-threaded applications provided
246that at least two callback functions are set.
247.PP
74dab6c2 248\fIlocking_function\fR\|(int mode, int n, const char *file, int line) is
984263bc
MD
249needed to perform locking on shared data structures.
250(Note that OpenSSL uses a number of global data structures that
251will be implicitly shared whenever multiple threads use OpenSSL.)
252Multi-threaded applications will crash at random if it is not set.
253.PP
74dab6c2 254\fIlocking_function()\fR must be able to handle up to \fICRYPTO_num_locks()\fR
984263bc 255different mutex locks. It sets the \fBn\fR\-th lock if \fBmode\fR &
74dab6c2 256\fBCRYPTO_LOCK\fR, and releases it otherwise.
984263bc 257.PP
74dab6c2 258\fBfile\fR and \fBline\fR are the file number of the function setting the
984263bc
MD
259lock. They can be useful for debugging.
260.PP
74dab6c2 261\fIid_function\fR\|(void) is a function that returns a thread ID. It is not
984263bc 262needed on Windows nor on platforms where \fIgetpid()\fR returns a different
74dab6c2 263ID for each thread (most notably Linux).
984263bc
MD
264.PP
265Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
266of OpenSSL need it for better performance. To enable this, the following
267is required:
268.Ip "\(bu Three additional callback function, dyn_create_function, dyn_lock_function and dyn_destroy_function." 4
984263bc 269.Ip "\(bu A structure defined with the data that each lock needs to handle." 4
984263bc
MD
270.PP
271struct CRYPTO_dynlock_value has to be defined to contain whatever structure
272is needed to handle locks.
273.PP
74dab6c2 274\fIdyn_create_function\fR\|(const char *file, int line) is needed to create a
984263bc
MD
275lock. Multi-threaded applications might crash at random if it is not set.
276.PP
74dab6c2 277\fIdyn_lock_function\fR\|(int mode, CRYPTO_dynlock *l, const char *file, int line)
984263bc
MD
278is needed to perform locking off dynamic lock numbered n. Multi-threaded
279applications might crash at random if it is not set.
280.PP
74dab6c2 281\fIdyn_destroy_function\fR\|(CRYPTO_dynlock *l, const char *file, int line) is
984263bc
MD
282needed to destroy the lock l. Multi-threaded applications might crash at
283random if it is not set.
284.PP
74dab6c2 285\fICRYPTO_get_new_dynlockid()\fR is used to create locks. It will call
984263bc
MD
286dyn_create_function for the actual creation.
287.PP
74dab6c2 288\fICRYPTO_destroy_dynlockid()\fR is used to destroy locks. It will call
984263bc
MD
289dyn_destroy_function for the actual destruction.
290.PP
74dab6c2 291\fICRYPTO_lock()\fR is used to lock and unlock the locks. mode is a bitfield
984263bc
MD
292describing what should be done with the lock. n is the number of the
293lock as returned from \fICRYPTO_get_new_dynlockid()\fR. mode can be combined
294from the following values. These values are pairwise exclusive, with
295undefined behaviour if misused (for example, \s-1CRYPTO_READ\s0 and \s-1CRYPTO_WRITE\s0
296should not be used together):
297.PP
298.Vb 4
299\& CRYPTO_LOCK 0x01
300\& CRYPTO_UNLOCK 0x02
301\& CRYPTO_READ 0x04
302\& CRYPTO_WRITE 0x08
303.Ve
304.SH "RETURN VALUES"
74dab6c2 305\fICRYPTO_num_locks()\fR returns the required number of locks.
984263bc 306.PP
74dab6c2 307\fICRYPTO_get_new_dynlockid()\fR returns the index to the newly created lock.
984263bc
MD
308.PP
309The other functions return no values.
310.SH "NOTE"
984263bc
MD
311You can find out if OpenSSL was configured with thread support:
312.PP
313.Vb 7
314\& #define OPENSSL_THREAD_DEFINES
315\& #include <openssl/opensslconf.h>
316\& #if defined(THREADS)
317\& // thread support enabled
318\& #else
319\& // no thread support
320\& #endif
321.Ve
322Also, dynamic locks are currently not used internally by OpenSSL, but
323may do so in the future.
324.SH "EXAMPLES"
74dab6c2 325\fBcrypto/threads/mttest.c\fR shows examples of the callback functions on
984263bc
MD
326Solaris, Irix and Win32.
327.SH "HISTORY"
74dab6c2 328\fICRYPTO_set_locking_callback()\fR and \fICRYPTO_set_id_callback()\fR are
984263bc 329available in all versions of SSLeay and OpenSSL.
74dab6c2 330\fICRYPTO_num_locks()\fR was added in OpenSSL 0.9.4.
984263bc
MD
331All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
332.SH "SEE ALSO"
984263bc 333crypto(3)
74dab6c2
JR
334
335.rn }` ''
336.IX Title "threads 3"
337.IX Name "CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
338CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
339CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
340CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support"
341
342.IX Header "NAME"
343
344.IX Header "SYNOPSIS"
345
346.IX Header "DESCRIPTION"
347
348.IX Item "\(bu Three additional callback function, dyn_create_function, dyn_lock_function and dyn_destroy_function."
349
350.IX Item "\(bu A structure defined with the data that each lock needs to handle."
351
352.IX Header "RETURN VALUES"
353
354.IX Header "NOTE"
355
356.IX Header "EXAMPLES"
357
358.IX Header "HISTORY"
359
360.IX Header "SEE ALSO"
361