glib/gutils.h

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