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 Memory 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  * Allocates the given number of bytes, as with standard
  67  * malloc(). Guaranteed to return NULL if bytes is zero
  68  * on all platforms. Returns NULL if the allocation fails.
  69  * The memory must be released with dbus_free().
  70  *
  71  * @param bytes number of bytes to allocate
  72  * @return allocated memory, or NULL if the allocation fails.
  73  */
  74 void*
  75 dbus_malloc (size_t bytes)
  76 {
  77   if (bytes == 0) /* some system mallocs handle this, some don't */
  78     return NULL;
  79   else
  80     return malloc (bytes);
  81 }
  82
  83 /**
  84  * Allocates the given number of bytes, as with standard malloc(), but
  85  * all bytes are initialized to zero as with calloc(). Guaranteed to
  86  * return NULL if bytes is zero on all platforms. Returns NULL if the
  87  * allocation fails.  The memory must be released with dbus_free().
  88  *
  89  * @param bytes number of bytes to allocate
  90  * @return allocated memory, or NULL if the allocation fails.
  91  */
  92 void*
  93 dbus_malloc0 (size_t bytes)
  94 {
  95   if (bytes == 0)
  96     return NULL;
  97   else
  98     return calloc (bytes, 1);
  99 }
 100
 101 /**
 102  * Resizes a block of memory previously allocated by dbus_malloc() or
 103  * dbus_malloc0(). Guaranteed to free the memory and return NULL if bytes
 104  * is zero on all platforms. Returns NULL if the resize fails.
 105  * If the resize fails, the memory is not freed.
 106  *
 107  * @param memory block to be resized
 108  * @param bytes new size of the memory block
 109  * @return allocated memory, or NULL if the resize fails.
 110  */
 111 void*
 112 dbus_realloc (void  *memory,
 113               size_t bytes)
 114 {
 115   if (bytes == 0) /* guarantee this is safe */
 116     {
 117       dbus_free (memory);
 118       return NULL;
 119     }
 120   else
 121     {
 122       return realloc (memory, bytes);
 123     }
 124 }
 125
 126 /**
 127  * Frees a block of memory previously allocated by dbus_malloc() or
 128  * dbus_malloc0().
 129  *
 130  * @param memory block to be freed
 131  */
 132 void
 133 dbus_free (void  *memory)
 134 {
 135   if (memory) /* we guarantee it's safe to free (NULL) */
 136     free (memory);
 137 }
 138
 139 /** @} */