1OPENSSL_MALLOC(3)                   OpenSSL                  OPENSSL_MALLOC(3)
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, OPENSSL_hexstr2buf,
11       OPENSSL_buf2hexstr, OPENSSL_hexchar2int, CRYPTO_strdup, CRYPTO_strndup,
12       OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, CRYPTO_mem_debug_push,
13       CRYPTO_mem_debug_pop, CRYPTO_clear_realloc, CRYPTO_clear_free,
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        unsigned char *OPENSSL_hexstr2buf(const char *str, long *len);
39        char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len);
40        int OPENSSL_hexchar2int(unsigned char c);
41
42        void *CRYPTO_malloc(size_t num, const char *file, int line)
43        void *CRYPTO_zalloc(size_t num, const char *file, int line)
44        void *CRYPTO_realloc(void *p, size_t num, const char *file, int line)
45        void CRYPTO_free(void *str, const char *, int)
46        char *CRYPTO_strdup(const char *p, const char *file, int line)
47        char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line)
48        void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num,
49                                   const char *file, int line)
50        void CRYPTO_clear_free(void *str, size_t num, const char *, int)
51
52        void CRYPTO_get_mem_functions(
53                void *(**m)(size_t, const char *, int),
54                void *(**r)(void *, size_t, const char *, int),
55                void (**f)(void *, const char *, int))
56        int CRYPTO_set_mem_functions(
57                void *(*m)(size_t, const char *, int),
58                void *(*r)(void *, size_t, const char *, int),
59                void (*f)(void *, const char *, int))
60
61        void CRYPTO_get_alloc_counts(int *m, int *r, int *f)
62
63        int CRYPTO_set_mem_debug(int onoff)
64
65        env OPENSSL_MALLOC_FAILURES=... <application>
66        env OPENSSL_MALLOC_FD=... <application>
67
68        int CRYPTO_mem_ctrl(int mode);
69
70        int OPENSSL_mem_debug_push(const char *info)
71        int OPENSSL_mem_debug_pop(void);
72
73        int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
74        int CRYPTO_mem_debug_pop(void);
75
76        int CRYPTO_mem_leaks(BIO *b);
77        int CRYPTO_mem_leaks_fp(FILE *fp);
78        int CRYPTO_mem_leaks_cb(int (*cb)(const char *str, size_t len, void *u),
79                                void *u);
80

DESCRIPTION

