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