PKCS12_parse manual page.

[openssl.git] / doc / crypto / threads.pod

diff --git a/doc/crypto/threads.pod b/doc/crypto/threads.pod
index a31b170806f8694e90a100d44d4ce9c961f3e9dd..afa45cd76cdaea221fae73bce0e09ea89b7c8554 100644 (file)
--- a/doc/crypto/threads.pod
+++ b/doc/crypto/threads.pod
@@ -2,7 +2,10 @@
 
 =head1 NAME
 
-CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
+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
 
 =head1 SYNOPSIS
 
@@ -17,14 +20,15 @@ CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
 
 
  /* struct CRYPTO_dynlock_value needs to be defined by the user */
- typedef struct CRYPTO_dynlock_value CRYPTO_dynlock;
+ struct CRYPTO_dynlock_value;
 
- void CRYPTO_set_dynlock_create_callback(CRYPTO_dynlock *(*dyn_create_function)
-       (char *file, int line));
+ 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, CRYPTO_dynlock *l, const char *file, int line));
+       (int mode, struct CRYPTO_dynlock_value *l,
+       const char *file, int line));
  void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
-       (CRYPTO_dynlock *l, const char *file, int line));
+       (struct CRYPTO_dynlock_value *l, const char *file, int line));
 
  int CRYPTO_get_new_dynlockid(void);
 
@@ -32,14 +36,27 @@ CRYPTO_set_locking_callback, CRYPTO_set_id_callback - OpenSSL thread support
 
  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__)
+
 =head1 DESCRIPTION
 
 OpenSSL can safely be used in multi-threaded applications provided
 that at least two callback functions are set.
 
 locking_function(int mode, int n, const char *file, int line) is
-needed to perform locking on shared data stuctures. Multi-threaded
-applications will crash at random if it is not set.
+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.
 
 locking_function() must be able to handle up to CRYPTO_num_locks()
 different mutex locks. It sets the B<n>-th lock if B<mode> &
@@ -56,6 +73,8 @@ Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
 of OpenSSL need it for better performance.  To enable this, the following
 is required:
 
+=over 4
+
 =item *
 Three additional callback function, dyn_create_function, dyn_lock_function
 and dyn_destroy_function.
@@ -63,6 +82,8 @@ and dyn_destroy_function.
 =item *
 A structure defined with the data that each lock needs to handle.
 
+=back
+
 struct CRYPTO_dynlock_value has to be defined to contain whatever structure
 is needed to handle locks.
 
@@ -70,7 +91,7 @@ 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.
 
 dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line)
-is needed to perform locking off dynamic lock nunmbered n. Multi-threaded
+is needed to perform locking off dynamic lock numbered n. Multi-threaded
 applications might crash at random if it is not set.
 
 dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
@@ -87,7 +108,7 @@ CRYPTO_lock() is used to lock and unlock the locks.  mode is a bitfield
 describing what should be done with the lock.  n is the number of the
 lock as returned from CRYPTO_get_new_dynlockid().  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
+undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE
 should not be used together):
 
        CRYPTO_LOCK     0x01
@@ -115,6 +136,9 @@ You can find out if OpenSSL was configured with thread support:
    // no thread support
  #endif
 
+Also, dynamic locks are currently not used internally by OpenSSL, but
+may do so in the future.
+
 =head1 EXAMPLES
 
 B<crypto/threads/mttest.c> shows examples of the callback functions on