Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / threads.3
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "threads 3"
132.TH threads 3 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc
MD
133.SH "NAME"
134CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
135CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
136CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
137CRYPTO_destroy_dynlockid, CRYPTO_lock \- OpenSSL thread support
138.SH "SYNOPSIS"
8b0cefbb 139.IX Header "SYNOPSIS"
984263bc
MD
140.Vb 1
141\& #include <openssl/crypto.h>
142.Ve
8b0cefbb 143.PP
984263bc
MD
144.Vb 2
145\& void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
146\& int n, const char *file, int line));
147.Ve
8b0cefbb 148.PP
984263bc
MD
149.Vb 1
150\& void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
151.Ve
8b0cefbb 152.PP
984263bc
MD
153.Vb 1
154\& int CRYPTO_num_locks(void);
155.Ve
8b0cefbb 156.PP
984263bc
MD
157.Vb 2
158\& /* struct CRYPTO_dynlock_value needs to be defined by the user */
159\& struct CRYPTO_dynlock_value;
160.Ve
8b0cefbb 161.PP
984263bc
MD
162.Vb 7
163\& void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
164\& (*dyn_create_function)(char *file, int line));
165\& void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
166\& (int mode, struct CRYPTO_dynlock_value *l,
167\& const char *file, int line));
168\& void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
169\& (struct CRYPTO_dynlock_value *l, const char *file, int line));
170.Ve
8b0cefbb 171.PP
984263bc
MD
172.Vb 1
173\& int CRYPTO_get_new_dynlockid(void);
174.Ve
8b0cefbb 175.PP
984263bc
MD
176.Vb 1
177\& void CRYPTO_destroy_dynlockid(int i);
178.Ve
8b0cefbb 179.PP
984263bc
MD
180.Vb 1
181\& void CRYPTO_lock(int mode, int n, const char *file, int line);
182.Ve
8b0cefbb 183.PP
984263bc
MD
184.Vb 10
185\& #define CRYPTO_w_lock(type) \e
186\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
187\& #define CRYPTO_w_unlock(type) \e
188\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
189\& #define CRYPTO_r_lock(type) \e
190\& CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
191\& #define CRYPTO_r_unlock(type) \e
192\& CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
193\& #define CRYPTO_add(addr,amount,type) \e
194\& CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
195.Ve
196.SH "DESCRIPTION"
8b0cefbb 197.IX Header "DESCRIPTION"
984263bc
MD
198OpenSSL can safely be used in multi-threaded applications provided
199that at least two callback functions are set.
200.PP
8b0cefbb 201locking_function(int mode, int n, const char *file, int line) is
984263bc
MD
202needed to perform locking on shared data structures.
203(Note that OpenSSL uses a number of global data structures that
204will be implicitly shared whenever multiple threads use OpenSSL.)
205Multi-threaded applications will crash at random if it is not set.
206.PP
8b0cefbb 207\&\fIlocking_function()\fR must be able to handle up to \fICRYPTO_num_locks()\fR
984263bc 208different mutex locks. It sets the \fBn\fR\-th lock if \fBmode\fR &
8b0cefbb 209\&\fB\s-1CRYPTO_LOCK\s0\fR, and releases it otherwise.
984263bc 210.PP
8b0cefbb 211\&\fBfile\fR and \fBline\fR are the file number of the function setting the
984263bc
MD
212lock. They can be useful for debugging.
213.PP
8b0cefbb 214id_function(void) is a function that returns a thread \s-1ID\s0. It is not
984263bc 215needed on Windows nor on platforms where \fIgetpid()\fR returns a different
8b0cefbb 216\&\s-1ID\s0 for each thread (most notably Linux).
984263bc
MD
217.PP
218Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
219of OpenSSL need it for better performance. To enable this, the following
220is required:
8b0cefbb
JR
221.IP "* Three additional callback function, dyn_create_function, dyn_lock_function and dyn_destroy_function." 4
222.IX Item "Three additional callback function, dyn_create_function, dyn_lock_function and dyn_destroy_function."
223.PD 0
224.IP "* A structure defined with the data that each lock needs to handle." 4
225.IX Item "A structure defined with the data that each lock needs to handle."
226.PD
984263bc
MD
227.PP
228struct CRYPTO_dynlock_value has to be defined to contain whatever structure
229is needed to handle locks.
230.PP
8b0cefbb 231dyn_create_function(const char *file, int line) is needed to create a
984263bc
MD
232lock. Multi-threaded applications might crash at random if it is not set.
233.PP
8b0cefbb 234dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line)
984263bc
MD
235is needed to perform locking off dynamic lock numbered n. Multi-threaded
236applications might crash at random if it is not set.
237.PP
8b0cefbb 238dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
984263bc
MD
239needed to destroy the lock l. Multi-threaded applications might crash at
240random if it is not set.
241.PP
8b0cefbb 242\&\fICRYPTO_get_new_dynlockid()\fR is used to create locks. It will call
984263bc
MD
243dyn_create_function for the actual creation.
244.PP
8b0cefbb 245\&\fICRYPTO_destroy_dynlockid()\fR is used to destroy locks. It will call
984263bc
MD
246dyn_destroy_function for the actual destruction.
247.PP
8b0cefbb 248\&\fICRYPTO_lock()\fR is used to lock and unlock the locks. mode is a bitfield
984263bc
MD
249describing what should be done with the lock. n is the number of the
250lock as returned from \fICRYPTO_get_new_dynlockid()\fR. mode can be combined
251from the following values. These values are pairwise exclusive, with
252undefined behaviour if misused (for example, \s-1CRYPTO_READ\s0 and \s-1CRYPTO_WRITE\s0
253should not be used together):
254.PP
255.Vb 4
256\& CRYPTO_LOCK 0x01
257\& CRYPTO_UNLOCK 0x02
258\& CRYPTO_READ 0x04
259\& CRYPTO_WRITE 0x08
260.Ve
261.SH "RETURN VALUES"
8b0cefbb
JR
262.IX Header "RETURN VALUES"
263\&\fICRYPTO_num_locks()\fR returns the required number of locks.
984263bc 264.PP
8b0cefbb 265\&\fICRYPTO_get_new_dynlockid()\fR returns the index to the newly created lock.
984263bc
MD
266.PP
267The other functions return no values.
268.SH "NOTE"
8b0cefbb 269.IX Header "NOTE"
984263bc
MD
270You can find out if OpenSSL was configured with thread support:
271.PP
272.Vb 7
273\& #define OPENSSL_THREAD_DEFINES
274\& #include <openssl/opensslconf.h>
275\& #if defined(THREADS)
276\& // thread support enabled
277\& #else
278\& // no thread support
279\& #endif
280.Ve
8b0cefbb 281.PP
984263bc
MD
282Also, dynamic locks are currently not used internally by OpenSSL, but
283may do so in the future.
284.SH "EXAMPLES"
8b0cefbb
JR
285.IX Header "EXAMPLES"
286\&\fBcrypto/threads/mttest.c\fR shows examples of the callback functions on
984263bc
MD
287Solaris, Irix and Win32.
288.SH "HISTORY"
8b0cefbb
JR
289.IX Header "HISTORY"
290\&\fICRYPTO_set_locking_callback()\fR and \fICRYPTO_set_id_callback()\fR are
984263bc 291available in all versions of SSLeay and OpenSSL.
8b0cefbb
JR
292\&\fICRYPTO_num_locks()\fR was added in OpenSSL 0.9.4.
293All functions dealing with dynamic locks were added in OpenSSL 0.9.5b\-dev.
984263bc 294.SH "SEE ALSO"
74dab6c2 295.IX Header "SEE ALSO"
8b0cefbb 296\&\fIcrypto\fR\|(3)