CRYPTO_clear_realloc, CRYPTO_clear_free,
CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
-CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
+CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb,
+OPENSSL_MALLOC_FAILURES,
+OPENSSL_MALLOC_FD
+- Memory allocation functions
=head1 SYNOPSIS
int CRYPTO_set_mem_debug(int onoff)
+ env OPENSSL_MALLOC_FAILURES=... <application>
+ env OPENSSL_MALLOC_FD=... <application>
+
int CRYPTO_mem_ctrl(int mode);
int OPENSSL_mem_debug_push(const char *info)
void CRYPTO_mem_leaks(BIO *b);
void CRYPTO_mem_leaks_fp(FILE *fp);
+ void CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
+ void *u);
=head1 DESCRIPTION
This adds some overhead by keeping a list of all memory allocations, and
removes items from the list when they are free'd.
This is most useful for identifying memory leaks.
-CRYPTO_set_mem_debug() turns this tracking on and off. It is normally
-called at startup, but can be called at any time.
+CRYPTO_set_mem_debug() turns this tracking on and off. In order to have
+any effect, is must be called before any of the allocation functions
+(e.g., CRYPTO_malloc()) are called, and is therefore normally one of the
+first lines of main() in an application.
+
+If the library is built with the C<crypto-mdebug> option, then two additional
+environment variables can be used for testing failure handling. The variable
+B<OPENSSL_MALLOC_FAILURES> controls how often allocations should fail.
+It is a set of fields separated by semicolons, which each field is a count
+(defaulting to zero) and an optional atsign and percentage (defaulting
+to 100). If the count is zero, then it lasts forever. For example,
+C<100;@25> or C<100@0;0@25> means the first 100 allocations pass, then all
+other allocations (until the program exits or crashes) have a 25% chance of
+failing.
+
+If the variable B<OPENSSL_MALLOC_FD> is parsed as a positive integer, then
+it is taken as an open file descriptor, and a record of all allocations is
+written to that descriptor. If an allocation will fail, and the platform
+supports it, then a backtrace will be written to the descriptor. This can
+be useful because a malloc may fail but not be checked, and problems will
+only occur later. The following example in classic shell syntax shows how
+to use this (will not work on all platforms):
+
+ OPENSSL_MALLOC_FAILURES='200;@10'
+ export OPENSSL_MALLOC_FAILURES
+ OPENSSL_MALLOC_FD=3
+ export OPENSSL_MALLOC_FD
+ ...app invocation... 3>/tmp/log$$
CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking.
To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
to the specified BIO B<b> or FILE B<fp>. These functions return 1 if
there are no leaks, 0 if there are leaks and -1 if an error occurred.
+CRYPTO_mem_leaks_cb() does the same as CRYPTO_mem_leaks(), but instead
+of writing to a given BIO, the callback function is called for each
+output string with the string, length, and userdata B<u> as the callback
+parameters.
+
=head1 RETURN VALUES
OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()