1OPENSSL_MALLOC(3ossl)               OpenSSL              OPENSSL_MALLOC(3ossl)
2
3
4

NAME

6       OPENSSL_malloc_init, OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc,
7       OPENSSL_free, OPENSSL_clear_realloc, OPENSSL_clear_free,
8       OPENSSL_cleanse, CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc,
9       CRYPTO_free, OPENSSL_strdup, OPENSSL_strndup, OPENSSL_memdup,
10       OPENSSL_strlcpy, OPENSSL_strlcat, CRYPTO_strdup, CRYPTO_strndup,
11       OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, CRYPTO_mem_debug_push,
12       CRYPTO_mem_debug_pop, CRYPTO_clear_realloc, CRYPTO_clear_free,
13       CRYPTO_malloc_fn, CRYPTO_realloc_fn, CRYPTO_free_fn,
14       CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
15       CRYPTO_get_alloc_counts, CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
16       CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp, CRYPTO_mem_leaks_cb,
17       OPENSSL_MALLOC_FAILURES, OPENSSL_MALLOC_FD - Memory allocation
18       functions
19

SYNOPSIS

21        #include <openssl/crypto.h>
22
23        int OPENSSL_malloc_init(void);
24
25        void *OPENSSL_malloc(size_t num);
26        void *OPENSSL_zalloc(size_t num);
27        void *OPENSSL_realloc(void *addr, size_t num);
28        void OPENSSL_free(void *addr);
29        char *OPENSSL_strdup(const char *str);
30        char *OPENSSL_strndup(const char *str, size_t s);
31        size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
32        size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
33        void *OPENSSL_memdup(void *data, size_t s);
34        void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num);
35        void OPENSSL_clear_free(void *str, size_t num);
36        void OPENSSL_cleanse(void *ptr, size_t len);
37
38        void *CRYPTO_malloc(size_t num, const char *file, int line);
39        void *CRYPTO_zalloc(size_t num, const char *file, int line);
40        void *CRYPTO_realloc(void *p, size_t num, const char *file, int line);
41        void CRYPTO_free(void *str, const char *, int);
42        char *CRYPTO_strdup(const char *p, const char *file, int line);
43        char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line);
44        void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,
45                                   const char *file, int line);
46        void CRYPTO_clear_free(void *str, size_t num, const char *, int);
47
48        typedef void *(*CRYPTO_malloc_fn)(size_t num, const char *file, int line);
49        typedef void *(*CRYPTO_realloc_fn)(void *addr, size_t num, const char *file,
50                                           int line);
51        typedef void (*CRYPTO_free_fn)(void *addr, const char *file, int line);
52        void CRYPTO_get_mem_functions(CRYPTO_malloc_fn *malloc_fn,
53                                      CRYPTO_realloc_fn *realloc_fn,
54                                      CRYPTO_free_fn *free_fn);
55        int CRYPTO_set_mem_functions(CRYPTO_malloc_fn malloc_fn,
56                                     CRYPTO_realloc_fn realloc_fn,
57                                     CRYPTO_free_fn free_fn);
58
59        void CRYPTO_get_alloc_counts(int *mcount, int *rcount, int *fcount);
60
61        env OPENSSL_MALLOC_FAILURES=... <application>
62        env OPENSSL_MALLOC_FD=... <application>
63
64       The following functions have been deprecated since OpenSSL 3.0, and can
65       be hidden entirely by defining OPENSSL_API_COMPAT with a suitable
66       version value, see openssl_user_macros(7):
67
68        int CRYPTO_mem_leaks(BIO *b);
69        int CRYPTO_mem_leaks_fp(FILE *fp);
70        int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
71                                void *u);
72
73        int CRYPTO_set_mem_debug(int onoff);
74        int CRYPTO_mem_ctrl(int mode);
75        int OPENSSL_mem_debug_push(const char *info);
76        int OPENSSL_mem_debug_pop(void);
77        int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
78        int CRYPTO_mem_debug_pop(void);
79

DESCRIPTION

