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.1 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, see <http://www.gnu.org/licenses/>. |
16 | */ |
17 | |
18 | /* |
19 | * Modified by the GLib Team and others 1997-2000. See the AUTHORS |
20 | * file for a list of people on the GLib Team. See the ChangeLog |
21 | * files for a list of changes. These files are distributed with |
22 | * GLib at ftp://ftp.gtk.org/pub/gtk/. |
23 | */ |
24 | |
25 | #ifndef __G_UTILS_H__ |
26 | #define __G_UTILS_H__ |
27 | |
28 | #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION) |
29 | #error "Only <glib.h> can be included directly." |
30 | #endif |
31 | |
32 | #include <glib/gtypes.h> |
33 | #include <stdarg.h> |
34 | |
35 | G_BEGIN_DECLS |
36 | |
37 | /* Define G_VA_COPY() to do the right thing for copying va_list variables. |
38 | * glibconfig.h may have already defined G_VA_COPY as va_copy or __va_copy. |
39 | */ |
40 | #if !defined (G_VA_COPY) |
41 | # if defined (__GNUC__) && defined (__PPC__) && (defined (_CALL_SYSV) || defined (_WIN32)) |
42 | # define G_VA_COPY(ap1, ap2) (*(ap1) = *(ap2)) |
43 | # elif defined (G_VA_COPY_AS_ARRAY) |
44 | # define G_VA_COPY(ap1, ap2) memmove ((ap1), (ap2), sizeof (va_list)) |
45 | # else /* va_list is a pointer */ |
46 | # define G_VA_COPY(ap1, ap2) ((ap1) = (ap2)) |
47 | # endif /* va_list is a pointer */ |
48 | #endif /* !G_VA_COPY */ |
49 | |
50 | GLIB_AVAILABLE_IN_ALL |
51 | const gchar * g_get_user_name (void); |
52 | GLIB_AVAILABLE_IN_ALL |
53 | const gchar * g_get_real_name (void); |
54 | GLIB_AVAILABLE_IN_ALL |
55 | const gchar * g_get_home_dir (void); |
56 | GLIB_AVAILABLE_IN_ALL |
57 | const gchar * g_get_tmp_dir (void); |
58 | GLIB_AVAILABLE_IN_ALL |
59 | const gchar * g_get_host_name (void); |
60 | GLIB_AVAILABLE_IN_ALL |
61 | const gchar * g_get_prgname (void); |
62 | GLIB_AVAILABLE_IN_ALL |
63 | void g_set_prgname (const gchar *prgname); |
64 | GLIB_AVAILABLE_IN_ALL |
65 | const gchar * g_get_application_name (void); |
66 | GLIB_AVAILABLE_IN_ALL |
67 | void g_set_application_name (const gchar *application_name); |
68 | GLIB_AVAILABLE_IN_2_64 |
69 | gchar * g_get_os_info (const gchar *key_name); |
70 | |
71 | /** |
72 | * G_OS_INFO_KEY_NAME: |
73 | * |
74 | * A key to get the name of the operating system excluding version information suitable for presentation to the user, e.g. "YoYoOS" |
75 | * |
76 | * Since: 2.64 |
77 | */ |
78 | #define G_OS_INFO_KEY_NAME \ |
79 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
80 | "NAME" |
81 | |
82 | /** |
83 | * G_OS_INFO_KEY_PRETTY_NAME: |
84 | * |
85 | * A key to get the name of the operating system in a format suitable for presentation to the user, e.g. "YoYoOS Foo" |
86 | * |
87 | * Since: 2.64 |
88 | */ |
89 | #define G_OS_INFO_KEY_PRETTY_NAME \ |
90 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
91 | "PRETTY_NAME" |
92 | |
93 | /** |
94 | * G_OS_INFO_KEY_VERSION: |
95 | * |
96 | * A key to get the operating system version suitable for presentation to the user, e.g. "42 (Foo)" |
97 | * |
98 | * Since: 2.64 |
99 | */ |
100 | #define G_OS_INFO_KEY_VERSION \ |
101 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
102 | "VERSION" |
103 | |
104 | /** |
105 | * G_OS_INFO_KEY_VERSION_CODENAME: |
106 | * |
107 | * A key to get a codename identifying the operating system release suitable for processing by scripts or usage in generated filenames, e.g. "foo" |
108 | * |
109 | * Since: 2.64 |
110 | */ |
111 | #define G_OS_INFO_KEY_VERSION_CODENAME \ |
112 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
113 | "VERSION_CODENAME" |
114 | |
115 | /** |
116 | * G_OS_INFO_KEY_VERSION_ID: |
117 | * |
118 | * A key to get the version of the operating system suitable for processing by scripts or usage in generated filenames, e.g. "42" |
119 | * |
120 | * Since: 2.64 |
121 | */ |
122 | #define G_OS_INFO_KEY_VERSION_ID \ |
123 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
124 | "VERSION_ID" |
125 | |
126 | /** |
127 | * G_OS_INFO_KEY_ID: |
128 | * |
129 | * A key to get an ID identifying the operating system suitable for processing by scripts or usage in generated filenames, e.g. "yoyoos" |
130 | * |
131 | * Since: 2.64 |
132 | */ |
133 | #define G_OS_INFO_KEY_ID \ |
134 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
135 | "ID" |
136 | |
137 | /** |
138 | * G_OS_INFO_KEY_HOME_URL: |
139 | * |
140 | * A key to get the homepage for the operating system, e.g. "https://www.yoyo-os.com/" |
141 | * |
142 | * Since: 2.64 |
143 | */ |
144 | #define G_OS_INFO_KEY_HOME_URL \ |
145 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
146 | "HOME_URL" |
147 | |
148 | /** |
149 | * G_OS_INFO_KEY_DOCUMENTATION_URL: |
150 | * |
151 | * A key to get the documentation page for the operating system, e.g. "https://docs.yoyo-os.com/" |
152 | * |
153 | * Since: 2.64 |
154 | */ |
155 | #define G_OS_INFO_KEY_DOCUMENTATION_URL \ |
156 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
157 | "DOCUMENTATION_URL" |
158 | |
159 | /** |
160 | * G_OS_INFO_KEY_SUPPORT_URL: |
161 | * |
162 | * A key to get the support page for the operating system, e.g. "https://support.yoyo-os.com/" |
163 | * |
164 | * Since: 2.64 |
165 | */ |
166 | #define G_OS_INFO_KEY_SUPPORT_URL \ |
167 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
168 | "SUPPORT_URL" |
169 | |
170 | /** |
171 | * G_OS_INFO_KEY_BUG_REPORT_URL: |
172 | * |
173 | * A key to get the bug reporting page for the operating system, e.g. "https://bugs.yoyo-os.com/" |
174 | * |
175 | * Since: 2.64 |
176 | */ |
177 | #define G_OS_INFO_KEY_BUG_REPORT_URL \ |
178 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
179 | "BUG_REPORT_URL" |
180 | |
181 | /** |
182 | * G_OS_INFO_KEY_PRIVACY_POLICY_URL: |
183 | * |
184 | * A key to get the privacy policy for the operating system, e.g. "https://privacy.yoyo-os.com/" |
185 | * |
186 | * Since: 2.64 |
187 | */ |
188 | #define G_OS_INFO_KEY_PRIVACY_POLICY_URL \ |
189 | GLIB_AVAILABLE_MACRO_IN_2_64 \ |
190 | "PRIVACY_POLICY_URL" |
191 | |
192 | GLIB_AVAILABLE_IN_ALL |
193 | void g_reload_user_special_dirs_cache (void); |
194 | GLIB_AVAILABLE_IN_ALL |
195 | const gchar * g_get_user_data_dir (void); |
196 | GLIB_AVAILABLE_IN_ALL |
197 | const gchar * g_get_user_config_dir (void); |
198 | GLIB_AVAILABLE_IN_ALL |
199 | const gchar * g_get_user_cache_dir (void); |
200 | GLIB_AVAILABLE_IN_ALL |
201 | const gchar * const * g_get_system_data_dirs (void); |
202 | |
203 | #ifdef G_OS_WIN32 |
204 | /* This function is not part of the public GLib API */ |
205 | GLIB_AVAILABLE_IN_ALL |
206 | const gchar * const * g_win32_get_system_data_dirs_for_module (void (*address_of_function)(void)); |
207 | #endif |
208 | |
209 | #if defined (G_OS_WIN32) && defined (G_CAN_INLINE) |
210 | /* This function is not part of the public GLib API either. Just call |
211 | * g_get_system_data_dirs() in your code, never mind that that is |
212 | * actually a macro and you will in fact call this inline function. |
213 | */ |
214 | static inline const gchar * const * |
215 | _g_win32_get_system_data_dirs (void) |
216 | { |
217 | return g_win32_get_system_data_dirs_for_module ((void (*)(void)) &_g_win32_get_system_data_dirs); |
218 | } |
219 | #define g_get_system_data_dirs _g_win32_get_system_data_dirs |
220 | #endif |
221 | |
222 | GLIB_AVAILABLE_IN_ALL |
223 | const gchar * const * g_get_system_config_dirs (void); |
224 | |
225 | GLIB_AVAILABLE_IN_ALL |
226 | const gchar * g_get_user_runtime_dir (void); |
227 | |
228 | /** |
229 | * GUserDirectory: |
230 | * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory |
231 | * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory |
232 | * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory |
233 | * @G_USER_DIRECTORY_MUSIC: the user's Music directory |
234 | * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory |
235 | * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory |
236 | * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory |
237 | * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory |
238 | * @G_USER_N_DIRECTORIES: the number of enum values |
239 | * |
240 | * These are logical ids for special directories which are defined |
241 | * depending on the platform used. You should use g_get_user_special_dir() |
242 | * to retrieve the full path associated to the logical id. |
243 | * |
244 | * The #GUserDirectory enumeration can be extended at later date. Not |
245 | * every platform has a directory for every logical id in this |
246 | * enumeration. |
247 | * |
248 | * Since: 2.14 |
249 | */ |
250 | typedef enum { |
251 | G_USER_DIRECTORY_DESKTOP, |
252 | G_USER_DIRECTORY_DOCUMENTS, |
253 | G_USER_DIRECTORY_DOWNLOAD, |
254 | G_USER_DIRECTORY_MUSIC, |
255 | G_USER_DIRECTORY_PICTURES, |
256 | G_USER_DIRECTORY_PUBLIC_SHARE, |
257 | G_USER_DIRECTORY_TEMPLATES, |
258 | G_USER_DIRECTORY_VIDEOS, |
259 | |
260 | G_USER_N_DIRECTORIES |
261 | } GUserDirectory; |
262 | |
263 | GLIB_AVAILABLE_IN_ALL |
264 | const gchar * g_get_user_special_dir (GUserDirectory directory); |
265 | |
266 | /** |
267 | * GDebugKey: |
268 | * @key: the string |
269 | * @value: the flag |
270 | * |
271 | * Associates a string with a bit flag. |
272 | * Used in g_parse_debug_string(). |
273 | */ |
274 | typedef struct _GDebugKey GDebugKey; |
275 | struct _GDebugKey |
276 | { |
277 | const gchar *key; |
278 | guint value; |
279 | }; |
280 | |
281 | /* Miscellaneous utility functions |
282 | */ |
283 | GLIB_AVAILABLE_IN_ALL |
284 | guint g_parse_debug_string (const gchar *string, |
285 | const GDebugKey *keys, |
286 | guint nkeys); |
287 | |
288 | GLIB_AVAILABLE_IN_ALL |
289 | gint g_snprintf (gchar *string, |
290 | gulong n, |
291 | gchar const *format, |
292 | ...) G_GNUC_PRINTF (3, 4); |
293 | GLIB_AVAILABLE_IN_ALL |
294 | gint g_vsnprintf (gchar *string, |
295 | gulong n, |
296 | gchar const *format, |
297 | va_list args) |
298 | G_GNUC_PRINTF(3, 0); |
299 | |
300 | GLIB_AVAILABLE_IN_ALL |
301 | void g_nullify_pointer (gpointer *nullify_location); |
302 | |
303 | typedef enum |
304 | { |
305 | G_FORMAT_SIZE_DEFAULT = 0, |
306 | G_FORMAT_SIZE_LONG_FORMAT = 1 << 0, |
307 | G_FORMAT_SIZE_IEC_UNITS = 1 << 1, |
308 | G_FORMAT_SIZE_BITS = 1 << 2 |
309 | } GFormatSizeFlags; |
310 | |
311 | GLIB_AVAILABLE_IN_2_30 |
312 | gchar *g_format_size_full (guint64 size, |
313 | GFormatSizeFlags flags); |
314 | GLIB_AVAILABLE_IN_2_30 |
315 | gchar *g_format_size (guint64 size); |
316 | |
317 | GLIB_DEPRECATED_IN_2_30_FOR(g_format_size) |
318 | gchar *g_format_size_for_display (goffset size); |
319 | |
320 | #define g_ATEXIT(proc) (atexit (proc)) GLIB_DEPRECATED_MACRO_IN_2_32 |
321 | #define g_memmove(dest,src,len) \ |
322 | G_STMT_START { memmove ((dest), (src), (len)); } G_STMT_END GLIB_DEPRECATED_MACRO_IN_2_40_FOR(memmove) |
323 | |
324 | /** |
325 | * GVoidFunc: |
326 | * |
327 | * Declares a type of function which takes no arguments |
328 | * and has no return value. It is used to specify the type |
329 | * function passed to g_atexit(). |
330 | */ |
331 | typedef void (*GVoidFunc) (void) GLIB_DEPRECATED_TYPE_IN_2_32; |
332 | #define ATEXIT(proc) g_ATEXIT(proc) GLIB_DEPRECATED_MACRO_IN_2_32 |
333 | |
334 | G_GNUC_BEGIN_IGNORE_DEPRECATIONS |
335 | GLIB_DEPRECATED |
336 | void g_atexit (GVoidFunc func); |
337 | G_GNUC_END_IGNORE_DEPRECATIONS |
338 | |
339 | #ifdef G_OS_WIN32 |
340 | /* It's a bad idea to wrap atexit() on Windows. If the GLib DLL calls |
341 | * atexit(), the function will be called when the GLib DLL is detached |
342 | * from the program, which is not what the caller wants. The caller |
343 | * wants the function to be called when it *itself* exits (or is |
344 | * detached, in case the caller, too, is a DLL). |
345 | */ |
346 | #if (defined(__MINGW_H) && !defined(_STDLIB_H_)) || (defined(_MSC_VER) && !defined(_INC_STDLIB)) |
347 | int atexit (void (*)(void)); |
348 | #endif |
349 | #define g_atexit(func) atexit(func) GLIB_DEPRECATED_MACRO_IN_2_32 |
350 | #endif |
351 | |
352 | |
353 | /* Look for an executable in PATH, following execvp() rules */ |
354 | GLIB_AVAILABLE_IN_ALL |
355 | gchar* g_find_program_in_path (const gchar *program); |
356 | |
357 | /* Bit tests |
358 | * |
359 | * These are defined in a convoluted way because we want the compiler to |
360 | * be able to inline the code for performance reasons, but for |
361 | * historical reasons, we must continue to provide non-inline versions |
362 | * on our ABI. |
363 | * |
364 | * We define these as functions in gutils.c which are just implemented |
365 | * as calls to the _impl() versions in order to preserve the ABI. |
366 | */ |
367 | |
368 | #define g_bit_nth_lsf(mask, nth_bit) g_bit_nth_lsf_impl(mask, nth_bit) |
369 | #define g_bit_nth_msf(mask, nth_bit) g_bit_nth_msf_impl(mask, nth_bit) |
370 | #define g_bit_storage(number) g_bit_storage_impl(number) |
371 | |
372 | GLIB_AVAILABLE_IN_ALL |
373 | gint (g_bit_nth_lsf) (gulong mask, |
374 | gint nth_bit); |
375 | GLIB_AVAILABLE_IN_ALL |
376 | gint (g_bit_nth_msf) (gulong mask, |
377 | gint nth_bit); |
378 | GLIB_AVAILABLE_IN_ALL |
379 | guint (g_bit_storage) (gulong number); |
380 | |
381 | static inline gint |
382 | g_bit_nth_lsf_impl (gulong mask, |
383 | gint nth_bit) |
384 | { |
385 | if (G_UNLIKELY (nth_bit < -1)) |
386 | nth_bit = -1; |
387 | while (nth_bit < ((GLIB_SIZEOF_LONG * 8) - 1)) |
388 | { |
389 | nth_bit++; |
390 | if (mask & (1UL << nth_bit)) |
391 | return nth_bit; |
392 | } |
393 | return -1; |
394 | } |
395 | |
396 | static inline gint |
397 | g_bit_nth_msf_impl (gulong mask, |
398 | gint nth_bit) |
399 | { |
400 | if (nth_bit < 0 || G_UNLIKELY (nth_bit > GLIB_SIZEOF_LONG * 8)) |
401 | nth_bit = GLIB_SIZEOF_LONG * 8; |
402 | while (nth_bit > 0) |
403 | { |
404 | nth_bit--; |
405 | if (mask & (1UL << nth_bit)) |
406 | return nth_bit; |
407 | } |
408 | return -1; |
409 | } |
410 | |
411 | static inline guint |
412 | g_bit_storage_impl (gulong number) |
413 | { |
414 | #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__) |
415 | return G_LIKELY (number) ? |
416 | ((GLIB_SIZEOF_LONG * 8U - 1) ^ (guint) __builtin_clzl(number)) + 1 : 1; |
417 | #else |
418 | guint n_bits = 0; |
419 | |
420 | do |
421 | { |
422 | n_bits++; |
423 | number >>= 1; |
424 | } |
425 | while (number); |
426 | return n_bits; |
427 | #endif |
428 | } |
429 | |
430 | /* Crashes the program. */ |
431 | #if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_50 |
432 | #ifndef G_OS_WIN32 |
433 | # include <stdlib.h> |
434 | # define g_abort() abort () |
435 | #else |
436 | GLIB_AVAILABLE_IN_2_50 |
437 | G_NORETURN void g_abort (void) G_ANALYZER_NORETURN; |
438 | #endif |
439 | #endif |
440 | |
441 | /* |
442 | * This macro is deprecated. This DllMain() is too complex. It is |
443 | * recommended to write an explicit minimal DLlMain() that just saves |
444 | * the handle to the DLL and then use that handle instead, for |
445 | * instance passing it to |
446 | * g_win32_get_package_installation_directory_of_module(). |
447 | * |
448 | * On Windows, this macro defines a DllMain function that stores the |
449 | * actual DLL name that the code being compiled will be included in. |
450 | * STATIC should be empty or 'static'. DLL_NAME is the name of the |
451 | * (pointer to the) char array where the DLL name will be stored. If |
452 | * this is used, you must also include <windows.h>. If you need a more complex |
453 | * DLL entry point function, you cannot use this. |
454 | * |
455 | * On non-Windows platforms, expands to nothing. |
456 | */ |
457 | |
458 | #ifndef G_PLATFORM_WIN32 |
459 | # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name) GLIB_DEPRECATED_MACRO_IN_2_26 |
460 | #else |
461 | # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name) \ |
462 | static char *dll_name; \ |
463 | \ |
464 | BOOL WINAPI \ |
465 | DllMain (HINSTANCE hinstDLL, \ |
466 | DWORD fdwReason, \ |
467 | LPVOID lpvReserved) \ |
468 | { \ |
469 | wchar_t wcbfr[1000]; \ |
470 | char *tem; \ |
471 | switch (fdwReason) \ |
472 | { \ |
473 | case DLL_PROCESS_ATTACH: \ |
474 | GetModuleFileNameW ((HMODULE) hinstDLL, wcbfr, G_N_ELEMENTS (wcbfr)); \ |
475 | tem = g_utf16_to_utf8 (wcbfr, -1, NULL, NULL, NULL); \ |
476 | dll_name = g_path_get_basename (tem); \ |
477 | g_free (tem); \ |
478 | break; \ |
479 | } \ |
480 | \ |
481 | return TRUE; \ |
482 | } GLIB_DEPRECATED_MACRO_IN_2_26 |
483 | #endif /* G_PLATFORM_WIN32 */ |
484 | |
485 | G_END_DECLS |
486 | |
487 | #endif /* __G_UTILS_H__ */ |
488 | |