1 /* -*- Mode: C ; c-basic-offset: 2 -*- */
3 * LADI Session Handler (ladish)
5 * Copyright (C) 2008 Juuso Alasuutari <juuso.alasuutari@gmail.com>
7 **************************************************************************
8 * This file contains interface to "safe" memory and string helpers (obsolete)
9 **************************************************************************
11 * LADI Session Handler is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * LADI Session Handler is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with LADI Session Handler. If not, see <http://www.gnu.org/licenses/>
23 * or write to the Free Software Foundation, Inc.,
24 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
28 * This module contains wrappers around system memory handling functions
29 * for reliable error handling and increased debugging verbosity.
31 * Some of the provided methods can be either macros or function definitions
32 * depending on whether or not LADISH_DEBUG is enabled. The programmer needn't
33 * worry, however, as the syntax is the same for both debug and normal builds.
36 #ifndef __LASH_SAFETY_H__
37 #define __LASH_SAFETY_H__
44 * This macro is a convenience wrapper around \ref _lash_free.
45 * It does nothing more than cast the provided argument to void**
46 * in order to eliminate invalid pointer type warnings.
48 #define lash_free(ptr) \
49 _lash_free((void **) ptr)
52 * Free the memory pointed to by *ptr. If the pointer was valid,
53 * set it to NULL after freeing it.
55 * @param ptr A pointer to a pointer to the memory to be be freed.
58 _lash_free(void **ptr
);
61 * If value is non-NULL, set *property to point to a new string
62 * which is a copy of value. If value is NULL, set *property
63 * to NULL. If *property is already set, it will be freed before setting
66 * @param property A pointer to the char* to set.
67 * @param value The value to set property to.
70 lash_strset(char **property
,
76 * This is a wrapper around malloc which checks whether nmemb * size
77 * would overflow, and whether malloc returns NULL. It prints an error
78 * using \ref log_error if anything fails.
80 * TODO: We currently call abort on failure,
81 * this probably needs to be changed.
83 * @param nmemb The number of elements to allocate.
84 * @param size The size in bytes of one element.
86 * @return A pointer to the allocated memory.
89 lash_malloc(size_t nmemb
,
93 * This is a wrapper around calloc which checks whether nmemb * size
94 * would overflow, and whether calloc) returns NULL. It prints an error
95 * using \ref log_error if anything fails.
97 * TODO: We currently call abort on failure,
98 * this probably needs to be changed.
100 * @param nmemb The number of elements to allocate.
101 * @param size The size of one element (in bytes).
103 * @return A pointer to the allocated memory.
106 lash_calloc(size_t nmemb
,
110 * This is a wrapper around realloc which checks whether nmemb * size
111 * would overflow, and whether realloc returns NULL. It prints an error
112 * using \ref log_error if anything fails.
114 * TODO: We currently call abort on failure,
115 * this probably needs to be changed.
117 * @param ptr A pointer to the memory block whose size to change.
118 * @param nmemb The number of elements to (re)allocate.
119 * @param size The size of one element (in bytes).
121 * @return A pointer to the allocated memory.
124 lash_realloc(void *ptr
,
129 * This is a wrapper around strdup which checks for a NULL return value.
130 * It prints an error using \ref log_error if strdup fails.
132 * TODO: We currently call abort on failure,
133 * this probably needs to be changed.
135 * @param s The string to duplicate.
137 * @return A pointer to the duplicated string.
140 lash_strdup(const char *s
);
142 /** TODO: Document this */
143 #else /* LADISH_DEBUG */
146 * This macro is a wrapper around \ref lash_malloc_dbg.
148 * @param nmemb The number of elements to allocate.
149 * @param size The size in bytes of one element.
151 * @return A pointer to the allocated memory.
153 # define lash_malloc(nmemb, size) \
154 lash_malloc_dbg(nmemb, size, __FILE__, __LINE__, __func__, # nmemb, # size)
157 * This macro is a wrapper around \ref lash_calloc_dbg.
159 * @param nmemb The number of elements to allocate.
160 * @param size The size in bytes of one element.
162 * @return A pointer to the allocated memory.
164 # define lash_calloc(nmemb, size) \
165 lash_calloc_dbg(nmemb, size, __FILE__, __LINE__, __func__, # nmemb, # size)
168 * This macro is a wrapper around \ref lash_realloc_dbg.
170 * @param ptr A pointer to the memory block whose size to change.
171 * @param nmemb The number of elements to allocate.
172 * @param size The size in bytes of one element.
174 * @return A pointer to the allocated memory.
176 # define lash_realloc(ptr, nmemb, size) \
177 lash_realloc_dbg(ptr, nmemb, size, __FILE__, __LINE__, __func__, # ptr, # nmemb, # size)
180 * This macro is a wrapper around \ref lash_strdup_dbg.
182 * @param s The string to duplicate.
184 * @return A pointer to the duplicated string.
186 # define lash_strdup(s) \
187 lash_strdup_dbg(s, __FILE__, __LINE__, __func__, # s)
190 * This is a wrapper around malloc which checks whether nmemb * size
191 * would overflow, and whether malloc returns NULL. It prints an error
192 * using \ref log_error if anything fails.
194 * This function is the 'debugging edition' of the LASH malloc wrapper and
195 * has extra parameters for printing more detailed debugging messages. It
196 * should never be called directly, but instead by using the \ref lash_malloc
199 * TODO: We currently call abort on failure,
200 * this probably needs to be changed.
202 * @param nmemb The number of elements to allocate.
203 * @param size The size of one element (in bytes).
204 * @param file The calling file name.
205 * @param line The calling line number.
206 * @param function The calling function name.
207 * @param arg1 A string representation of the nmemb argument passed by the caller.
208 * @param arg2 A string representation of the size argument passed by the caller.
210 * @return A pointer to the allocated memory.
213 lash_malloc_dbg(size_t nmemb
,
217 const char *function
,
222 * This is a wrapper around calloc which checks whether nmemb * size
223 * would overflow, and whether calloc returns NULL. It prints an error
224 * using \ref log_error if anything fails.
226 * This function is the 'debugging edition' of the LASH calloc wrapper and
227 * has extra parameters for printing more detailed debugging messages. It
228 * should never be called directly, but instead by using the \ref lash_calloc
231 * TODO: We currently call abort on failure,
232 * this probably needs to be changed.
234 * @param nmemb The number of elements to allocate.
235 * @param size The size of one element (in bytes).
236 * @param file The calling file name.
237 * @param line The calling line number.
238 * @param function The calling function name.
239 * @param arg1 A string representation of the nmemb argument passed by the caller.
240 * @param arg2 A string representation of the size argument passed by the caller.
242 * @return A pointer to the allocated memory.
245 lash_calloc_dbg(size_t nmemb
,
249 const char *function
,
254 * This is a wrapper around realloc which checks whether nmemb * size
255 * would overflow, and whether realloc returns NULL. It prints an error
256 * using \ref log_error if anything fails.
258 * This function is the 'debugging edition' of the LASH realloc wrapper and
259 * has extra parameters for printing more detailed debugging messages. It
260 * should never be called directly, but instead by using the \ref lash_realloc
263 * TODO: We currently call abort on failure,
264 * this probably needs to be changed.
266 * @param nmemb The number of elements to allocate.
267 * @param size The size of one element (in bytes).
268 * @param file The calling file name.
269 * @param line The calling line number.
270 * @param function The calling function name.
271 * @param arg1 A string representation of the ptr argument passed by the caller.
272 * @param arg2 A string representation of the nmemb argument passed by the caller.
273 * @param arg3 A string representation of the size argument passed by the caller.
275 * @return A pointer to the allocated memory.
278 lash_realloc_dbg(void *ptr
,
283 const char *function
,
289 * This is a wrapper around strdup which checks for a NULL return value.
290 * It prints an error using \ref log_error if strdup fails.
292 * This function is the 'debugging edition' of the LASH strdup wrapper and
293 * has extra parameters for printing more detailed debugging messages. It
294 * should never be called directly, but instead by using the \ref lash_strdup
297 * TODO: We currently call abort on failure,
298 * this probably needs to be changed.
300 * @param s The string to duplicate.
301 * @param file The calling file name.
302 * @param line The calling line number.
303 * @param function The calling function name.
304 * @param arg1 A string representation of the argument passed by the caller.
306 * @return A pointer to the duplicated string.
309 lash_strdup_dbg(const char *s
,
312 const char *function
,
315 #endif /* LADISH_DEBUG */
317 #endif /* __LASH_SAFETY_H__ */