New functions CRYPTO_set_idptr_callback(),

CRYPTO_get_idptr_callback(), CRYPTO_thread_idptr() for a 'void *' type
thread ID, since the 'unsigned long' type of the existing thread ID
does not always work well.

1 files changed, 21 insertions, 7 deletions

diff --git a/doc/crypto/threads.pod b/doc/crypto/threads.pod
index 3df4ecd776..230cbe890b 100644
--- a/doc/crypto/threads.pod
+++ b/doc/crypto/threads.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
+CRYPTO_set_locking_callback, CRYPTO_set_id_callback,
+CRYPTO_set_idptr_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
@@ -16,6 +17,8 @@ CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
 
  void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
 
+ void CRYPTO_set_idptr_callback(void *(*idptr_function)(void));
+
  int CRYPTO_num_locks(void);
 
 
@@ -65,10 +68,17 @@ B<CRYPTO_LOCK>, and releases it otherwise.
 B<file> and B<line> are the file number of the function setting the
 lock. They can be useful for debugging.
 
-id_function(void) is a function that returns a thread ID, for example
-pthread_self() if it returns an integer (see NOTES below).  It isn't
-needed on Windows nor on platforms where getpid() returns a different
-ID for each thread (see NOTES below).
+id_function(void) is a function that returns a numerical thread ID,
+for example pthread_self() if it returns an integer (see NOTES below).
+By OpenSSL's defaults, this is not needed on Windows nor on platforms
+where getpid() returns a different ID for each thread (see NOTES
+below).
+
+idptr_function(void) is a function that similarly returns a thread ID,
+but of type void *.  This is not needed on platforms where &errno is
+different for each thread.  OpenSSL assumes that it is in the same
+thread iff both the numerical and the pointer thread ID agree, so it
+suffices to define one of these two callback functions appropriately.
 
 Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
 of OpenSSL need it for better performance.  To enable this, the following
@@ -153,8 +163,10 @@ Red Hat 9 will therefore see getpid() returning the same value for
 all threads.
 
 There is still the issue of platforms where pthread_self() returns
-something other than an integer.  This is a bit unusual, and this
-manual has no cookbook solution for that case.
+something other than an integer.  It is for cases like this that
+CRYPTO_set_idptr_callback() comes in handy.  (E.g., call malloc(1)
+once in each thread, and have idptr_function() return a pointer to
+this object.)
 
 =head1 EXAMPLES
 
@@ -168,6 +180,8 @@ available in all versions of SSLeay and OpenSSL.
 CRYPTO_num_locks() was added in OpenSSL 0.9.4.
 All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
 
+CRYPTO_set_idptr_callback() was added in OpenSSL 0.9.9.
+
 =head1 SEE ALSO
 
 L<crypto(3)|crypto(3)>