X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FOPENSSL_malloc.pod;h=e17ff633b50cdadb16d45190903b77d570891aa7;hp=50f09751cf916e93aae792e1f57fd875d2fda6c0;hb=df1f538f28c10f2954757164b17781040d2355ef;hpb=99d63d4662e16afbeff49f29b48f1c87d5558ed0 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 50f09751cf..e17ff633b5 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -14,8 +14,12 @@ 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 - Memory allocation functions +CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, +OPENSSL_MALLOC_FAILURES, +OPENSSL_MALLOC_FD +- Memory allocation functions =head1 SYNOPSIS @@ -46,7 +50,8 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions void CRYPTO_free(void *str, const char *, int) char *CRYPTO_strdup(const char *p, const char *file, int line) char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line) - void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, const char *file, int line) + void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, + const char *file, int line) void CRYPTO_clear_free(void *str, size_t num, const char *, int) void CRYPTO_get_mem_functions( @@ -58,8 +63,13 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions 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=... + env OPENSSL_MALLOC_FD=... + int CRYPTO_mem_ctrl(int mode); int OPENSSL_mem_debug_push(const char *info) @@ -68,8 +78,10 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions 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); + 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 @@ -135,9 +147,10 @@ at build-time). This adds some overhead by keeping a list of all memory allocations, and removes items from the list when they are free'd. This is most useful for identifying memory leaks. -CRYPTO_set_mem_debug() turns this tracking on and off. It is normally -called at startup, but can be called at any time. - +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. 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. @@ -158,14 +171,53 @@ CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it to the specified BIO B or FILE B. These functions return 1 if there are no leaks, 0 if there are leaks and -1 if an error occurred. +CRYPTO_mem_leaks_cb() does the same as CRYPTO_mem_leaks(), but instead +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(), @@ -195,9 +247,9 @@ only, say, the malloc() implementation is outright dangerous.> =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L.