Index Index for
Section 3
Index Alphabetical
listing for T
Bottom of page Bottom of
page		 

threads(3)


NAME

  threads, CRYPTO_set_locking_callback, CRYPTO_set_id_callback,
  CRYPTO_num_locks, CRYPTO_set_dynlock_create_callback,
  CRYPTO_set_dynlock_lock_callback, CRYPTO_set_dynlock_destroy_callback,
  CRYPTO_get_new_dynlockid, CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL
  thread support


SYNOPSIS

  #include <openssl/crypto.h>

  void CRYPTO_set_locking_callback(
	  void (*locking_function)(int mode, int n, const char *file, int
  line) );

  void CRYPTO_set_id_callback(
	  unsigned long (*id_function)(void) );

  int CRYPTO_num_locks(
	  void );

       /* struct CRYPTO_dynlock_value needs to be defined by the user */
       struct CRYPTO_dynlock_value;

  void CRYPTO_set_dynlock_create_callback(
	  struct CRYPTO_dynlock_value * (*dyn_create_function)(char *file,
  int line) );

  void CRYPTO_set_dynlock_lock_callback(
	  void (*dyn_lock_function)(int mode, struct CRYPTO_dynlock_value *l,
  const char *file, int line) );

  void CRYPTO_set_dynlock_destroy_callback(
	  void (*dyn_destroy_function)(struct CRYPTO_dynlock_value *l, const
  char *file, int line) );

  int CRYPTO_get_new_dynlockid(
	  void );

  void CRYPTO_destroy_dynlockid(
	  int i );

  void CRYPTO_lock(
	  int mode,
	  int n,
	  const char *file,
	  int line );

       #define CRYPTO_w_lock(type)     \
       CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)

       #define CRYPTO_w_unlock(type)   \
       CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)

       #define CRYPTO_r_lock(type)     \
       CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)

       #define CRYPTO_r_unlock(type)   \
       CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)

       #define CRYPTO_add(addr,amount,type)    \
       CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)


DESCRIPTION

  OpenSSL can safely be used in multi-threaded applications provided that at
  least two callback functions are set.

  The locking_function(int mode, int n, const char *file, int line) is needed
  to perform locking on shared data structures. Multi-threaded applications
  will crash at random if it is not set.

  The locking_function() (int mode, int n, const char *file, int line) is
  needed to   perform locking on shared data structures.  (Note that OpenSSL
  uses a number of global data structures that will be implicitly shared
  whenever multiple threads use OpenSSL.) Multi-threaded applications will
  crash at random if it is not set.

  The file and line are the file number of the function setting the lock.
  They can be useful for debugging.

  The id_function(void) function returns a thread ID.  It is not needed on
  Windows nor on platforms where getpid() returns a different ID for each
  thread (most notably Linux).

  Additionally, OpenSSL supports dynamic locks, and some parts of OpenSSL
  need it for better performance.  To enable this, the following is required:

    ·  Three additional callback functions: dyn_create_function,
       dyn_lock_function and dyn_destroy_function.

    ·  A structure defined with the data that each lock needs to handle.

  The struct CRYPTO_dynlock_value has to be defined to contain whatever
  structure is needed to handle locks.

  The dyn_create_function(const char *file, int line) is needed to create a
  lock.	 Multi-threaded applications might crash at random if it is not set.

  The dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int
  line) is needed to perform locking off dynamic lock numbered n. Multi-
  threaded applications might crash at random if it is not set.

  The dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
  needed to destroy the lock  l. Multi-threaded applications might crash at
  random if it is not set.

  The CRYPTO_get_new_dynlockid() function is used to create locks.  It will
  call dyn_create_function for the actual creation.

  The CRYPTO_destroy_dynlockid() function is used to destroy locks.  It will
  call dyn_destroy_function for the actual destruction.

  The CRYPTO_lock() function is used to lock and unlock the locks.  The mode
  is a bitfield describing what should be done with the lock.  The value of n
  is the number of the lock as returned from the CRYPTO_get_new_dynlockid()
  function.  The mode can be combined from the following values.  These
  values are pairwise exclusive, with undefined behavior if misused. For
  example, CRYPTO_READ and CRYPTO_WRITE should not be used together:

       CRYPTO_LOCK     0x01
       CRYPTO_UNLOCK   0x02
       CRYPTO_READ     0x04
       CRYPTO_WRITE    0x08


RETURN VALUES

  The CRYPTO_num_locks() function returns the required number of locks.

  CRYPTO_get_new_dynlockid() function returns the index to the newly created
  lock.

  The other functions return no values.


NOTES

  You can determine if OpenSSL was configured with thread support:

       #define OPENSSL_THREAD_DEFINES
       #include <openssl/opensslconf.h>
       #if defined(THREADS)
	  // thread support enabled
       #else
	  // no thread support
       #endif

  Also, dynamic locks are not used internally by OpenSSL.


HISTORY

  The CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() functions
  are available in all versions of SSLeay and OpenSSL. The CRYPTO_num_locks()
  function was added in OpenSSL 0.9.4. All functions dealing with dynamic
  locks were added in OpenSSL 0.9.5b-dev.


SEE ALSO

  Functions: crypto(3)

Index Index for
Section 3
Index Alphabetical
listing for T
Top of page Top of
page