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 | { |
378 | if (G_UNLIKELY (nth_bit < -1)) |
379 | nth_bit = -1; |
380 | while (nth_bit < ((GLIB_SIZEOF_LONG * 8) - 1)) |
381 | { |
382 | nth_bit++; |
383 | if (mask & (1UL << nth_bit)) |
384 | return nth_bit; |
385 | } |
386 | return -1; |
387 | } |
388 | |
389 | static inline gint |
390 | g_bit_nth_msf_impl (gulong mask, |
391 | gint nth_bit) |
392 | { |
393 | if (nth_bit < 0 || G_UNLIKELY (nth_bit > GLIB_SIZEOF_LONG * 8)) |
394 | nth_bit = GLIB_SIZEOF_LONG * 8; |
395 | while (nth_bit > 0) |
396 | { |
397 | nth_bit--; |
398 | if (mask & (1UL << nth_bit)) |
399 | return nth_bit; |
400 | } |
401 | return -1; |
402 | } |
403 | |
404 | static inline guint |
405 | g_bit_storage_impl (gulong number) |
406 | { |
407 | #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__) |
408 | return G_LIKELY (number) ? |
409 | ((GLIB_SIZEOF_LONG * 8U - 1) ^ (guint) __builtin_clzl(number)) + 1 : 1; |
410 | #else |
411 | guint n_bits = 0; |
412 | |
413 | do |
414 | { |
415 | n_bits++; |
416 | number >>= 1; |
417 | } |
418 | while (number); |
419 | return n_bits; |
420 | #endif |
421 | } |
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__ */ |
480 | |