81       OpenSSL memory allocation is handled by the OPENSSL_xxx API. These are
82       generally macro's that add the standard C __FILE__ and __LINE__
83       parameters and call a lower-level CRYPTO_xxx API.  Some functions do
84       not add those parameters, but exist for consistency.
85
86       OPENSSL_malloc_init() does nothing and does not need to be called. It
87       is included for compatibility with older versions of OpenSSL.
88
89       OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the C
90       malloc(), realloc(), and free() functions.  OPENSSL_zalloc() calls
91       memset() to zero the memory before returning.
92
93       OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when
94       the buffer at addr holds sensitive information.  The old buffer is
95       filled with zero's by calling OPENSSL_cleanse() before ultimately
96       calling OPENSSL_free().
97
98       OPENSSL_cleanse() fills ptr of size len with a string of 0's.  Use
99       OPENSSL_cleanse() with care if the memory is a mapping of a file.  If
100       the storage controller uses write compression, then it's possible that
101       sensitive tail bytes will survive zeroization because the block of
102       zeros will be compressed. If the storage controller uses wear leveling,
103       then the old sensitive data will not be overwritten; rather, a block of
104       0's will be written at a new physical location.
105
106       OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
107       equivalent C functions, except that memory is allocated by calling the
108       OPENSSL_malloc() and should be released by calling OPENSSL_free().
109
110       OPENSSL_strlcpy(), OPENSSL_strlcat() and OPENSSL_strnlen() are
111       equivalents of the common C library functions and are provided for
112       portability.
113
114       If no allocations have been done, it is possible to "swap out" the
115       default implementations for OPENSSL_malloc(), OPENSSL_realloc() and
116       OPENSSL_free() and replace them with alternate versions.
117       CRYPTO_get_mem_functions() function fills in the given arguments with
118       the function pointers for the current implementations.  With
119       CRYPTO_set_mem_functions(), you can specify a different set of
120       functions.  If any of malloc_fn, realloc_fn, or free_fn are NULL, then
121       the function is not changed.  While it's permitted to swap out only a
122       few and not all the functions with CRYPTO_set_mem_functions(), it's
123       recommended to swap them all out at once.
124
125       If the library is built with the "crypto-mdebug" option, then one
126       function, CRYPTO_get_alloc_counts(), and two additional environment
127       variables, OPENSSL_MALLOC_FAILURES and OPENSSL_MALLOC_FD, are
128       available.
129
130       The function CRYPTO_get_alloc_counts() fills in the number of times
131       each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been
132       called, into the values pointed to by mcount, rcount, and fcount,
133       respectively.  If a pointer is NULL, then the corresponding count is
134       not stored.
135
136       The variable OPENSSL_MALLOC_FAILURES controls how often allocations
137       should fail.  It is a set of fields separated by semicolons, which each
138       field is a count (defaulting to zero) and an optional atsign and
139       percentage (defaulting to 100).  If the count is zero, then it lasts
140       forever.  For example, "100;@25" or "100@0;0@25" means the first 100
141       allocations pass, then all other allocations (until the program exits
142       or crashes) have a 25% chance of failing.
143
144       If the variable OPENSSL_MALLOC_FD is parsed as a positive integer, then
145       it is taken as an open file descriptor. This is used in conjunction
146       with OPENSSL_MALLOC_FAILURES described above. For every allocation it
147       will log details about how many allocations there have been so far,
148       what percentage chance there is for this allocation failing, and
149       whether it has actually failed.  The following example in classic shell
150       syntax shows how to use this (will not work on all platforms):
151
152         OPENSSL_MALLOC_FAILURES='200;@10'
153         export OPENSSL_MALLOC_FAILURES
154         OPENSSL_MALLOC_FD=3
155         export OPENSSL_MALLOC_FD
156         ...app invocation... 3>/tmp/log$$
157

RETURN VALUES

159       OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
160       CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
161       return no value.
162
163       OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
164       OPENSSL_clear_realloc(), CRYPTO_malloc(), CRYPTO_zalloc(),
165       CRYPTO_realloc(), CRYPTO_clear_realloc(), OPENSSL_strdup(), and
166       OPENSSL_strndup() return a pointer to allocated memory or NULL on
167       error.
168
169       CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost
170       always because allocations have already happened).
171
172       CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(),
173       CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and are
174       no-ops that always return -1.  OPENSSL_mem_debug_push(),
175       OPENSSL_mem_debug_pop(), CRYPTO_mem_debug_push(), and
176       CRYPTO_mem_debug_pop() are deprecated and are no-ops that always return
177       0.
178

HISTORY

180       OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
181       CRYPTO_mem_debug_push(), CRYPTO_mem_debug_pop(), CRYPTO_mem_leaks(),
182       CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(), CRYPTO_set_mem_debug(),
183       CRYPTO_mem_ctrl() were deprecated in OpenSSL 3.0.  The memory-leak
184       checking has been deprecated in OpenSSL 3.0 in favor of clang's memory
185       and leak sanitizer.
186
188       Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved.
189
190       Licensed under the Apache License 2.0 (the "License").  You may not use
191       this file except in compliance with the License.  You can obtain a copy
192       in the file LICENSE in the source distribution or at
193       <https://www.openssl.org/source/license.html>.
194
195
196
1973.0.9                             2023-07-27             OPENSSL_MALLOC(3ossl)
Impressum