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