diff options
author | Rich Salz <rsalz@openssl.org> | 2017-01-12 12:22:12 -0500 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-01-12 14:04:41 -0500 |
commit | a68d8c7b77a3d46d591b89cfd0ecd2a2242e4613 (patch) | |
tree | 0aea319f2832e1c521367c969d74fb18e8a135c4 /doc/man3/OPENSSL_malloc.pod | |
parent | f7edeced4d8d3f650c5ee32f20ba7165da4e3067 (diff) | |
download | openssl-a68d8c7b77a3d46d591b89cfd0ecd2a2242e4613.zip openssl-a68d8c7b77a3d46d591b89cfd0ecd2a2242e4613.tar.gz openssl-a68d8c7b77a3d46d591b89cfd0ecd2a2242e4613.tar.bz2 |
Add documentation
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1252)
Diffstat (limited to 'doc/man3/OPENSSL_malloc.pod')
-rw-r--r-- | doc/man3/OPENSSL_malloc.pod | 32 |
1 files changed, 31 insertions, 1 deletions
diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 2104f43..4b55f31 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=... <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>. |