From 2c35d61790603530d11f52eda9132ff8640f9852 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 9 Aug 2022 11:55:45 +0100 Subject: Correct the documentation for OPENSSL_MALLOC_FD The documentation was misleading in that it suggests that this environment variable will record information about all allocations. While this is true it doesn't record the most useful information that you might expect such as the requested size of the allocation! It is mainly for use in conjunction with OPENSSL_MALLOC_FAILURES, and reports information about what chance an allocation has of failing. We also clarify that the mem_debug functions are actually no-ops in 3.0. Reviewed-by: Hugo Landau Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/18967) --- doc/man3/OPENSSL_malloc.pod | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 99a76e000d..7dc6468f0e 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -149,12 +149,12 @@ other allocations (until the program exits or crashes) 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): +it is taken as an open file descriptor. This is used in conjunction with +B described above. For every allocation it will log +details about how many allocations there have been so far, what percentage +chance there is for this allocation failing, and whether it has actually failed. +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 @@ -179,10 +179,11 @@ CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost always because allocations have already happened). CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), -CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and return -1. +CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and are no-ops that +always return -1. OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop() -are deprecated and return 0. +are deprecated and are no-ops that always return 0. =head1 HISTORY -- cgit v1.2.3