Branch data Line data Source code
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 : 29 : _g_win32_get_system_data_dirs (void)
207 : : {
208 : 29 : 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 : : /**
252 : : * G_USER_DIRECTORY_PROJECTS:
253 : : *
254 : : * The user's Projects directory.
255 : : *
256 : : * Since: 2.90
257 : : */
258 : : G_USER_DIRECTORY_PROJECTS,
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 : : /**
304 : : * GFormatSizeFlags:
305 : : * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size()
306 : : * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part
307 : : * of the returned string. For example, "45.6 kB (45,612 bytes)".
308 : : * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style
309 : : * suffixes. IEC units should only be used for reporting things with
310 : : * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
311 : : * Network and storage sizes should be reported in the normal SI units.
312 : : * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than
313 : : * bytes, and return units in bits. For example, ‘Mbit’ rather than ‘MB’.
314 : : *
315 : : * Flags to modify the format of the string returned by g_format_size_full().
316 : : */
317 : : typedef enum
318 : : {
319 : : G_FORMAT_SIZE_DEFAULT = 0,
320 : : G_FORMAT_SIZE_LONG_FORMAT = 1 << 0,
321 : : G_FORMAT_SIZE_IEC_UNITS = 1 << 1,
322 : : G_FORMAT_SIZE_BITS = 1 << 2,
323 : : /**
324 : : * G_FORMAT_SIZE_ONLY_VALUE:
325 : : *
326 : : * Returns only the value, without a unit.
327 : : *
328 : : * This should not be used together with `G_FORMAT_SIZE_LONG_FORMAT` nor
329 : : * `G_FORMAT_SIZE_ONLY_UNIT`.
330 : : *
331 : : * Since: 2.74
332 : : */
333 : : G_FORMAT_SIZE_ONLY_VALUE GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 1 << 3,
334 : : /**
335 : : * G_FORMAT_SIZE_ONLY_UNIT:
336 : : *
337 : : * Returns only the unit, without a value.
338 : : *
339 : : * This should not be used together with `G_FORMAT_SIZE_LONG_FORMAT` nor
340 : : * `G_FORMAT_SIZE_ONLY_VALUE`.
341 : : *
342 : : * Since: 2.74
343 : : */
344 : : G_FORMAT_SIZE_ONLY_UNIT GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 1 << 4
345 : : } G_GNUC_FLAG_ENUM GFormatSizeFlags;
346 : :
347 : : GLIB_AVAILABLE_IN_2_30
348 : : gchar *g_format_size_full (guint64 size,
349 : : GFormatSizeFlags flags);
350 : : GLIB_AVAILABLE_IN_2_30
351 : : gchar *g_format_size (guint64 size);
352 : :
353 : : GLIB_DEPRECATED_IN_2_30_FOR(g_format_size)
354 : : gchar *g_format_size_for_display (goffset size);
355 : :
356 : : #define g_ATEXIT(proc) (atexit (proc)) GLIB_DEPRECATED_MACRO_IN_2_32
357 : : #define g_memmove(dest,src,len) \
358 : : G_STMT_START { memmove ((dest), (src), (len)); } G_STMT_END GLIB_DEPRECATED_MACRO_IN_2_40_FOR(memmove)
359 : :
360 : : /**
361 : : * GVoidFunc:
362 : : *
363 : : * Declares a type of function which takes no arguments
364 : : * and has no return value. It is used to specify the type
365 : : * function passed to g_atexit().
366 : : */
367 : : typedef void (*GVoidFunc) (void) GLIB_DEPRECATED_TYPE_IN_2_32;
368 : : #define ATEXIT(proc) g_ATEXIT(proc) GLIB_DEPRECATED_MACRO_IN_2_32
369 : :
370 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
371 : : GLIB_DEPRECATED
372 : : void g_atexit (GVoidFunc func);
373 : : G_GNUC_END_IGNORE_DEPRECATIONS
374 : :
375 : : #ifdef G_OS_WIN32
376 : : /* It's a bad idea to wrap atexit() on Windows. If the GLib DLL calls
377 : : * atexit(), the function will be called when the GLib DLL is detached
378 : : * from the program, which is not what the caller wants. The caller
379 : : * wants the function to be called when it *itself* exits (or is
380 : : * detached, in case the caller, too, is a DLL).
381 : : */
382 : : #if (defined(__MINGW_H) && !defined(_STDLIB_H_)) || (defined(_MSC_VER) && !defined(_INC_STDLIB))
383 : : int atexit (void (*)(void));
384 : : #endif
385 : : #define g_atexit(func) atexit(func) GLIB_DEPRECATED_MACRO_IN_2_32
386 : : #endif
387 : :
388 : :
389 : : /* Look for an executable in PATH, following execvp() rules */
390 : : GLIB_AVAILABLE_IN_ALL
391 : : gchar* g_find_program_in_path (const gchar *program);
392 : :
393 : : /* Bit tests
394 : : *
395 : : * These are defined in a convoluted way because we want the compiler to
396 : : * be able to inline the code for performance reasons, but for
397 : : * historical reasons, we must continue to provide non-inline versions
398 : : * on our ABI.
399 : : *
400 : : * We define these as functions in gutils.c which are just implemented
401 : : * as calls to the _impl() versions in order to preserve the ABI.
402 : : */
403 : :
404 : : #define g_bit_nth_lsf(mask, nth_bit) g_bit_nth_lsf_impl(mask, nth_bit)
405 : : #define g_bit_nth_msf(mask, nth_bit) g_bit_nth_msf_impl(mask, nth_bit)
406 : : #define g_bit_storage(number) g_bit_storage_impl(number)
407 : :
408 : : GLIB_AVAILABLE_IN_ALL
409 : : gint (g_bit_nth_lsf) (gulong mask,
410 : : gint nth_bit);
411 : : GLIB_AVAILABLE_IN_ALL
412 : : gint (g_bit_nth_msf) (gulong mask,
413 : : gint nth_bit);
414 : : GLIB_AVAILABLE_IN_ALL
415 : : guint (g_bit_storage) (gulong number);
416 : :
417 : : static inline gint
418 : 3890316 : g_bit_nth_lsf_impl (gulong mask,
419 : : gint nth_bit)
420 : : {
421 : 3890316 : if (G_UNLIKELY (nth_bit < -1))
422 : 144024 : nth_bit = -1;
423 : 36520692 : while (nth_bit < ((GLIB_SIZEOF_LONG * 8) - 1))
424 : : {
425 : 34850352 : nth_bit++;
426 : 34850352 : if (mask & (1UL << nth_bit))
427 : 2219976 : return nth_bit;
428 : : }
429 : 1670340 : return -1;
430 : 1368774 : }
431 : :
432 : : static inline gint
433 : 17846126 : g_bit_nth_msf_impl (gulong mask,
434 : : gint nth_bit)
435 : : {
436 : 17846126 : if (nth_bit < 0 || G_UNLIKELY (nth_bit > GLIB_SIZEOF_LONG * 8))
437 : 7338565 : nth_bit = GLIB_SIZEOF_LONG * 8;
438 : 388213063 : while (nth_bit > 0)
439 : : {
440 : 381089154 : nth_bit--;
441 : 381089154 : if (mask & (1UL << nth_bit))
442 : 10722217 : return nth_bit;
443 : : }
444 : 7123909 : return -1;
445 : 8158332 : }
446 : :
447 : : static inline guint
448 : 369330 : g_bit_storage_impl (gulong number)
449 : : {
450 : : #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__)
451 : : return G_LIKELY (number) ?
452 : : ((GLIB_SIZEOF_LONG * 8U - 1) ^ (guint) __builtin_clzl(number)) + 1 : 1;
453 : : #else
454 : 369330 : guint n_bits = 0;
455 : :
456 : 126790 : do
457 : : {
458 : 5310885 : n_bits++;
459 : 5310885 : number >>= 1;
460 : 1738938 : }
461 : 5310885 : while (number);
462 : 369330 : return n_bits;
463 : : #endif
464 : : }
465 : :
466 : : /* Crashes the program. */
467 : : #if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_50
468 : : #ifndef G_OS_WIN32
469 : : # include <stdlib.h>
470 : : # define g_abort() abort ()
471 : : #else
472 : : G_NORETURN GLIB_AVAILABLE_IN_2_50 void g_abort (void) G_ANALYZER_NORETURN;
473 : : #endif
474 : : #endif
475 : :
476 : : /*
477 : : * This macro is deprecated. This DllMain() is too complex. It is
478 : : * recommended to write an explicit minimal DLlMain() that just saves
479 : : * the handle to the DLL and then use that handle instead, for
480 : : * instance passing it to
481 : : * g_win32_get_package_installation_directory_of_module().
482 : : *
483 : : * On Windows, this macro defines a DllMain function that stores the
484 : : * actual DLL name that the code being compiled will be included in.
485 : : * STATIC should be empty or 'static'. DLL_NAME is the name of the
486 : : * (pointer to the) char array where the DLL name will be stored. If
487 : : * this is used, you must also include <windows.h>. If you need a more complex
488 : : * DLL entry point function, you cannot use this.
489 : : *
490 : : * On non-Windows platforms, expands to nothing.
491 : : */
492 : :
493 : : #ifndef G_PLATFORM_WIN32
494 : : # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name) GLIB_DEPRECATED_MACRO_IN_2_26
495 : : #else
496 : : # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name) \
497 : : static char *dll_name; \
498 : : \
499 : : BOOL WINAPI \
500 : : DllMain (HINSTANCE hinstDLL, \
501 : : DWORD fdwReason, \
502 : : LPVOID lpvReserved) \
503 : : { \
504 : : wchar_t wcbfr[1000]; \
505 : : char *tem; \
506 : : switch (fdwReason) \
507 : : { \
508 : : case DLL_PROCESS_ATTACH: \
509 : : GetModuleFileNameW ((HMODULE) hinstDLL, wcbfr, G_N_ELEMENTS (wcbfr)); \
510 : : tem = g_utf16_to_utf8 (wcbfr, -1, NULL, NULL, NULL); \
511 : : dll_name = g_path_get_basename (tem); \
512 : : g_free (tem); \
513 : : break; \
514 : : } \
515 : : \
516 : : return TRUE; \
517 : : } GLIB_DEPRECATED_MACRO_IN_2_26
518 : : #endif /* G_PLATFORM_WIN32 */
519 : :
520 : : G_END_DECLS
521 : :
522 : : #endif /* __G_UTILS_H__ */
|
