doc/crypto/threads.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/crypto.h>
  10
  11  void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
  12         int n, const char *file, int line));
  13
  14  void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
  15
  16  int CRYPTO_num_locks(void);
  17
  18 =head1 DESCRIPTION
  19
  20 OpenSSL can safely be used in multi-threaded applications provided
  21 that two callback functions are set.
  22
  23 locking_function(int mode, int n, const char *file, int line) is
  24 needed to perform locking on shared data stuctures. Multi-threaded
  25 applications will crash at random if it is not set.
  26
  27 locking_function() must be able to handle up to CRYPTO_num_locks()
  28 different mutex locks. It sets the B<n>-th lock if B<mode> &
  29 B<CRYPTO_LOCK>, and releases it otherwise.
  30
  31 B<file> and B<line> are the file number of the function setting the
  32 lock. They can be useful for debugging.
  33
  34 id_function(void) is a function that returns a thread ID. It is not
  35 needed on Windows nor on platforms where getpid() returns a different
  36 ID for each thread.
  37
  38 =head1 RETURN VALUES
  39
  40 CRYPTO_num_locks() returns the required number of locks.
  41 The other functions return no values.
  42
  43 =head1 NOTE
  44
  45 You can find out if OpenSSL was configured with thread support:
  46
  47  #define OPENSSL_THREAD_DEFINES
  48  #include <openssl/opensslconf.h>
  49  #if defined(THREADS)
  50    // thread support enabled
  51  #else
  52    // no thread support
  53  #endif
  54
  55 =head1 EXAMPLES
  56
  57 B<crypto/threads/mttest.c> shows examples of the callback functions on
  58 Solaris, Irix and Win32.
  59
  60 =head1 HISTORY
  61
  62 CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are
  63 available in all versions of SSLeay and OpenSSL.
  64 CRYPTO_num_locks() was added in OpenSSL 0.9.4.
  65
  66 =head1 SEE ALSO
  67
  68 L<crypto(3)|crypto(3)>
  69
  70 =cut