82       OpenSSL memory allocation is handled by the OPENSSL_xxx API. These are
83       generally macro's that add the standard C __FILE__ and __LINE__
84       parameters and call a lower-level CRYPTO_xxx API.  Some functions do
85       not add those parameters, but exist for consistency.
86
87       OPENSSL_malloc_init() does nothing and does not need to be called. It
88       is included for compatibility with older versions of OpenSSL.
89
90       OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the C
91       malloc(), realloc(), and free() functions.  OPENSSL_zalloc() calls
92       memset() to zero the memory before returning.
93
94       OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when
95       the buffer at addr holds sensitive information.  The old buffer is
96       filled with zero's by calling OPENSSL_cleanse() before ultimately
97       calling OPENSSL_free().
98
99       OPENSSL_cleanse() fills ptr of size len with a string of 0's.  Use
100       OPENSSL_cleanse() with care if the memory is a mapping of a file.  If
101       the storage controller uses write compression, then it's possible that
102       sensitive tail bytes will survive zeroization because the block of
103       zeros will be compressed. If the storage controller uses wear leveling,
104       then the old sensitive data will not be overwritten; rather, a block of
105       0's will be written at a new physical location.
106
107       OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
108       equivalent C functions, except that memory is allocated by calling the
109       OPENSSL_malloc() and should be released by calling OPENSSL_free().
110
111       OPENSSL_strlcpy(), OPENSSL_strlcat() and OPENSSL_strnlen() are
112       equivalents of the common C library functions and are provided for
113       portability.
114
115       OPENSSL_hexstr2buf() parses str as a hex string and returns a pointer
116       to the parsed value. The memory is allocated by calling
117       OPENSSL_malloc() and should be released by calling OPENSSL_free().  If
118       len is not NULL, it is filled in with the output length.  Colons
119       between two-character hex "bytes" are ignored.  An odd number of hex
120       digits is an error.
121
122       OPENSSL_buf2hexstr() takes the specified buffer and length, and returns
123       a hex string for value, or NULL on error.  Buffer cannot be NULL; if
124       len is 0 an empty string is returned.
125
126       OPENSSL_hexchar2int() converts a character to the hexadecimal
127       equivalent, or returns -1 on error.
128
129       If no allocations have been done, it is possible to "swap out" the
130       default implementations for OPENSSL_malloc(), OPENSSL_realloc and
131       OPENSSL_free() and replace them with alternate versions (hooks).
132       CRYPTO_get_mem_functions() function fills in the given arguments with
133       the function pointers for the current implementations.  With
134       CRYPTO_set_mem_functions(), you can specify a different set of
135       functions.  If any of m, r, or f are NULL, then the function is not
136       changed.
137
138       The default implementation can include some debugging capability (if
139       enabled at build-time).  This adds some overhead by keeping a list of
140       all memory allocations, and removes items from the list when they are
141       free'd.  This is most useful for identifying memory leaks.
142       CRYPTO_set_mem_debug() turns this tracking on and off.  In order to
143       have any effect, is must be called before any of the allocation
144       functions (e.g., CRYPTO_malloc()) are called, and is therefore normally
145       one of the first lines of main() in an application.  CRYPTO_mem_ctrl()
146       provides fine-grained control of memory leak tracking.  To enable
147       tracking call CRYPTO_mem_ctrl() with a mode argument of the
148       CRYPTO_MEM_CHECK_ON.  To disable tracking call CRYPTO_mem_ctrl() with a
149       mode argument of the CRYPTO_MEM_CHECK_OFF.
150
151       While checking memory, it can be useful to store additional context
152       about what is being done.  For example, identifying the field names
153       when parsing a complicated data structure.  OPENSSL_mem_debug_push()
154       (which calls CRYPTO_mem_debug_push()) attaches an identifying string to
155       the allocation stack.  This must be a global or other static string; it
156       is not copied.  OPENSSL_mem_debug_pop() removes identifying state from
157       the stack.
158
159       At the end of the program, calling CRYPTO_mem_leaks() or
160       CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it to
161       the specified BIO b or FILE fp. These functions return 1 if there are
162       no leaks, 0 if there are leaks and -1 if an error occurred.
163
164       CRYPTO_mem_leaks_cb() does the same as CRYPTO_mem_leaks(), but instead
165       of writing to a given BIO, the callback function is called for each
166       output string with the string, length, and userdata u as the callback
167       parameters.
168
169       If the library is built with the "crypto-mdebug" option, then one
170       function, CRYPTO_get_alloc_counts(), and two additional environment
171       variables, OPENSSL_MALLOC_FAILURES and OPENSSL_MALLOC_FD, are
172       available.
173
174       The function CRYPTO_get_alloc_counts() fills in the number of times
175       each of CRYPTO_malloc(), CRYPTO_realloc(), and CRYPTO_free() have been
176       called, into the values pointed to by mcount, rcount, and fcount,
177       respectively.  If a pointer is NULL, then the corresponding count is
178       not stored.
179
180       The variable OPENSSL_MALLOC_FAILURES controls how often allocations
181       should fail.  It is a set of fields separated by semicolons, which each
182       field is a count (defaulting to zero) and an optional atsign and
183       percentage (defaulting to 100).  If the count is zero, then it lasts
184       forever.  For example, "100;@25" or "100@0;0@25" means the first 100
185       allocations pass, then all other allocations (until the program exits
186       or crashes) have a 25% chance of failing.
187
188       If the variable OPENSSL_MALLOC_FD is parsed as a positive integer, then
189       it is taken as an open file descriptor, and a record of all allocations
190       is written to that descriptor.  If an allocation will fail, and the
191       platform supports it, then a backtrace will be written to the
192       descriptor.  This can be useful because a malloc may fail but not be
193       checked, and problems will only occur later.  The following example in
194       classic shell syntax shows how to use this (will not work on all
195       platforms):
196
197         OPENSSL_MALLOC_FAILURES='200;@10'
198         export OPENSSL_MALLOC_FAILURES
199         OPENSSL_MALLOC_FD=3
200         export OPENSSL_MALLOC_FD
201         ...app invocation... 3>/tmp/log$$
202

RETURN VALUES

204       OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free()
205       CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions()
206       return no value.
207
208       CRYPTO_mem_leaks(), CRYPTO_mem_leaks_fp() and CRYPTO_mem_leaks_cb()
209       return 1 if there are no leaks, 0 if there are leaks and -1 if an error
210       occurred.
211
212       OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(),
213       OPENSSL_clear_realloc(), CRYPTO_malloc(), CRYPTO_zalloc(),
214       CRYPTO_realloc(), CRYPTO_clear_realloc(), OPENSSL_buf2hexstr(),
215       OPENSSL_hexstr2buf(), OPENSSL_strdup(), and OPENSSL_strndup() return a
216       pointer to allocated memory or NULL on error.
217
218       CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug() return 1 on
219       success or 0 on failure (almost always because allocations have already
220       happened).
221
222       CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the
223       previous value of the mode.
224
225       OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop() return 1 on
226       success or 0 on failure.
227

NOTES

229       While it's permitted to swap out only a few and not all the functions
230       with CRYPTO_set_mem_functions(), it's recommended to swap them all out
231       at once.  This applies specially if OpenSSL was built with the
232       configuration option "crypto-mdebug" enabled.  In case, swapping out
233       only, say, the malloc() implementation is outright dangerous.
234
236       Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
237
238       Licensed under the OpenSSL license (the "License").  You may not use
239       this file except in compliance with the License.  You can obtain a copy
240       in the file LICENSE in the source distribution or at
241       <https://www.openssl.org/source/license.html>.
242
243
244
2451.1.1q                            2023-07-20                 OPENSSL_MALLOC(3)
Impressum