X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FOPENSSL_malloc.pod;h=2d678c951f0ae20701b6fc6cf6a2405293acb1f5;hp=39f9047bda9804a6120afc2690f1a8f384af06ba;hb=72a7a7021fa8bc82a11bc08bac1b0241a92143d0;hpb=e9b77246879071308130cda42336338ddb63cbb4 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 39f9047bda..2d678c951f 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -14,6 +14,7 @@ OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, CRYPTO_clear_realloc, CRYPTO_clear_free, CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, +CRYPTO_get_alloc_counts, CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, OPENSSL_MALLOC_FAILURES, @@ -62,6 +63,8 @@ OPENSSL_MALLOC_FD void *(*r)(void *, size_t, const char *, int), void (*f)(void *, const char *, int)) + void CRYPTO_get_alloc_counts(int *m, int *r, int *f) + int CRYPTO_set_mem_debug(int onoff) env OPENSSL_MALLOC_FAILURES=... @@ -75,10 +78,10 @@ OPENSSL_MALLOC_FD int CRYPTO_mem_debug_push(const char *info, const char *file, int line); int CRYPTO_mem_debug_pop(void); - void CRYPTO_mem_leaks(BIO *b); - void CRYPTO_mem_leaks_fp(FILE *fp); - void CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), - void *u); + int CRYPTO_mem_leaks(BIO *b); + int CRYPTO_mem_leaks_fp(FILE *fp); + int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), + void *u); =head1 DESCRIPTION @@ -87,10 +90,8 @@ generally macro's that add the standard C B<__FILE__> and B<__LINE__> parameters and call a lower-level B API. Some functions do not add those parameters, but exist for consistency. -OPENSSL_malloc_init() sets the lower-level memory allocation functions -to their default implementation. -It is generally not necessary to call this, except perhaps in certain -shared-library situations. +OPENSSL_malloc_init() does nothing and does not need to be called. It is +included for compatibility with older versions of OpenSSL. OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the C malloc(), realloc(), and free() functions. @@ -148,31 +149,6 @@ CRYPTO_set_mem_debug() turns this tracking on and off. In order to have 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> or C<100@0;0@25> means the first 100 allocations pass, then all -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): - - 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. @@ -198,14 +174,48 @@ of writing to a given BIO, the callback function is called for each output string with the string, length, and userdata B as the callback parameters. +If the library is built with the C option, then one +function, CRYPTO_get_alloc_counts(), and two additional environment +variables, B and B, +are available. + +The function CRYPTO_get_alloc_counts() fills in the number of times +each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been +called, into the values pointed to by B, B, and B, +respectively. If a pointer is NULL, then the corresponding count is not stored. + +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> or C<100@0;0@25> means the first 100 allocations pass, then all +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): + + OPENSSL_MALLOC_FAILURES='200;@10' + export OPENSSL_MALLOC_FAILURES + OPENSSL_MALLOC_FD=3 + export OPENSSL_MALLOC_FD + ...app invocation... 3>/tmp/log$$ + + =head1 RETURN VALUES OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() return no value. -CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there -are no leaks, 0 if there are leaks and -1 if an error occurred. +CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp() and CRYPTO_mem_leaks_cb() return 1 if +there are no leaks, 0 if there are leaks and -1 if an error occurred. OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), OPENSSL_clear_realloc(), @@ -235,7 +245,7 @@ only, say, the malloc() implementation is outright dangerous.> =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy