Update copyright year

[openssl.git] / doc / man3 / OPENSSL_malloc.pod

diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod
index 39f9047bda9804a6120afc2690f1a8f384af06ba..2d678c951f0ae20701b6fc6cf6a2405293acb1f5 100644 (file)
--- 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_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,
 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 *(*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=... <application>
  int CRYPTO_set_mem_debug(int onoff)
 
  env OPENSSL_MALLOC_FAILURES=... <application>


@@ -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);
 
  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
 
 
 =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<CRYPTO_xxx> API.
 Some functions do not add those parameters, but exist for consistency.
 
 parameters and call a lower-level B<CRYPTO_xxx> 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.
 
 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.
 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> 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<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>.
 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>.


@@ -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<u> as the callback
 parameters.
 
 output string with the string, length, and userdata B<u> as the callback
 parameters.
 

+If the library is built with the C<crypto-mdebug> option, then one
+function, CRYPTO_get_alloc_counts(), and two additional environment
+variables, B<OPENSSL_MALLOC_FAILURES> and B<OPENSSL_MALLOC_FD>,
+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<mcount>, B<rcount>, and B<fcount>,
+respectively.  If a pointer is NULL, then the corresponding count is not stored.
+
+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> 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<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$$
+
+

 =head1 RETURN VALUES
 
 OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
 CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
 return no value.
 
 =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(),
 
 OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
 OPENSSL_clear_realloc(),


@@ -235,7 +245,7 @@ only, say, the malloc() implementation is outright dangerous.>
 
 =head1 COPYRIGHT
 
 
 =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
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy