do not use reserved names.
[protos/libecoli.git] / lib / ecoli_malloc.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
3  */
4
5 /**
6  * Interface to configure the allocator used by libecoli.
7  * By default, the standard allocation functions from libc are used.
8  */
9
10 #ifndef ECOLI_MALLOC_
11 #define ECOLI_MALLOC_
12
13 #include <sys/types.h>
14 #include <stdlib.h>
15 #include <string.h>
16
17 /**
18  * Function type of malloc, passed to ec_malloc_register().
19  *
20  * The API is the same than malloc(), excepted the file and line
21  * arguments.
22  *
23  * @param size
24  *   The size of the memory area to allocate.
25  * @param file
26  *   The path to the file that invoked the malloc.
27  * @param line
28  *   The line in the file that invoked the malloc.
29  * @return
30  *   A pointer to the allocated memory area, or NULL on error (errno
31  *   is set).
32  */
33 typedef void *(*ec_malloc_t)(size_t size, const char *file, unsigned int line);
34
35 /**
36  * Function type of free, passed to ec_malloc_register().
37  *
38  * The API is the same than free(), excepted the file and line
39  * arguments.
40  *
41  * @param ptr
42  *   The pointer to the memory area to be freed.
43  * @param file
44  *   The path to the file that invoked the malloc.
45  * @param line
46  *   The line in the file that invoked the malloc.
47  */
48 typedef void (*ec_free_t)(void *ptr, const char *file, unsigned int line);
49
50 /**
51  * Function type of realloc, passed to ec_malloc_register().
52  *
53  * The API is the same than realloc(), excepted the file and line
54  * arguments.
55  *
56  * @param ptr
57  *   The pointer to the memory area to be reallocated.
58  * @param file
59  *   The path to the file that invoked the malloc.
60  * @param line
61  *   The line in the file that invoked the malloc.
62  * @return
63  *   A pointer to the allocated memory area, or NULL on error (errno
64  *   is set).
65  */
66 typedef void *(*ec_realloc_t)(void *ptr, size_t size, const char *file,
67         unsigned int line);
68
69 /**
70  * Register allocation functions.
71  *
72  * This function can be use to register another allocator
73  * to be used by libecoli. By default, ec_malloc(), ec_free() and
74  * ec_realloc() use the standard libc allocator. Another handler
75  * can be used for debug purposes or when running in a specific
76  * environment.
77  *
78  * This function must be called before ec_init().
79  *
80  * @param usr_malloc
81  *   A user-defined malloc function.
82  * @param usr_free
83  *   A user-defined free function.
84  * @param usr_realloc
85  *   A user-defined realloc function.
86  * @return
87  *   0 on success, or -1 on error (errno is set).
88  */
89 int ec_malloc_register(ec_malloc_t usr_malloc, ec_free_t usr_free,
90         ec_realloc_t usr_realloc);
91
92 struct ec_malloc_handler {
93         ec_malloc_t malloc;
94         ec_free_t free;
95         ec_realloc_t realloc;
96 };
97
98 extern struct ec_malloc_handler ec_malloc_handler;
99
100 /**
101  * Allocate a memory area.
102  *
103  * Like malloc(), ec_malloc() allocates size bytes and returns a pointer
104  * to the allocated memory. The memory is not initialized. The memory is
105  * freed with ec_free().
106  *
107  * @param size
108  *   The size of the area to allocate in bytes.
109  * @return
110  *   The pointer to the allocated memory, or NULL on error (errno is set).
111  */
112 #define ec_malloc(size) ({                                              \
113         void *ret_;                                                     \
114         if (ec_malloc_handler.malloc == NULL)                           \
115                 ret_ = malloc(size);                                    \
116         else                                                            \
117                 ret_ = __ec_malloc(size, __FILE__, __LINE__);           \
118         ret_;                                                           \
119         })
120
121 /**
122  * Ecoli malloc function.
123  *
124  * Use this function when the macro ec_malloc() cannot be used,
125  * for instance when it is passed as a callback pointer.
126  */
127 void *ec_malloc_func(size_t size);
128
129 /**
130  * Free a memory area.
131  *
132  * Like free(), ec_free() frees the area pointed by ptr, which must have
133  * been returned by a previous call to ec_malloc() or any other
134  * allocation function of this file.
135  *
136  * @param ptr
137  *   The pointer to the memory area.
138  */
139 #define ec_free(ptr) ({                                                 \
140         if (ec_malloc_handler.free == NULL)                             \
141                 free(ptr);                                              \
142         else                                                            \
143                 __ec_free(ptr, __FILE__, __LINE__);                     \
144         })
145
146 /**
147  * Ecoli free function.
148  *
149  * Use this function when the macro ec_free() cannot be used,
150  * for instance when it is passed as a callback pointer.
151  */
152 void ec_free_func(void *ptr);
153
154 /**
155  * Resize an allocated memory area.
156  *
157  * @param ptr
158  *   The pointer to the previously allocated memory area, or NULL.
159  * @param size
160  *   The new size of the memory area.
161  * @return
162  *   A pointer to the newly allocated memory, or NULL if the request
163  *   fails. In that case, the original area is left untouched.
164  */
165 #define ec_realloc(ptr, size) ({                                        \
166         void *ret_;                                                     \
167         if (ec_malloc_handler.realloc == NULL)                          \
168                 ret_ = realloc(ptr, size);                              \
169         else                                                            \
170                 ret_ = __ec_realloc(ptr, size, __FILE__, __LINE__);     \
171         ret_;                                                           \
172         })
173
174 /**
175  * Allocate and initialize an array of elements.
176  *
177  * @param n
178  *   The number of elements.
179  * @param size
180  *   The size of each element.
181  * @return
182  *   The pointer to the allocated memory, or NULL on error (errno is set).
183  */
184 #define ec_calloc(n, size) ({                                           \
185         void *ret_;                                                     \
186         if (ec_malloc_handler.malloc == NULL)                           \
187                 ret_ = calloc(n, size);                                 \
188         else                                                            \
189                 ret_ = __ec_calloc(n, size, __FILE__, __LINE__);        \
190         ret_;                                                           \
191         })
192
193 /**
194  * Duplicate a string.
195  *
196  * Memory for the new string is obtained with ec_malloc(), and can be
197  * freed with ec_free().
198  *
199  * @param s
200  *   The string to be duplicated.
201  * @return
202  *   The pointer to the duplicated string, or NULL on error (errno is set).
203  */
204 #define ec_strdup(s) ({                                                 \
205         void *ret_;                                                     \
206         if (ec_malloc_handler.malloc == NULL)                           \
207                 ret_ = strdup(s);                                       \
208         else                                                            \
209                 ret_ = __ec_strdup(s, __FILE__, __LINE__);              \
210         ret_;                                                           \
211         })
212
213 /**
214  * Duplicate at most n bytes of a string.
215  *
216  * This function is similar to ec_strdup(), except that it copies at
217  * most n bytes.  If s is longer than n, only n bytes are copied, and a
218  * terminating null byte ('\0') is added.
219  *
220  * @param s
221  *   The string to be duplicated.
222  * @param n
223  *   The maximum length of the new string.
224  * @return
225  *   The pointer to the duplicated string, or NULL on error (errno is set).
226  */
227 #define ec_strndup(s, n) ({                                             \
228         void *ret_;                                                     \
229         if (ec_malloc_handler.malloc == NULL)                           \
230                 ret_ = strndup(s, n);                                   \
231         else                                                            \
232                 ret_ = __ec_strndup(s, n, __FILE__, __LINE__);          \
233         ret_;                                                           \
234         })
235
236 /* internal */
237 void *__ec_malloc(size_t size, const char *file, unsigned int line);
238 void __ec_free(void *ptr, const char *file, unsigned int line);
239 void *__ec_calloc(size_t nmemb, size_t size, const char *file,
240         unsigned int line);
241 void *__ec_realloc(void *ptr, size_t size, const char *file, unsigned int line);
242 char *__ec_strdup(const char *s, const char *file, unsigned int line);
243 char *__ec_strndup(const char *s, size_t n, const char *file,
244         unsigned int line);
245
246
247 #endif