Coverage Report

Created: 2025-01-28 06:43

/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__ */