common/safety.h

   1 /* -*- Mode: C ; c-basic-offset: 2 -*- */
   2 /*
   3  * LADI Session Handler (ladish)
   4  *
   5  * Copyright (C) 2008 Juuso Alasuutari <juuso.alasuutari@gmail.com>
   6  *
   7  **************************************************************************
   8  * This file contains interface to "safe" memory and string helpers (obsolete)
   9  **************************************************************************
  10  *
  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.
  15  *
  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.
  20  *
  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.
  25  */
  26
  27 /** @file safety.h
  28  *   This module contains wrappers around system memory handling functions
  29  *   for reliable error handling and increased debugging verbosity.
  30  *
  31  *   Some of the provided methods can be either macros or function definitions
  32  *   depending on whether or not LASH_DEBUG is enabled. The programmer needn't
  33  *   worry, however, as the syntax is the same for both debug and normal builds.
  34  */
  35
  36 #ifndef __LASH_SAFETY_H__
  37 #define __LASH_SAFETY_H__
  38
  39 #include <stdlib.h>
  40
  41 #include "config.h"
  42
  43 /**
  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.
  47  */
  48 #define lash_free(ptr) \
  49   _lash_free((void **) ptr)
  50
  51 /**
  52  * Free the memory pointed to by *ptr. If the pointer was valid,
  53  * set it to NULL after freeing it.
  54  *
  55  * @param ptr A pointer to a pointer to the memory to be be freed.
  56  */
  57 void
  58 _lash_free(void **ptr);
  59
  60 /**
  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
  64  * it to value.
  65  *
  66  * @param property A pointer to the char* to set.
  67  * @param value The value to set property to.
  68  */
  69 void
  70 lash_strset(char       **property,
  71             const char  *value);
  72
  73 #ifndef LASH_DEBUG
  74
  75 /**
  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 lash_error if anything fails.
  79  *
  80  * TODO: We currently call abort on failure,
  81  *       this probably needs to be changed.
  82  *
  83  * @param nmemb The number of elements to allocate.
  84  * @param size The size in bytes of one element.
  85  *
  86  * @return A pointer to the allocated memory.
  87  */
  88 void *
  89 lash_malloc(size_t nmemb,
  90             size_t size);
  91
  92 /**
  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 lash_error if anything fails.
  96  *
  97  * TODO: We currently call abort on failure,
  98  *       this probably needs to be changed.
  99  *
 100  * @param nmemb The number of elements to allocate.
 101  * @param size The size of one element (in bytes).
 102  *
 103  * @return A pointer to the allocated memory.
 104  */
 105 void *
 106 lash_calloc(size_t nmemb,
 107             size_t size);
 108
 109 /**
 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 lash_error if anything fails.
 113  *
 114  * TODO: We currently call abort on failure,
 115  *       this probably needs to be changed.
 116  *
 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).
 120  *
 121  * @return A pointer to the allocated memory.
 122  */
 123 void *
 124 lash_realloc(void   *ptr,
 125              size_t  nmemb,
 126              size_t  size);
 127
 128 /**
 129  * This is a wrapper around strdup which checks for a NULL return value.
 130  * It prints an error using \ref lash_error if strdup fails.
 131  *
 132  * TODO: We currently call abort on failure,
 133  *       this probably needs to be changed.
 134  *
 135  * @param s The string to duplicate.
 136  *
 137  * @return A pointer to the duplicated string.
 138  */
 139 char *
 140 lash_strdup(const char *s);
 141
 142 /** TODO: Document this */
 143 #else /* LASH_DEBUG */
 144
 145 /**
 146  * This macro is a wrapper around \ref lash_malloc_dbg.
 147  *
 148  * @param nmemb The number of elements to allocate.
 149  * @param size The size in bytes of one element.
 150  *
 151  * @return A pointer to the allocated memory.
 152  */
 153 # define lash_malloc(nmemb, size) \
 154   lash_malloc_dbg(nmemb, size, __FILE__, __LINE__, __func__, # nmemb, # size)
 155
 156 /**
 157  * This macro is a wrapper around \ref lash_calloc_dbg.
 158  *
 159  * @param nmemb The number of elements to allocate.
 160  * @param size The size in bytes of one element.
 161  *
 162  * @return A pointer to the allocated memory.
 163  */
 164 # define lash_calloc(nmemb, size) \
 165   lash_calloc_dbg(nmemb, size, __FILE__, __LINE__, __func__, # nmemb, # size)
 166
 167 /**
 168  * This macro is a wrapper around \ref lash_realloc_dbg.
 169  *
 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.
 173  *
 174  * @return A pointer to the allocated memory.
 175  */
 176 # define lash_realloc(ptr, nmemb, size) \
 177   lash_realloc_dbg(ptr, nmemb, size, __FILE__, __LINE__, __func__, # ptr, # nmemb, # size)
 178
 179 /**
 180  * This macro is a wrapper around \ref lash_strdup_dbg.
 181  *
 182  * @param s The string to duplicate.
 183  *
 184  * @return A pointer to the duplicated string.
 185  */
 186 # define lash_strdup(s) \
 187   lash_strdup_dbg(s, __FILE__, __LINE__, __func__, # s)
 188
 189 /**
 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 lash_error if anything fails.
 193  *
 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
 197  * macro.
 198  *
 199  * TODO: We currently call abort on failure,
 200  *       this probably needs to be changed.
 201  *
 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.
 209  *
 210  * @return A pointer to the allocated memory.
 211  */
 212 void *
 213 lash_malloc_dbg(size_t      nmemb,
 214                 size_t      size,
 215                 const char *file,
 216                 int         line,
 217                 const char *function,
 218                 const char *arg1,
 219                 const char *arg2);
 220
 221 /**
 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 lash_error if anything fails.
 225  *
 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
 229  * macro.
 230  *
 231  * TODO: We currently call abort on failure,
 232  *       this probably needs to be changed.
 233  *
 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.
 241  *
 242  * @return A pointer to the allocated memory.
 243  */
 244 void *
 245 lash_calloc_dbg(size_t      nmemb,
 246                 size_t      size,
 247                 const char *file,
 248                 int         line,
 249                 const char *function,
 250                 const char *arg1,
 251                 const char *arg2);
 252
 253 /**
 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 lash_error if anything fails.
 257  *
 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
 261  * macro.
 262  *
 263  * TODO: We currently call abort on failure,
 264  *       this probably needs to be changed.
 265  *
 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.
 274  *
 275  * @return A pointer to the allocated memory.
 276  */
 277 void *
 278 lash_realloc_dbg(void       *ptr,
 279                  size_t      nmemb,
 280                  size_t      size,
 281                  const char *file,
 282                  int         line,
 283                  const char *function,
 284                  const char *arg1,
 285                  const char *arg2,
 286                  const char *arg3);
 287
 288 /**
 289  * This is a wrapper around strdup which checks for a NULL return value.
 290  * It prints an error using \ref lash_error if strdup fails.
 291  *
 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
 295  * macro.
 296  *
 297  * TODO: We currently call abort on failure,
 298  *       this probably needs to be changed.
 299  *
 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.
 305  *
 306  * @return A pointer to the duplicated string.
 307  */
 308 char *
 309 lash_strdup_dbg(const char *s,
 310                 const char *file,
 311                 int         line,
 312                 const char *function,
 313                 const char *arg1);
 314
 315 #endif /* LASH_DEBUG */
 316
 317 #endif /* __LASH_SAFETY_H__ */