glib/auto/functions.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556
// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT
#[cfg(feature = "v2_66")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
use crate::FileSetContentsFlags;
use crate::{
ffi, translate::*, Bytes, ChecksumType, Error, FileTest, FormatSizeFlags, Pid, Source,
SpawnFlags, UserDirectory,
};
use std::boxed::Box as Box_;
/// A wrapper for the POSIX access() function. This function is used to
/// test a pathname for one or several of read, write or execute
/// permissions, or just existence.
///
/// On Windows, the file protection mechanism is not at all POSIX-like,
/// and the underlying function in the C library only checks the
/// FAT-style READONLY attribute, and does not look at the ACL of a
/// file at all. This function is this in practise almost useless on
/// Windows. Software that needs to handle file permissions on Windows
/// more exactly should use the Win32 API.
///
/// See your C library manual for more details about access().
/// ## `filename`
/// a pathname in the GLib file name encoding
/// (UTF-8 on Windows)
/// ## `mode`
/// as in access()
///
/// # Returns
///
/// zero if the pathname refers to an existing file system
/// object that has all the tested permissions, or -1 otherwise
/// or on error.
#[doc(alias = "g_access")]
pub fn access(filename: impl AsRef<std::path::Path>, mode: i32) -> i32 {
unsafe { ffi::g_access(filename.as_ref().to_glib_none().0, mode) }
}
/// Decode a sequence of Base-64 encoded text into binary data. Note
/// that the returned binary data is not necessarily zero-terminated,
/// so it should not be used as a character string.
/// ## `text`
/// zero-terminated string with base64 text to decode
///
/// # Returns
///
///
/// newly allocated buffer containing the binary data
/// that @text represents. The returned buffer must
/// be freed with g_free().
#[doc(alias = "g_base64_decode")]
pub fn base64_decode(text: &str) -> Vec<u8> {
unsafe {
let mut out_len = std::mem::MaybeUninit::uninit();
let ret = FromGlibContainer::from_glib_full_num(
ffi::g_base64_decode(text.to_glib_none().0, out_len.as_mut_ptr()),
out_len.assume_init() as _,
);
ret
}
}
//#[doc(alias = "g_base64_decode_inplace")]
//pub fn base64_decode_inplace(text: /*Unimplemented*/Vec<u8>) -> u8 {
// unsafe { TODO: call ffi:g_base64_decode_inplace() }
//}
//#[doc(alias = "g_base64_decode_step")]
//pub fn base64_decode_step(in_: &[u8], out: Vec<u8>, state: &mut i32, save: &mut u32) -> usize {
// unsafe { TODO: call ffi:g_base64_decode_step() }
//}
/// Encode a sequence of binary data into its Base-64 stringified
/// representation.
/// ## `data`
/// the binary data to encode
///
/// # Returns
///
/// a newly allocated, zero-terminated Base-64
/// encoded string representing @data. The returned string must
/// be freed with g_free().
#[doc(alias = "g_base64_encode")]
pub fn base64_encode(data: &[u8]) -> crate::GString {
let len = data.len() as _;
unsafe { from_glib_full(ffi::g_base64_encode(data.to_glib_none().0, len)) }
}
//#[doc(alias = "g_base64_encode_close")]
//pub fn base64_encode_close(break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
// unsafe { TODO: call ffi:g_base64_encode_close() }
//}
//#[doc(alias = "g_base64_encode_step")]
//pub fn base64_encode_step(in_: &[u8], break_lines: bool, out: Vec<u8>, state: &mut i32, save: &mut i32) -> usize {
// unsafe { TODO: call ffi:g_base64_encode_step() }
//}
/// Checks that the GLib library in use is compatible with the
/// given version.
///
/// Generally you would pass in the constants `GLIB_MAJOR_VERSION`,
/// `GLIB_MINOR_VERSION`, `GLIB_MICRO_VERSION` as the three arguments
/// to this function; that produces a check that the library in use
/// is compatible with the version of GLib the application or module
/// was compiled against.
///
/// Compatibility is defined by two things: first the version
/// of the running library is newer than the version
/// `@required_major.required_minor.@required_micro`. Second
/// the running library must be binary compatible with the
/// version `@required_major.@required_minor.@required_micro`
/// (same major version.)
/// ## `required_major`
/// the required major version
/// ## `required_minor`
/// the required minor version
/// ## `required_micro`
/// the required micro version
///
/// # Returns
///
/// [`None`] if the GLib library is
/// compatible with the given version, or a string describing the
/// version mismatch. The returned string is owned by GLib and must
/// not be modified or freed.
#[doc(alias = "glib_check_version")]
pub fn check_version(
required_major: u32,
required_minor: u32,
required_micro: u32,
) -> Option<crate::GString> {
unsafe {
from_glib_none(ffi::glib_check_version(
required_major,
required_minor,
required_micro,
))
}
}
/// Computes the checksum for a binary @data. This is a
/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
/// and g_checksum_free().
///
/// The hexadecimal string returned will be in lower case.
/// ## `checksum_type`
/// a #GChecksumType
/// ## `data`
/// binary blob to compute the digest of
///
/// # Returns
///
/// the digest of the binary data as a
/// string in hexadecimal, or [`None`] if g_checksum_new() fails for
/// @checksum_type. The returned string should be freed with g_free() when
/// done using it.
#[doc(alias = "g_compute_checksum_for_bytes")]
pub fn compute_checksum_for_bytes(
checksum_type: ChecksumType,
data: &Bytes,
) -> Option<crate::GString> {
unsafe {
from_glib_full(ffi::g_compute_checksum_for_bytes(
checksum_type.into_glib(),
data.to_glib_none().0,
))
}
}
/// Computes the checksum for a binary @data of @length. This is a
/// convenience wrapper for g_checksum_new(), g_checksum_get_string()
/// and g_checksum_free().
///
/// The hexadecimal string returned will be in lower case.
/// ## `checksum_type`
/// a #GChecksumType
/// ## `data`
/// binary blob to compute the digest of
///
/// # Returns
///
/// the digest of the binary data as a
/// string in hexadecimal, or [`None`] if g_checksum_new() fails for
/// @checksum_type. The returned string should be freed with g_free() when
/// done using it.
#[doc(alias = "g_compute_checksum_for_data")]
pub fn compute_checksum_for_data(
checksum_type: ChecksumType,
data: &[u8],
) -> Option<crate::GString> {
let length = data.len() as _;
unsafe {
from_glib_full(ffi::g_compute_checksum_for_data(
checksum_type.into_glib(),
data.to_glib_none().0,
length,
))
}
}
/// Computes the HMAC for a binary @data. This is a
/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
/// and g_hmac_unref().
///
/// The hexadecimal string returned will be in lower case.
/// ## `digest_type`
/// a #GChecksumType to use for the HMAC
/// ## `key`
/// the key to use in the HMAC
/// ## `data`
/// binary blob to compute the HMAC of
///
/// # Returns
///
/// the HMAC of the binary data as a string in hexadecimal.
/// The returned string should be freed with g_free() when done using it.
#[doc(alias = "g_compute_hmac_for_bytes")]
pub fn compute_hmac_for_bytes(
digest_type: ChecksumType,
key: &Bytes,
data: &Bytes,
) -> crate::GString {
unsafe {
from_glib_full(ffi::g_compute_hmac_for_bytes(
digest_type.into_glib(),
key.to_glib_none().0,
data.to_glib_none().0,
))
}
}
/// Computes the HMAC for a binary @data of @length. This is a
/// convenience wrapper for g_hmac_new(), g_hmac_get_string()
/// and g_hmac_unref().
///
/// The hexadecimal string returned will be in lower case.
/// ## `digest_type`
/// a #GChecksumType to use for the HMAC
/// ## `key`
/// the key to use in the HMAC
/// ## `data`
/// binary blob to compute the HMAC of
///
/// # Returns
///
/// the HMAC of the binary data as a string in hexadecimal.
/// The returned string should be freed with g_free() when done using it.
#[doc(alias = "g_compute_hmac_for_data")]
pub fn compute_hmac_for_data(digest_type: ChecksumType, key: &[u8], data: &[u8]) -> crate::GString {
let key_len = key.len() as _;
let length = data.len() as _;
unsafe {
from_glib_full(ffi::g_compute_hmac_for_data(
digest_type.into_glib(),
key.to_glib_none().0,
key_len,
data.to_glib_none().0,
length,
))
}
}
/// This is a variant of g_dgettext() that allows specifying a locale
/// category instead of always using `LC_MESSAGES`. See g_dgettext() for
/// more information about how this functions differs from calling
/// dcgettext() directly.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
/// the domain set with textdomain()
/// ## `msgid`
/// message to translate
/// ## `category`
/// a locale category
///
/// # Returns
///
/// the translated string for the given locale category
#[doc(alias = "g_dcgettext")]
pub fn dcgettext(domain: Option<&str>, msgid: &str, category: i32) -> crate::GString {
unsafe {
from_glib_none(ffi::g_dcgettext(
domain.to_glib_none().0,
msgid.to_glib_none().0,
category,
))
}
}
/// This function is a wrapper of dgettext() which does not translate
/// the message if the default domain as set with textdomain() has no
/// translations for the current locale.
///
/// The advantage of using this function over dgettext() proper is that
/// libraries using this function (like GTK) will not use translations
/// if the application using the library does not have translations for
/// the current locale. This results in a consistent English-only
/// interface instead of one having partial translations. For this
/// feature to work, the call to textdomain() and setlocale() should
/// precede any g_dgettext() invocations. For GTK, it means calling
/// textdomain() before gtk_init or its variants.
///
/// This function disables translations if and only if upon its first
/// call all the following conditions hold:
///
/// - @domain is not [`None`]
///
/// - textdomain() has been called to set a default text domain
///
/// - there is no translations available for the default text domain
/// and the current locale
///
/// - current locale is not "C" or any English locales (those
/// starting with "en_")
///
/// Note that this behavior may not be desired for example if an application
/// has its untranslated messages in a language other than English. In those
/// cases the application should call textdomain() after initializing GTK.
///
/// Applications should normally not use this function directly,
/// but use the _() macro for translations.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
/// the domain set with textdomain()
/// ## `msgid`
/// message to translate
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dgettext")]
pub fn dgettext(domain: Option<&str>, msgid: &str) -> crate::GString {
unsafe {
from_glib_none(ffi::g_dgettext(
domain.to_glib_none().0,
msgid.to_glib_none().0,
))
}
}
/// This function is a wrapper of dngettext() which does not translate
/// the message if the default domain as set with textdomain() has no
/// translations for the current locale.
///
/// See g_dgettext() for details of how this differs from dngettext()
/// proper.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
/// the domain set with textdomain()
/// ## `msgid`
/// message to translate
/// ## `msgid_plural`
/// plural form of the message
/// ## `n`
/// the quantity for which translation is needed
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dngettext")]
pub fn dngettext(
domain: Option<&str>,
msgid: &str,
msgid_plural: &str,
n: libc::c_ulong,
) -> crate::GString {
unsafe {
from_glib_none(ffi::g_dngettext(
domain.to_glib_none().0,
msgid.to_glib_none().0,
msgid_plural.to_glib_none().0,
n,
))
}
}
/// This function is a variant of g_dgettext() which supports
/// a disambiguating message context. GNU gettext uses the
/// '\004' character to separate the message context and
/// message id in @msgctxtid.
/// If 0 is passed as @msgidoffset, this function will fall back to
/// trying to use the deprecated convention of using "|" as a separation
/// character.
///
/// This uses g_dgettext() internally. See that functions for differences
/// with dgettext() proper.
///
/// Applications should normally not use this function directly,
/// but use the C_() macro for translations with context.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
/// the domain set with textdomain()
/// ## `msgctxtid`
/// a combined message context and message id, separated
/// by a \004 character
/// ## `msgidoffset`
/// the offset of the message id in @msgctxid
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dpgettext")]
pub fn dpgettext(domain: Option<&str>, msgctxtid: &str, msgidoffset: usize) -> crate::GString {
unsafe {
from_glib_none(ffi::g_dpgettext(
domain.to_glib_none().0,
msgctxtid.to_glib_none().0,
msgidoffset,
))
}
}
/// This function is a variant of g_dgettext() which supports
/// a disambiguating message context. GNU gettext uses the
/// '\004' character to separate the message context and
/// message id in @msgctxtid.
///
/// This uses g_dgettext() internally. See that functions for differences
/// with dgettext() proper.
///
/// This function differs from C_() in that it is not a macro and
/// thus you may use non-string-literals as context and msgid arguments.
/// ## `domain`
/// the translation domain to use, or [`None`] to use
/// the domain set with textdomain()
/// ## `context`
/// the message context
/// ## `msgid`
/// the message
///
/// # Returns
///
/// The translated string
#[doc(alias = "g_dpgettext2")]
pub fn dpgettext2(domain: Option<&str>, context: &str, msgid: &str) -> crate::GString {
unsafe {
from_glib_none(ffi::g_dpgettext2(
domain.to_glib_none().0,
context.to_glib_none().0,
msgid.to_glib_none().0,
))
}
}
/// Writes all of @contents to a file named @filename. This is a convenience
/// wrapper around calling g_file_set_contents_full() with `flags` set to
/// `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
/// `mode` set to `0666`.
/// ## `filename`
/// name of a file to write @contents to, in the GLib file name
/// encoding
/// ## `contents`
/// string to write to the file
///
/// # Returns
///
/// [`true`] on success, [`false`] if an error occurred
#[doc(alias = "g_file_set_contents")]
pub fn file_set_contents(
filename: impl AsRef<std::path::Path>,
contents: &[u8],
) -> Result<(), crate::Error> {
let length = contents.len() as _;
unsafe {
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_file_set_contents(
filename.as_ref().to_glib_none().0,
contents.to_glib_none().0,
length,
&mut error,
);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(())
} else {
Err(from_glib_full(error))
}
}
}
/// Writes all of @contents to a file named @filename, with good error checking.
/// If a file called @filename already exists it will be overwritten.
///
/// @flags control the properties of the write operation: whether it’s atomic,
/// and what the tradeoff is between returning quickly or being resilient to
/// system crashes.
///
/// As this function performs file I/O, it is recommended to not call it anywhere
/// where blocking would cause problems, such as in the main loop of a graphical
/// application. In particular, if @flags has any value other than
/// [`FileSetContentsFlags::NONE`][crate::FileSetContentsFlags::NONE] then this function may call `fsync()`.
///
/// If [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the operation is atomic
/// in the sense that it is first written to a temporary file which is then
/// renamed to the final name.
///
/// Notes:
///
/// - On UNIX, if @filename already exists hard links to @filename will break.
/// Also since the file is recreated, existing permissions, access control
/// lists, metadata etc. may be lost. If @filename is a symbolic link,
/// the link itself will be replaced, not the linked file.
///
/// - On UNIX, if @filename already exists and is non-empty, and if the system
/// supports it (via a journalling filesystem or equivalent), and if
/// [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] is set in @flags, the `fsync()` call (or
/// equivalent) will be used to ensure atomic replacement: @filename
/// will contain either its old contents or @contents, even in the face of
/// system power loss, the disk being unsafely removed, etc.
///
/// - On UNIX, if @filename does not already exist or is empty, there is a
/// possibility that system power loss etc. after calling this function will
/// leave @filename empty or full of NUL bytes, depending on the underlying
/// filesystem, unless [`FileSetContentsFlags::DURABLE`][crate::FileSetContentsFlags::DURABLE] and
/// [`FileSetContentsFlags::CONSISTENT`][crate::FileSetContentsFlags::CONSISTENT] are set in @flags.
///
/// - On Windows renaming a file will not remove an existing file with the
/// new name, so on Windows there is a race condition between the existing
/// file being removed and the temporary file being renamed.
///
/// - On Windows there is no way to remove a file that is open to some
/// process, or mapped into memory. Thus, this function will fail if
/// @filename already exists and is open.
///
/// If the call was successful, it returns [`true`]. If the call was not successful,
/// it returns [`false`] and sets @error. The error domain is `G_FILE_ERROR`.
/// Possible error codes are those in the #GFileError enumeration.
///
/// Note that the name for the temporary file is constructed by appending up
/// to 7 characters to @filename.
///
/// If the file didn’t exist before and is created, it will be given the
/// permissions from @mode. Otherwise, the permissions of the existing file may
/// be changed to @mode depending on @flags, or they may remain unchanged.
/// ## `filename`
/// name of a file to write @contents to, in the GLib file name
/// encoding
/// ## `contents`
/// string to write to the file
/// ## `flags`
/// flags controlling the safety vs speed of the operation
/// ## `mode`
/// file mode, as passed to `open()`; typically this will be `0666`
///
/// # Returns
///
/// [`true`] on success, [`false`] if an error occurred
#[cfg(feature = "v2_66")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_66")))]
#[doc(alias = "g_file_set_contents_full")]
pub fn file_set_contents_full(
filename: impl AsRef<std::path::Path>,
contents: &[u8],
flags: FileSetContentsFlags,
mode: i32,
) -> Result<(), crate::Error> {
let length = contents.len() as _;
unsafe {
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_file_set_contents_full(
filename.as_ref().to_glib_none().0,
contents.to_glib_none().0,
length,
flags.into_glib(),
mode,
&mut error,
);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(())
} else {
Err(from_glib_full(error))
}
}
}
/// Returns [`true`] if any of the tests in the bitfield @test are
/// [`true`]. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
/// will return [`true`] if the file exists; the check whether it's a
/// directory doesn't matter since the existence test is [`true`]. With
/// the current set of available tests, there's no point passing in
/// more than one test at a time.
///
/// Apart from [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] all tests follow symbolic links,
/// so for a symbolic link to a regular file g_file_test() will return
/// [`true`] for both [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`FileTest::IS_REGULAR`][crate::FileTest::IS_REGULAR].
///
/// Note, that for a dangling symbolic link g_file_test() will return
/// [`true`] for [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] and [`false`] for all other flags.
///
/// You should never use g_file_test() to test whether it is safe
/// to perform an operation, because there is always the possibility
/// of the condition changing before you actually perform the operation,
/// see [TOCTOU](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use).
///
/// For example, you might think you could use [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK]
/// to know whether it is safe to write to a file without being
/// tricked into writing into a different location. It doesn't work!
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// // DON'T DO THIS
/// if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
/// {
/// fd = g_open (filename, O_WRONLY);
/// // write to fd
/// }
///
/// // DO THIS INSTEAD
/// fd = g_open (filename, O_WRONLY | O_NOFOLLOW | O_CLOEXEC);
/// if (fd == -1)
/// {
/// // check error
/// if (errno == ELOOP)
/// // file is a symlink and can be ignored
/// else
/// // handle errors as before
/// }
/// else
/// {
/// // write to fd
/// }
/// ```
///
/// Another thing to note is that [`FileTest::EXISTS`][crate::FileTest::EXISTS] and
/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] are implemented using the access()
/// system call. This usually doesn't matter, but if your program
/// is setuid or setgid it means that these tests will give you
/// the answer for the real user ID and group ID, rather than the
/// effective user ID and group ID.
///
/// On Windows, there are no symlinks, so testing for
/// [`FileTest::IS_SYMLINK`][crate::FileTest::IS_SYMLINK] will always return [`false`]. Testing for
/// [`FileTest::IS_EXECUTABLE`][crate::FileTest::IS_EXECUTABLE] will just check that the file exists and
/// its name indicates that it is executable, checking for well-known
/// extensions and those listed in the `PATHEXT` environment variable.
/// ## `filename`
/// a filename to test in the
/// GLib file name encoding
/// ## `test`
/// bitfield of #GFileTest flags
///
/// # Returns
///
/// whether a test was [`true`]
#[doc(alias = "g_file_test")]
#[allow(dead_code)]
pub(crate) fn file_test(filename: impl AsRef<std::path::Path>, test: FileTest) -> bool {
unsafe {
from_glib(ffi::g_file_test(
filename.as_ref().to_glib_none().0,
test.into_glib(),
))
}
}
/// Returns the display basename for the particular filename, guaranteed
/// to be valid UTF-8. The display name might not be identical to the filename,
/// for instance there might be problems converting it to UTF-8, and some files
/// can be translated in the display.
///
/// If GLib cannot make sense of the encoding of @filename, as a last resort it
/// replaces unknown characters with U+FFFD, the Unicode replacement character.
/// You can search the result for the UTF-8 encoding of this character (which is
/// "\357\277\275" in octal notation) to find out if @filename was in an invalid
/// encoding.
///
/// You must pass the whole absolute pathname to this functions so that
/// translation of well known locations can be done.
///
/// This function is preferred over g_filename_display_name() if you know the
/// whole path, as it allows translation.
/// ## `filename`
/// an absolute pathname in the
/// GLib file name encoding
///
/// # Returns
///
/// a newly allocated string containing
/// a rendition of the basename of the filename in valid UTF-8
#[doc(alias = "g_filename_display_basename")]
pub fn filename_display_basename(filename: impl AsRef<std::path::Path>) -> crate::GString {
unsafe {
from_glib_full(ffi::g_filename_display_basename(
filename.as_ref().to_glib_none().0,
))
}
}
/// Converts a filename into a valid UTF-8 string. The conversion is
/// not necessarily reversible, so you should keep the original around
/// and use the return value of this function only for display purposes.
/// Unlike g_filename_to_utf8(), the result is guaranteed to be non-[`None`]
/// even if the filename actually isn't in the GLib file name encoding.
///
/// If GLib cannot make sense of the encoding of @filename, as a last resort it
/// replaces unknown characters with U+FFFD, the Unicode replacement character.
/// You can search the result for the UTF-8 encoding of this character (which is
/// "\357\277\275" in octal notation) to find out if @filename was in an invalid
/// encoding.
///
/// If you know the whole pathname of the file you should use
/// g_filename_display_basename(), since that allows location-based
/// translation of filenames.
/// ## `filename`
/// a pathname hopefully in the
/// GLib file name encoding
///
/// # Returns
///
/// a newly allocated string containing
/// a rendition of the filename in valid UTF-8
#[doc(alias = "g_filename_display_name")]
pub fn filename_display_name(filename: impl AsRef<std::path::Path>) -> crate::GString {
unsafe {
from_glib_full(ffi::g_filename_display_name(
filename.as_ref().to_glib_none().0,
))
}
}
/// Converts an escaped ASCII-encoded URI to a local filename in the
/// encoding used for filenames.
///
/// Since GLib 2.78, the query string and fragment can be present in the URI,
/// but are not part of the resulting filename.
/// We take inspiration from https://url.spec.whatwg.org/#file-state,
/// but we don't support the entire standard.
/// ## `uri`
/// a uri describing a filename (escaped, encoded in ASCII).
///
/// # Returns
///
/// a newly-allocated string holding
/// the resulting filename, or [`None`] on an error.
///
/// ## `hostname`
/// Location to store hostname for the URI.
/// If there is no hostname in the URI, [`None`] will be
/// stored in this location.
#[doc(alias = "g_filename_from_uri")]
pub fn filename_from_uri(
uri: &str,
) -> Result<(std::path::PathBuf, Option<crate::GString>), crate::Error> {
unsafe {
let mut hostname = std::ptr::null_mut();
let mut error = std::ptr::null_mut();
let ret = ffi::g_filename_from_uri(uri.to_glib_none().0, &mut hostname, &mut error);
if error.is_null() {
Ok((from_glib_full(ret), from_glib_full(hostname)))
} else {
Err(from_glib_full(error))
}
}
}
/// Converts an absolute filename to an escaped ASCII-encoded URI, with the path
/// component following Section 3.3. of RFC 2396.
/// ## `filename`
/// an absolute filename specified in the GLib file
/// name encoding, which is the on-disk file name bytes on Unix, and UTF-8
/// on Windows
/// ## `hostname`
/// A UTF-8 encoded hostname, or [`None`] for none.
///
/// # Returns
///
/// a newly-allocated string holding the resulting
/// URI, or [`None`] on an error.
#[doc(alias = "g_filename_to_uri")]
pub fn filename_to_uri(
filename: impl AsRef<std::path::Path>,
hostname: Option<&str>,
) -> Result<crate::GString, crate::Error> {
unsafe {
let mut error = std::ptr::null_mut();
let ret = ffi::g_filename_to_uri(
filename.as_ref().to_glib_none().0,
hostname.to_glib_none().0,
&mut error,
);
if error.is_null() {
Ok(from_glib_full(ret))
} else {
Err(from_glib_full(error))
}
}
}
/// Locates the first executable named @program in the user's path, in the
/// same way that execvp() would locate it. Returns an allocated string
/// with the absolute path name, or [`None`] if the program is not found in
/// the path. If @program is already an absolute path, returns a copy of
/// @program if @program exists and is executable, and [`None`] otherwise.
///
/// On Windows, if @program does not have a file type suffix, tries
/// with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
/// the `PATHEXT` environment variable.
///
/// On Windows, it looks for the file in the same way as CreateProcess()
/// would. This means first in the directory where the executing
/// program was loaded from, then in the current directory, then in the
/// Windows 32-bit system directory, then in the Windows directory, and
/// finally in the directories in the `PATH` environment variable. If
/// the program is found, the return value contains the full name
/// including the type suffix.
/// ## `program`
/// a program name in the GLib file name encoding
///
/// # Returns
///
/// a newly-allocated
/// string with the absolute path, or [`None`]
#[doc(alias = "g_find_program_in_path")]
pub fn find_program_in_path(program: impl AsRef<std::path::Path>) -> Option<std::path::PathBuf> {
unsafe {
from_glib_full(ffi::g_find_program_in_path(
program.as_ref().to_glib_none().0,
))
}
}
/// Formats a size (for example the size of a file) into a human readable
/// string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
/// and are displayed rounded to the nearest tenth. E.g. the file size
/// 3292528 bytes will be converted into the string "3.2 MB". The returned string
/// is UTF-8, and may use a non-breaking space to separate the number and units,
/// to ensure they aren’t separated when line wrapped.
///
/// The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
///
/// This string should be freed with g_free() when not needed any longer.
///
/// See g_format_size_full() for more options about how the size might be
/// formatted.
/// ## `size`
/// a size in bytes
///
/// # Returns
///
/// a newly-allocated formatted string containing
/// a human readable file size
#[doc(alias = "g_format_size")]
pub fn format_size(size: u64) -> crate::GString {
unsafe { from_glib_full(ffi::g_format_size(size)) }
}
/// Formats a size.
///
/// This function is similar to g_format_size() but allows for flags
/// that modify the output. See #GFormatSizeFlags.
/// ## `size`
/// a size in bytes
/// ## `flags`
/// #GFormatSizeFlags to modify the output
///
/// # Returns
///
/// a newly-allocated formatted string
/// containing a human readable file size
#[doc(alias = "g_format_size_full")]
pub fn format_size_full(size: u64, flags: FormatSizeFlags) -> crate::GString {
unsafe { from_glib_full(ffi::g_format_size_full(size, flags.into_glib())) }
}
/// Gets a human-readable name for the application, as set by
/// g_set_application_name(). This name should be localized if
/// possible, and is intended for display to the user. Contrast with
/// g_get_prgname(), which gets a non-localized name. If
/// g_set_application_name() has not been called, returns the result of
/// g_get_prgname() (which may be [`None`] if g_set_prgname() has also not
/// been called).
///
/// # Returns
///
/// human-readable application
/// name. May return [`None`]
#[doc(alias = "g_get_application_name")]
#[doc(alias = "get_application_name")]
pub fn application_name() -> Option<crate::GString> {
unsafe { from_glib_none(ffi::g_get_application_name()) }
}
/// Gets the character set for the current locale.
///
/// # Returns
///
/// a newly allocated string containing the name
/// of the character set. This string must be freed with g_free().
#[doc(alias = "g_get_codeset")]
#[doc(alias = "get_codeset")]
pub fn codeset() -> crate::GString {
unsafe { from_glib_full(ffi::g_get_codeset()) }
}
/// Obtains the character set used by the console attached to the process,
/// which is suitable for printing output to the terminal.
///
/// Usually this matches the result returned by g_get_charset(), but in
/// environments where the locale's character set does not match the encoding
/// of the console this function tries to guess a more suitable value instead.
///
/// On Windows the character set returned by this function is the
/// output code page used by the console associated with the calling process.
/// If the codepage can't be determined (for example because there is no
/// console attached) UTF-8 is assumed.
///
/// The return value is [`true`] if the locale's encoding is UTF-8, in that
/// case you can perhaps avoid calling g_convert().
///
/// The string returned in @charset is not allocated, and should not be
/// freed.
///
/// # Returns
///
/// [`true`] if the returned charset is UTF-8
///
/// ## `charset`
/// return location for character set
/// name, or [`None`].
#[cfg(feature = "v2_62")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
#[doc(alias = "g_get_console_charset")]
#[doc(alias = "get_console_charset")]
pub fn console_charset() -> Option<crate::GString> {
unsafe {
let mut charset = std::ptr::null();
let ret = from_glib(ffi::g_get_console_charset(&mut charset));
if ret {
Some(from_glib_none(charset))
} else {
None
}
}
}
/// Gets the current directory.
///
/// The returned string should be freed when no longer needed.
/// The encoding of the returned string is system defined.
/// On Windows, it is always UTF-8.
///
/// Since GLib 2.40, this function will return the value of the "PWD"
/// environment variable if it is set and it happens to be the same as
/// the current directory. This can make a difference in the case that
/// the current directory is the target of a symbolic link.
///
/// # Returns
///
/// the current directory
#[doc(alias = "g_get_current_dir")]
#[doc(alias = "get_current_dir")]
pub fn current_dir() -> std::path::PathBuf {
unsafe { from_glib_full(ffi::g_get_current_dir()) }
}
/// Gets the list of environment variables for the current process.
///
/// The list is [`None`] terminated and each item in the list is of the
/// form 'NAME=VALUE'.
///
/// This is equivalent to direct access to the 'environ' global variable,
/// except portable.
///
/// The return value is freshly allocated and it should be freed with
/// g_strfreev() when it is no longer needed.
///
/// # Returns
///
///
/// the list of environment variables
#[doc(alias = "g_get_environ")]
#[doc(alias = "get_environ")]
pub fn environ() -> Vec<std::ffi::OsString> {
unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_get_environ()) }
}
/// Gets the current user's home directory.
///
/// As with most UNIX tools, this function will return the value of the
/// `HOME` environment variable if it is set to an existing absolute path
/// name, falling back to the `passwd` file in the case that it is unset.
///
/// If the path given in `HOME` is non-absolute, does not exist, or is
/// not a directory, the result is undefined.
///
/// Before version 2.36 this function would ignore the `HOME` environment
/// variable, taking the value from the `passwd` database instead. This was
/// changed to increase the compatibility of GLib with other programs (and
/// the XDG basedir specification) and to increase testability of programs
/// based on GLib (by making it easier to run them from test frameworks).
///
/// If your program has a strong requirement for either the new or the
/// old behaviour (and if you don't wish to increase your GLib
/// dependency to ensure that the new behaviour is in effect) then you
/// should either directly check the `HOME` environment variable yourself
/// or unset it before calling any functions in GLib.
///
/// # Returns
///
/// the current user's home directory
#[doc(alias = "g_get_home_dir")]
#[doc(alias = "get_home_dir")]
pub fn home_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_home_dir()) }
}
/// Return a name for the machine.
///
/// The returned name is not necessarily a fully-qualified domain name,
/// or even present in DNS or some other name service at all. It need
/// not even be unique on your local network or site, but usually it
/// is. Callers should not rely on the return value having any specific
/// properties like uniqueness for security purposes. Even if the name
/// of the machine is changed while an application is running, the
/// return value from this function does not change. The returned
/// string is owned by GLib and should not be modified or freed. If no
/// name can be determined, a default fixed string "localhost" is
/// returned.
///
/// The encoding of the returned string is UTF-8.
///
/// # Returns
///
/// the host name of the machine.
#[doc(alias = "g_get_host_name")]
#[doc(alias = "get_host_name")]
pub fn host_name() -> crate::GString {
unsafe { from_glib_none(ffi::g_get_host_name()) }
}
/// Computes a list of applicable locale names, which can be used to
/// e.g. construct locale-dependent filenames or search paths. The returned
/// list is sorted from most desirable to least desirable and always contains
/// the default locale "C".
///
/// For example, if LANGUAGE=de:en_US, then the returned list is
/// "de", "en_US", "en", "C".
///
/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
/// `LC_MESSAGES` and `LANG` to find the list of locales specified by the
/// user.
///
/// # Returns
///
/// a [`None`]-terminated array of strings owned by GLib
/// that must not be modified or freed.
#[doc(alias = "g_get_language_names")]
#[doc(alias = "get_language_names")]
pub fn language_names() -> Vec<crate::GString> {
unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names()) }
}
/// Computes a list of applicable locale names with a locale category name,
/// which can be used to construct the fallback locale-dependent filenames
/// or search paths. The returned list is sorted from most desirable to
/// least desirable and always contains the default locale "C".
///
/// This function consults the environment variables `LANGUAGE`, `LC_ALL`,
/// @category_name, and `LANG` to find the list of locales specified by the
/// user.
///
/// g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
/// ## `category_name`
/// a locale category name
///
/// # Returns
///
/// a [`None`]-terminated array of strings owned by
/// the thread g_get_language_names_with_category was called from.
/// It must not be modified or freed. It must be copied if planned to be used in another thread.
#[cfg(feature = "v2_58")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
#[doc(alias = "g_get_language_names_with_category")]
#[doc(alias = "get_language_names_with_category")]
pub fn language_names_with_category(category_name: &str) -> Vec<crate::GString> {
unsafe {
FromGlibPtrContainer::from_glib_none(ffi::g_get_language_names_with_category(
category_name.to_glib_none().0,
))
}
}
/// Returns a list of derived variants of @locale, which can be used to
/// e.g. construct locale-dependent filenames or search paths. The returned
/// list is sorted from most desirable to least desirable.
/// This function handles territory, charset and extra locale modifiers. See
/// [`setlocale(3)`](man:setlocale) for information about locales and their format.
///
/// @locale itself is guaranteed to be returned in the output.
///
/// For example, if @locale is `fr_BE`, then the returned list
/// is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
/// is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
/// `en.UTF-8`, `en@euro`, `en`.
///
/// If you need the list of variants for the current locale,
/// use g_get_language_names().
/// ## `locale`
/// a locale identifier
///
/// # Returns
///
/// a newly
/// allocated array of newly allocated strings with the locale variants. Free with
/// g_strfreev().
#[doc(alias = "g_get_locale_variants")]
#[doc(alias = "get_locale_variants")]
pub fn locale_variants(locale: &str) -> Vec<crate::GString> {
unsafe {
FromGlibPtrContainer::from_glib_full(ffi::g_get_locale_variants(locale.to_glib_none().0))
}
}
/// Queries the system monotonic time.
///
/// The monotonic clock will always increase and doesn't suffer
/// discontinuities when the user (or NTP) changes the system time. It
/// may or may not continue to tick during times where the machine is
/// suspended.
///
/// We try to use the clock that corresponds as closely as possible to
/// the passage of time as measured by system calls such as poll() but it
/// may not always be possible to do this.
///
/// # Returns
///
/// the monotonic time, in microseconds
#[doc(alias = "g_get_monotonic_time")]
#[doc(alias = "get_monotonic_time")]
pub fn monotonic_time() -> i64 {
unsafe { ffi::g_get_monotonic_time() }
}
/// Determine the approximate number of threads that the system will
/// schedule simultaneously for this process. This is intended to be
/// used as a parameter to g_thread_pool_new() for CPU bound tasks and
/// similar cases.
///
/// # Returns
///
/// Number of schedulable threads, always greater than 0
#[doc(alias = "g_get_num_processors")]
#[doc(alias = "get_num_processors")]
pub fn num_processors() -> u32 {
unsafe { ffi::g_get_num_processors() }
}
/// Get information about the operating system.
///
/// On Linux this comes from the `/etc/os-release` file. On other systems, it may
/// come from a variety of sources. You can either use the standard key names
/// like `G_OS_INFO_KEY_NAME` or pass any UTF-8 string key name. For example,
/// `/etc/os-release` provides a number of other less commonly used values that may
/// be useful. No key is guaranteed to be provided, so the caller should always
/// check if the result is [`None`].
/// ## `key_name`
/// a key for the OS info being requested, for example `G_OS_INFO_KEY_NAME`.
///
/// # Returns
///
/// The associated value for the requested key or [`None`] if
/// this information is not provided.
#[cfg(feature = "v2_64")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
#[doc(alias = "g_get_os_info")]
#[doc(alias = "get_os_info")]
pub fn os_info(key_name: &str) -> Option<crate::GString> {
unsafe { from_glib_full(ffi::g_get_os_info(key_name.to_glib_none().0)) }
}
/// Gets the real name of the user. This usually comes from the user's
/// entry in the `passwd` file. The encoding of the returned string is
/// system-defined. (On Windows, it is, however, always UTF-8.) If the
/// real user name cannot be determined, the string "Unknown" is
/// returned.
///
/// # Returns
///
/// the user's real name.
#[doc(alias = "g_get_real_name")]
#[doc(alias = "get_real_name")]
pub fn real_name() -> std::ffi::OsString {
unsafe { from_glib_none(ffi::g_get_real_name()) }
}
/// Queries the system wall-clock time.
///
/// This call is functionally equivalent to `get_current_time()` except
/// that the return value is often more convenient than dealing with a
/// #GTimeVal.
///
/// You should only use this call if you are actually interested in the real
/// wall-clock time. [`monotonic_time()`][crate::monotonic_time()] is probably more useful for
/// measuring intervals.
///
/// # Returns
///
/// the number of microseconds since January 1, 1970 UTC.
#[doc(alias = "g_get_real_time")]
#[doc(alias = "get_real_time")]
pub fn real_time() -> i64 {
unsafe { ffi::g_get_real_time() }
}
/// Returns an ordered list of base directories in which to access
/// system-wide configuration information.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined.
/// If `XDG_CONFIG_DIRS` is undefined, the directory that contains application
/// data for all users is used instead. A typical path is
/// `C:\Documents and Settings\All Users\Application Data`.
/// This folder is used for application data
/// that is not user specific. For example, an application can store
/// a spell-check dictionary, a database of clip art, or a log file in the
/// FOLDERID_ProgramData folder. This information will not roam and is available
/// to anyone using the computer.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
///
/// a [`None`]-terminated array of strings owned by GLib that must not be
/// modified or freed.
#[doc(alias = "g_get_system_config_dirs")]
#[doc(alias = "get_system_config_dirs")]
pub fn system_config_dirs() -> Vec<std::path::PathBuf> {
unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_config_dirs()) }
}
/// Returns an ordered list of base directories in which to access
/// system-wide application data.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
/// In this case the list of directories retrieved will be `XDG_DATA_DIRS`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined.
/// If `XDG_DATA_DIRS` is undefined,
/// the first elements in the list are the Application Data
/// and Documents folders for All Users. (These can be determined only
/// on Windows 2000 or later and are not present in the list on other
/// Windows versions.) See documentation for FOLDERID_ProgramData and
/// FOLDERID_PublicDocuments.
///
/// Then follows the "share" subfolder in the installation folder for
/// the package containing the DLL that calls this function, if it can
/// be determined.
///
/// Finally the list contains the "share" subfolder in the installation
/// folder for GLib, and in the installation folder for the package the
/// application's .exe file belongs to.
///
/// The installation folders above are determined by looking up the
/// folder where the module (DLL or EXE) in question is located. If the
/// folder's name is "bin", its parent is used, otherwise the folder
/// itself.
///
/// Note that on Windows the returned list can vary depending on where
/// this function is called.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
///
/// a [`None`]-terminated array of strings owned by GLib that must not be
/// modified or freed.
#[doc(alias = "g_get_system_data_dirs")]
#[doc(alias = "get_system_data_dirs")]
pub fn system_data_dirs() -> Vec<std::path::PathBuf> {
unsafe { FromGlibPtrContainer::from_glib_none(ffi::g_get_system_data_dirs()) }
}
/// Gets the directory to use for temporary files.
///
/// On UNIX, this is taken from the `TMPDIR` environment variable.
/// If the variable is not set, `P_tmpdir` is
/// used, as defined by the system C library. Failing that, a
/// hard-coded default of "/tmp" is returned.
///
/// On Windows, the `TEMP` environment variable is used, with the
/// root directory of the Windows installation (eg: "C:\") used
/// as a default.
///
/// The encoding of the returned string is system-defined. On Windows,
/// it is always UTF-8. The return value is never [`None`] or the empty
/// string.
///
/// # Returns
///
/// the directory to use for temporary files.
#[doc(alias = "g_get_tmp_dir")]
#[doc(alias = "get_tmp_dir")]
pub fn tmp_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_tmp_dir()) }
}
/// Returns a base directory in which to store non-essential, cached
/// data specific to particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_CACHE_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined.
/// If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
/// repository for temporary Internet files is used instead. A typical path is
/// `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
/// See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
/// must not be modified or freed.
#[doc(alias = "g_get_user_cache_dir")]
#[doc(alias = "get_user_cache_dir")]
pub fn user_cache_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_user_cache_dir()) }
}
/// Returns a base directory in which to store user-specific application
/// configuration information such as user preferences and settings.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_CONFIG_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
/// If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
/// to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be the same
/// as what g_get_user_data_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
/// must not be modified or freed.
#[doc(alias = "g_get_user_config_dir")]
#[doc(alias = "get_user_config_dir")]
pub fn user_config_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_user_config_dir()) }
}
/// Returns a base directory in which to access application data such
/// as icons that is customized for a particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_DATA_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
/// is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
/// opposed to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be the same
/// as what g_get_user_config_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that must
/// not be modified or freed.
#[doc(alias = "g_get_user_data_dir")]
#[doc(alias = "get_user_data_dir")]
pub fn user_data_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_user_data_dir()) }
}
/// Gets the user name of the current user. The encoding of the returned
/// string is system-defined. On UNIX, it might be the preferred file name
/// encoding, or something else, and there is no guarantee that it is even
/// consistent on a machine. On Windows, it is always UTF-8.
///
/// # Returns
///
/// the user name of the current user.
#[doc(alias = "g_get_user_name")]
#[doc(alias = "get_user_name")]
pub fn user_name() -> std::ffi::OsString {
unsafe { from_glib_none(ffi::g_get_user_name()) }
}
/// Returns a directory that is unique to the current user on the local
/// system.
///
/// This is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// This is the directory
/// specified in the `XDG_RUNTIME_DIR` environment variable.
/// In the case that this variable is not set, we return the value of
/// g_get_user_cache_dir(), after verifying that it exists.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that must not be
/// modified or freed.
#[doc(alias = "g_get_user_runtime_dir")]
#[doc(alias = "get_user_runtime_dir")]
pub fn user_runtime_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_user_runtime_dir()) }
}
/// Returns the full path of a special directory using its logical id.
///
/// On UNIX this is done using the XDG special user directories.
/// For compatibility with existing practise, [`UserDirectory::DirectoryDesktop`][crate::UserDirectory::DirectoryDesktop]
/// falls back to `$HOME/Desktop` when XDG special user directories have
/// not been set up.
///
/// Depending on the platform, the user might be able to change the path
/// of the special directory without requiring the session to restart; GLib
/// will not reflect any change once the special directories are loaded.
/// ## `directory`
/// the logical id of special directory
///
/// # Returns
///
/// the path to the specified special
/// directory, or [`None`] if the logical id was not found. The returned string is
/// owned by GLib and should not be modified or freed.
#[doc(alias = "g_get_user_special_dir")]
#[doc(alias = "get_user_special_dir")]
pub fn user_special_dir(directory: UserDirectory) -> Option<std::path::PathBuf> {
unsafe { from_glib_none(ffi::g_get_user_special_dir(directory.into_glib())) }
}
/// Returns a base directory in which to store state files specific to
/// particular user.
///
/// On UNIX platforms this is determined using the mechanisms described
/// in the
/// [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
/// In this case the directory retrieved will be `XDG_STATE_HOME`.
///
/// On Windows it follows XDG Base Directory Specification if `XDG_STATE_HOME` is defined.
/// If `XDG_STATE_HOME` is undefined, the folder to use for local (as opposed
/// to roaming) application data is used instead. See the
/// [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
/// Note that in this case on Windows it will be the same
/// as what g_get_user_data_dir() returns.
///
/// The return value is cached and modifying it at runtime is not supported, as
/// it’s not thread-safe to modify environment variables at runtime.
///
/// # Returns
///
/// a string owned by GLib that
/// must not be modified or freed.
#[cfg(feature = "v2_72")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
#[doc(alias = "g_get_user_state_dir")]
#[doc(alias = "get_user_state_dir")]
pub fn user_state_dir() -> std::path::PathBuf {
unsafe { from_glib_none(ffi::g_get_user_state_dir()) }
}
/// Returns the value of an environment variable.
///
/// On UNIX, the name and value are byte strings which might or might not
/// be in some consistent character set and encoding. On Windows, they are
/// in UTF-8.
/// On Windows, in case the environment variable's value contains
/// references to other environment variables, they are expanded.
/// ## `variable`
/// the environment variable to get
///
/// # Returns
///
/// the value of the environment variable, or [`None`] if
/// the environment variable is not found. The returned string
/// may be overwritten by the next call to g_getenv(), g_setenv()
/// or g_unsetenv().
#[doc(alias = "g_getenv")]
pub fn getenv(variable: impl AsRef<std::ffi::OsStr>) -> Option<std::ffi::OsString> {
unsafe { from_glib_none(ffi::g_getenv(variable.as_ref().to_glib_none().0)) }
}
/// Tests if @hostname contains segments with an ASCII-compatible
/// encoding of an Internationalized Domain Name. If this returns
/// [`true`], you should decode the hostname with g_hostname_to_unicode()
/// before displaying it to the user.
///
/// Note that a hostname might contain a mix of encoded and unencoded
/// segments, and so it is possible for g_hostname_is_non_ascii() and
/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
/// ## `hostname`
/// a hostname
///
/// # Returns
///
/// [`true`] if @hostname contains any ASCII-encoded
/// segments.
#[doc(alias = "g_hostname_is_ascii_encoded")]
pub fn hostname_is_ascii_encoded(hostname: &str) -> bool {
unsafe { from_glib(ffi::g_hostname_is_ascii_encoded(hostname.to_glib_none().0)) }
}
/// Tests if @hostname is the string form of an IPv4 or IPv6 address.
/// (Eg, "192.168.0.1".)
///
/// Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
/// ## `hostname`
/// a hostname (or IP address in string form)
///
/// # Returns
///
/// [`true`] if @hostname is an IP address
#[doc(alias = "g_hostname_is_ip_address")]
pub fn hostname_is_ip_address(hostname: &str) -> bool {
unsafe { from_glib(ffi::g_hostname_is_ip_address(hostname.to_glib_none().0)) }
}
/// Tests if @hostname contains Unicode characters. If this returns
/// [`true`], you need to encode the hostname with g_hostname_to_ascii()
/// before using it in non-IDN-aware contexts.
///
/// Note that a hostname might contain a mix of encoded and unencoded
/// segments, and so it is possible for g_hostname_is_non_ascii() and
/// g_hostname_is_ascii_encoded() to both return [`true`] for a name.
/// ## `hostname`
/// a hostname
///
/// # Returns
///
/// [`true`] if @hostname contains any non-ASCII characters
#[doc(alias = "g_hostname_is_non_ascii")]
pub fn hostname_is_non_ascii(hostname: &str) -> bool {
unsafe { from_glib(ffi::g_hostname_is_non_ascii(hostname.to_glib_none().0)) }
}
/// Converts @hostname to its canonical ASCII form; an ASCII-only
/// string containing no uppercase letters and not ending with a
/// trailing dot.
/// ## `hostname`
/// a valid UTF-8 or ASCII hostname
///
/// # Returns
///
/// an ASCII hostname, which must be freed,
/// or [`None`] if @hostname is in some way invalid.
#[doc(alias = "g_hostname_to_ascii")]
pub fn hostname_to_ascii(hostname: &str) -> Option<crate::GString> {
unsafe { from_glib_full(ffi::g_hostname_to_ascii(hostname.to_glib_none().0)) }
}
/// Converts @hostname to its canonical presentation form; a UTF-8
/// string in Unicode normalization form C, containing no uppercase
/// letters, no forbidden characters, and no ASCII-encoded segments,
/// and not ending with a trailing dot.
///
/// Of course if @hostname is not an internationalized hostname, then
/// the canonical presentation form will be entirely ASCII.
/// ## `hostname`
/// a valid UTF-8 or ASCII hostname
///
/// # Returns
///
/// a UTF-8 hostname, which must be freed,
/// or [`None`] if @hostname is in some way invalid.
#[doc(alias = "g_hostname_to_unicode")]
pub fn hostname_to_unicode(hostname: &str) -> Option<crate::GString> {
unsafe { from_glib_full(ffi::g_hostname_to_unicode(hostname.to_glib_none().0)) }
}
/// Gets the names of all variables set in the environment.
///
/// Programs that want to be portable to Windows should typically use
/// this function and g_getenv() instead of using the environ array
/// from the C library directly. On Windows, the strings in the environ
/// array are in system codepage encoding, while in most of the typical
/// use cases for environment variables in GLib-using programs you want
/// the UTF-8 encoding that this function and g_getenv() provide.
///
/// # Returns
///
///
/// a [`None`]-terminated list of strings which must be freed with
/// g_strfreev().
#[doc(alias = "g_listenv")]
pub fn listenv() -> Vec<std::ffi::OsString> {
unsafe { FromGlibPtrContainer::from_glib_full(ffi::g_listenv()) }
}
/// Returns the currently firing source for this thread.
///
/// # Returns
///
/// The currently firing source or [`None`].
#[doc(alias = "g_main_current_source")]
pub fn main_current_source() -> Option<Source> {
unsafe { from_glib_none(ffi::g_main_current_source()) }
}
/// Returns the depth of the stack of calls to
/// [`MainContext::dispatch()`][crate::MainContext::dispatch()] on any #GMainContext in the current thread.
/// That is, when called from the toplevel, it gives 0. When
/// called from within a callback from [`MainContext::iteration()`][crate::MainContext::iteration()]
/// (or [`MainLoop::run()`][crate::MainLoop::run()], etc.) it returns 1. When called from within
/// a callback to a recursive call to [`MainContext::iteration()`][crate::MainContext::iteration()],
/// it returns 2. And so forth.
///
/// This function is useful in a situation like the following:
/// Imagine an extremely simple "garbage collected" system.
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// static GList *free_list;
///
/// gpointer
/// allocate_memory (gsize size)
/// {
/// gpointer result = g_malloc (size);
/// free_list = g_list_prepend (free_list, result);
/// return result;
/// }
///
/// void
/// free_allocated_memory (void)
/// {
/// GList *l;
/// for (l = free_list; l; l = l->next);
/// g_free (l->data);
/// g_list_free (free_list);
/// free_list = NULL;
/// }
///
/// [...]
///
/// while (TRUE);
/// {
/// g_main_context_iteration (NULL, TRUE);
/// free_allocated_memory();
/// }
/// ```
///
/// This works from an application, however, if you want to do the same
/// thing from a library, it gets more difficult, since you no longer
/// control the main loop. You might think you can simply use an idle
/// function to make the call to free_allocated_memory(), but that
/// doesn't work, since the idle function could be called from a
/// recursive callback. This can be fixed by using [`main_depth()`][crate::main_depth()]
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// gpointer
/// allocate_memory (gsize size)
/// {
/// FreeListBlock *block = g_new (FreeListBlock, 1);
/// block->mem = g_malloc (size);
/// block->depth = g_main_depth ();
/// free_list = g_list_prepend (free_list, block);
/// return block->mem;
/// }
///
/// void
/// free_allocated_memory (void)
/// {
/// GList *l;
///
/// int depth = g_main_depth ();
/// for (l = free_list; l; );
/// {
/// GList *next = l->next;
/// FreeListBlock *block = l->data;
/// if (block->depth > depth)
/// {
/// g_free (block->mem);
/// g_free (block);
/// free_list = g_list_delete_link (free_list, l);
/// }
///
/// l = next;
/// }
/// }
/// ```
///
/// There is a temptation to use [`main_depth()`][crate::main_depth()] to solve
/// problems with reentrancy. For instance, while waiting for data
/// to be received from the network in response to a menu item,
/// the menu item might be selected again. It might seem that
/// one could make the menu item's callback return immediately
/// and do nothing if [`main_depth()`][crate::main_depth()] returns a value greater than 1.
/// However, this should be avoided since the user then sees selecting
/// the menu item do nothing. Furthermore, you'll find yourself adding
/// these checks all over your code, since there are doubtless many,
/// many things that the user could do. Instead, you can use the
/// following techniques:
///
/// 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
/// the user from interacting with elements while the main
/// loop is recursing.
///
/// 2. Avoid main loop recursion in situations where you can't handle
/// arbitrary callbacks. Instead, structure your code so that you
/// simply return to the main loop and then get called again when
/// there is more work to do.
///
/// # Returns
///
/// The main loop recursion level in the current thread
#[doc(alias = "g_main_depth")]
pub fn main_depth() -> i32 {
unsafe { ffi::g_main_depth() }
}
/// Escapes text so that the markup parser will parse it verbatim.
/// Less than, greater than, ampersand, etc. are replaced with the
/// corresponding entities. This function would typically be used
/// when writing out a file to be parsed with the markup parser.
///
/// Note that this function doesn't protect whitespace and line endings
/// from being processed according to the XML rules for normalization
/// of line endings and attribute values.
///
/// Note also that this function will produce character references in
/// the range of  ...  for all control sequences
/// except for tabstop, newline and carriage return. The character
/// references in this range are not valid XML 1.0, but they are
/// valid XML 1.1 and will be accepted by the GMarkup parser.
/// ## `text`
/// some valid UTF-8 text
/// ## `length`
/// length of @text in bytes, or -1 if the text is nul-terminated
///
/// # Returns
///
/// a newly allocated string with the escaped text
#[doc(alias = "g_markup_escape_text")]
pub fn markup_escape_text(text: &str) -> crate::GString {
let length = text.len() as _;
unsafe { from_glib_full(ffi::g_markup_escape_text(text.to_glib_none().0, length)) }
}
/// Create a directory if it doesn't already exist. Create intermediate
/// parent directories as needed, too.
/// ## `pathname`
/// a pathname in the GLib file name encoding
/// ## `mode`
/// permissions to use for newly created directories
///
/// # Returns
///
/// 0 if the directory already exists, or was successfully
/// created. Returns -1 if an error occurred, with errno set.
#[doc(alias = "g_mkdir_with_parents")]
pub fn mkdir_with_parents(pathname: impl AsRef<std::path::Path>, mode: i32) -> i32 {
unsafe { ffi::g_mkdir_with_parents(pathname.as_ref().to_glib_none().0, mode) }
}
/// Prompts the user with
/// `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
/// This function is intended to be used for debugging use only.
/// The following example shows how it can be used together with
/// the g_log() functions.
///
///
///
/// **⚠️ The following code is in C ⚠️**
///
/// ```C
/// #include <glib.h>
///
/// static void
/// log_handler (const gchar *log_domain,
/// GLogLevelFlags log_level,
/// const gchar *message,
/// gpointer user_data)
/// {
/// g_log_default_handler (log_domain, log_level, message, user_data);
///
/// g_on_error_query (MY_PROGRAM_NAME);
/// }
///
/// int
/// main (int argc, char *argv[])
/// {
/// g_log_set_handler (MY_LOG_DOMAIN,
/// G_LOG_LEVEL_WARNING |
/// G_LOG_LEVEL_ERROR |
/// G_LOG_LEVEL_CRITICAL,
/// log_handler,
/// NULL);
/// ...
/// ```
///
/// If "[E]xit" is selected, the application terminates with a call
/// to _exit(0).
///
/// If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
/// This invokes gdb, which attaches to the current process and shows
/// a stack trace. The prompt is then shown again.
///
/// If "[P]roceed" is selected, the function returns.
///
/// This function may cause different actions on non-UNIX platforms.
///
/// On Windows consider using the `G_DEBUGGER` environment
/// variable (see [Running GLib Applications](glib-running.html)) and
/// calling g_on_error_stack_trace() instead.
/// ## `prg_name`
/// the program name, needed by gdb for the "[S]tack trace"
/// option. If @prg_name is [`None`], g_get_prgname() is called to get
/// the program name (which will work correctly if gdk_init() or
/// gtk_init() has been called)
#[doc(alias = "g_on_error_query")]
pub fn on_error_query(prg_name: &str) {
unsafe {
ffi::g_on_error_query(prg_name.to_glib_none().0);
}
}
/// Invokes gdb, which attaches to the current process and shows a
/// stack trace. Called by g_on_error_query() when the "[S]tack trace"
/// option is selected. You can get the current process's program name
/// with g_get_prgname(), assuming that you have called gtk_init() or
/// gdk_init().
///
/// This function may cause different actions on non-UNIX platforms.
///
/// When running on Windows, this function is *not* called by
/// g_on_error_query(). If called directly, it will raise an
/// exception, which will crash the program. If the `G_DEBUGGER` environment
/// variable is set, a debugger will be invoked to attach and
/// handle that exception (see [Running GLib Applications](glib-running.html)).
/// ## `prg_name`
/// the program name, needed by gdb for the "[S]tack trace"
/// option
#[doc(alias = "g_on_error_stack_trace")]
pub fn on_error_stack_trace(prg_name: &str) {
unsafe {
ffi::g_on_error_stack_trace(prg_name.to_glib_none().0);
}
}
/// Gets the last component of the filename.
///
/// If @file_name ends with a directory separator it gets the component
/// before the last slash. If @file_name consists only of directory
/// separators (and on Windows, possibly a drive letter), a single
/// separator is returned. If @file_name is empty, it gets ".".
/// ## `file_name`
/// the name of the file
///
/// # Returns
///
/// a newly allocated string
/// containing the last component of the filename
#[doc(alias = "g_path_get_basename")]
#[allow(dead_code)]
pub(crate) fn path_get_basename(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
unsafe {
from_glib_full(ffi::g_path_get_basename(
file_name.as_ref().to_glib_none().0,
))
}
}
/// Gets the directory components of a file name. For example, the directory
/// component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
/// is `/`.
///
/// If the file name has no directory components "." is returned.
/// The returned string should be freed when no longer needed.
/// ## `file_name`
/// the name of the file
///
/// # Returns
///
/// the directory components of the file
#[doc(alias = "g_path_get_dirname")]
#[allow(dead_code)]
pub(crate) fn path_get_dirname(file_name: impl AsRef<std::path::Path>) -> std::path::PathBuf {
unsafe { from_glib_full(ffi::g_path_get_dirname(file_name.as_ref().to_glib_none().0)) }
}
//#[doc(alias = "g_poll")]
//pub fn poll(fds: /*Ignored*/&mut PollFD, nfds: u32, timeout: i32) -> i32 {
// unsafe { TODO: call ffi:g_poll() }
//}
/// Returns a random #gdouble equally distributed over the range [0..1).
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_double")]
pub fn random_double() -> f64 {
unsafe { ffi::g_random_double() }
}
/// Returns a random #gdouble equally distributed over the range
/// [@begin..@end).
/// ## `begin`
/// lower closed bound of the interval
/// ## `end`
/// upper open bound of the interval
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_double_range")]
pub fn random_double_range(begin: f64, end: f64) -> f64 {
unsafe { ffi::g_random_double_range(begin, end) }
}
/// Return a random #guint32 equally distributed over the range
/// [0..2^32-1].
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_int")]
pub fn random_int() -> u32 {
unsafe { ffi::g_random_int() }
}
/// Returns a random #gint32 equally distributed over the range
/// [@begin..@end-1].
/// ## `begin`
/// lower closed bound of the interval
/// ## `end`
/// upper open bound of the interval
///
/// # Returns
///
/// a random number
#[doc(alias = "g_random_int_range")]
pub fn random_int_range(begin: i32, end: i32) -> i32 {
unsafe { ffi::g_random_int_range(begin, end) }
}
/// Sets the seed for the global random number generator, which is used
/// by the g_random_* functions, to @seed.
/// ## `seed`
/// a value to reinitialize the global random number generator
#[doc(alias = "g_random_set_seed")]
pub fn random_set_seed(seed: u32) {
unsafe {
ffi::g_random_set_seed(seed);
}
}
/// Resets the cache used for g_get_user_special_dir(), so
/// that the latest on-disk version is used. Call this only
/// if you just changed the data on disk yourself.
///
/// Due to thread safety issues this may cause leaking of strings
/// that were previously returned from g_get_user_special_dir()
/// that can't be freed. We ensure to only leak the data for
/// the directories that actually changed value though.
#[doc(alias = "g_reload_user_special_dirs_cache")]
pub fn reload_user_special_dirs_cache() {
unsafe {
ffi::g_reload_user_special_dirs_cache();
}
}
/// Sets a human-readable name for the application. This name should be
/// localized if possible, and is intended for display to the user.
/// Contrast with g_set_prgname(), which sets a non-localized name.
/// g_set_prgname() will be called automatically by gtk_init(),
/// but g_set_application_name() will not.
///
/// Note that for thread safety reasons, this function can only
/// be called once.
///
/// The application name will be used in contexts such as error messages,
/// or when displaying an application's name in the task list.
/// ## `application_name`
/// localized name of the application
#[doc(alias = "g_set_application_name")]
pub fn set_application_name(application_name: &str) {
unsafe {
ffi::g_set_application_name(application_name.to_glib_none().0);
}
}
/// Sets an environment variable. On UNIX, both the variable's name and
/// value can be arbitrary byte strings, except that the variable's name
/// cannot contain '='. On Windows, they should be in UTF-8.
///
/// Note that on some systems, when variables are overwritten, the memory
/// used for the previous variables and its value isn't reclaimed.
///
/// You should be mindful of the fact that environment variable handling
/// in UNIX is not thread-safe, and your program may crash if one thread
/// calls g_setenv() while another thread is calling getenv(). (And note
/// that many functions, such as gettext(), call getenv() internally.)
/// This function is only safe to use at the very start of your program,
/// before creating any other threads (or creating objects that create
/// worker threads of their own).
///
/// If you need to set up the environment for a child process, you can
/// use g_get_environ() to get an environment array, modify that with
/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
/// array directly to execvpe(), g_spawn_async(), or the like.
/// ## `variable`
/// the environment variable to set, must not
/// contain '='.
/// ## `value`
/// the value for to set the variable to.
/// ## `overwrite`
/// whether to change the variable if it already exists.
///
/// # Returns
///
/// [`false`] if the environment variable couldn't be set.
#[doc(alias = "g_setenv")]
pub fn setenv(
variable: impl AsRef<std::ffi::OsStr>,
value: impl AsRef<std::ffi::OsStr>,
overwrite: bool,
) -> Result<(), crate::error::BoolError> {
unsafe {
crate::result_from_gboolean!(
ffi::g_setenv(
variable.as_ref().to_glib_none().0,
value.as_ref().to_glib_none().0,
overwrite.into_glib()
),
"Failed to set environment variable"
)
}
}
/// Parses a command line into an argument vector, in much the same way
/// the shell would, but without many of the expansions the shell would
/// perform (variable expansion, globs, operators, filename expansion,
/// etc. are not supported).
///
/// The results are defined to be the same as those you would get from
/// a UNIX98 `/bin/sh`, as long as the input contains none of the
/// unsupported shell expansions. If the input does contain such expansions,
/// they are passed through literally.
///
/// Possible errors are those from the `G_SHELL_ERROR` domain.
///
/// In particular, if @command_line is an empty string (or a string containing
/// only whitespace), `G_SHELL_ERROR_EMPTY_STRING` will be returned. It’s
/// guaranteed that @argvp will be a non-empty array if this function returns
/// successfully.
///
/// Free the returned vector with g_strfreev().
/// ## `command_line`
/// command line to parse
///
/// # Returns
///
/// [`true`] on success, [`false`] if error set
///
/// ## `argvp`
///
/// return location for array of args
#[doc(alias = "g_shell_parse_argv")]
pub fn shell_parse_argv(
command_line: impl AsRef<std::ffi::OsStr>,
) -> Result<Vec<std::ffi::OsString>, crate::Error> {
unsafe {
let mut argcp = std::mem::MaybeUninit::uninit();
let mut argvp = std::ptr::null_mut();
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_shell_parse_argv(
command_line.as_ref().to_glib_none().0,
argcp.as_mut_ptr(),
&mut argvp,
&mut error,
);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(FromGlibContainer::from_glib_full_num(
argvp,
argcp.assume_init() as _,
))
} else {
Err(from_glib_full(error))
}
}
}
/// Quotes a string so that the shell (/bin/sh) will interpret the
/// quoted string to mean @unquoted_string.
///
/// If you pass a filename to the shell, for example, you should first
/// quote it with this function.
///
/// The return value must be freed with g_free().
///
/// The quoting style used is undefined (single or double quotes may be
/// used).
/// ## `unquoted_string`
/// a literal string
///
/// # Returns
///
/// quoted string
#[doc(alias = "g_shell_quote")]
pub fn shell_quote(unquoted_string: impl AsRef<std::ffi::OsStr>) -> std::ffi::OsString {
unsafe {
from_glib_full(ffi::g_shell_quote(
unquoted_string.as_ref().to_glib_none().0,
))
}
}
/// Unquotes a string as the shell (/bin/sh) would.
///
/// This function only handles quotes; if a string contains file globs,
/// arithmetic operators, variables, backticks, redirections, or other
/// special-to-the-shell features, the result will be different from the
/// result a real shell would produce (the variables, backticks, etc.
/// will be passed through literally instead of being expanded).
///
/// This function is guaranteed to succeed if applied to the result of
/// g_shell_quote(). If it fails, it returns [`None`] and sets the
/// error.
///
/// The @quoted_string need not actually contain quoted or escaped text;
/// g_shell_unquote() simply goes through the string and unquotes/unescapes
/// anything that the shell would. Both single and double quotes are
/// handled, as are escapes including escaped newlines.
///
/// The return value must be freed with g_free().
///
/// Possible errors are in the `G_SHELL_ERROR` domain.
///
/// Shell quoting rules are a bit strange. Single quotes preserve the
/// literal string exactly. escape sequences are not allowed; not even
/// `\'` - if you want a `'` in the quoted text, you have to do something
/// like `'foo'\''bar'`. Double quotes allow `$`, **⚠️ The following code is in , `"`, `\`, and ⚠️**
///
/// ```, `"`, `\`, and
/// newline to be escaped with backslash. Otherwise double quotes
/// preserve things literally.
/// ## `quoted_string`
/// shell-quoted string
///
/// # Returns
///
/// an unquoted string
#[doc(alias = "g_shell_unquote")]
pub fn shell_unquote(
quoted_string: impl AsRef<std::ffi::OsStr>,
) -> Result<std::ffi::OsString, crate::Error> {
unsafe {
let mut error = std::ptr::null_mut();
let ret = ffi::g_shell_unquote(quoted_string.as_ref().to_glib_none().0, &mut error);
if error.is_null() {
Ok(from_glib_full(ret))
} else {
Err(from_glib_full(error))
}
}
}
//#[cfg(feature = "v2_82")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v2_82")))]
//#[doc(alias = "g_sort_array")]
//pub fn sort_array(array: /*Unimplemented*/&[&Basic: Pointer], element_size: usize, compare_func: /*Unimplemented*/FnMut(/*Unimplemented*/Option<Basic: Pointer>, /*Unimplemented*/Option<Basic: Pointer>) -> i32, user_data: /*Unimplemented*/Option<Basic: Pointer>) {
// unsafe { TODO: call ffi:g_sort_array() }
//}
/// Gets the smallest prime number from a built-in array of primes which
/// is larger than @num. This is used within GLib to calculate the optimum
/// size of a #GHashTable.
///
/// The built-in array of primes ranges from 11 to 13845163 such that
/// each prime is approximately 1.5-2 times the previous prime.
/// ## `num`
/// a #guint
///
/// # Returns
///
/// the smallest prime number from a built-in array of primes
/// which is larger than @num
#[doc(alias = "g_spaced_primes_closest")]
pub fn spaced_primes_closest(num: u32) -> u32 {
unsafe { ffi::g_spaced_primes_closest(num) }
}
/// Executes a child program asynchronously.
///
/// See g_spawn_async_with_pipes() for a full description; this function
/// simply calls the g_spawn_async_with_pipes() without any pipes.
///
/// You should call g_spawn_close_pid() on the returned child process
/// reference when you don't need it any more.
///
/// If you are writing a GTK application, and the program you are spawning is a
/// graphical application too, then to ensure that the spawned program opens its
/// windows on the right screen, you may want to use #GdkAppLaunchContext,
/// #GAppLaunchContext, or set the `DISPLAY` environment variable.
///
/// Note that the returned @child_pid on Windows is a handle to the child
/// process and not its identifier. Process handles and process identifiers
/// are different concepts on Windows.
/// ## `working_directory`
/// child's current working
/// directory, or [`None`] to inherit parent's
/// ## `argv`
///
/// child's argument vector
/// ## `envp`
///
/// child's environment, or [`None`] to inherit parent's
/// ## `flags`
/// flags from #GSpawnFlags
/// ## `child_setup`
/// function to run
/// in the child just before `exec()`
///
/// # Returns
///
/// [`true`] on success, [`false`] if error is set
///
/// ## `child_pid`
/// return location for child process reference, or [`None`]
#[doc(alias = "g_spawn_async")]
pub fn spawn_async(
working_directory: Option<impl AsRef<std::path::Path>>,
argv: &[&std::path::Path],
envp: &[&std::path::Path],
flags: SpawnFlags,
child_setup: Option<Box_<dyn FnOnce() + 'static>>,
) -> Result<Pid, crate::Error> {
let child_setup_data: Box_<Option<Box_<dyn FnOnce() + 'static>>> = Box_::new(child_setup);
unsafe extern "C" fn child_setup_func(data: ffi::gpointer) {
let callback = Box_::from_raw(data as *mut Option<Box_<dyn FnOnce() + 'static>>);
let callback = (*callback).expect("cannot get closure...");
callback()
}
let child_setup = if child_setup_data.is_some() {
Some(child_setup_func as _)
} else {
None
};
let super_callback0: Box_<Option<Box_<dyn FnOnce() + 'static>>> = child_setup_data;
unsafe {
let mut child_pid = std::mem::MaybeUninit::uninit();
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_spawn_async(
working_directory
.as_ref()
.map(|p| p.as_ref())
.to_glib_none()
.0,
argv.to_glib_none().0,
envp.to_glib_none().0,
flags.into_glib(),
child_setup,
Box_::into_raw(super_callback0) as *mut _,
child_pid.as_mut_ptr(),
&mut error,
);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(from_glib(child_pid.assume_init()))
} else {
Err(from_glib_full(error))
}
}
}
//#[cfg(feature = "v2_68")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
//#[doc(alias = "g_spawn_async_with_pipes_and_fds")]
//pub fn spawn_async_with_pipes_and_fds(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<Box_<dyn FnOnce() + 'static>>, stdin_fd: i32, stdout_fd: i32, stderr_fd: i32, source_fds: &[i32], target_fds: &[i32], n_fds: usize) -> Result<(Pid, i32, i32, i32), crate::Error> {
// unsafe { TODO: call ffi:g_spawn_async_with_pipes_and_fds() }
//}
/// An old name for g_spawn_check_wait_status(), deprecated because its
/// name is misleading.
///
/// Despite the name of the function, @wait_status must be the wait status
/// as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`,
/// etc. On Unix platforms, it is incorrect for it to be the exit status
/// as passed to `exit()` or returned by g_subprocess_get_exit_status() or
/// `WEXITSTATUS()`.
///
/// # Deprecated since 2.70
///
/// Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.
/// ## `wait_status`
/// A status as returned from g_spawn_sync()
///
/// # Returns
///
/// [`true`] if child exited successfully, [`false`] otherwise (and
/// @error will be set)
#[cfg_attr(feature = "v2_70", deprecated = "Since 2.70")]
#[allow(deprecated)]
#[doc(alias = "g_spawn_check_exit_status")]
pub fn spawn_check_exit_status(wait_status: i32) -> Result<(), crate::Error> {
unsafe {
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_spawn_check_exit_status(wait_status, &mut error);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(())
} else {
Err(from_glib_full(error))
}
}
}
/// Set @error if @wait_status indicates the child exited abnormally
/// (e.g. with a nonzero exit code, or via a fatal signal).
///
/// The g_spawn_sync() and g_child_watch_add() family of APIs return the
/// status of subprocesses encoded in a platform-specific way.
/// On Unix, this is guaranteed to be in the same format waitpid() returns,
/// and on Windows it is guaranteed to be the result of GetExitCodeProcess().
///
/// Prior to the introduction of this function in GLib 2.34, interpreting
/// @wait_status required use of platform-specific APIs, which is problematic
/// for software using GLib as a cross-platform layer.
///
/// Additionally, many programs simply want to determine whether or not
/// the child exited successfully, and either propagate a #GError or
/// print a message to standard error. In that common case, this function
/// can be used. Note that the error message in @error will contain
/// human-readable information about the wait status.
///
/// The @domain and @code of @error have special semantics in the case
/// where the process has an "exit code", as opposed to being killed by
/// a signal. On Unix, this happens if WIFEXITED() would be true of
/// @wait_status. On Windows, it is always the case.
///
/// The special semantics are that the actual exit code will be the
/// code set in @error, and the domain will be `G_SPAWN_EXIT_ERROR`.
/// This allows you to differentiate between different exit codes.
///
/// If the process was terminated by some means other than an exit
/// status (for example if it was killed by a signal), the domain will be
/// `G_SPAWN_ERROR` and the code will be `G_SPAWN_ERROR_FAILED`.
///
/// This function just offers convenience; you can of course also check
/// the available platform via a macro such as `G_OS_UNIX`, and use
/// WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt
/// to scan or parse the error message string; it may be translated and/or
/// change in future versions of GLib.
///
/// Prior to version 2.70, g_spawn_check_exit_status() provides the same
/// functionality, although under a misleading name.
/// ## `wait_status`
/// A platform-specific wait status as returned from g_spawn_sync()
///
/// # Returns
///
/// [`true`] if child exited successfully, [`false`] otherwise (and
/// @error will be set)
#[cfg(feature = "v2_70")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_70")))]
#[doc(alias = "g_spawn_check_wait_status")]
pub fn spawn_check_wait_status(wait_status: i32) -> Result<(), crate::Error> {
unsafe {
let mut error = std::ptr::null_mut();
let is_ok = ffi::g_spawn_check_wait_status(wait_status, &mut error);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(())
} else {
Err(from_glib_full(error))
}
}
}
/// A simple version of g_spawn_async() that parses a command line with
/// g_shell_parse_argv() and passes it to g_spawn_async().
///
/// Runs a command line in the background. Unlike g_spawn_async(), the
/// [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] flag is enabled, other flags are not. Note
/// that [`SpawnFlags::SEARCH_PATH`][crate::SpawnFlags::SEARCH_PATH] can have security implications, so
/// consider using g_spawn_async() directly if appropriate. Possible
/// errors are those from g_shell_parse_argv() and g_spawn_async().
///
/// The same concerns on Windows apply as for g_spawn_command_line_sync().
/// ## `command_line`
/// a command line
///
/// # Returns
///
/// [`true`] on success, [`false`] if error is set
#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
#[doc(alias = "g_spawn_command_line_async")]
pub fn spawn_command_line_async(
command_line: impl AsRef<std::ffi::OsStr>,
) -> Result<(), crate::Error> {
unsafe {
let mut error = std::ptr::null_mut();
let is_ok =
ffi::g_spawn_command_line_async(command_line.as_ref().to_glib_none().0, &mut error);
debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
if error.is_null() {
Ok(())
} else {
Err(from_glib_full(error))
}
}
}
//#[doc(alias = "g_spawn_command_line_sync")]
//pub fn spawn_command_line_sync(command_line: impl AsRef<std::path::Path>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
// unsafe { TODO: call ffi:g_spawn_command_line_sync() }
//}
//#[doc(alias = "g_spawn_sync")]
//pub fn spawn_sync(working_directory: Option<impl AsRef<std::path::Path>>, argv: &[&std::path::Path], envp: &[&std::path::Path], flags: SpawnFlags, child_setup: Option<&mut dyn (FnMut())>, standard_output: Vec<u8>, standard_error: Vec<u8>) -> Result<i32, crate::Error> {
// unsafe { TODO: call ffi:g_spawn_sync() }
//}
//#[doc(alias = "g_stat")]
//pub fn stat(filename: impl AsRef<std::path::Path>, buf: /*Ignored*/&mut StatBuf) -> i32 {
// unsafe { TODO: call ffi:g_stat() }
//}
//#[cfg(unix)]
//#[cfg_attr(docsrs, doc(cfg(unix)))]
//#[cfg(feature = "v2_64")]
//#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
//#[doc(alias = "g_unix_get_passwd_entry")]
//pub fn unix_get_passwd_entry(user_name: &str) -> Result</*Unimplemented*/Option<Basic: Pointer>, crate::Error> {
// unsafe { TODO: call ffi:g_unix_get_passwd_entry() }
//}
/// A wrapper for the POSIX unlink() function. The unlink() function
/// deletes a name from the filesystem. If this was the last link to the
/// file and no processes have it opened, the diskspace occupied by the
/// file is freed.
///
/// See your C library manual for more details about unlink(). Note
/// that on Windows, it is in general not possible to delete files that
/// are open to some process, or mapped into memory.
/// ## `filename`
/// a pathname in the GLib file name encoding
/// (UTF-8 on Windows)
///
/// # Returns
///
/// 0 if the name was successfully deleted, -1 if an error
/// occurred
#[doc(alias = "g_unlink")]
pub fn unlink(filename: impl AsRef<std::path::Path>) -> i32 {
unsafe { ffi::g_unlink(filename.as_ref().to_glib_none().0) }
}
/// Removes an environment variable from the environment.
///
/// Note that on some systems, when variables are overwritten, the
/// memory used for the previous variables and its value isn't reclaimed.
///
/// You should be mindful of the fact that environment variable handling
/// in UNIX is not thread-safe, and your program may crash if one thread
/// calls g_unsetenv() while another thread is calling getenv(). (And note
/// that many functions, such as gettext(), call getenv() internally.) This
/// function is only safe to use at the very start of your program, before
/// creating any other threads (or creating objects that create worker
/// threads of their own).
///
/// If you need to set up the environment for a child process, you can
/// use g_get_environ() to get an environment array, modify that with
/// g_environ_setenv() and g_environ_unsetenv(), and then pass that
/// array directly to execvpe(), g_spawn_async(), or the like.
/// ## `variable`
/// the environment variable to remove, must
/// not contain '='
#[doc(alias = "g_unsetenv")]
pub fn unsetenv(variable: impl AsRef<std::ffi::OsStr>) {
unsafe {
ffi::g_unsetenv(variable.as_ref().to_glib_none().0);
}
}
/// Pauses the current thread for the given number of microseconds.
///
/// There are 1 million microseconds per second (represented by the
/// `G_USEC_PER_SEC` macro). g_usleep() may have limited precision,
/// depending on hardware and operating system; don't rely on the exact
/// length of the sleep.
/// ## `microseconds`
/// number of microseconds to pause
#[doc(alias = "g_usleep")]
pub fn usleep(microseconds: libc::c_ulong) {
unsafe {
ffi::g_usleep(microseconds);
}
}
/// Parses the string @str and verify if it is a UUID.
///
/// The function accepts the following syntax:
///
/// - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
///
/// Note that hyphens are required within the UUID string itself,
/// as per the aforementioned RFC.
/// ## `str`
/// a string representing a UUID
///
/// # Returns
///
/// [`true`] if @str is a valid UUID, [`false`] otherwise.
#[doc(alias = "g_uuid_string_is_valid")]
pub fn uuid_string_is_valid(str: &str) -> bool {
unsafe { from_glib(ffi::g_uuid_string_is_valid(str.to_glib_none().0)) }
}
/// Generates a random UUID (RFC 4122 version 4) as a string. It has the same
/// randomness guarantees as #GRand, so must not be used for cryptographic
/// purposes such as key generation, nonces, salts or one-time pads.
///
/// # Returns
///
/// A string that should be freed with g_free().
#[doc(alias = "g_uuid_string_random")]
pub fn uuid_string_random() -> crate::GString {
unsafe { from_glib_full(ffi::g_uuid_string_random()) }
}