Add documentation

Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1252)

doc/man3/OPENSSL_malloc.pod

@@ -15,7 +15,10 @@ CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
 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
 
@@ -60,6 +63,9 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
 
  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)
@@ -140,6 +146,30 @@ 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> 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>.