threads(3)                  OpenSSL                  threads(3)





NAME
       CRYPTO_set_locking_callback, CRYPTO_set_id_callback,
       CRYPTO_num_locks, CRYPTO_set_dynlock_create_callback,
       CRYPTO_set_dynlock_lock_callback, CRYPTO_set_dyn-
       lock_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 applica-
       tions 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 struc-
       tures.  (Note that OpenSSL uses a number of global data
       structures that will be implicitly shared whenever mul-
       tiple 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 other-
       wise.

       file and 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. 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-
       times, some parts of OpenSSL need it for better perfor-
       mance.  To enable this, the following is required:

       o Three additional callback function, dyn_create_func-
       tion, dyn_lock_function and dyn_destroy_function.
       o A structure defined with the data that each lock needs
       to handle.

       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 destruc-
       tion.

       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 exclu-
       sive, with undefined behaviour 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
       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.

NOTE
       You can find out 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 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() and CRYPTO_set_id_call-
       back() are 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.

SEE ALSO
       crypto(3)



0.9.7c                     2001-11-08                threads(3)
