Update the documentation on heap allocators / deallocators

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

diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
index eef8c6439384ccf7a06eb06618f77924e8a29e16..04fa0b718c76ba674e25f8c79e180a6896cdb52d 100644 (file)
--- a/doc/crypto/OPENSSL_malloc.pod
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -34,20 +34,20 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
  void *CRYPTO_malloc(size_t num, const char *file, int line)
  void *CRYPTO_zalloc(size_t num, const char *file, int line)
  void *CRYPTO_realloc(void *p, size_t num, const char *file, int line)
- void CRYPTO_free(void *str)
+ 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_free(void *str, size_t num)
+ void CRYPTO_clear_free(void *str, size_t num, const char *, int)
 
  void CRYPTO_get_mem_functions(
          void *(**m)(size_t, const char *, int),
          void *(**r)(void *, size_t, const char *, int),
-         void (**f)(void *))
+         void (**f)(void *, const char *, int))
  int CRYPTO_set_mem_functions(
          void *(*m)(size_t, const char *, int),
          void *(*r)(void *, size_t, const char *, int),
-         void (*f)(void *))
+         void (*f)(void *, const char *, int))
 
  int CRYPTO_set_mem_debug(int onoff)
 
@@ -96,12 +96,11 @@ OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
 library functions and are provided for portability.
 
 If no allocations have been done, it is possible to "swap out" the default
-implementations and replace them with alternate versions, or wrappers that
-do some additional housekeeping and then defer to the OpenSSL implementation.
-The CRYPTO_get_mem_functions() function fills in the function pointers for
-with the current functions (normally, and by default,
-CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free()).
-The CRYPTO_set_mem_functions() specifies a different set of functions.
+implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free()
+and replace them with alternate versions (hooks).
+CRYPTO_get_mem_functions() function fills in the given arguments with the
+function pointers for the current implementations.
+With CRYPTO_set_mem_functions(), you can specify a different set of functions.
 If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed.
 
 The default implementation can include some debugging capability (if enabled
@@ -132,17 +131,18 @@ OPENSSL_mem_debug_pop() removes identifying state from the stack.
 
 At the end of the program, calling CRYPTO_mem_leaks() or
 CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it
-to the specified BIO B<b> or FILE B<fp>.
-It will then L<abort(3)> if there were any unfree'd allocations.
+to the specified BIO B<b> or FILE B<fp>. These functions return 1 if
+there are no leaks, 0 if there are leaks and -1 if an error occurred.
 
 =head1 RETURN VALUES
 
 OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
-CRYPTO_free(), CRYPTO_clear_free(),
-CRYPTO_get_mem_functions(), and
-CRYPTO_mem_leaks()
+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.
+
 OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
 OPENSSL_clear_realloc(),
 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
@@ -159,4 +159,12 @@ CRYPTO_mem_ctrl() returns the previous value of the mode.
 OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop()
 return 1 on success or 0 on failure.
 
+=head1 NOTES
+
+While it's permitted to swap out only a few and not all the functions
+with CRYPTO_set_mem_functions(), it's recommended to swap them all out
+at once.  I<This applies specially if OpenSSL was built with the
+configuration option> C<crypto-mdebug> I<enabled.  In case, swapping out
+only, say, the malloc() implementation is outright dangerous.>
+
 =cut