dbus/dbus-memory.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-memory.c  D-BUS memory handling
   3  *
   4  * Copyright (C) 2002  Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 1.2
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  *
  22  */
  23
  24 #include "dbus-memory.h"
  25 #include <stdlib.h>
  26
  27 /**
  28  * @defgroup DBusMemory Memory Allocation
  29  * @ingroup  DBus
  30  * @brief dbus_malloc(), dbus_free(), etc.
  31  *
  32  * Functions and macros related to allocating and releasing
  33  * blocks of memory.
  34  *
  35  * @{
  36  */
  37
  38 /**
  39  * @def dbus_new
  40  *
  41  * Safe macro for using dbus_malloc(). Accepts the type
  42  * to allocate and the number of type instances to
  43  * allocate as arguments, and returns a memory block
  44  * cast to the desired type, instead of as a void*.
  45  *
  46  * @param type type name to allocate
  47  * @param count number of instances in the allocated array
  48  * @returns the new memory block or #NULL on failure
  49  */
  50
  51 /**
  52  * @def dbus_new0
  53  *
  54  * Safe macro for using dbus_malloc0(). Accepts the type
  55  * to allocate and the number of type instances to
  56  * allocate as arguments, and returns a memory block
  57  * cast to the desired type, instead of as a void*.
  58  * The allocated array is initialized to all-bits-zero.
  59  *
  60  * @param type type name to allocate
  61  * @param count number of instances in the allocated array
  62  * @returns the new memory block or #NULL on failure
  63  */
  64
  65 /**
  66  * @typedef DBusFreeFunction
  67  *
  68  * The type of a function which frees a block of memory.
  69  *
  70  * @param memory the memory to free
  71  */
  72
  73 /**
  74  * Allocates the given number of bytes, as with standard
  75  * malloc(). Guaranteed to return #NULL if bytes is zero
  76  * on all platforms. Returns #NULL if the allocation fails.
  77  * The memory must be released with dbus_free().
  78  *
  79  * @param bytes number of bytes to allocate
  80  * @return allocated memory, or #NULL if the allocation fails.
  81  */
  82 void*
  83 dbus_malloc (size_t bytes)
  84 {
  85   if (bytes == 0) /* some system mallocs handle this, some don't */
  86     return NULL;
  87   else
  88     return malloc (bytes);
  89 }
  90
  91 /**
  92  * Allocates the given number of bytes, as with standard malloc(), but
  93  * all bytes are initialized to zero as with calloc(). Guaranteed to
  94  * return #NULL if bytes is zero on all platforms. Returns #NULL if the
  95  * allocation fails.  The memory must be released with dbus_free().
  96  *
  97  * @param bytes number of bytes to allocate
  98  * @return allocated memory, or #NULL if the allocation fails.
  99  */
 100 void*
 101 dbus_malloc0 (size_t bytes)
 102 {
 103   if (bytes == 0)
 104     return NULL;
 105   else
 106     return calloc (bytes, 1);
 107 }
 108
 109 /**
 110  * Resizes a block of memory previously allocated by dbus_malloc() or
 111  * dbus_malloc0(). Guaranteed to free the memory and return #NULL if bytes
 112  * is zero on all platforms. Returns #NULL if the resize fails.
 113  * If the resize fails, the memory is not freed.
 114  *
 115  * @param memory block to be resized
 116  * @param bytes new size of the memory block
 117  * @return allocated memory, or #NULL if the resize fails.
 118  */
 119 void*
 120 dbus_realloc (void  *memory,
 121               size_t bytes)
 122 {
 123   if (bytes == 0) /* guarantee this is safe */
 124     {
 125       dbus_free (memory);
 126       return NULL;
 127     }
 128   else
 129     {
 130       return realloc (memory, bytes);
 131     }
 132 }
 133
 134 /**
 135  * Frees a block of memory previously allocated by dbus_malloc() or
 136  * dbus_malloc0(). If passed #NULL, does nothing.
 137  *
 138  * @param memory block to be freed
 139  */
 140 void
 141 dbus_free (void  *memory)
 142 {
 143   if (memory) /* we guarantee it's safe to free (NULL) */
 144     free (memory);
 145 }
 146
 147 /** @} */