Cache getenv("G_BROKEN_FILENAMES") in have_broken_filenames() and use
[platform/upstream/glib.git] / glib / gutils.h
1 /* GLIB - Library of useful routines for C programming
2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library 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 GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19
20 /*
21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
22  * file for a list of people on the GLib Team.  See the ChangeLog
23  * files for a list of changes.  These files are distributed with
24  * GLib at ftp://ftp.gtk.org/pub/gtk/. 
25  */
26
27 #ifndef __G_UTILS_H__
28 #define __G_UTILS_H__
29
30 #include <glib/gtypes.h>
31 #include <stdarg.h>
32
33 G_BEGIN_DECLS
34
35 #ifdef G_OS_WIN32
36
37 /* On native Win32, directory separator is the backslash, and search path
38  * separator is the semicolon.
39  */
40 #define G_DIR_SEPARATOR '\\'
41 #define G_DIR_SEPARATOR_S "\\"
42 #define G_SEARCHPATH_SEPARATOR ';'
43 #define G_SEARCHPATH_SEPARATOR_S ";"
44
45 #else  /* !G_OS_WIN32 */
46
47 /* Unix */
48
49 #define G_DIR_SEPARATOR '/'
50 #define G_DIR_SEPARATOR_S "/"
51 #define G_SEARCHPATH_SEPARATOR ':'
52 #define G_SEARCHPATH_SEPARATOR_S ":"
53
54 #endif /* !G_OS_WIN32 */
55
56 /* Define G_VA_COPY() to do the right thing for copying va_list variables.
57  * glibconfig.h may have already defined G_VA_COPY as va_copy or __va_copy.
58  */
59 #if !defined (G_VA_COPY)
60 #  if defined (__GNUC__) && defined (__PPC__) && (defined (_CALL_SYSV) || defined (_WIN32))
61 #    define G_VA_COPY(ap1, ap2)   (*(ap1) = *(ap2))
62 #  elif defined (G_VA_COPY_AS_ARRAY)
63 #    define G_VA_COPY(ap1, ap2)   g_memmove ((ap1), (ap2), sizeof (va_list))
64 #  else /* va_list is a pointer */
65 #    define G_VA_COPY(ap1, ap2)   ((ap1) = (ap2))
66 #  endif /* va_list is a pointer */
67 #endif /* !G_VA_COPY */
68
69 /* inlining hassle. for compilers that don't allow the `inline' keyword,
70  * mostly because of strict ANSI C compliance or dumbness, we try to fall
71  * back to either `__inline__' or `__inline'.
72  * we define G_CAN_INLINE, if the compiler seems to be actually
73  * *capable* to do function inlining, in which case inline function bodys
74  * do make sense. we also define G_INLINE_FUNC to properly export the
75  * function prototypes if no inlining can be performed.
76  * inline function bodies have to be special cased with G_CAN_INLINE and a
77  * .c file specific macro to allow one compiled instance with extern linkage
78  * of the functions by defining G_IMPLEMENT_INLINES and the .c file macro.
79  */
80 #ifdef G_IMPLEMENT_INLINES
81 #  define G_INLINE_FUNC extern
82 #  undef  G_CAN_INLINE
83 #endif
84 #ifndef G_INLINE_FUNC
85 #  define G_CAN_INLINE 1
86 #endif
87 #if defined (G_HAVE_INLINE) && defined (__GNUC__) && defined (__STRICT_ANSI__)
88 #  undef inline
89 #  define inline __inline__
90 #elif !defined (G_HAVE_INLINE)
91 #  undef inline
92 #  if defined (G_HAVE___INLINE__)
93 #    define inline __inline__
94 #  elif defined (G_HAVE___INLINE)
95 #    define inline __inline
96 #  else /* !inline && !__inline__ && !__inline */
97 #    define inline  /* don't inline, then */
98 #    ifndef G_INLINE_FUNC
99 #      undef G_CAN_INLINE
100 #    endif
101 #  endif
102 #endif
103 #ifndef G_INLINE_FUNC
104 #  if defined (__GNUC__) && (__OPTIMIZE__)
105 #    define G_INLINE_FUNC extern inline
106 #  elif defined (G_CAN_INLINE) && !defined (__GNUC__)
107 #    define G_INLINE_FUNC static inline
108 #  else /* can't inline */
109 #    define G_INLINE_FUNC extern
110 #    undef G_CAN_INLINE
111 #  endif
112 #endif /* !G_INLINE_FUNC */
113
114 /* Retrive static string info
115  */
116 G_CONST_RETURN gchar* g_get_user_name      (void);
117 G_CONST_RETURN gchar* g_get_real_name      (void);
118 G_CONST_RETURN gchar* g_get_home_dir       (void);
119 G_CONST_RETURN gchar* g_get_tmp_dir        (void);
120 gchar*                g_get_prgname        (void);
121 void                  g_set_prgname        (const gchar *prgname);
122
123
124 typedef struct _GDebugKey       GDebugKey;
125 struct _GDebugKey
126 {
127   gchar *key;
128   guint  value;
129 };
130
131 /* Miscellaneous utility functions
132  */
133 guint                 g_parse_debug_string (const gchar     *string,
134                                             const GDebugKey *keys,
135                                             guint            nkeys);
136
137 gint                  g_snprintf           (gchar       *string,
138                                             gulong       n,
139                                             gchar const *format,
140                                             ...) G_GNUC_PRINTF (3, 4);
141 gint                  g_vsnprintf          (gchar       *string,
142                                             gulong       n,
143                                             gchar const *format,
144                                             va_list      args);
145
146 /* Check if a file name is an absolute path */
147 gboolean              g_path_is_absolute   (const gchar *file_name);
148
149 /* In case of absolute paths, skip the root part */
150 G_CONST_RETURN gchar* g_path_skip_root     (const gchar *file_name);
151
152 #ifndef G_DISABLE_DEPRECATED
153
154 /* These two functions are deprecated and will be removed in the next
155  * major release of GLib. Use g_path_get_dirname/g_path_get_basename
156  * instead. Whatch out! The string returned by g_path_get_basename
157  * must be g_freed, while the string returned by g_basename must not.*/
158 G_CONST_RETURN gchar* g_basename           (const gchar *file_name);
159 #define g_dirname g_path_get_dirname
160
161 #endif /* G_DISABLE_DEPRECATED */
162
163 /* The returned strings are newly allocated with g_malloc() */
164 gchar*                g_get_current_dir    (void);
165 gchar*                g_path_get_basename  (const gchar *file_name);
166 gchar*                g_path_get_dirname   (const gchar *file_name);
167
168
169 /* Set the pointer at the specified location to NULL */
170 void                  g_nullify_pointer    (gpointer    *nullify_location);
171
172 /* Get the codeset for the current locale */
173 /* gchar * g_get_codeset    (void); */
174
175 /* return the environment string for the variable. The returned memory
176  * must not be freed. */
177 G_CONST_RETURN gchar* g_getenv             (const gchar *variable);
178
179
180 /* we try to provide a usefull equivalent for ATEXIT if it is
181  * not defined, but use is actually abandoned. people should
182  * use g_atexit() instead.
183  */
184 typedef void            (*GVoidFunc)            (void);
185 #ifndef ATEXIT
186 # define ATEXIT(proc)   g_ATEXIT(proc)
187 #else
188 # define G_NATIVE_ATEXIT
189 #endif /* ATEXIT */
190 /* we use a GLib function as a replacement for ATEXIT, so
191  * the programmer is not required to check the return value
192  * (if there is any in the implementation) and doesn't encounter
193  * missing include files.
194  */
195 void    g_atexit                (GVoidFunc    func);
196
197 /* Look for an executable in PATH, following execvp() rules */
198 gchar*  g_find_program_in_path  (const gchar *program);
199
200 /* Bit tests
201  */
202 G_INLINE_FUNC gint      g_bit_nth_lsf (gulong  mask,
203                                        gint    nth_bit);
204 G_INLINE_FUNC gint      g_bit_nth_msf (gulong  mask,
205                                        gint    nth_bit);
206 G_INLINE_FUNC guint     g_bit_storage (gulong  number);
207
208 /* Trash Stacks
209  * elements need to be >= sizeof (gpointer)
210  */
211 typedef struct _GTrashStack     GTrashStack;
212 struct _GTrashStack
213 {
214   GTrashStack *next;
215 };
216
217 G_INLINE_FUNC void      g_trash_stack_push      (GTrashStack **stack_p,
218                                                  gpointer      data_p);
219 G_INLINE_FUNC gpointer  g_trash_stack_pop       (GTrashStack **stack_p);
220 G_INLINE_FUNC gpointer  g_trash_stack_peek      (GTrashStack **stack_p);
221 G_INLINE_FUNC guint     g_trash_stack_height    (GTrashStack **stack_p);
222
223 /* inline function implementations
224  */
225 #if defined (G_CAN_INLINE) || defined (__G_UTILS_C__)
226 G_INLINE_FUNC gint
227 g_bit_nth_lsf (gulong mask,
228                gint   nth_bit)
229 {
230   do
231     {
232       nth_bit++;
233       if (mask & (1 << (gulong) nth_bit))
234         return nth_bit;
235     }
236   while (nth_bit < 32);
237   return -1;
238 }
239 G_INLINE_FUNC gint
240 g_bit_nth_msf (gulong mask,
241                gint   nth_bit)
242 {
243   if (nth_bit < 0)
244     nth_bit = GLIB_SIZEOF_LONG * 8;
245   do
246     {
247       nth_bit--;
248       if (mask & (1 << (gulong) nth_bit))
249         return nth_bit;
250     }
251   while (nth_bit > 0);
252   return -1;
253 }
254 G_INLINE_FUNC guint
255 g_bit_storage (gulong number)
256 {
257   register guint n_bits = 0;
258   
259   do
260     {
261       n_bits++;
262       number >>= 1;
263     }
264   while (number);
265   return n_bits;
266 }
267 G_INLINE_FUNC void
268 g_trash_stack_push (GTrashStack **stack_p,
269                     gpointer      data_p)
270 {
271   GTrashStack *data = (GTrashStack *) data_p;
272
273   data->next = *stack_p;
274   *stack_p = data;
275 }
276 G_INLINE_FUNC gpointer
277 g_trash_stack_pop (GTrashStack **stack_p)
278 {
279   GTrashStack *data;
280
281   data = *stack_p;
282   if (data)
283     {
284       *stack_p = data->next;
285       /* NULLify private pointer here, most platforms store NULL as
286        * subsequent 0 bytes
287        */
288       data->next = NULL;
289     }
290
291   return data;
292 }
293 G_INLINE_FUNC gpointer
294 g_trash_stack_peek (GTrashStack **stack_p)
295 {
296   GTrashStack *data;
297
298   data = *stack_p;
299
300   return data;
301 }
302 G_INLINE_FUNC guint
303 g_trash_stack_height (GTrashStack **stack_p)
304 {
305   GTrashStack *data;
306   guint i = 0;
307
308   for (data = *stack_p; data; data = data->next)
309     i++;
310
311   return i;
312 }
313 #endif  /* G_CAN_INLINE || __G_UTILS_C__ */
314
315 /* Glib version.
316  * we prefix variable declarations so they can
317  * properly get exported in windows dlls.
318  */
319 GLIB_VAR const guint glib_major_version;
320 GLIB_VAR const guint glib_minor_version;
321 GLIB_VAR const guint glib_micro_version;
322 GLIB_VAR const guint glib_interface_age;
323 GLIB_VAR const guint glib_binary_age;
324
325 #define GLIB_CHECK_VERSION(major,minor,micro)    \
326     (GLIB_MAJOR_VERSION > (major) || \
327      (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION > (minor)) || \
328      (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION == (minor) && \
329       GLIB_MICRO_VERSION >= (micro)))
330
331 G_END_DECLS
332
333 /*
334  * On Windows, this macro defines a DllMain function that stores the
335  * actual DLL name that the code being compiled will be included in.
336  * STATIC should be empty or 'static'. DLL_NAME is the name of the
337  * (pointer to the) char array where the DLL name will be stored. If
338  * this is used, you must also include <windows.h>. If you need a more complex
339  * DLL entry point function, you cannot use this.
340  *
341  * On non-Windows platforms, expands to nothing.
342  */
343
344 #ifndef G_PLATFORM_WIN32
345 # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)
346 #else
347 # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)                    \
348 static char *dll_name;                                                     \
349                                                                            \
350 BOOL WINAPI                                                                \
351 DllMain (HINSTANCE hinstDLL,                                               \
352          DWORD     fdwReason,                                              \
353          LPVOID    lpvReserved)                                            \
354 {                                                                          \
355   char bfr[1000];                                                          \
356   switch (fdwReason)                                                       \
357     {                                                                      \
358     case DLL_PROCESS_ATTACH:                                               \
359       GetModuleFileName ((HMODULE) hinstDLL, bfr, sizeof (bfr));           \
360       dll_name = g_path_get_basename (bfr);                                \
361       break;                                                               \
362     }                                                                      \
363                                                                            \
364   return TRUE;                                                             \
365 }
366 #endif /* G_PLATFORM_WIN32 */
367
368 #endif /* __G_UTILS_H__ */