doc/man3/OPENSSL_malloc.pod: document OPENSSL_aligned_alloc peculiarity

OPENSSL_aligned_alloc can return NULL in cases other than memory
exhaustion or incorrect arguments, document that.

Signed-off-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/28059)

diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod
index 6e8d350dd306550b0012cbe4ad54eac22fe0510d..9dd3bc17666601e2f808e1b036da35a0402637dc 100644 (file)
--- a/doc/man3/OPENSSL_malloc.pod
+++ b/doc/man3/OPENSSL_malloc.pod
@@ -127,7 +127,13 @@ allows for the caller to specify an alignment value, for instances in
 which the default alignment of malloc is insufficient for the caller's
 needs.  Note, the alignment value must be a power of 2, and the size
 specified must be a multiple of the alignment.
-NOTE: The call to OPENSSL_aligned_alloc() accepts a 3rd argument, I<freeptr>
+NOTES:
+
+=over 4
+
+=item *
+
+The call to OPENSSL_aligned_alloc() accepts a 3rd argument, I<freeptr>
 which must point to a void pointer.  On some platforms, there is no available
 library call to obtain memory allocations with alignment greater than what
 malloc provides.  In this case, OPENSSL_aligned_alloc() implements its own
@@ -136,6 +142,18 @@ pointer to be on the requested alignment boundary.  In order to safely free
 allocations made by this method, the caller must return the value
 in the I<freeptr> variable, rather than the returned pointer.
 
+=item *
+
+The call to OPENSSL_aligned_alloc() may fail for reasons other than memory
+exhaustion, depending on the underlying implementation, and, most notably,
+OpenSSL library's build configuration:  for example, it always returns C<NULL>
+without setting any error if OpenSSL is built with C<OPENSSL_SMALL_FOOTPRINT>
+macro defined.  Consequently, caller may need to fall back to a non-aligned
+memory allocation (and open-code the alignment routine if the alignment
+is a requirement).
+
+=back
+
 OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
 when the buffer at B<addr> holds sensitive information.
 The old buffer is filled with zero's by calling OPENSSL_cleanse()