2002-11-23 Havoc Pennington <hp@pobox.com>
[platform/upstream/dbus.git] / dbus / dbus-internals.c
1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-internals.c  random utility stuff (internal to D-BUS implementation)
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 #include "dbus-internals.h"
24 #include <stdio.h>
25 #include <stdarg.h>
26
27 /**
28  * @defgroup DBusInternals D-BUS internal implementation details
29  * @brief Documentation useful when developing or debugging D-BUS itself.
30  * 
31  */
32
33 /**
34  * @defgroup DBusInternalsUtils Utilities
35  * @ingroup DBusInternals
36  * @brief Utility functions (_dbus_assert(), _dbus_warn(), etc.)
37  * @{
38  */
39
40 /**
41  * @def _dbus_assert
42  *
43  * Aborts with an error message if the condition is false.
44  * 
45  * @param condition condition which must be true.
46  */
47
48 /**
49  * @def _dbus_assert_not_reached
50  *
51  * Aborts with an error message if called.
52  * The given explanation will be printed.
53  * 
54  * @param explanation explanation of what happened if the code was reached.
55  */
56
57 /**
58  * @def _DBUS_N_ELEMENTS
59  *
60  * Computes the number of elements in a fixed-size array using
61  * sizeof().
62  *
63  * @param array the array to count elements in.
64  */
65
66 /**
67  * @def _DBUS_POINTER_TO_INT
68  *
69  * Safely casts a void* to an integer; should only be used on void*
70  * that actually contain integers, for example one created with
71  * _DBUS_INT_TO_POINTER.  Only guaranteed to preserve 32 bits.
72  * (i.e. it's used to store 32-bit ints in pointers, but
73  * can't be used to store 64-bit pointers in ints.)
74  *
75  * @param pointer pointer to extract an integer from.
76  */
77 /**
78  * @def _DBUS_INT_TO_POINTER
79  *
80  * Safely stuffs an integer into a pointer, to be extracted later with
81  * _DBUS_POINTER_TO_INT. Only guaranteed to preserve 32 bits.
82  *
83  * @param integer the integer to stuff into a pointer.
84  */
85
86 /**
87  * @def _DBUS_INT_MIN
88  *
89  * Minimum value of type "int"
90  */
91 /**
92  * @def _DBUS_INT_MAX
93  *
94  * Maximum value of type "int"
95  */
96
97 /**
98  * Prints a warning message to stderr.
99  *
100  * @param format printf-style format string.
101  */
102 void
103 _dbus_warn (const char *format,
104             ...)
105 {
106   /* FIXME not portable enough? */
107   va_list args;
108
109   va_start (args, format);
110   vfprintf (stderr, format, args);
111   va_end (args);
112 }
113
114 /**
115  * Duplicates a string. Result must be freed with
116  * dbus_free(). Returns #NULL if memory allocation fails.
117  * If the string to be duplicated is #NULL, returns #NULL.
118  * 
119  * @param str string to duplicate.
120  * @returns newly-allocated copy.
121  */
122 char*
123 _dbus_strdup (const char *str)
124 {
125   int len;
126   char *copy;
127   
128   if (str == NULL)
129     return NULL;
130   
131   len = strlen (str);
132
133   copy = dbus_malloc (len + 1);
134   if (copy == NULL)
135     return NULL;
136
137   memcpy (copy, str, len + 1);
138   
139   return copy;
140 }
141
142 /** @} */