docs/reference/glib/tmpl/misc_utils.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Miscellaneous Utility Functions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a selection of portable utility functions
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These are portable utility functions.
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### SECTION Stability_Level ##### -->
  18
  19
  20 <!-- ##### FUNCTION g_get_application_name ##### -->
  21 <para>
  22
  23 </para>
  24
  25 @Returns:
  26
  27
  28 <!-- ##### FUNCTION g_set_application_name ##### -->
  29 <para>
  30
  31 </para>
  32
  33 @application_name:
  34
  35
  36 <!-- ##### FUNCTION g_get_prgname ##### -->
  37 <para>
  38
  39 </para>
  40
  41 @Returns:
  42
  43
  44 <!-- ##### FUNCTION g_set_prgname ##### -->
  45 <para>
  46
  47 </para>
  48
  49 @prgname:
  50
  51
  52 <!-- ##### FUNCTION g_getenv ##### -->
  53 <para>
  54
  55 </para>
  56
  57 @variable:
  58 @Returns:
  59
  60
  61 <!-- ##### FUNCTION g_setenv ##### -->
  62 <para>
  63
  64 </para>
  65
  66 @variable:
  67 @value:
  68 @overwrite:
  69 @Returns:
  70
  71
  72 <!-- ##### FUNCTION g_unsetenv ##### -->
  73 <para>
  74
  75 </para>
  76
  77 @variable:
  78
  79
  80 <!-- ##### FUNCTION g_listenv ##### -->
  81 <para>
  82
  83 </para>
  84
  85 @Returns:
  86
  87
  88 <!-- ##### FUNCTION g_get_user_name ##### -->
  89 <para>
  90
  91 </para>
  92
  93 @Returns:
  94
  95
  96 <!-- ##### FUNCTION g_get_real_name ##### -->
  97 <para>
  98
  99 </para>
 100
 101 @Returns:
 102
 103
 104 <!-- ##### FUNCTION g_get_user_cache_dir ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @Returns:
 110
 111
 112 <!-- ##### FUNCTION g_get_user_data_dir ##### -->
 113 <para>
 114
 115 </para>
 116
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION g_get_user_config_dir ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @Returns:
 126
 127
 128 <!-- ##### ENUM GUserDirectory ##### -->
 129 <para>
 130
 131 </para>
 132
 133 @G_USER_DIRECTORY_DESKTOP:
 134 @G_USER_DIRECTORY_DOCUMENTS:
 135 @G_USER_DIRECTORY_DOWNLOAD:
 136 @G_USER_DIRECTORY_MUSIC:
 137 @G_USER_DIRECTORY_PICTURES:
 138 @G_USER_DIRECTORY_PUBLIC_SHARE:
 139 @G_USER_DIRECTORY_TEMPLATES:
 140 @G_USER_DIRECTORY_VIDEOS:
 141 @G_USER_N_DIRECTORIES:
 142
 143 <!-- ##### FUNCTION g_get_user_special_dir ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @directory:
 149 @Returns:
 150
 151
 152 <!-- ##### FUNCTION g_get_system_data_dirs ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @Returns:
 158
 159
 160 <!-- ##### FUNCTION g_get_system_config_dirs ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @Returns:
 166
 167
 168 <!-- ##### FUNCTION g_reload_user_special_dirs_cache ##### -->
 169 <para>
 170
 171 </para>
 172
 173
 174
 175 <!-- ##### FUNCTION g_get_host_name ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @Returns:
 181
 182
 183 <!-- ##### FUNCTION g_get_home_dir ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @Returns:
 189
 190
 191 <!-- ##### FUNCTION g_get_tmp_dir ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION g_get_current_dir ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION g_basename ##### -->
 208
 209
 210 @file_name:
 211 @Returns:
 212
 213
 214 <!-- ##### MACRO g_dirname ##### -->
 215 <para>
 216 This function is deprecated and will be removed in the next major
 217 release of GLib. Use g_path_get_dirname() instead.
 218 </para>
 219
 220 <para>
 221 Gets the directory components of a file name.
 222 If the file name has no directory components "." is returned.
 223 The returned string should be freed when no longer needed.
 224 </para>
 225
 226 @Returns: the directory components of the file.
 227
 228
 229 <!-- ##### FUNCTION g_path_is_absolute ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @file_name:
 235 @Returns:
 236
 237
 238 <!-- ##### FUNCTION g_path_skip_root ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @file_name:
 244 @Returns:
 245
 246
 247 <!-- ##### FUNCTION g_path_get_basename ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @file_name:
 253 @Returns:
 254
 255
 256 <!-- ##### FUNCTION g_path_get_dirname ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @file_name:
 262 @Returns:
 263
 264
 265 <!-- ##### FUNCTION g_build_filename ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @first_element:
 271 @Varargs:
 272 @Returns:
 273
 274
 275 <!-- ##### FUNCTION g_build_filenamev ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @args:
 281 @Returns:
 282
 283
 284 <!-- ##### FUNCTION g_build_path ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @separator:
 290 @first_element:
 291 @Varargs:
 292 @Returns:
 293
 294
 295 <!-- ##### FUNCTION g_build_pathv ##### -->
 296 <para>
 297
 298 </para>
 299
 300 @separator:
 301 @args:
 302 @Returns:
 303
 304
 305 <!-- ##### FUNCTION g_format_size_for_display ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @size:
 311 @Returns:
 312
 313
 314 <!-- ##### FUNCTION g_find_program_in_path ##### -->
 315 <para>
 316
 317 </para>
 318
 319 @program:
 320 @Returns:
 321
 322
 323 <!-- ##### FUNCTION g_bit_nth_lsf ##### -->
 324 <para>
 325 Find the position of the first bit set in @mask, searching from (but not
 326 including) @nth_bit upwards. Bits are numbered from 0 (least significant)
 327 to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
 328 0th bit, set @nth_bit to -1.
 329 </para>
 330
 331 @mask: a #gulong containing flags.
 332 @nth_bit: the index of the bit to start the search from.
 333 @Returns: the index of the first bit set which is higher than @nth_bit.
 334
 335
 336 <!-- ##### FUNCTION g_bit_nth_msf ##### -->
 337 <para>
 338 Find the position of the first bit set in @mask, searching from (but not
 339 including) @nth_bit downwards. Bits are numbered from 0 (least significant)
 340 to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
 341 last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8.
 342 </para>
 343
 344 @mask: a #gulong containing flags.
 345 @nth_bit: the index of the bit to start the search from.
 346 @Returns: the index of the first bit set which is lower than @nth_bit.
 347
 348
 349 <!-- ##### FUNCTION g_bit_storage ##### -->
 350 <para>
 351 Gets the number of bits used to hold @number,
 352 e.g. if @number is 4, 3 bits are needed.
 353 </para>
 354
 355 @number: a guint.
 356 @Returns: the number of bits used to hold @number.
 357
 358
 359 <!-- ##### FUNCTION g_spaced_primes_closest ##### -->
 360 <para>
 361 Gets the smallest prime number from a built-in array of primes which
 362 is larger than @num. This is used within GLib to calculate the optimum
 363 size of a #GHashTable.
 364 </para>
 365 <para>
 366 The built-in array of primes ranges from 11 to 13845163 such that
 367 each prime is approximately 1.5-2 times the previous prime.
 368 </para>
 369
 370 @num: a #guint.
 371 @Returns: the smallest prime number from a built-in array of primes which is
 372 larger than @num.
 373
 374
 375 <!-- ##### FUNCTION g_atexit ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @func:
 381
 382
 383 <!-- ##### FUNCTION g_parse_debug_string ##### -->
 384 <para>
 385
 386 </para>
 387
 388 @string:
 389 @keys:
 390 @nkeys:
 391 @Returns:
 392
 393
 394 <!-- ##### STRUCT GDebugKey ##### -->
 395 <para>
 396 Associates a string with a bit flag.
 397 Used in g_parse_debug_string().
 398 </para>
 399
 400 @key: the string
 401 @value: the flag
 402
 403 <!-- ##### USER_FUNCTION GVoidFunc ##### -->
 404 <para>
 405 Declares a type of function which takes no arguments and has no return value.
 406 It is used to specify the type function passed to g_atexit().
 407 </para>
 408
 409
 410
 411 <!-- ##### USER_FUNCTION GFreeFunc ##### -->
 412 <para>
 413 Declares a type of function which takes an arbitrary data pointer argument
 414 and has no return value. It is not currently used in GLib or GTK+.
 415 </para>
 416
 417 @data: a data pointer.
 418
 419
 420 <!-- ##### FUNCTION g_qsort_with_data ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @pbase:
 426 @total_elems:
 427 @size:
 428 @compare_func:
 429 @user_data:
 430
 431
 432 <!-- ##### FUNCTION g_nullify_pointer ##### -->
 433 <para>
 434
 435 </para>
 436
 437 @nullify_location:
 438
 439