secure/lib/libcrypto/man/threads.3

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