Update the documentation on heap allocators / deallocators

Reviewed-by: NRich Salz <rsalz@openssl.org>

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
@@ -160,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

doc/crypto/OPENSSL_secure_malloc.pod

@@ -25,7 +25,7 @@ CYRPTO_secure_malloc_used - secure heap storage
  void *CRYPTO_secure_zalloc(int num, const char *file, int line);
 
  void OPENSSL_secure_free(void* ptr);
- void CRYPTO_secure_free(void *ptr);
+ void CRYPTO_secure_free(void *ptr, const char *, int);
 
  size_t OPENSSL_secure_actual_size(const void *ptr);
  int OPENSSL_secure_allocated(const void *ptr);
@@ -74,7 +74,8 @@ OPENSSL_secure_malloc().
 If CRYPTO_secure_malloc_init() is not called, this is equivalent to
 calling OPENSSL_free().
 It exists for consistency with OPENSSL_secure_malloc() , and
-is a macro that expands to CRYPTO_secure_free().
+is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__>
+and C<__LINE__> parameters..
 
 OPENSSL_secure_allocated() tells whether or not a pointer is within
 the secure heap.