core: Stop using AST_INLINE_API for allocator functions.
[asterisk/asterisk.git] / include / asterisk / astmm.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Asterisk memory management routines
21  *
22  * This file should never be \#included directly, it is included
23  * by asterisk.h.
24  */
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 #ifndef _ASTERISK_ASTMM_H
31 #define _ASTERISK_ASTMM_H
32 /* IWYU pragma: private, include "asterisk.h" */
33
34 #if defined(MALLOC_DEBUG) && !defined(STANDALONE) && !defined(STANDALONE2)
35 #define __AST_DEBUG_MALLOC
36
37 void __ast_mm_init_phase_1(void);
38 void __ast_mm_init_phase_2(void);
39 #endif
40
41 void *ast_std_malloc(size_t size) attribute_malloc;
42 void *ast_std_calloc(size_t nmemb, size_t size) attribute_malloc;
43 void *ast_std_realloc(void *ptr, size_t size);
44 void ast_std_free(void *ptr);
45
46 /*!
47  * \brief free() wrapper
48  *
49  * ast_free_ptr should be used when a function pointer for free() needs to be passed
50  * as the argument to a function. Otherwise, astmm will cause seg faults.
51  */
52 void ast_free_ptr(void *ptr);
53
54 void *__ast_calloc(size_t nmemb, size_t size, const char *file, int lineno, const char *func) attribute_malloc;
55 void *__ast_calloc_cache(size_t nmemb, size_t size, const char *file, int lineno, const char *func) attribute_malloc;
56 void *__ast_malloc(size_t size, const char *file, int lineno, const char *func) attribute_malloc;
57 void __ast_free(void *ptr, const char *file, int lineno, const char *func);
58 void *__ast_realloc(void *ptr, size_t size, const char *file, int lineno, const char *func);
59 char *__ast_strdup(const char *s, const char *file, int lineno, const char *func) attribute_malloc;
60 char *__ast_strndup(const char *s, size_t n, const char *file, int lineno, const char *func) attribute_malloc;
61 int __ast_asprintf(const char *file, int lineno, const char *func, char **strp, const char *format, ...)
62         __attribute__((format(printf, 5, 6)));
63 int __ast_vasprintf(char **strp, const char *format, va_list ap, const char *file, int lineno, const char *func)
64         __attribute__((format(printf, 2, 0)));
65
66 /* The __ast_repl functions should not used from Asterisk sources, they are exposed
67  * for use by ASTMM_REDIRECT and bundled pjproject. */
68 void *__ast_repl_calloc(size_t nmemb, size_t size, const char *file, int lineno, const char *func) attribute_malloc;
69 void *__ast_repl_malloc(size_t size, const char *file, int lineno, const char *func) attribute_malloc;
70 void *__ast_repl_realloc(void *ptr, size_t size, const char *file, int lineno, const char *func);
71 char *__ast_repl_strdup(const char *s, const char *file, int lineno, const char *func) attribute_malloc;
72 char *__ast_repl_strndup(const char *s, size_t n, const char *file, int lineno, const char *func) attribute_malloc;
73 int __ast_repl_asprintf(const char *file, int lineno, const char *func, char **strp, const char *format, ...)
74         __attribute__((format(printf, 5, 6)));
75 int __ast_repl_vasprintf(char **strp, const char *format, va_list ap, const char *file, int lineno, const char *func)
76         __attribute__((format(printf, 2, 0)));
77
78 /*!
79  * \brief ASTMM_LIBC can be defined to control the meaning of standard allocators.
80  *
81  * \note The standard allocators effected by this compiler define are:
82  *    malloc, calloc, realloc, strdup, strndup, asprintf, vasprintf and free.
83  *
84  * @{
85  */
86
87 /*!
88  * \brief Produce compiler errors if standard allocators are used.
89  *
90  * \note This is the default option, and in most cases the correct option.
91  * Any use of standard allocators will cause an error, even if those uses
92  * are in unused static inline header functions.
93  */
94 #define ASTMM_BLOCK    0
95
96 /*!
97  * \brief Redirect standard allocators to use Asterisk functions.
98  *
99  * \note This option is used in some cases instead of changing the
100  * existing source to use Asterisk functions.  New code should
101  * generally avoid this option, except where it's needed to work
102  * with situations where switching the code is unreasonable, such
103  * as output from code generators that are hard coded to use
104  * standard functions.
105  */
106 #define ASTMM_REDIRECT 1
107
108 /*!
109  * \brief Standard allocators are used directly.
110  *
111  * \note This option is needed when including 3rd party headers with calls
112  * to standard allocators from inline functions.  Using ASTMM_REDIRECT in
113  * this situation could result in an object being allocated by malloc and
114  * freed by ast_free, or the reverse.
115  */
116 #define ASTMM_IGNORE   2
117
118 /*!
119  * }@
120  */
121
122 #if !defined(ASTMM_LIBC)
123 /* BLOCK libc allocators by default. */
124 #define ASTMM_LIBC ASTMM_BLOCK
125 #endif
126
127 #if ASTMM_LIBC == ASTMM_IGNORE
128 /* Don't touch the libc functions. */
129 #else
130
131 /* Undefine any macros */
132 #undef malloc
133 #undef calloc
134 #undef realloc
135 #undef strdup
136 #undef strndup
137 #undef asprintf
138 #undef vasprintf
139 #undef free
140
141 #if ASTMM_LIBC == ASTMM_REDIRECT
142
143 /* Redefine libc functions to our own versions */
144 #define calloc(nmemb, size) \
145         __ast_repl_calloc(nmemb, size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
146 #define malloc(size) \
147         __ast_repl_malloc(size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
148 #define free(ptr) \
149         __ast_free(ptr, __FILE__, __LINE__, __PRETTY_FUNCTION__)
150 #define realloc(ptr, size) \
151         __ast_repl_realloc(ptr, size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
152 #define strdup(s) \
153         __ast_repl_strdup(s, __FILE__, __LINE__, __PRETTY_FUNCTION__)
154 #define strndup(s, n) \
155         __ast_repl_strndup(s, n, __FILE__, __LINE__, __PRETTY_FUNCTION__)
156 #define asprintf(strp, format, args...) \
157         __ast_repl_asprintf(__FILE__, __LINE__, __PRETTY_FUNCTION__, strp, format, args)
158 #define vasprintf(strp, format, ap) \
159         __ast_repl_vasprintf(strp, format, ap, __FILE__, __LINE__, __PRETTY_FUNCTION__)
160
161 #elif ASTMM_LIBC == ASTMM_BLOCK
162
163 /* Redefine libc functions to cause compile errors */
164 #define calloc(a, b) \
165         Do_not_use_calloc__use_ast_calloc->fail(a, b)
166 #define malloc(a) \
167         Do_not_use_malloc__use_ast_malloc->fail(a)
168 #define free(a) \
169         Do_not_use_free__use_ast_free_or_ast_std_free_for_remotely_allocated_memory->fail(a)
170 #define realloc(a, b) \
171         Do_not_use_realloc__use_ast_realloc->fail(a, b)
172 #define strdup(a) \
173         Do_not_use_strdup__use_ast_strdup->fail(a)
174 #define strndup(a, b) \
175         Do_not_use_strndup__use_ast_strndup->fail(a, b)
176 #define asprintf(a, b, c...) \
177         Do_not_use_asprintf__use_ast_asprintf->fail(a, b, c)
178 #define vasprintf(a, b, c) \
179         Do_not_use_vasprintf__use_ast_vasprintf->fail(a, b, c)
180
181 #else
182 #error "Unacceptable value for the macro ASTMM_LIBC"
183 #endif
184
185 #endif
186
187 /* Provide our own definition for ast_free */
188
189 #define ast_free(a) \
190         __ast_free(a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
191
192 /*!
193  * \brief A wrapper for malloc()
194  *
195  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
196  * message in the case that the allocation fails.
197  *
198  * The argument and return value are the same as malloc()
199  */
200 #define ast_malloc(len) \
201         __ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
202
203 /*!
204  * \brief A wrapper for calloc()
205  *
206  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
207  * message in the case that the allocation fails.
208  *
209  * The arguments and return value are the same as calloc()
210  */
211 #define ast_calloc(num, len) \
212         __ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
213
214 /*!
215  * \brief A wrapper for calloc() for use in cache pools
216  *
217  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
218  * message in the case that the allocation fails. When memory debugging is in use,
219  * the memory allocated by this function will be marked as 'cache' so it can be
220  * distinguished from normal memory allocations.
221  *
222  * The arguments and return value are the same as calloc()
223  */
224 #define ast_calloc_cache(num, len) \
225         __ast_calloc_cache((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
226
227 /*!
228  * \brief A wrapper for realloc()
229  *
230  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
231  * message in the case that the allocation fails.
232  *
233  * The arguments and return value are the same as realloc()
234  */
235 #define ast_realloc(p, len) \
236         __ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
237
238 /*!
239  * \brief A wrapper for strdup()
240  *
241  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
242  * message in the case that the allocation fails.
243  *
244  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
245  * argument is provided, ast_strdup will return NULL without generating any
246  * kind of error log message.
247  *
248  * The argument and return value are the same as strdup()
249  */
250 #define ast_strdup(str) \
251         __ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
252
253 /*!
254  * \brief A wrapper for strndup()
255  *
256  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
257  * message in the case that the allocation fails.
258  *
259  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
260  * string to duplicate. If a NULL argument is provided, ast_strdup will return
261  * NULL without generating any kind of error log message.
262  *
263  * The arguments and return value are the same as strndup()
264  */
265 #define ast_strndup(str, len) \
266         __ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
267
268 /*!
269  * \brief A wrapper for asprintf()
270  *
271  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
272  * message in the case that the allocation fails.
273  *
274  * The arguments and return value are the same as asprintf()
275  */
276 #define ast_asprintf(ret, fmt, ...) \
277         __ast_asprintf(__FILE__, __LINE__, __PRETTY_FUNCTION__, (ret), (fmt), __VA_ARGS__)
278
279 /*!
280  * \brief A wrapper for vasprintf()
281  *
282  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
283  * message in the case that the allocation fails.
284  *
285  * The arguments and return value are the same as vasprintf()
286  */
287 #define ast_vasprintf(ret, fmt, ap) \
288         __ast_vasprintf((ret), (fmt), (ap), __FILE__, __LINE__, __PRETTY_FUNCTION__)
289
290 /*!
291   \brief call __builtin_alloca to ensure we get gcc builtin semantics
292   \param size The size of the buffer we want allocated
293
294   This macro will attempt to allocate memory from the stack.  If it fails
295   you won't get a NULL returned, but a SEGFAULT if you're lucky.
296 */
297 #define ast_alloca(size) __builtin_alloca(size)
298
299 #if !defined(ast_strdupa) && defined(__GNUC__)
300 /*!
301  * \brief duplicate a string in memory from the stack
302  * \param s The string to duplicate
303  *
304  * This macro will duplicate the given string.  It returns a pointer to the stack
305  * allocatted memory for the new string.
306  */
307 #define ast_strdupa(s)                                                    \
308         (__extension__                                                    \
309         ({                                                                \
310                 const char *__old = (s);                                  \
311                 size_t __len = strlen(__old) + 1;                         \
312                 char *__new = __builtin_alloca(__len);                    \
313                 memcpy (__new, __old, __len);                             \
314                 __new;                                                    \
315         }))
316 #endif
317
318 #else
319 #error "NEVER INCLUDE astmm.h DIRECTLY!!"
320 #endif /* _ASTERISK_ASTMM_H */
321
322 #ifdef __cplusplus
323 }
324 #endif