From a68d8c7b77a3d46d591b89cfd0ecd2a2242e4613 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 12 Jan 2017 12:22:12 -0500 Subject: [PATCH] Add documentation Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/1252) --- doc/man3/OPENSSL_malloc.pod | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 2104f43108..4b55f312f9 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/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=... + env OPENSSL_MALLOC_FD=... + 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 option, then two additional +environment variables can be used for testing failure handling. The variable +B 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 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 argument of the B. -- 2.25.1