DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

CRYPTO_set_dynlock_create_callback(3)




threads(3)                   OpenSSL                   threads(3)


NAME

     CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback,
     CRYPTO_THREADID_current, CRYPTO_THREADID_cmp,
     CRYPTO_THREADID_cpy, CRYPTO_THREADID_hash,
     CRYPTO_set_locking_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>

      /* Don't use this structure directly. */
      typedef struct crypto_threadid_st
              {
              void *ptr;
              unsigned long val;
              } CRYPTO_THREADID;
      /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */
      void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val);
      void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr);
      int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *));
      void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *);
      void CRYPTO_THREADID_current(CRYPTO_THREADID *id);
      int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a,
                              const CRYPTO_THREADID *b);
      void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest,
                               const CRYPTO_THREADID *src);
      unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id);

      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);

1.0.2t               Last change: 2019-09-10                    1

threads(3)                   OpenSSL                   threads(3)

      #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 generally be used safely in multi-threaded
     applications provided that at least two callback functions
     are set, the locking_function and threadid_func.  Note that
     OpenSSL is not completely thread-safe, and unfortunately not
     all global resources have the necessary locks.  Further, the
     thread-safety does not extend to things like multiple
     threads using the same SSL object at the same time.

     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.

     locking_function() must be able to handle up to
     CRYPTO_num_locks() different mutex locks. It sets the n-th
     lock if mode & CRYPTO_LOCK, and releases it otherwise.

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

     threadid_func(CRYPTO_THREADID *id) is needed to record the
     currently-executing thread's identifier into id. The
     implementation of this callback should not fill in id
     directly, but should use CRYPTO_THREADID_set_numeric() if
     thread IDs are numeric, or CRYPTO_THREADID_set_pointer() if
     they are pointer-based.  If the application does not
     register such a callback using
     CRYPTO_THREADID_set_callback(), then a default
     implementation is used - on Windows and BeOS this uses the
     system's default thread identifying APIs, and on all other
     platforms it uses the address of errno. The latter is
     satisfactory for thread-safety if and only if the platform
     has a thread-local error number facility.

     Once threadid_func() is registered, or if the built-in
     default implementation is to be used;


thread ID into the given id object.


1.0.2t               Last change: 2019-09-10                    2

threads(3)                   OpenSSL                   threads(3)

     * CRYPTO_THREADID_current() records the currently-executing
for equality, ie. the same semantics as memcmp()).
     * CRYPTO_THREADID_cmp() compares two thread IDs (returning zero
     * CRYPTO_THREADID_cpy() duplicates a thread ID value,
hash-table key. This is usually the exact numeric or pointer-
based thread ID used internally, however this also handles the
unusual case where pointers are larger than 'long' variables and
the platform's thread IDs are pointer-based - in this case,
mixing is done to attempt to produce a unique numeric value even
though it is not as wide as the platform's true thread IDs.
     * CRYPTO_THREADID_hash() returns a numeric value usable as a

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

dyn_lock_function and dyn_destroy_function.
     * Three additional callback function, dyn_create_function,
handle.
     * A structure defined with the data that each lock needs to

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

     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 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 needed to destroy the lock l. Multi-threaded
     applications might crash at random if it is not set.

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

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

     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 behaviour if misused (for example, CRYPTO_READ and
     CRYPTO_WRITE should not be used together):

1.0.2t               Last change: 2019-09-10                    3

threads(3)                   OpenSSL                   threads(3)

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


RETURN VALUES

     CRYPTO_num_locks() returns the required number of locks.

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

     The other functions return no values.


NOTES

     You can find out if OpenSSL was configured with thread
     support:

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

     Also, dynamic locks are currently not used internally by
     OpenSSL, but may do so in the future.


EXAMPLES

     crypto/threads/mttest.c shows examples of the callback
     functions on Solaris, Irix and Win32.


HISTORY

     CRYPTO_set_locking_callback() is 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_THREADID and
     associated functions were introduced in OpenSSL 1.0.0 to
     replace (actually, deprecate) the previous
     CRYPTO_set_id_callback(), CRYPTO_get_id_callback(), and
     CRYPTO_thread_id() functions which assumed thread IDs to
     always be represented by 'unsigned long'.


SEE ALSO

     crypto(3)

1.0.2t               Last change: 2019-09-10                    4


Man(1) output converted with man2html