| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "OPENSSL_MALLOC 3SSL" |
| 58 |
.TH OPENSSL_MALLOC 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
OPENSSL_malloc_init, |
| 65 |
OPENSSL_malloc, OPENSSL_aligned_alloc, OPENSSL_zalloc, OPENSSL_realloc, |
| 66 |
OPENSSL_malloc_array, OPENSSL_aligned_alloc_array, OPENSSL_calloc, |
| 67 |
OPENSSL_realloc_array, OPENSSL_free, |
| 68 |
OPENSSL_clear_realloc, OPENSSL_clear_realloc_array, |
| 69 |
OPENSSL_clear_free, OPENSSL_cleanse, |
| 70 |
CRYPTO_malloc, CRYPTO_aligned_alloc, CRYPTO_zalloc, |
| 71 |
CRYPTO_malloc_array, CRYPTO_aligned_alloc_array, CRYPTO_calloc, |
| 72 |
CRYPTO_realloc, CRYPTO_realloc_array, CRYPTO_free, |
| 73 |
OPENSSL_strdup, OPENSSL_strndup, |
| 74 |
OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, OPENSSL_strtoul, |
| 75 |
CRYPTO_strdup, CRYPTO_strndup, |
| 76 |
OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, |
| 77 |
CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, |
| 78 |
CRYPTO_clear_realloc, CRYPTO_clear_realloc_array, CRYPTO_clear_free, |
| 79 |
CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn, |
| 80 |
CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, |
| 81 |
CRYPTO_get_alloc_counts, |
| 82 |
CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, |
| 83 |
CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb, |
| 84 |
OPENSSL_MALLOC_FAILURES, |
| 85 |
OPENSSL_MALLOC_FD, |
| 86 |
OPENSSL_MALLOC_SEED |
| 87 |
\&\- Memory allocation functions |
| 88 |
.SH SYNOPSIS |
| 89 |
.IX Header "SYNOPSIS" |
| 90 |
.Vb 1 |
| 91 |
\& #include <openssl/crypto.h> |
| 92 |
\& |
| 93 |
\& int OPENSSL_malloc_init(void); |
| 94 |
\& |
| 95 |
\& void *OPENSSL_malloc(size_t num); |
| 96 |
\& void *OPENSSL_aligned_alloc(size_t num, size_t alignment, void **freeptr); |
| 97 |
\& void *OPENSSL_zalloc(size_t num); |
| 98 |
\& void *OPENSSL_realloc(void *addr, size_t num); |
| 99 |
\& void *OPENSSL_malloc_array(size_t num, size_t size); |
| 100 |
\& void *OPENSSL_aligned_alloc_array(size_t num, size_t size, size_t alignment, |
| 101 |
\& void **freeptr); |
| 102 |
\& void *OPENSSL_calloc(size_t num, size_t size); |
| 103 |
\& void *OPENSSL_realloc_array(void *addr, size_t num, size_t size); |
| 104 |
\& void OPENSSL_free(void *addr); |
| 105 |
\& char *OPENSSL_strdup(const char *str); |
| 106 |
\& char *OPENSSL_strndup(const char *str, size_t s); |
| 107 |
\& size_t OPENSSL_strlcat(char *dst, const char *src, size_t size); |
| 108 |
\& size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size); |
| 109 |
\& int OPENSSL_strtoul(char *src, char **endptr, int base, unsigned long *num); |
| 110 |
\& void *OPENSSL_memdup(void *data, size_t s); |
| 111 |
\& void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num); |
| 112 |
\& void *OPENSSL_clear_realloc_array(void *p, size_t old_len, size_t num, |
| 113 |
\& size_t size); |
| 114 |
\& void OPENSSL_clear_free(void *str, size_t num); |
| 115 |
\& void OPENSSL_cleanse(void *ptr, size_t len); |
| 116 |
\& |
| 117 |
\& void *CRYPTO_malloc(size_t num, const char *file, int line); |
| 118 |
\& void *CRYPTO_aligned_alloc(size_t num, size_t align, void **freeptr, |
| 119 |
\& const char *file, int line); |
| 120 |
\& void *CRYPTO_zalloc(size_t num, const char *file, int line); |
| 121 |
\& void *CRYPTO_realloc(void *p, size_t num, const char *file, int line); |
| 122 |
\& void *CRYPTO_malloc_array(size_t num, size_t size, const char *file, int line); |
| 123 |
\& void *CRYPTO_aligned_alloc_array(size_t num, size_t size, size_t align, |
| 124 |
\& void **freeptr, const char *file, int line); |
| 125 |
\& void *CRYPTO_calloc(size_t num, size_t size, const char *file, int line); |
| 126 |
\& void *CRYPTO_realloc_array(void *p, size_t num, size_t size, |
| 127 |
\& const char *file, int line); |
| 128 |
\& void CRYPTO_free(void *str, const char *file, int line); |
| 129 |
\& char *CRYPTO_strdup(const char *p, const char *file, int line); |
| 130 |
\& char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line); |
| 131 |
\& void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, |
| 132 |
\& const char *file, int line); |
| 133 |
\& void *CRYPTO_clear_realloc_array(void *p, size_t old_len, size_t num, |
| 134 |
\& size_t size, const char *file, int line); |
| 135 |
\& void CRYPTO_clear_free(void *str, size_t num, const char *file, int line); |
| 136 |
\& |
| 137 |
\& typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line); |
| 138 |
\& typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file, |
| 139 |
\& int line); |
| 140 |
\& typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line); |
| 141 |
\& void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn, |
| 142 |
\& CRYPTO_realloc_fn *realloc_fn, |
| 143 |
\& CRYPTO_free_fn *free_fn); |
| 144 |
\& int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn, |
| 145 |
\& CRYPTO_realloc_fn realloc_fn, |
| 146 |
\& CRYPTO_free_fn free_fn); |
| 147 |
\& |
| 148 |
\& void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount); |
| 149 |
\& |
| 150 |
\& env OPENSSL_MALLOC_FAILURES=... <application> |
| 151 |
\& env OPENSSL_MALLOC_FD=... <application> |
| 152 |
\& env OPENSSL_MALLOC_SEED=... <application> |
| 153 |
.Ve |
| 154 |
.PP |
| 155 |
The following functions have been deprecated since OpenSSL 3.0, and can be |
| 156 |
hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, |
| 157 |
see \fBopenssl_user_macros\fR\|(7): |
| 158 |
.PP |
| 159 |
.Vb 4 |
| 160 |
\& int CRYPTO_mem_leaks(BIO *b); |
| 161 |
\& int CRYPTO_mem_leaks_fp(FILE *fp); |
| 162 |
\& int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u), |
| 163 |
\& void *u); |
| 164 |
\& |
| 165 |
\& int CRYPTO_set_mem_debug(int onoff); |
| 166 |
\& int CRYPTO_mem_ctrl(int mode); |
| 167 |
\& int OPENSSL_mem_debug_push(const char *info); |
| 168 |
\& int OPENSSL_mem_debug_pop(void); |
| 169 |
\& int CRYPTO_mem_debug_push(const char *info, const char *file, int line); |
| 170 |
\& int CRYPTO_mem_debug_pop(void); |
| 171 |
.Ve |
| 172 |
.SH DESCRIPTION |
| 173 |
.IX Header "DESCRIPTION" |
| 174 |
OpenSSL memory allocation is handled by the \fBOPENSSL_xxx\fR API. These are |
| 175 |
generally macro's that add the standard C \fB_\|_FILE_\|_\fR and \fB_\|_LINE_\|_\fR |
| 176 |
parameters and call a lower-level \fBCRYPTO_xxx\fR API. |
| 177 |
Some functions do not add those parameters, but exist for consistency. |
| 178 |
.PP |
| 179 |
\&\fBOPENSSL_malloc_init()\fR does nothing and does not need to be called. It is |
| 180 |
included for compatibility with older versions of OpenSSL. |
| 181 |
.PP |
| 182 |
\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR, and \fBOPENSSL_free()\fR are like the |
| 183 |
C \fBmalloc()\fR, \fBrealloc()\fR, and \fBfree()\fR functions. |
| 184 |
\&\fBOPENSSL_zalloc()\fR calls \fBmemset()\fR to zero the memory before returning. |
| 185 |
.PP |
| 186 |
\&\fBOPENSSL_aligned_alloc()\fR operates just as \fBOPENSSL_malloc()\fR does, but it |
| 187 |
allows for the caller to specify an alignment value, for instances in |
| 188 |
which the default alignment of malloc is insufficient for the caller's |
| 189 |
needs. Note, the alignment value must be a power of 2, and the size |
| 190 |
specified must be a multiple of the alignment. |
| 191 |
NOTES: |
| 192 |
.IP \(bu 4 |
| 193 |
The call to \fBOPENSSL_aligned_alloc()\fR accepts a 3rd argument, \fIfreeptr\fR |
| 194 |
which must point to a void pointer. On some platforms, there is no available |
| 195 |
library call to obtain memory allocations with alignment greater than what |
| 196 |
malloc provides. In this case, \fBOPENSSL_aligned_alloc()\fR implements its own |
| 197 |
alignment routine, allocating additional memory and offsetting the returned |
| 198 |
pointer to be on the requested alignment boundary. In order to safely free |
| 199 |
allocations made by this method, the caller must return the value |
| 200 |
in the \fIfreeptr\fR variable, rather than the returned pointer. |
| 201 |
.IP \(bu 4 |
| 202 |
The call to \fBOPENSSL_aligned_alloc()\fR may fail for reasons other than memory |
| 203 |
exhaustion, depending on the underlying implementation, and, most notably, |
| 204 |
OpenSSL library's build configuration: for example, it always returns \f(CW\*(C`NULL\*(C'\fR |
| 205 |
without setting any error if OpenSSL is built with \f(CW\*(C`OPENSSL_SMALL_FOOTPRINT\*(C'\fR |
| 206 |
macro defined. Consequently, caller may need to fall back to a non-aligned |
| 207 |
memory allocation (and open-code the alignment routine if the alignment |
| 208 |
is a requirement). |
| 209 |
.PP |
| 210 |
\&\fBOPENSSL_clear_realloc()\fR and \fBOPENSSL_clear_free()\fR should be used |
| 211 |
when the buffer at \fBaddr\fR holds sensitive information. |
| 212 |
The old buffer is filled with zero's by calling \fBOPENSSL_cleanse()\fR |
| 213 |
before ultimately calling \fBOPENSSL_free()\fR. If the argument to |
| 214 |
\&\fBOPENSSL_clear_free()\fR is NULL, nothing is done. |
| 215 |
.PP |
| 216 |
\&\fBOPENSSL_malloc_array()\fR, \fBOPENSSL_calloc()\fR, \fBOPENSSL_aligned_alloc_array()\fR, |
| 217 |
\&\fBOPENSSL_realloc_array()\fR, and \fBOPENSSL_clear_realloc_array()\fR are variants |
| 218 |
of \fBOPENSSL_malloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_aligned_alloc()\fR, |
| 219 |
\&\fBOPENSSL_realloc()\fR, and \fBOPENSSL_clear_realloc()\fR, respectively, that accept |
| 220 |
an additional parameter, \fBsize\fR, which enables memory allocation |
| 221 |
operations for an array of \fBnum\fR members \fBsize\fR bytes each; |
| 222 |
these functions return an error if multiplication of \fBnum\fR and \fBsize\fR |
| 223 |
leads to an integer overflow, thus preventing allocations of an incorrect size. |
| 224 |
.PP |
| 225 |
\&\fBOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0's. |
| 226 |
It is useful in cases when it is needed to ensure that memory (that contains |
| 227 |
sensitive information) is overwritten (for example, before it is reclaimed, |
| 228 |
or when it is stored on stack), and such operation is not optimised out |
| 229 |
by compiler optimisations such as dead store elimination (as \fBmemset\fR\|(3) may be). |
| 230 |
Use \fBOPENSSL_cleanse()\fR with care if the memory is a mapping of a file. |
| 231 |
If the storage controller uses write compression, then it's possible |
| 232 |
that sensitive tail bytes will survive zeroization because the block of |
| 233 |
zeros will be compressed. If the storage controller uses wear leveling, |
| 234 |
then the old sensitive data will not be overwritten; rather, a block of |
| 235 |
0's will be written at a new physical location. |
| 236 |
.PP |
| 237 |
\&\fBOPENSSL_strdup()\fR, \fBOPENSSL_strndup()\fR and \fBOPENSSL_memdup()\fR are like the |
| 238 |
equivalent C functions, except that memory is allocated by calling the |
| 239 |
\&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR. |
| 240 |
.PP |
| 241 |
\&\fBOPENSSL_strlcpy()\fR, |
| 242 |
\&\fBOPENSSL_strlcat()\fR and \fBOPENSSL_strnlen()\fR are equivalents of the common C |
| 243 |
library functions and are provided for portability. |
| 244 |
.PP |
| 245 |
\&\fBOPENSSL_strtoul()\fR is a wrapper around the POSIX function strtoul, with the same |
| 246 |
behaviors listed in the POSIX documentation, with the additional behavior that |
| 247 |
it validates the input \fIstr\fR and \fInum\fR parameters for not being NULL, and confirms |
| 248 |
that at least a single byte of input has been consumed in the translation, |
| 249 |
returning an error in the event that no bytes were consumed. |
| 250 |
.PP |
| 251 |
If no allocations have been done, it is possible to "swap out" the default |
| 252 |
implementations for \fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR and \fBOPENSSL_free()\fR |
| 253 |
and replace them with alternate versions. |
| 254 |
\&\fBCRYPTO_get_mem_functions()\fR function fills in the given arguments with the |
| 255 |
function pointers for the current implementations. |
| 256 |
With \fBCRYPTO_set_mem_functions()\fR, you can specify a different set of functions. |
| 257 |
If any of \fBmalloc_fn\fR, \fBrealloc_fn\fR, or \fBfree_fn\fR are NULL, then |
| 258 |
the function is not changed. |
| 259 |
While it's permitted to swap out only a few and not all the functions |
| 260 |
with \fBCRYPTO_set_mem_functions()\fR, it's recommended to swap them all out |
| 261 |
at once. |
| 262 |
.PP |
| 263 |
If the library is built with the \f(CW\*(C`crypto\-mdebug\*(C'\fR option, then one |
| 264 |
function, \fBCRYPTO_get_alloc_counts()\fR, and three additional environment |
| 265 |
variables, \fBOPENSSL_MALLOC_FAILURES\fR, \fBOPENSSL_MALLOC_FD\fR, |
| 266 |
and \fBOPENSSL_MALLOC_SEED\fR, are available. |
| 267 |
.PP |
| 268 |
The function \fBCRYPTO_get_alloc_counts()\fR fills in the number of times |
| 269 |
each of \fBCRYPTO_malloc()\fR, \fBCRYPTO_realloc()\fR, and \fBCRYPTO_free()\fR have been |
| 270 |
called, into the values pointed to by \fBmcount\fR, \fBrcount\fR, and \fBfcount\fR, |
| 271 |
respectively. If a pointer is NULL, then the corresponding count is not stored. |
| 272 |
.PP |
| 273 |
The variable |
| 274 |
\&\fBOPENSSL_MALLOC_FAILURES\fR controls how often allocations should fail. |
| 275 |
It is a set of fields separated by semicolons, which each field is a count |
| 276 |
(defaulting to zero) and an optional atsign and percentage (interpreted |
| 277 |
as a floating point number that is rounded up to two decimal digits |
| 278 |
of precision, defaulting to 100). If the count is zero, then it lasts forever. |
| 279 |
For example, \f(CW\*(C`100;@0.258\*(C'\fR or \f(CW\*(C`100@0;[email protected]\*(C'\fR means the first 100 allocations |
| 280 |
pass, then all other allocations (until the program exits or crashes) have |
| 281 |
a 0.26% chance of failing, with \fBrandom\fR\|(3) used as a source of randomness. |
| 282 |
The length of the value of \fBOPENSSL_MALLOC_FAILURES\fR must be 256 or fewer |
| 283 |
characters. |
| 284 |
.PP |
| 285 |
If the variable \fBOPENSSL_MALLOC_FD\fR is parsed as a positive integer, then |
| 286 |
it is taken as an open file descriptor. This is used in conjunction with |
| 287 |
\&\fBOPENSSL_MALLOC_FAILURES\fR described above. For every allocation it will log |
| 288 |
details about how many allocations there have been so far, what percentage |
| 289 |
chance there is for this allocation failing, and whether it has actually failed. |
| 290 |
The following example in classic shell syntax shows how to use this (will not |
| 291 |
work on all platforms): |
| 292 |
.PP |
| 293 |
.Vb 5 |
| 294 |
\& OPENSSL_MALLOC_FAILURES=\*(Aq200;@10\*(Aq |
| 295 |
\& export OPENSSL_MALLOC_FAILURES |
| 296 |
\& OPENSSL_MALLOC_FD=3 |
| 297 |
\& export OPENSSL_MALLOC_FD |
| 298 |
\& ...app invocation... 3>/tmp/log$$ |
| 299 |
.Ve |
| 300 |
.PP |
| 301 |
If the environment variable \fBOPENSSL_MALLOC_SEED\fR is set, its value |
| 302 |
is interpreted as an integer using \fBatoi\fR\|(3) and supplied to the \fBsrandom\fR\|(3) |
| 303 |
call for the random number generator initialisation. |
| 304 |
.SH "RETURN VALUES" |
| 305 |
.IX Header "RETURN VALUES" |
| 306 |
\&\fBOPENSSL_malloc_init()\fR, \fBOPENSSL_free()\fR, \fBOPENSSL_clear_free()\fR |
| 307 |
\&\fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR and \fBCRYPTO_get_mem_functions()\fR |
| 308 |
return no value. |
| 309 |
.PP |
| 310 |
\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_aligned_alloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_realloc()\fR, |
| 311 |
\&\fBOPENSSL_malloc_array()\fR, \fBOPENSSL_aligned_alloc_array()\fR, \fBOPENSSL_calloc()\fR, |
| 312 |
\&\fBOPENSSL_realloc_array()\fR, |
| 313 |
\&\fBOPENSSL_clear_realloc()\fR, \fBOPENSSL_clear_realloc_array()\fR, |
| 314 |
\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_realloc()\fR, |
| 315 |
\&\fBCRYPTO_malloc_array()\fR, \fBCRYPTO_calloc()\fR, \fBCRYPTO_realloc_array()\fR, |
| 316 |
\&\fBCRYPTO_clear_realloc()\fR, \fBCRYPTO_clear_realloc_array()\fR, |
| 317 |
\&\fBOPENSSL_strdup()\fR, and \fBOPENSSL_strndup()\fR |
| 318 |
return a pointer to allocated memory or NULL on error. |
| 319 |
.PP |
| 320 |
\&\fBOPENSSL_aligned_alloc()\fR and \fBOPENSSL_aligned_alloc_array()\fR set \fBfreeptr\fR |
| 321 |
to NULL on error. |
| 322 |
.PP |
| 323 |
\&\fBCRYPTO_set_mem_functions()\fR returns 1 on success or 0 on failure (almost |
| 324 |
always because allocations have already happened). |
| 325 |
.PP |
| 326 |
\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, \fBCRYPTO_mem_leaks_cb()\fR, |
| 327 |
\&\fBCRYPTO_set_mem_debug()\fR, and \fBCRYPTO_mem_ctrl()\fR are deprecated and are no-ops that |
| 328 |
always return \-1. |
| 329 |
\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, |
| 330 |
\&\fBCRYPTO_mem_debug_push()\fR, and \fBCRYPTO_mem_debug_pop()\fR |
| 331 |
are deprecated and are no-ops that always return 0. |
| 332 |
.PP |
| 333 |
\&\fBOPENSSL_strtoul()\fR returns 1 on success and 0 in the event that an error has |
| 334 |
occurred. Specifically, 0 is returned in the following events: |
| 335 |
.IP \(bu 4 |
| 336 |
If the underlying call to strtoul returned a non zero errno value |
| 337 |
.IP \(bu 4 |
| 338 |
If the translation did not consume the entire input string, and the passed |
| 339 |
endptr value was NULL |
| 340 |
.IP \(bu 4 |
| 341 |
If no characters were consumed in the translation |
| 342 |
.PP |
| 343 |
Note that a success condition does not imply that the expected |
| 344 |
translation has been performed. For instance calling |
| 345 |
.PP |
| 346 |
.Vb 1 |
| 347 |
\& OPENSSL_strtoul("0x12345", &endptr, 10, &num); |
| 348 |
.Ve |
| 349 |
.PP |
| 350 |
will result in a successful translation with num having the value 0, and |
| 351 |
*endptr = 'x'. Be sure to validate how much data was consumed when calling this |
| 352 |
function. |
| 353 |
.SH HISTORY |
| 354 |
.IX Header "HISTORY" |
| 355 |
\&\fBOPENSSL_mem_debug_push()\fR, \fBOPENSSL_mem_debug_pop()\fR, |
| 356 |
\&\fBCRYPTO_mem_debug_push()\fR, \fBCRYPTO_mem_debug_pop()\fR, |
| 357 |
\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR, |
| 358 |
\&\fBCRYPTO_mem_leaks_cb()\fR, \fBCRYPTO_set_mem_debug()\fR, \fBCRYPTO_mem_ctrl()\fR |
| 359 |
were deprecated in OpenSSL 3.0. |
| 360 |
The memory-leak checking has been deprecated in OpenSSL 3.0 in favor of |
| 361 |
clang's memory and leak sanitizer. |
| 362 |
\&\fBOPENSSL_aligned_alloc()\fR, \fBCRYPTO_aligned_alloc()\fR, \fBOPENSSL_strtoul()\fR were |
| 363 |
added in OpenSSL 3.4. |
| 364 |
\&\fBOPENSSL_malloc_array()\fR, \fBOPENSSL_calloc()\fR, \fBOPENSSL_aligned_alloc_array()\fR, |
| 365 |
\&\fBOPENSSL_realloc_array()\fR, \fBOPENSSL_clear_realloc_array()\fR, \fBCRYPTO_malloc_array()\fR, |
| 366 |
\&\fBCRYPTO_calloc()\fR, \fBCRYPTO_aligned_alloc_array()\fR, \fBCRYPTO_realloc_array()\fR, |
| 367 |
\&\fBCRYPTO_clear_realloc_array()\fR were added in OpenSSL 3.6. |
| 368 |
.SH COPYRIGHT |
| 369 |
.IX Header "COPYRIGHT" |
| 370 |
Copyright 2016\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 371 |
.PP |
| 372 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 373 |
this file except in compliance with the License. You can obtain a copy |
| 374 |
in the file LICENSE in the source distribution or at |
| 375 |
<https://www.openssl.org/source/license.html>. |