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, and a record of all allocations
146       is written to that descriptor.  If an allocation will fail, and the
147       platform supports it, then a backtrace will be written to the
148       descriptor.  This can be useful because a malloc may fail but not be
149       checked, and problems will only occur later.  The following example in
150       classic shell syntax shows how to use this (will not work on all
151       platforms):
152
153         OPENSSL_MALLOC_FAILURES='200;@10'
154         export OPENSSL_MALLOC_FAILURES
155         OPENSSL_MALLOC_FD=3
156         export OPENSSL_MALLOC_FD
157         ...app invocation... 3>/tmp/log$$
158

RETURN VALUES

160       OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
161       CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
162       return no value.
163
164       OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
165       OPENSSL_clear_realloc(), CRYPTO_malloc(), CRYPTO_zalloc(),
166       CRYPTO_realloc(), CRYPTO_clear_realloc(), OPENSSL_strdup(), and
167       OPENSSL_strndup() return a pointer to allocated memory or NULL on
168       error.
169
170       CRYPTO_set_mem_functions() returns 1 on success or 0 on failure (almost
171       always because allocations have already happened).
172
173       CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp(), CRYPTO_mem_leaks_cb(),
174       CRYPTO_set_mem_debug(), and CRYPTO_mem_ctrl() are deprecated and return
175       -1.  OPENSSL_mem_debug_push(), OPENSSL_mem_debug_pop(),
176       CRYPTO_mem_debug_push(), and CRYPTO_mem_debug_pop() are deprecated and
177       return 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-2021 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.5                             2022-11-01             OPENSSL_MALLOC(3ossl)
Impressum