Add documentation

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

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)

(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> means the first 100 allocations pass, then all other allocations

(until the program exits or crashes) have the rest 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

the B<CRYPTO_MEM_CHECK_ON>.