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 <!-- ##### FUNCTION g_get_application_name ##### -->
  18 <para>
  19
  20 </para>
  21
  22 @Returns:
  23
  24
  25 <!-- ##### FUNCTION g_set_application_name ##### -->
  26 <para>
  27
  28 </para>
  29
  30 @application_name:
  31
  32
  33 <!-- ##### FUNCTION g_get_prgname ##### -->
  34 <para>
  35 Gets the name of the program. This name should NOT be localized,
  36 contrast with g_get_application_name().
  37 (If you are using GDK or GTK+ the program name is set in gdk_init(), which
  38 is called by gtk_init(). The program name is found by taking the last
  39 component of <literal>argv[0]</literal>.)
  40 </para>
  41
  42 @Returns: the name of the program.
  43
  44
  45 <!-- ##### FUNCTION g_set_prgname ##### -->
  46 <para>
  47 Sets the name of the program. This name should NOT be localized,
  48 contrast with g_set_application_name(). Note that for thread-safety
  49 reasons this function can only be called once.
  50 </para>
  51
  52 @prgname: the name of the program.
  53
  54
  55 <!-- ##### FUNCTION g_getenv ##### -->
  56 <para>
  57
  58 </para>
  59
  60 @variable:
  61 @Returns:
  62
  63
  64 <!-- ##### FUNCTION g_setenv ##### -->
  65 <para>
  66
  67 </para>
  68
  69 @variable:
  70 @value:
  71 @overwrite:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION g_unsetenv ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @variable:
  81
  82
  83 <!-- ##### FUNCTION g_get_user_name ##### -->
  84 <para>
  85 Gets the user name of the current user.
  86 </para>
  87
  88 @Returns: the user name of the current user.
  89
  90
  91 <!-- ##### FUNCTION g_get_real_name ##### -->
  92 <para>
  93 Gets the real name of the user. This usually comes from the user's entry in the
  94 <filename>passwd</filename> file. The encoding of the returned string is system
  95 defined. If the real user name cannot be determined, the string "Unknown" is
  96 returned.
  97 </para>
  98
  99 @Returns: the user's real name.
 100
 101
 102 <!-- ##### FUNCTION g_get_user_cache_dir ##### -->
 103 <para>
 104
 105 </para>
 106
 107 @Returns:
 108
 109
 110 <!-- ##### FUNCTION g_get_user_data_dir ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @Returns:
 116
 117
 118 <!-- ##### FUNCTION g_get_user_config_dir ##### -->
 119 <para>
 120
 121 </para>
 122
 123 @Returns:
 124
 125
 126 <!-- ##### FUNCTION g_get_home_dir ##### -->
 127 <para>
 128 Gets the current user's home directory.
 129 </para>
 130 <para>
 131 Note that in contrast to traditional Unix tools, this function
 132 prefers <filename>passwd</filename> entries over the <envar>HOME</envar>
 133 environment variable.
 134 </para>
 135
 136 @Returns: the current user's home directory.
 137
 138
 139 <!-- ##### FUNCTION g_get_tmp_dir ##### -->
 140 <para>
 141 Gets the directory to use for temporary files.
 142 This is found from inspecting the environment variables <envar>TMPDIR</envar>,
 143 <envar>TMP</envar>, and <envar>TEMP</envar>
 144 in that order. If none of those are defined "/tmp" is returned on UNIX and
 145 "C:\" on Windows.
 146 </para>
 147
 148 @Returns: the directory to use for temporary files.
 149
 150
 151 <!-- ##### FUNCTION g_get_current_dir ##### -->
 152 <para>
 153 Gets the current directory.
 154 The returned string should be freed when no longer needed.
 155 </para>
 156
 157 @Returns: the current directory.
 158
 159
 160 <!-- ##### FUNCTION g_basename ##### -->
 161
 162
 163 @file_name:
 164 @Returns:
 165
 166
 167 <!-- ##### MACRO g_dirname ##### -->
 168 <para>
 169 This function is deprecated and will be removed in the next major
 170 release of GLib. Use g_path_get_dirname() instead.
 171 </para>
 172
 173 <para>
 174 Gets the directory components of a file name.
 175 If the file name has no directory components "." is returned.
 176 The returned string should be freed when no longer needed.
 177 </para>
 178
 179 @Returns: the directory components of the file.
 180
 181
 182 <!-- ##### FUNCTION g_path_is_absolute ##### -->
 183 <para>
 184 Returns %TRUE if the given @file_name is an absolute file name,
 185 i.e. it contains a full path from the root directory such as '/usr/local'
 186 on UNIX or 'C:\windows' on Windows systems.
 187 </para>
 188
 189 @file_name: a file name.
 190 @Returns: %TRUE if @file_name is an absolute path.
 191
 192
 193 <!-- ##### FUNCTION g_path_skip_root ##### -->
 194 <para>
 195 Returns a pointer into @file_name after the root component, i.e. after
 196 the '/' in UNIX or 'C:\' under Windows. If @file_name is not an absolute
 197 path it returns %NULL.
 198 </para>
 199
 200 @file_name: a file name.
 201 @Returns: a pointer into @file_name after the root component.
 202
 203
 204 <!-- ##### FUNCTION g_path_get_basename ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @file_name:
 210 @Returns:
 211
 212
 213 <!-- ##### FUNCTION g_path_get_dirname ##### -->
 214 <para>
 215 Gets the directory components of a file name.  If the file name has no
 216 directory components "." is returned.  The returned string should be
 217 freed when no longer needed.
 218 </para>
 219
 220 @file_name: the name of the file.
 221 @Returns: the directory components of the file.
 222
 223
 224 <!-- ##### FUNCTION g_build_filename ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @first_element:
 230 @Varargs:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION g_build_path ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @separator:
 240 @first_element:
 241 @Varargs:
 242 @Returns:
 243
 244
 245 <!-- ##### FUNCTION g_find_program_in_path ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @program:
 251 @Returns:
 252
 253
 254 <!-- ##### FUNCTION g_bit_nth_lsf ##### -->
 255 <para>
 256 Find the position of the first bit set in @mask, searching from (but not
 257 including) @nth_bit upwards. Bits are numbered from 0 (least significant)
 258 to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
 259 0th bit, set @nth_bit to -1.
 260 </para>
 261
 262 @mask: a #gulong containing flags.
 263 @nth_bit: the index of the bit to start the search from.
 264 @Returns: the index of the first bit set which is higher than @nth_bit.
 265
 266
 267 <!-- ##### FUNCTION g_bit_nth_msf ##### -->
 268 <para>
 269 Find the position of the first bit set in @mask, searching from (but not
 270 including) @nth_bit downwards. Bits are numbered from 0 (least significant)
 271 to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
 272 last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8.
 273 </para>
 274
 275 @mask: a #gulong containing flags.
 276 @nth_bit: the index of the bit to start the search from.
 277 @Returns: the index of the first bit set which is lower than @nth_bit.
 278
 279
 280 <!-- ##### FUNCTION g_bit_storage ##### -->
 281 <para>
 282 Gets the number of bits used to hold @number,
 283 e.g. if @number is 4, 3 bits are needed.
 284 </para>
 285
 286 @number: a guint.
 287 @Returns: the number of bits used to hold @number.
 288
 289
 290 <!-- ##### FUNCTION g_spaced_primes_closest ##### -->
 291 <para>
 292 Gets the smallest prime number from a built-in array of primes which
 293 is larger than @num. This is used within GLib to calculate the optimum
 294 size of a #GHashTable.
 295 </para>
 296 <para>
 297 The built-in array of primes ranges from 11 to 13845163 such that
 298 each prime is approximately 1.5-2 times the previous prime.
 299 </para>
 300
 301 @num: a #guint.
 302 @Returns: the smallest prime number from a built-in array of primes which is
 303 larger than @num.
 304
 305
 306 <!-- ##### FUNCTION g_atexit ##### -->
 307 <para>
 308 Specifies a function to be called at normal program termination.
 309 </para>
 310
 311 @func: the function to call on normal program termination.
 312
 313
 314 <!-- ##### FUNCTION g_parse_debug_string ##### -->
 315 <para>
 316 Parses a string containing debugging options separated by ':' into a guint
 317 containing bit flags.
 318 This is used within GDK and GTK+ to parse the debug options passed on the
 319 command line or through environment variables.
 320 </para>
 321
 322 @string: a list of debug options separated by ':' or "all" to set all flags.
 323 @keys: pointer to an array of #GDebugKey which associate strings with
 324 bit flags.
 325 @nkeys: the number of #GDebugKey in the array.
 326 @Returns: the combined set of bit flags.
 327
 328
 329 <!-- ##### STRUCT GDebugKey ##### -->
 330 <para>
 331 Associates a string with a bit flag.
 332 Used in g_parse_debug_string().
 333 </para>
 334
 335 @key:
 336 @value:
 337
 338 <!-- ##### USER_FUNCTION GVoidFunc ##### -->
 339 <para>
 340 Declares a type of function which takes no arguments and has no return value.
 341 It is used to specify the type function passed to g_atexit().
 342 </para>
 343
 344
 345
 346 <!-- ##### USER_FUNCTION GFreeFunc ##### -->
 347 <para>
 348 Declares a type of function which takes an arbitrary data pointer argument
 349 and has no return value. It is not currently used in GLib or GTK+.
 350 </para>
 351
 352 @data: a data pointer.
 353
 354
 355 <!-- ##### FUNCTION g_qsort_with_data ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @pbase:
 361 @total_elems:
 362 @size:
 363 @compare_func:
 364 @user_data:
 365
 366
 367 <!-- ##### FUNCTION g_nullify_pointer ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @nullify_location:
 373
 374