src/libcaptive/include/captive/macros.h

   1 /* $Id$
   2  * Include file with general macros and typedefs used through Captive project
   3  * Copyright (C) 2002 Jan Kratochvil <project-captive@jankratochvil.net>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; exactly version 2 of June 1991 is required
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19
  20 #ifndef _CAPTIVE_MACROS_H
  21 #define _CAPTIVE_MACROS_H 1
  22
  23
  24 #include <glib/gmacros.h>
  25 #include <glib/gmem.h>
  26 #include <stdarg.h>
  27 #include <string.h>     /* for memset() */
  28
  29
  30 G_BEGIN_DECLS
  31
  32 /**
  33  * CAPTIVE_FAKEUSE:
  34  *
  35  * Prevent 'might be used uninitialized' warning.
  36  * Macro will fakes the use of the variable as sometimes GCC can't code flow
  37  * analyse #C correctly.
  38  *
  39  * <informalexample>
  40  * <programlisting>
  41  * g_some_type some_variable CAPTIVE_FAKEUSE;
  42  * </programlisting>
  43  * </informalexample>
  44  */
  45 #define CAPTIVE_FAKEUSE =0
  46
  47
  48 /**
  49  * captive_newn:
  50  * @objp: Variable with the pointer to the objects wished to be allocated.
  51  * Original value is discarded.
  52  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  53  *
  54  * Macto to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  55  * Allocated memory may contain garbage.
  56  *
  57  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  58  */
  59 #define captive_newn(objp,n) ((objp)=g_new(typeof(*(objp)),(n)))
  60
  61
  62 /**
  63  * captive_new0n:
  64  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
  65  * Original value is discarded.
  66  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  67  *
  68  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  69  * Allocated memory is precleared.
  70  *
  71  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
  72  */
  73 #define captive_new0n(objp,n) ((objp)=g_new0(typeof(*(objp)),(n)))
  74
  75
  76 /**
  77  * captive_renewn:
  78  * @objp: Variable with the pointer to the objects wished to be reallocated.
  79  * Value %NULL is permitted (g_malloc() effect).
  80  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  81  *
  82  * Macro to reallocate the original memory stored in @objp
  83  * to the size @n objects of type *@objp and to assign the resulting pointer to @objp.
  84  * New allocated space may contain garbage. Both @objp and @n can be nonexclusively
  85  * passed as zero.
  86  *
  87  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  88  */
  89 #define captive_renewn(objp,n) ((objp)=g_renew(typeof(*(objp)),(objp),(n)))
  90
  91
  92 /**
  93  * captive_new:
  94  * @objp: Variable with the pointer to the object wished to be allocated.
  95  * Original value is discarded.
  96  *
  97  * Macto to allocate one object of type *@objp and to assign the resulting pointer to @objp.
  98  * Allocated memory may contain garbage. Equivalent to captive_newn(objp,1) call.
  99  *
 100  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 101  */
 102 #define captive_new(objp) (captive_newn((objp),1))
 103
 104
 105 /**
 106  * captive_new0:
 107  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 108  * Original value is discarded.
 109  *
 110  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 111  * Allocated memory is precleared. Equivalent to captive_new0n(objp,1) call.
 112  *
 113  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 114  */
 115 #define captive_new0(objp) (captive_new0n((objp),1))
 116
 117
 118 /**
 119  * captive_va_arg:
 120  * @objp: Variable to be filled from the next argument of @ap.
 121  * @ap: Initialized #va_list type.
 122  *
 123  * Automatically determines the size of @objp.
 124  * Equivalent to objp=va_arg(ap,typeof(objp)) call.
 125  *
 126  * @Returns: Initialized @objp value.
 127  */
 128 #define captive_va_arg(objp,ap) ((objp)=va_arg((ap),typeof(objp)))
 129
 130
 131 /**
 132  * CAPTIVE_MEMZERO:
 133  * @objp: Pointer to the variable to be cleared.
 134  *
 135  * Clears the sizeof(*@objp) bytes of the given pointer with memset().
 136  * Pass _pointer_ to the object to be cleared.
 137  */
 138 #define CAPTIVE_MEMZERO(objp) (memset((objp),0,sizeof(*(objp))))
 139
 140 G_END_DECLS
 141
 142
 143 #endif /* _CAPTIVE_MACROS_H */