1 files changed, 62 insertions, 7 deletions
diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod
index 20441e76ac65..d02eb47e9a6e 100644
--- a/doc/man3/OPENSSL_malloc.pod
+++ b/doc/man3/OPENSSL_malloc.pod
@@ -3,11 +3,11 @@
 =head1 NAME
 
 OPENSSL_malloc_init,
-OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
-OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
-CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
+OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc,
+OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
+CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free,
 OPENSSL_strdup, OPENSSL_strndup,
-OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat,
+OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul,
 CRYPTO_strdup, CRYPTO_strndup,
 OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
 CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
@@ -28,6 +28,7 @@ OPENSSL_MALLOC_FD
  int OPENSSL_malloc_init(void);
 
  void *OPENSSL_malloc(size_t num);
+ void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr);
  void *OPENSSL_zalloc(size_t num);
  void *OPENSSL_realloc(void *addr, size_t num);
  void OPENSSL_free(void *addr);
@@ -35,12 +36,15 @@ OPENSSL_MALLOC_FD
  char *OPENSSL_strndup(const char *str, size_t s);
  size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
  size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
+ int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num);
  void *OPENSSL_memdup(void *data, size_t s);
  void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);
  void OPENSSL_clear_free(void *str, size_t num);
  void OPENSSL_cleanse(void *ptr, size_t len);
 
  void *CRYPTO_malloc(size_t num, const char *file, int line);
+ void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr, 
+                            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, const char *, int);
@@ -96,6 +100,20 @@ OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the
 C malloc(), realloc(), and free() functions.
 OPENSSL_zalloc() calls memset() to zero the memory before returning.
 
+OPENSSL_aligned_alloc() operates just as OPENSSL_malloc does, but it
+allows for the caller to specify an alignment value, for instances in
+which the default alignment of malloc is insufficient for the callers
+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>
+which must point to a void pointer.  On some platforms, there is no available
+library call to obtain memory allocations greater than what malloc provides.  In
+this case, OPENSSL_aligned_alloc implements its own alignment routine,
+allocating additional memory and offsetting the returned 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.
+
 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()
@@ -118,6 +136,12 @@ OPENSSL_strlcpy(),
 OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C
 library functions and are provided for portability.
 
+OPENSSL_strtoul() is a wrapper around the POSIX function strtoul, with the same
+behaviors listed in the POSIX documentation, with the additional behavior that
+it validates the input I<str> and I<num> parameters for not being NULL, and confirms
+that at least a single byte of input has been consumed in the translation,
+returning an error in the event that no bytes were consumed.
+
 If no allocations have been done, it is possible to "swap out" the default
 implementations for OPENSSL_malloc(), OPENSSL_realloc() and OPENSSL_free()
 and replace them with alternate versions.
@@ -147,7 +171,8 @@ It is a set of fields separated by semicolons, which each field is a count
 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.
+failing. The length of the value of B<OPENSSL_MALLOC_FAILURES> must be 256 or
+fewer characters.
 
 If the variable B<OPENSSL_MALLOC_FD> is parsed as a positive integer, then
 it is taken as an open file descriptor. This is used in conjunction with
@@ -169,7 +194,7 @@ OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
 CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
 return no value.
 
-OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
+OPENSSL_malloc(), OPENSSL_aligned_alloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
 OPENSSL_clear_realloc(),
 CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(),
 CRYPTO_clear_realloc(),
@@ -186,6 +211,35 @@ OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
 CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop()
 are deprecated and are no-ops that always return 0.
 
+OPENSSL_strtoul() returns 1 on success and 0 in the event that an error has
+occurred. Specifically, 0 is returned in the following events:
+
+=over 4
+
+=item *
+
+If the underlying call to strtoul returned a non zero errno value
+
+=item *
+
+If the translation did not consume the entire input string, and the passed
+endptr value was NULL
+
+=item *
+
+If no characters were consumed in the translation
+
+=back
+
+Note that a success condition does not imply that the expected
+translation has been performed.  For instance calling
+
+    OPENSSL_strtoul("0x12345", &endptr, 10, &num);
+
+will result in a successful translation with num having the value 0, and
+*endptr = 'x'.  Be sure to validate how much data was consumed when calling this
+function.
+
 =head1 HISTORY
 
 OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
@@ -195,7 +249,8 @@ CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(), CRYPTO_mem_ctrl()
 were deprecated in OpenSSL 3.0.
 The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of
 clang's memory and leak sanitizer.
-
+OPENSSL_aligned_alloc(), CRYPTO_aligned_alloc(), OPENSSL_strtoul() were
+added in OpenSSL 3.4.
 
 =head1 COPYRIGHT