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