1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.Util; 26 27 private import glib.Str; 28 private import gtkc.glib; 29 public import gtkc.glibtypes; 30 31 32 public struct Util 33 { 34 /** 35 * Behaves exactly like g_build_filename(), but takes the path elements 36 * as a string array, instead of varargs. This function is mainly 37 * meant for language bindings. 38 * 39 * Params: 40 * args = strings containing the path elements. 41 * 42 * Return: a newly-allocated string that must be freed with g_free(). 43 * 44 * Since: 2.8 45 */ 46 public static string buildFilename(string[] firstElement ... ) 47 { 48 return Str.toString(g_build_filenamev(Str.toStringzArray(firstElement))); 49 } 50 51 /** 52 * Behaves exactly like g_build_path(), but takes the path elements 53 * as a string array, instead of varargs. This function is mainly 54 * meant for language bindings. 55 * 56 * Params: 57 * separator = a string used to separator the elements of the path. 58 * args = strings containing the path elements. 59 * 60 * Return: a newly-allocated string that must be freed with g_free(). 61 * 62 * Since: 2.8 63 */ 64 public static string buildPath(string separator, string[] firstElement ... ) 65 { 66 return Str.toString(g_build_pathv(Str.toStringz(separator), Str.toStringzArray(firstElement))); 67 } 68 69 /** 70 */ 71 72 /** 73 * Specifies a function to be called at normal program termination. 74 * 75 * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor 76 * macro that maps to a call to the atexit() function in the C 77 * library. This means that in case the code that calls g_atexit(), 78 * i.e. atexit(), is in a DLL, the function will be called when the 79 * DLL is detached from the program. This typically makes more sense 80 * than that the function is called when the GLib DLL is detached, 81 * which happened earlier when g_atexit() was a function in the GLib 82 * DLL. 83 * 84 * The behaviour of atexit() in the context of dynamically loaded 85 * modules is not formally specified and varies wildly. 86 * 87 * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically 88 * loaded module which is unloaded before the program terminates might 89 * well cause a crash at program exit. 90 * 91 * Some POSIX systems implement atexit() like Windows, and have each 92 * dynamically loaded module maintain an own atexit chain that is 93 * called when the module is unloaded. 94 * 95 * On other POSIX systems, before a dynamically loaded module is 96 * unloaded, the registered atexit functions (if any) residing in that 97 * module are called, regardless where the code that registered them 98 * resided. This is presumably the most robust approach. 99 * 100 * As can be seen from the above, for portability it's best to avoid 101 * calling g_atexit() (or atexit()) except in the main executable of a 102 * program. 103 * 104 * Deprecated: It is best to avoid g_atexit(). 105 * 106 * Params: 107 * func = the function to call on normal program termination. 108 */ 109 public static void atexit(GVoidFunc func) 110 { 111 g_atexit(func); 112 } 113 114 /** 115 * Gets the name of the file without any leading directory 116 * components. It returns a pointer into the given file name 117 * string. 118 * 119 * Deprecated: Use g_path_get_basename() instead, but notice 120 * that g_path_get_basename() allocates new memory for the 121 * returned string, unlike this function which returns a pointer 122 * into the argument. 123 * 124 * Params: 125 * fileName = the name of the file 126 * 127 * Return: the name of the file without any leading 128 * directory components 129 */ 130 public static string basename(string fileName) 131 { 132 return Str.toString(g_basename(Str.toStringz(fileName))); 133 } 134 135 /** 136 * Find the position of the first bit set in @mask, searching 137 * from (but not including) @nth_bit upwards. Bits are numbered 138 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, 139 * usually). To start searching from the 0th bit, set @nth_bit to -1. 140 * 141 * Params: 142 * mask = a #gulong containing flags 143 * nthBit = the index of the bit to start the search from 144 * 145 * Return: the index of the first bit set which is higher than @nth_bit 146 */ 147 public static int bitNthLsf(gulong mask, int nthBit) 148 { 149 return g_bit_nth_lsf(mask, nthBit); 150 } 151 152 /** 153 * Find the position of the first bit set in @mask, searching 154 * from (but not including) @nth_bit downwards. Bits are numbered 155 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, 156 * usually). To start searching from the last bit, set @nth_bit to 157 * -1 or GLIB_SIZEOF_LONG * 8. 158 * 159 * Params: 160 * mask = a #gulong containing flags 161 * nthBit = the index of the bit to start the search from 162 * 163 * Return: the index of the first bit set which is lower than @nth_bit 164 */ 165 public static int bitNthMsf(gulong mask, int nthBit) 166 { 167 return g_bit_nth_msf(mask, nthBit); 168 } 169 170 /** 171 * Gets the number of bits used to hold @number, 172 * e.g. if @number is 4, 3 bits are needed. 173 * 174 * Params: 175 * number = a #guint 176 * 177 * Return: the number of bits used to hold @number 178 */ 179 public static uint bitStorage(gulong number) 180 { 181 return g_bit_storage(number); 182 } 183 184 /** 185 * Returns the value of the environment variable @variable in the 186 * provided list @envp. 187 * 188 * Params: 189 * envp = an environment 190 * list (eg, as returned from g_get_environ()), or %NULL 191 * for an empty environment list 192 * variable = the environment variable to get, in the GLib file name 193 * encoding 194 * 195 * Return: the value of the environment variable, or %NULL if 196 * the environment variable is not set in @envp. The returned 197 * string is owned by @envp, and will be freed if @variable is 198 * set or unset again. 199 * 200 * Since: 2.32 201 */ 202 public static string environGetenv(string[] envp, string variable) 203 { 204 return Str.toString(g_environ_getenv(Str.toStringzArray(envp), Str.toStringz(variable))); 205 } 206 207 /** 208 * Sets the environment variable @variable in the provided list 209 * @envp to @value. 210 * 211 * Params: 212 * envp = an 213 * environment list that can be freed using g_strfreev() (e.g., as 214 * returned from g_get_environ()), or %NULL for an empty 215 * environment list 216 * variable = the environment variable to set, must not contain '=' 217 * value = the value for to set the variable to 218 * overwrite = whether to change the variable if it already exists 219 * 220 * Return: the 221 * updated environment list. Free it using g_strfreev(). 222 * 223 * Since: 2.32 224 */ 225 public static string[] environSetenv(string[] envp, string variable, string value, bool overwrite) 226 { 227 return Str.toStringArray(g_environ_setenv(Str.toStringzArray(envp), Str.toStringz(variable), Str.toStringz(value), overwrite)); 228 } 229 230 /** 231 * Removes the environment variable @variable from the provided 232 * environment @envp. 233 * 234 * Params: 235 * envp = an environment 236 * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), 237 * or %NULL for an empty environment list 238 * variable = the environment variable to remove, must not contain '=' 239 * 240 * Return: the 241 * updated environment list. Free it using g_strfreev(). 242 * 243 * Since: 2.32 244 */ 245 public static string[] environUnsetenv(string[] envp, string variable) 246 { 247 return Str.toStringArray(g_environ_unsetenv(Str.toStringzArray(envp), Str.toStringz(variable))); 248 } 249 250 /** 251 * Locates the first executable named @program in the user's path, in the 252 * same way that execvp() would locate it. Returns an allocated string 253 * with the absolute path name, or %NULL if the program is not found in 254 * the path. If @program is already an absolute path, returns a copy of 255 * @program if @program exists and is executable, and %NULL otherwise. 256 * 257 * On Windows, if @program does not have a file type suffix, tries 258 * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in 259 * the `PATHEXT` environment variable. 260 * 261 * On Windows, it looks for the file in the same way as CreateProcess() 262 * would. This means first in the directory where the executing 263 * program was loaded from, then in the current directory, then in the 264 * Windows 32-bit system directory, then in the Windows directory, and 265 * finally in the directories in the `PATH` environment variable. If 266 * the program is found, the return value contains the full name 267 * including the type suffix. 268 * 269 * Params: 270 * program = a program name in the GLib file name encoding 271 * 272 * Return: a newly-allocated string with the absolute path, or %NULL 273 */ 274 public static string findProgramInPath(string program) 275 { 276 return Str.toString(g_find_program_in_path(Str.toStringz(program))); 277 } 278 279 /** 280 * Formats a size (for example the size of a file) into a human readable 281 * string. Sizes are rounded to the nearest size prefix (kB, MB, GB) 282 * and are displayed rounded to the nearest tenth. E.g. the file size 283 * 3292528 bytes will be converted into the string "3.2 MB". 284 * 285 * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). 286 * 287 * This string should be freed with g_free() when not needed any longer. 288 * 289 * See g_format_size_full() for more options about how the size might be 290 * formatted. 291 * 292 * Params: 293 * size = a size in bytes 294 * 295 * Return: a newly-allocated formatted string containing a human readable 296 * file size 297 * 298 * Since: 2.30 299 */ 300 public static string formatSize(ulong size) 301 { 302 return Str.toString(g_format_size(size)); 303 } 304 305 /** 306 * Formats a size (for example the size of a file) into a human 307 * readable string. Sizes are rounded to the nearest size prefix 308 * (KB, MB, GB) and are displayed rounded to the nearest tenth. 309 * E.g. the file size 3292528 bytes will be converted into the 310 * string "3.1 MB". 311 * 312 * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). 313 * 314 * This string should be freed with g_free() when not needed any longer. 315 * 316 * Deprecated: This function is broken due to its use of SI 317 * suffixes to denote IEC units. Use g_format_size() instead. 318 * 319 * Params: 320 * size = a size in bytes 321 * 322 * Return: a newly-allocated formatted string containing a human 323 * readable file size 324 * 325 * Since: 2.16 326 */ 327 public static string formatSizeForDisplay(long size) 328 { 329 return Str.toString(g_format_size_for_display(size)); 330 } 331 332 /** 333 * Formats a size. 334 * 335 * This function is similar to g_format_size() but allows for flags 336 * that modify the output. See #GFormatSizeFlags. 337 * 338 * Params: 339 * size = a size in bytes 340 * flags = #GFormatSizeFlags to modify the output 341 * 342 * Return: a newly-allocated formatted string containing a human 343 * readable file size 344 * 345 * Since: 2.30 346 */ 347 public static string formatSizeFull(ulong size, GFormatSizeFlags flags) 348 { 349 return Str.toString(g_format_size_full(size, flags)); 350 } 351 352 /** 353 * Gets a human-readable name for the application, as set by 354 * g_set_application_name(). This name should be localized if 355 * possible, and is intended for display to the user. Contrast with 356 * g_get_prgname(), which gets a non-localized name. If 357 * g_set_application_name() has not been called, returns the result of 358 * g_get_prgname() (which may be %NULL if g_set_prgname() has also not 359 * been called). 360 * 361 * Return: human-readable application name. may return %NULL 362 * 363 * Since: 2.2 364 */ 365 public static string getApplicationName() 366 { 367 return Str.toString(g_get_application_name()); 368 } 369 370 /** 371 * Gets the list of environment variables for the current process. 372 * 373 * The list is %NULL terminated and each item in the list is of the 374 * form 'NAME=VALUE'. 375 * 376 * This is equivalent to direct access to the 'environ' global variable, 377 * except portable. 378 * 379 * The return value is freshly allocated and it should be freed with 380 * g_strfreev() when it is no longer needed. 381 * 382 * Return: the list of 383 * environment variables 384 * 385 * Since: 2.28 386 */ 387 public static string[] getEnviron() 388 { 389 return Str.toStringArray(g_get_environ()); 390 } 391 392 /** 393 * Gets the current directory. 394 * 395 * The returned string should be freed when no longer needed. 396 * The encoding of the returned string is system defined. 397 * On Windows, it is always UTF-8. 398 * 399 * Since GLib 2.40, this function will return the value of the "PWD" 400 * environment variable if it is set and it happens to be the same as 401 * the current directory. This can make a difference in the case that 402 * the current directory is the target of a symbolic link. 403 * 404 * Return: the current directory 405 */ 406 public static string getCurrentDir() 407 { 408 return Str.toString(g_get_current_dir()); 409 } 410 411 /** 412 * Gets the current user's home directory. 413 * 414 * As with most UNIX tools, this function will return the value of the 415 * `HOME` environment variable if it is set to an existing absolute path 416 * name, falling back to the `passwd` file in the case that it is unset. 417 * 418 * If the path given in `HOME` is non-absolute, does not exist, or is 419 * not a directory, the result is undefined. 420 * 421 * Before version 2.36 this function would ignore the `HOME` environment 422 * variable, taking the value from the `passwd` database instead. This was 423 * changed to increase the compatibility of GLib with other programs (and 424 * the XDG basedir specification) and to increase testability of programs 425 * based on GLib (by making it easier to run them from test frameworks). 426 * 427 * If your program has a strong requirement for either the new or the 428 * old behaviour (and if you don't wish to increase your GLib 429 * dependency to ensure that the new behaviour is in effect) then you 430 * should either directly check the `HOME` environment variable yourself 431 * or unset it before calling any functions in GLib. 432 * 433 * Return: the current user's home directory 434 */ 435 public static string getHomeDir() 436 { 437 return Str.toString(g_get_home_dir()); 438 } 439 440 /** 441 * Return a name for the machine. 442 * 443 * The returned name is not necessarily a fully-qualified domain name, 444 * or even present in DNS or some other name service at all. It need 445 * not even be unique on your local network or site, but usually it 446 * is. Callers should not rely on the return value having any specific 447 * properties like uniqueness for security purposes. Even if the name 448 * of the machine is changed while an application is running, the 449 * return value from this function does not change. The returned 450 * string is owned by GLib and should not be modified or freed. If no 451 * name can be determined, a default fixed string "localhost" is 452 * returned. 453 * 454 * Return: the host name of the machine. 455 * 456 * Since: 2.8 457 */ 458 public static string getHostName() 459 { 460 return Str.toString(g_get_host_name()); 461 } 462 463 /** 464 * Gets the name of the program. This name should not be localized, 465 * in contrast to g_get_application_name(). 466 * 467 * If you are using GDK or GTK+ the program name is set in gdk_init(), 468 * which is called by gtk_init(). The program name is found by taking 469 * the last component of @argv[0]. 470 * 471 * Return: the name of the program. The returned string belongs 472 * to GLib and must not be modified or freed. 473 */ 474 public static string getPrgname() 475 { 476 return Str.toString(g_get_prgname()); 477 } 478 479 /** 480 * Gets the real name of the user. This usually comes from the user's 481 * entry in the `passwd` file. The encoding of the returned string is 482 * system-defined. (On Windows, it is, however, always UTF-8.) If the 483 * real user name cannot be determined, the string "Unknown" is 484 * returned. 485 * 486 * Return: the user's real name. 487 */ 488 public static string getRealName() 489 { 490 return Str.toString(g_get_real_name()); 491 } 492 493 /** 494 * Returns an ordered list of base directories in which to access 495 * system-wide configuration information. 496 * 497 * On UNIX platforms this is determined using the mechanisms described 498 * in the 499 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). 500 * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. 501 * 502 * On Windows is the directory that contains application data for all users. 503 * A typical path is C:\Documents and Settings\All Users\Application Data. 504 * This folder is used for application data that is not user specific. 505 * For example, an application can store a spell-check dictionary, a database 506 * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. 507 * This information will not roam and is available to anyone using the computer. 508 * 509 * Return: a %NULL-terminated array of strings owned by GLib that must 510 * not be modified or freed. 511 * 512 * Since: 2.6 513 */ 514 public static string[] getSystemConfigDirs() 515 { 516 return Str.toStringArray(g_get_system_config_dirs()); 517 } 518 519 /** 520 * Returns an ordered list of base directories in which to access 521 * system-wide application data. 522 * 523 * On UNIX platforms this is determined using the mechanisms described 524 * in the 525 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) 526 * In this case the list of directories retrieved will be XDG_DATA_DIRS. 527 * 528 * On Windows the first elements in the list are the Application Data 529 * and Documents folders for All Users. (These can be determined only 530 * on Windows 2000 or later and are not present in the list on other 531 * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and 532 * CSIDL_COMMON_DOCUMENTS. 533 * 534 * Then follows the "share" subfolder in the installation folder for 535 * the package containing the DLL that calls this function, if it can 536 * be determined. 537 * 538 * Finally the list contains the "share" subfolder in the installation 539 * folder for GLib, and in the installation folder for the package the 540 * application's .exe file belongs to. 541 * 542 * The installation folders above are determined by looking up the 543 * folder where the module (DLL or EXE) in question is located. If the 544 * folder's name is "bin", its parent is used, otherwise the folder 545 * itself. 546 * 547 * Note that on Windows the returned list can vary depending on where 548 * this function is called. 549 * 550 * Return: a %NULL-terminated array of strings owned by GLib that must 551 * not be modified or freed. 552 * 553 * Since: 2.6 554 */ 555 public static string[] getSystemDataDirs() 556 { 557 return Str.toStringArray(g_get_system_data_dirs()); 558 } 559 560 /** 561 * Gets the directory to use for temporary files. 562 * 563 * On UNIX, this is taken from the `TMPDIR` environment variable. 564 * If the variable is not set, `P_tmpdir` is 565 * used, as defined by the system C library. Failing that, a 566 * hard-coded default of "/tmp" is returned. 567 * 568 * On Windows, the `TEMP` environment variable is used, with the 569 * root directory of the Windows installation (eg: "C:\") used 570 * as a default. 571 * 572 * The encoding of the returned string is system-defined. On Windows, 573 * it is always UTF-8. The return value is never %NULL or the empty 574 * string. 575 * 576 * Return: the directory to use for temporary files. 577 */ 578 public static string getTmpDir() 579 { 580 return Str.toString(g_get_tmp_dir()); 581 } 582 583 /** 584 * Returns a base directory in which to store non-essential, cached 585 * data specific to particular user. 586 * 587 * On UNIX platforms this is determined using the mechanisms described 588 * in the 589 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). 590 * In this case the directory retrieved will be XDG_CACHE_HOME. 591 * 592 * On Windows is the directory that serves as a common repository for 593 * temporary Internet files. A typical path is 594 * C:\Documents and Settings\username\Local Settings\Temporary Internet Files. 595 * See documentation for CSIDL_INTERNET_CACHE. 596 * 597 * Return: a string owned by GLib that must not be modified 598 * or freed. 599 * 600 * Since: 2.6 601 */ 602 public static string getUserCacheDir() 603 { 604 return Str.toString(g_get_user_cache_dir()); 605 } 606 607 /** 608 * Returns a base directory in which to store user-specific application 609 * configuration information such as user preferences and settings. 610 * 611 * On UNIX platforms this is determined using the mechanisms described 612 * in the 613 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). 614 * In this case the directory retrieved will be `XDG_CONFIG_HOME`. 615 * 616 * On Windows this is the folder to use for local (as opposed to 617 * roaming) application data. See documentation for 618 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as 619 * what g_get_user_data_dir() returns. 620 * 621 * Return: a string owned by GLib that must not be modified 622 * or freed. 623 * 624 * Since: 2.6 625 */ 626 public static string getUserConfigDir() 627 { 628 return Str.toString(g_get_user_config_dir()); 629 } 630 631 /** 632 * Returns a base directory in which to access application data such 633 * as icons that is customized for a particular user. 634 * 635 * On UNIX platforms this is determined using the mechanisms described 636 * in the 637 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). 638 * In this case the directory retrieved will be `XDG_DATA_HOME`. 639 * 640 * On Windows this is the folder to use for local (as opposed to 641 * roaming) application data. See documentation for 642 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as 643 * what g_get_user_config_dir() returns. 644 * 645 * Return: a string owned by GLib that must not be modified 646 * or freed. 647 * 648 * Since: 2.6 649 */ 650 public static string getUserDataDir() 651 { 652 return Str.toString(g_get_user_data_dir()); 653 } 654 655 /** 656 * Gets the user name of the current user. The encoding of the returned 657 * string is system-defined. On UNIX, it might be the preferred file name 658 * encoding, or something else, and there is no guarantee that it is even 659 * consistent on a machine. On Windows, it is always UTF-8. 660 * 661 * Return: the user name of the current user. 662 */ 663 public static string getUserName() 664 { 665 return Str.toString(g_get_user_name()); 666 } 667 668 /** 669 * Returns a directory that is unique to the current user on the local 670 * system. 671 * 672 * On UNIX platforms this is determined using the mechanisms described 673 * in the 674 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). 675 * This is the directory 676 * specified in the `XDG_RUNTIME_DIR` environment variable. 677 * In the case that this variable is not set, GLib will issue a warning 678 * message to stderr and return the value of g_get_user_cache_dir(). 679 * 680 * On Windows this is the folder to use for local (as opposed to 681 * roaming) application data. See documentation for 682 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as 683 * what g_get_user_config_dir() returns. 684 * 685 * Return: a string owned by GLib that must not be modified or freed. 686 * 687 * Since: 2.28 688 */ 689 public static string getUserRuntimeDir() 690 { 691 return Str.toString(g_get_user_runtime_dir()); 692 } 693 694 /** 695 * Returns the full path of a special directory using its logical id. 696 * 697 * On UNIX this is done using the XDG special user directories. 698 * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP 699 * falls back to `$HOME/Desktop` when XDG special user directories have 700 * not been set up. 701 * 702 * Depending on the platform, the user might be able to change the path 703 * of the special directory without requiring the session to restart; GLib 704 * will not reflect any change once the special directories are loaded. 705 * 706 * Params: 707 * directory = the logical id of special directory 708 * 709 * Return: the path to the specified special directory, or %NULL 710 * if the logical id was not found. The returned string is owned by 711 * GLib and should not be modified or freed. 712 * 713 * Since: 2.14 714 */ 715 public static string getUserSpecialDir(GUserDirectory directory) 716 { 717 return Str.toString(g_get_user_special_dir(directory)); 718 } 719 720 /** 721 * Returns the value of an environment variable. 722 * 723 * The name and value are in the GLib file name encoding. On UNIX, 724 * this means the actual bytes which might or might not be in some 725 * consistent character set and encoding. On Windows, it is in UTF-8. 726 * On Windows, in case the environment variable's value contains 727 * references to other environment variables, they are expanded. 728 * 729 * Params: 730 * variable = the environment variable to get, in the GLib file name 731 * encoding 732 * 733 * Return: the value of the environment variable, or %NULL if 734 * the environment variable is not found. The returned string 735 * may be overwritten by the next call to g_getenv(), g_setenv() 736 * or g_unsetenv(). 737 */ 738 public static string getenv(string variable) 739 { 740 return Str.toString(g_getenv(Str.toStringz(variable))); 741 } 742 743 /** 744 * Gets the names of all variables set in the environment. 745 * 746 * Programs that want to be portable to Windows should typically use 747 * this function and g_getenv() instead of using the environ array 748 * from the C library directly. On Windows, the strings in the environ 749 * array are in system codepage encoding, while in most of the typical 750 * use cases for environment variables in GLib-using programs you want 751 * the UTF-8 encoding that this function and g_getenv() provide. 752 * 753 * Return: a %NULL-terminated 754 * list of strings which must be freed with g_strfreev(). 755 * 756 * Since: 2.8 757 */ 758 public static string[] listenv() 759 { 760 return Str.toStringArray(g_listenv()); 761 } 762 763 /** 764 * Set the pointer at the specified location to %NULL. 765 * 766 * Params: 767 * nullifyLocation = the memory address of the pointer. 768 */ 769 public static void nullifyPointer(void** nullifyLocation) 770 { 771 g_nullify_pointer(nullifyLocation); 772 } 773 774 /** 775 * Parses a string containing debugging options 776 * into a %guint containing bit flags. This is used 777 * within GDK and GTK+ to parse the debug options passed on the 778 * command line or through environment variables. 779 * 780 * If @string is equal to "all", all flags are set. Any flags 781 * specified along with "all" in @string are inverted; thus, 782 * "all,foo,bar" or "foo,bar,all" sets all flags except those 783 * corresponding to "foo" and "bar". 784 * 785 * If @string is equal to "help", all the available keys in @keys 786 * are printed out to standard error. 787 * 788 * Params: 789 * str = a list of debug options separated by colons, spaces, or 790 * commas, or %NULL. 791 * keys = pointer to an array of #GDebugKey which associate 792 * strings with bit flags. 793 * nkeys = the number of #GDebugKeys in the array. 794 * 795 * Return: the combined set of bit flags. 796 */ 797 public static uint parseDebugString(string str, GDebugKey[] keys) 798 { 799 return g_parse_debug_string(Str.toStringz(str), keys.ptr, cast(uint)keys.length); 800 } 801 802 /** 803 * Gets the last component of the filename. 804 * 805 * If @file_name ends with a directory separator it gets the component 806 * before the last slash. If @file_name consists only of directory 807 * separators (and on Windows, possibly a drive letter), a single 808 * separator is returned. If @file_name is empty, it gets ".". 809 * 810 * Params: 811 * fileName = the name of the file 812 * 813 * Return: a newly allocated string containing the last 814 * component of the filename 815 */ 816 public static string pathGetBasename(string fileName) 817 { 818 return Str.toString(g_path_get_basename(Str.toStringz(fileName))); 819 } 820 821 /** 822 * Gets the directory components of a file name. 823 * 824 * If the file name has no directory components "." is returned. 825 * The returned string should be freed when no longer needed. 826 * 827 * Params: 828 * fileName = the name of the file 829 * 830 * Return: the directory components of the file 831 */ 832 public static string pathGetDirname(string fileName) 833 { 834 return Str.toString(g_path_get_dirname(Str.toStringz(fileName))); 835 } 836 837 /** 838 * Returns %TRUE if the given @file_name is an absolute file name. 839 * Note that this is a somewhat vague concept on Windows. 840 * 841 * On POSIX systems, an absolute file name is well-defined. It always 842 * starts from the single root directory. For example "/usr/local". 843 * 844 * On Windows, the concepts of current drive and drive-specific 845 * current directory introduce vagueness. This function interprets as 846 * an absolute file name one that either begins with a directory 847 * separator such as "\Users\tml" or begins with the root on a drive, 848 * for example "C:\Windows". The first case also includes UNC paths 849 * such as "\\myserver\docs\foo". In all cases, either slashes or 850 * backslashes are accepted. 851 * 852 * Note that a file name relative to the current drive root does not 853 * truly specify a file uniquely over time and across processes, as 854 * the current drive is a per-process value and can be changed. 855 * 856 * File names relative the current directory on some specific drive, 857 * such as "D:foo/bar", are not interpreted as absolute by this 858 * function, but they obviously are not relative to the normal current 859 * directory as returned by getcwd() or g_get_current_dir() 860 * either. Such paths should be avoided, or need to be handled using 861 * Windows-specific code. 862 * 863 * Params: 864 * fileName = a file name 865 * 866 * Return: %TRUE if @file_name is absolute 867 */ 868 public static bool pathIsAbsolute(string fileName) 869 { 870 return g_path_is_absolute(Str.toStringz(fileName)) != 0; 871 } 872 873 /** 874 * Returns a pointer into @file_name after the root component, 875 * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name 876 * is not an absolute path it returns %NULL. 877 * 878 * Params: 879 * fileName = a file name 880 * 881 * Return: a pointer into @file_name after the root component 882 */ 883 public static string pathSkipRoot(string fileName) 884 { 885 return Str.toString(g_path_skip_root(Str.toStringz(fileName))); 886 } 887 888 /** 889 * This is just like the standard C qsort() function, but 890 * the comparison routine accepts a user data argument. 891 * 892 * This is guaranteed to be a stable sort since version 2.32. 893 * 894 * Params: 895 * pbase = start of array to sort 896 * totalElems = elements in the array 897 * size = size of each element 898 * compareFunc = function to compare elements 899 * userData = data to pass to @compare_func 900 */ 901 public static void qsortWithData(void* pbase, int totalElems, size_t size, GCompareDataFunc compareFunc, void* userData) 902 { 903 g_qsort_with_data(pbase, totalElems, size, compareFunc, userData); 904 } 905 906 /** 907 * Resets the cache used for g_get_user_special_dir(), so 908 * that the latest on-disk version is used. Call this only 909 * if you just changed the data on disk yourself. 910 * 911 * Due to threadsafety issues this may cause leaking of strings 912 * that were previously returned from g_get_user_special_dir() 913 * that can't be freed. We ensure to only leak the data for 914 * the directories that actually changed value though. 915 * 916 * Since: 2.22 917 */ 918 public static void reloadUserSpecialDirsCache() 919 { 920 g_reload_user_special_dirs_cache(); 921 } 922 923 /** 924 * Sets a human-readable name for the application. This name should be 925 * localized if possible, and is intended for display to the user. 926 * Contrast with g_set_prgname(), which sets a non-localized name. 927 * g_set_prgname() will be called automatically by gtk_init(), 928 * but g_set_application_name() will not. 929 * 930 * Note that for thread safety reasons, this function can only 931 * be called once. 932 * 933 * The application name will be used in contexts such as error messages, 934 * or when displaying an application's name in the task list. 935 * 936 * Params: 937 * applicationName = localized name of the application 938 * 939 * Since: 2.2 940 */ 941 public static void setApplicationName(string applicationName) 942 { 943 g_set_application_name(Str.toStringz(applicationName)); 944 } 945 946 /** 947 * Sets the name of the program. This name should not be localized, 948 * in contrast to g_set_application_name(). 949 * 950 * Note that for thread-safety reasons this function can only be called once. 951 * 952 * Params: 953 * prgname = the name of the program. 954 */ 955 public static void setPrgname(string prgname) 956 { 957 g_set_prgname(Str.toStringz(prgname)); 958 } 959 960 /** 961 * Sets an environment variable. Both the variable's name and value 962 * should be in the GLib file name encoding. On UNIX, this means that 963 * they can be arbitrary byte strings. On Windows, they should be in 964 * UTF-8. 965 * 966 * Note that on some systems, when variables are overwritten, the memory 967 * used for the previous variables and its value isn't reclaimed. 968 * 969 * You should be mindful of the fact that environment variable handling 970 * in UNIX is not thread-safe, and your program may crash if one thread 971 * calls g_setenv() while another thread is calling getenv(). (And note 972 * that many functions, such as gettext(), call getenv() internally.) 973 * This function is only safe to use at the very start of your program, 974 * before creating any other threads (or creating objects that create 975 * worker threads of their own). 976 * 977 * If you need to set up the environment for a child process, you can 978 * use g_get_environ() to get an environment array, modify that with 979 * g_environ_setenv() and g_environ_unsetenv(), and then pass that 980 * array directly to execvpe(), g_spawn_async(), or the like. 981 * 982 * Params: 983 * variable = the environment variable to set, must not contain '='. 984 * value = the value for to set the variable to. 985 * overwrite = whether to change the variable if it already exists. 986 * 987 * Return: %FALSE if the environment variable couldn't be set. 988 * 989 * Since: 2.4 990 */ 991 public static bool setenv(string variable, string value, bool overwrite) 992 { 993 return g_setenv(Str.toStringz(variable), Str.toStringz(value), overwrite) != 0; 994 } 995 996 /** 997 * Gets the smallest prime number from a built-in array of primes which 998 * is larger than @num. This is used within GLib to calculate the optimum 999 * size of a #GHashTable. 1000 * 1001 * The built-in array of primes ranges from 11 to 13845163 such that 1002 * each prime is approximately 1.5-2 times the previous prime. 1003 * 1004 * Params: 1005 * num = a #guint 1006 * 1007 * Return: the smallest prime number from a built-in array of primes 1008 * which is larger than @num 1009 */ 1010 public static uint spacedPrimesClosest(uint num) 1011 { 1012 return g_spaced_primes_closest(num); 1013 } 1014 1015 /** 1016 * Removes an environment variable from the environment. 1017 * 1018 * Note that on some systems, when variables are overwritten, the 1019 * memory used for the previous variables and its value isn't reclaimed. 1020 * 1021 * You should be mindful of the fact that environment variable handling 1022 * in UNIX is not thread-safe, and your program may crash if one thread 1023 * calls g_unsetenv() while another thread is calling getenv(). (And note 1024 * that many functions, such as gettext(), call getenv() internally.) This 1025 * function is only safe to use at the very start of your program, before 1026 * creating any other threads (or creating objects that create worker 1027 * threads of their own). 1028 * 1029 * If you need to set up the environment for a child process, you can 1030 * use g_get_environ() to get an environment array, modify that with 1031 * g_environ_setenv() and g_environ_unsetenv(), and then pass that 1032 * array directly to execvpe(), g_spawn_async(), or the like. 1033 * 1034 * Params: 1035 * variable = the environment variable to remove, must not contain '=' 1036 * 1037 * Since: 2.4 1038 */ 1039 public static void unsetenv(string variable) 1040 { 1041 g_unsetenv(Str.toStringz(variable)); 1042 } 1043 }