glib-2.0/glib/gutils.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026
0027 #ifndef __G_UTILS_H__
0028 #define __G_UTILS_H__
0029
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033
0034 #include <glib/gtypes.h>
0035 #include <stdarg.h>
0036
0037 G_BEGIN_DECLS
0038
0039 GLIB_AVAILABLE_IN_ALL
0040 const gchar *         g_get_user_name        (void);
0041 GLIB_AVAILABLE_IN_ALL
0042 const gchar *         g_get_real_name        (void);
0043 GLIB_AVAILABLE_IN_ALL
0044 const gchar *         g_get_home_dir         (void);
0045 GLIB_AVAILABLE_IN_ALL
0046 const gchar *         g_get_tmp_dir          (void);
0047 GLIB_AVAILABLE_IN_ALL
0048 const gchar *         g_get_host_name        (void);
0049 GLIB_AVAILABLE_IN_ALL
0050 const gchar *         g_get_prgname          (void);
0051 GLIB_AVAILABLE_IN_ALL
0052 void                  g_set_prgname          (const gchar *prgname);
0053 GLIB_AVAILABLE_IN_ALL
0054 const gchar *         g_get_application_name (void);
0055 GLIB_AVAILABLE_IN_ALL
0056 void                  g_set_application_name (const gchar *application_name);
0057 GLIB_AVAILABLE_IN_2_64
0058 gchar *               g_get_os_info          (const gchar *key_name);
0059
0060 /**
0061  * G_OS_INFO_KEY_NAME:
0062  *
0063  * A key to get the name of the operating system excluding version information suitable for presentation to the user, e.g. "YoYoOS"
0064  *
0065  * Since: 2.64
0066  */
0067 #define G_OS_INFO_KEY_NAME \
0068     GLIB_AVAILABLE_MACRO_IN_2_64 \
0069     "NAME"
0070
0071 /**
0072  * G_OS_INFO_KEY_PRETTY_NAME:
0073  *
0074  * A key to get the name of the operating system in a format suitable for presentation to the user, e.g. "YoYoOS Foo"
0075  *
0076  * Since: 2.64
0077  */
0078 #define G_OS_INFO_KEY_PRETTY_NAME \
0079     GLIB_AVAILABLE_MACRO_IN_2_64 \
0080     "PRETTY_NAME"
0081
0082 /**
0083  * G_OS_INFO_KEY_VERSION:
0084  *
0085  * A key to get the operating system version suitable for presentation to the user, e.g. "42 (Foo)"
0086  *
0087  * Since: 2.64
0088  */
0089 #define G_OS_INFO_KEY_VERSION \
0090     GLIB_AVAILABLE_MACRO_IN_2_64 \
0091     "VERSION"
0092
0093 /**
0094  * G_OS_INFO_KEY_VERSION_CODENAME:
0095  *
0096  * A key to get a codename identifying the operating system release suitable for processing by scripts or usage in generated filenames, e.g. "foo"
0097  *
0098  * Since: 2.64
0099  */
0100 #define G_OS_INFO_KEY_VERSION_CODENAME \
0101     GLIB_AVAILABLE_MACRO_IN_2_64 \
0102     "VERSION_CODENAME"
0103
0104 /**
0105  * G_OS_INFO_KEY_VERSION_ID:
0106  *
0107  * A key to get the version of the operating system suitable for processing by scripts or usage in generated filenames, e.g. "42"
0108  *
0109  * Since: 2.64
0110  */
0111 #define G_OS_INFO_KEY_VERSION_ID \
0112     GLIB_AVAILABLE_MACRO_IN_2_64 \
0113     "VERSION_ID"
0114
0115 /**
0116  * G_OS_INFO_KEY_ID:
0117  *
0118  * A key to get an ID identifying the operating system suitable for processing by scripts or usage in generated filenames, e.g. "yoyoos"
0119  *
0120  * Since: 2.64
0121  */
0122 #define G_OS_INFO_KEY_ID \
0123     GLIB_AVAILABLE_MACRO_IN_2_64 \
0124     "ID"
0125
0126 /**
0127  * G_OS_INFO_KEY_HOME_URL:
0128  *
0129  * A key to get the homepage for the operating system, e.g. "https://www.yoyo-os.com/"
0130  *
0131  * Since: 2.64
0132  */
0133 #define G_OS_INFO_KEY_HOME_URL \
0134     GLIB_AVAILABLE_MACRO_IN_2_64 \
0135     "HOME_URL"
0136
0137 /**
0138  * G_OS_INFO_KEY_DOCUMENTATION_URL:
0139  *
0140  * A key to get the documentation page for the operating system, e.g. "https://docs.yoyo-os.com/"
0141  *
0142  * Since: 2.64
0143  */
0144 #define G_OS_INFO_KEY_DOCUMENTATION_URL \
0145     GLIB_AVAILABLE_MACRO_IN_2_64 \
0146     "DOCUMENTATION_URL"
0147
0148 /**
0149  * G_OS_INFO_KEY_SUPPORT_URL:
0150  *
0151  * A key to get the support page for the operating system, e.g. "https://support.yoyo-os.com/"
0152  *
0153  * Since: 2.64
0154  */
0155 #define G_OS_INFO_KEY_SUPPORT_URL \
0156     GLIB_AVAILABLE_MACRO_IN_2_64 \
0157     "SUPPORT_URL"
0158
0159 /**
0160  * G_OS_INFO_KEY_BUG_REPORT_URL:
0161  *
0162  * A key to get the bug reporting page for the operating system, e.g. "https://bugs.yoyo-os.com/"
0163  *
0164  * Since: 2.64
0165  */
0166 #define G_OS_INFO_KEY_BUG_REPORT_URL \
0167     GLIB_AVAILABLE_MACRO_IN_2_64 \
0168     "BUG_REPORT_URL"
0169
0170 /**
0171  * G_OS_INFO_KEY_PRIVACY_POLICY_URL:
0172  *
0173  * A key to get the privacy policy for the operating system, e.g. "https://privacy.yoyo-os.com/"
0174  *
0175  * Since: 2.64
0176  */
0177 #define G_OS_INFO_KEY_PRIVACY_POLICY_URL \
0178     GLIB_AVAILABLE_MACRO_IN_2_64 \
0179     "PRIVACY_POLICY_URL"
0180
0181 GLIB_AVAILABLE_IN_ALL
0182 void      g_reload_user_special_dirs_cache     (void);
0183 GLIB_AVAILABLE_IN_ALL
0184 const gchar *         g_get_user_data_dir      (void);
0185 GLIB_AVAILABLE_IN_ALL
0186 const gchar *         g_get_user_config_dir    (void);
0187 GLIB_AVAILABLE_IN_ALL
0188 const gchar *         g_get_user_cache_dir     (void);
0189 GLIB_AVAILABLE_IN_2_72
0190 const gchar *         g_get_user_state_dir     (void);
0191 GLIB_AVAILABLE_IN_ALL
0192 const gchar * const * g_get_system_data_dirs   (void);
0193
0194 #ifdef G_OS_WIN32
0195 /* This function is not part of the public GLib API */
0196 GLIB_AVAILABLE_IN_ALL
0197 const gchar * const * g_win32_get_system_data_dirs_for_module (void (*address_of_function)(void));
0198 #endif
0199
0200 #if defined (G_OS_WIN32) && defined (G_CAN_INLINE)
0201 /* This function is not part of the public GLib API either. Just call
0202  * g_get_system_data_dirs() in your code, never mind that that is
0203  * actually a macro and you will in fact call this inline function.
0204  */
0205 static inline const gchar * const *
0206 _g_win32_get_system_data_dirs (void)
0207 {
0208   return g_win32_get_system_data_dirs_for_module ((void (*)(void)) &_g_win32_get_system_data_dirs);
0209 }
0210 #define g_get_system_data_dirs _g_win32_get_system_data_dirs
0211 #endif
0212
0213 GLIB_AVAILABLE_IN_ALL
0214 const gchar * const * g_get_system_config_dirs (void);
0215
0216 GLIB_AVAILABLE_IN_ALL
0217 const gchar * g_get_user_runtime_dir (void);
0218
0219 /**
0220  * GUserDirectory:
0221  * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory
0222  * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory
0223  * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory
0224  * @G_USER_DIRECTORY_MUSIC: the user's Music directory
0225  * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory
0226  * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory
0227  * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory
0228  * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory
0229  * @G_USER_N_DIRECTORIES: the number of enum values
0230  *
0231  * These are logical ids for special directories which are defined
0232  * depending on the platform used. You should use g_get_user_special_dir()
0233  * to retrieve the full path associated to the logical id.
0234  *
0235  * The #GUserDirectory enumeration can be extended at later date. Not
0236  * every platform has a directory for every logical id in this
0237  * enumeration.
0238  *
0239  * Since: 2.14
0240  */
0241 typedef enum {
0242   G_USER_DIRECTORY_DESKTOP,
0243   G_USER_DIRECTORY_DOCUMENTS,
0244   G_USER_DIRECTORY_DOWNLOAD,
0245   G_USER_DIRECTORY_MUSIC,
0246   G_USER_DIRECTORY_PICTURES,
0247   G_USER_DIRECTORY_PUBLIC_SHARE,
0248   G_USER_DIRECTORY_TEMPLATES,
0249   G_USER_DIRECTORY_VIDEOS,
0250
0251   G_USER_N_DIRECTORIES
0252 } GUserDirectory;
0253
0254 GLIB_AVAILABLE_IN_ALL
0255 const gchar * g_get_user_special_dir (GUserDirectory directory);
0256
0257 /**
0258  * GDebugKey:
0259  * @key: the string
0260  * @value: the flag
0261  *
0262  * Associates a string with a bit flag.
0263  * Used in g_parse_debug_string().
0264  */
0265 typedef struct _GDebugKey GDebugKey;
0266 struct _GDebugKey
0267 {
0268   const gchar *key;
0269   guint        value;
0270 };
0271
0272 /* Miscellaneous utility functions
0273  */
0274 GLIB_AVAILABLE_IN_ALL
0275 guint                 g_parse_debug_string (const gchar     *string,
0276                         const GDebugKey *keys,
0277                         guint            nkeys);
0278
0279 GLIB_AVAILABLE_IN_ALL
0280 gint                  g_snprintf           (gchar       *string,
0281                         gulong       n,
0282                         gchar const *format,
0283                         ...) G_GNUC_PRINTF (3, 4);
0284 GLIB_AVAILABLE_IN_ALL
0285 gint                  g_vsnprintf          (gchar       *string,
0286                         gulong       n,
0287                         gchar const *format,
0288                         va_list      args)
0289                         G_GNUC_PRINTF(3, 0);
0290
0291 GLIB_AVAILABLE_IN_ALL
0292 void                  g_nullify_pointer    (gpointer    *nullify_location);
0293
0294 typedef enum
0295 {
0296   G_FORMAT_SIZE_DEFAULT     = 0,
0297   G_FORMAT_SIZE_LONG_FORMAT = 1 << 0,
0298   G_FORMAT_SIZE_IEC_UNITS   = 1 << 1,
0299   G_FORMAT_SIZE_BITS        = 1 << 2,
0300   G_FORMAT_SIZE_ONLY_VALUE GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 1 << 3,
0301   G_FORMAT_SIZE_ONLY_UNIT GLIB_AVAILABLE_ENUMERATOR_IN_2_74 = 1 << 4
0302 } GFormatSizeFlags;
0303
0304 GLIB_AVAILABLE_IN_2_30
0305 gchar *g_format_size_full   (guint64          size,
0306                              GFormatSizeFlags flags);
0307 GLIB_AVAILABLE_IN_2_30
0308 gchar *g_format_size        (guint64          size);
0309
0310 GLIB_DEPRECATED_IN_2_30_FOR(g_format_size)
0311 gchar *g_format_size_for_display (goffset size);
0312
0313 #define g_ATEXIT(proc)  (atexit (proc)) GLIB_DEPRECATED_MACRO_IN_2_32
0314 #define g_memmove(dest,src,len) \
0315   G_STMT_START { memmove ((dest), (src), (len)); } G_STMT_END  GLIB_DEPRECATED_MACRO_IN_2_40_FOR(memmove)
0316
0317 /**
0318  * GVoidFunc:
0319  *
0320  * Declares a type of function which takes no arguments
0321  * and has no return value. It is used to specify the type
0322  * function passed to g_atexit().
0323  */
0324 typedef void (*GVoidFunc) (void) GLIB_DEPRECATED_TYPE_IN_2_32;
0325 #define ATEXIT(proc) g_ATEXIT(proc) GLIB_DEPRECATED_MACRO_IN_2_32
0326
0327 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0328 GLIB_DEPRECATED
0329 void    g_atexit        (GVoidFunc    func);
0330 G_GNUC_END_IGNORE_DEPRECATIONS
0331
0332 #ifdef G_OS_WIN32
0333 /* It's a bad idea to wrap atexit() on Windows. If the GLib DLL calls
0334  * atexit(), the function will be called when the GLib DLL is detached
0335  * from the program, which is not what the caller wants. The caller
0336  * wants the function to be called when it *itself* exits (or is
0337  * detached, in case the caller, too, is a DLL).
0338  */
0339 #if (defined(__MINGW_H) && !defined(_STDLIB_H_)) || (defined(_MSC_VER) && !defined(_INC_STDLIB))
0340 int atexit (void (*)(void));
0341 #endif
0342 #define g_atexit(func) atexit(func) GLIB_DEPRECATED_MACRO_IN_2_32
0343 #endif
0344
0345
0346 /* Look for an executable in PATH, following execvp() rules */
0347 GLIB_AVAILABLE_IN_ALL
0348 gchar*  g_find_program_in_path  (const gchar *program);
0349
0350 /* Bit tests
0351  *
0352  * These are defined in a convoluted way because we want the compiler to
0353  * be able to inline the code for performance reasons, but for
0354  * historical reasons, we must continue to provide non-inline versions
0355  * on our ABI.
0356  *
0357  * We define these as functions in gutils.c which are just implemented
0358  * as calls to the _impl() versions in order to preserve the ABI.
0359  */
0360
0361 #define g_bit_nth_lsf(mask, nth_bit) g_bit_nth_lsf_impl(mask, nth_bit)
0362 #define g_bit_nth_msf(mask, nth_bit) g_bit_nth_msf_impl(mask, nth_bit)
0363 #define g_bit_storage(number)        g_bit_storage_impl(number)
0364
0365 GLIB_AVAILABLE_IN_ALL
0366 gint    (g_bit_nth_lsf)         (gulong mask,
0367                                  gint   nth_bit);
0368 GLIB_AVAILABLE_IN_ALL
0369 gint    (g_bit_nth_msf)         (gulong mask,
0370                                  gint   nth_bit);
0371 GLIB_AVAILABLE_IN_ALL
0372 guint   (g_bit_storage)         (gulong number);
0373
0374 static inline gint
0375 g_bit_nth_lsf_impl (gulong mask,
0376                     gint   nth_bit)
0377 {
0378   if (G_UNLIKELY (nth_bit < -1))
0379     nth_bit = -1;
0380   while (nth_bit < ((GLIB_SIZEOF_LONG * 8) - 1))
0381     {
0382       nth_bit++;
0383       if (mask & (1UL << nth_bit))
0384         return nth_bit;
0385     }
0386   return -1;
0387 }
0388
0389 static inline gint
0390 g_bit_nth_msf_impl (gulong mask,
0391                     gint   nth_bit)
0392 {
0393   if (nth_bit < 0 || G_UNLIKELY (nth_bit > GLIB_SIZEOF_LONG * 8))
0394     nth_bit = GLIB_SIZEOF_LONG * 8;
0395   while (nth_bit > 0)
0396     {
0397       nth_bit--;
0398       if (mask & (1UL << nth_bit))
0399         return nth_bit;
0400     }
0401   return -1;
0402 }
0403
0404 static inline guint
0405 g_bit_storage_impl (gulong number)
0406 {
0407 #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__)
0408   return G_LIKELY (number) ?
0409            ((GLIB_SIZEOF_LONG * 8U - 1) ^ (guint) __builtin_clzl(number)) + 1 : 1;
0410 #else
0411   guint n_bits = 0;
0412
0413   do
0414     {
0415       n_bits++;
0416       number >>= 1;
0417     }
0418   while (number);
0419   return n_bits;
0420 #endif
0421 }
0422
0423 /* Crashes the program. */
0424 #if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_50
0425 #ifndef G_OS_WIN32
0426 #  include <stdlib.h>
0427 #  define g_abort() abort ()
0428 #else
0429 G_NORETURN GLIB_AVAILABLE_IN_2_50 void g_abort (void) G_ANALYZER_NORETURN;
0430 #endif
0431 #endif
0432
0433 /*
0434  * This macro is deprecated. This DllMain() is too complex. It is
0435  * recommended to write an explicit minimal DLlMain() that just saves
0436  * the handle to the DLL and then use that handle instead, for
0437  * instance passing it to
0438  * g_win32_get_package_installation_directory_of_module().
0439  *
0440  * On Windows, this macro defines a DllMain function that stores the
0441  * actual DLL name that the code being compiled will be included in.
0442  * STATIC should be empty or 'static'. DLL_NAME is the name of the
0443  * (pointer to the) char array where the DLL name will be stored. If
0444  * this is used, you must also include <windows.h>. If you need a more complex
0445  * DLL entry point function, you cannot use this.
0446  *
0447  * On non-Windows platforms, expands to nothing.
0448  */
0449
0450 #ifndef G_PLATFORM_WIN32
0451 # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name) GLIB_DEPRECATED_MACRO_IN_2_26
0452 #else
0453 # define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)         \
0454 static char *dll_name;                          \
0455                                     \
0456 BOOL WINAPI                             \
0457 DllMain (HINSTANCE hinstDLL,                        \
0458      DWORD     fdwReason,                       \
0459      LPVOID    lpvReserved)                     \
0460 {                                   \
0461   wchar_t wcbfr[1000];                          \
0462   char *tem;                                \
0463   switch (fdwReason)                            \
0464     {                                   \
0465     case DLL_PROCESS_ATTACH:                        \
0466       GetModuleFileNameW ((HMODULE) hinstDLL, wcbfr, G_N_ELEMENTS (wcbfr)); \
0467       tem = g_utf16_to_utf8 (wcbfr, -1, NULL, NULL, NULL);      \
0468       dll_name = g_path_get_basename (tem);             \
0469       g_free (tem);                         \
0470       break;                                \
0471     }                                   \
0472                                     \
0473   return TRUE;                              \
0474 } GLIB_DEPRECATED_MACRO_IN_2_26
0475 #endif /* G_PLATFORM_WIN32 */
0476
0477 G_END_DECLS
0478
0479 #endif /* __G_UTILS_H__ */