/usr/include/physfs.h is in libphysfs-dev 2.0.3-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | /**
* \file physfs.h
*
* Main header file for PhysicsFS.
*/
/**
* \mainpage PhysicsFS
*
* The latest version of PhysicsFS can be found at:
* http://icculus.org/physfs/
*
* PhysicsFS; a portable, flexible file i/o abstraction.
*
* This API gives you access to a system file system in ways superior to the
* stdio or system i/o calls. The brief benefits:
*
* - It's portable.
* - It's safe. No file access is permitted outside the specified dirs.
* - It's flexible. Archives (.ZIP files) can be used transparently as
* directory structures.
*
* This system is largely inspired by Quake 3's PK3 files and the related
* fs_* cvars. If you've ever tinkered with these, then this API will be
* familiar to you.
*
* With PhysicsFS, you have a single writing directory and multiple
* directories (the "search path") for reading. You can think of this as a
* filesystem within a filesystem. If (on Windows) you were to set the
* writing directory to "C:\MyGame\MyWritingDirectory", then no PHYSFS calls
* could touch anything above this directory, including the "C:\MyGame" and
* "C:\" directories. This prevents an application's internal scripting
* language from piddling over c:\\config.sys, for example. If you'd rather
* give PHYSFS full access to the system's REAL file system, set the writing
* dir to "C:\", but that's generally A Bad Thing for several reasons.
*
* Drive letters are hidden in PhysicsFS once you set up your initial paths.
* The search path creates a single, hierarchical directory structure.
* Not only does this lend itself well to general abstraction with archives,
* it also gives better support to operating systems like MacOS and Unix.
* Generally speaking, you shouldn't ever hardcode a drive letter; not only
* does this hurt portability to non-Microsoft OSes, but it limits your win32
* users to a single drive, too. Use the PhysicsFS abstraction functions and
* allow user-defined configuration options, too. When opening a file, you
* specify it like it was on a Unix filesystem: if you want to write to
* "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to
* "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
* abstraction across all platforms. Specifying a file in this way is termed
* "platform-independent notation" in this documentation. Specifying a
* a filename in a form such as "C:\mydir\myfile" or
* "MacOS hard drive:My Directory:My File" is termed "platform-dependent
* notation". The only time you use platform-dependent notation is when
* setting up your write directory and search path; after that, all file
* access into those directories are done with platform-independent notation.
*
* All files opened for writing are opened in relation to the write directory,
* which is the root of the writable filesystem. When opening a file for
* reading, PhysicsFS goes through the search path. This is NOT the
* same thing as the PATH environment variable. An application using
* PhysicsFS specifies directories to be searched which may be actual
* directories, or archive files that contain files and subdirectories of
* their own. See the end of these docs for currently supported archive
* formats.
*
* Once the search path is defined, you may open files for reading. If you've
* got the following search path defined (to use a win32 example again):
*
* - C:\\mygame
* - C:\\mygame\\myuserfiles
* - D:\\mygamescdromdatafiles
* - C:\\mygame\\installeddatafiles.zip
*
* Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory
* separator, lack of drive letter, and lack of dir separator at the start of
* the string; this is platform-independent notation) will check for
* C:\\mygame\\textfiles\\myfile.txt, then
* C:\\mygame\\myuserfiles\\textfiles\\myfile.txt, then
* D:\\mygamescdromdatafiles\\textfiles\\myfile.txt, then, finally, for
* textfiles\\myfile.txt inside of C:\\mygame\\installeddatafiles.zip.
* Remember that most archive types and platform filesystems store their
* filenames in a case-sensitive manner, so you should be careful to specify
* it correctly.
*
* Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir
* elements. Not only are these meaningless on MacOS Classic and/or Unix,
* they are a security hole. Also, symbolic links (which can be found in
* some archive types and directly in the filesystem on Unix platforms) are
* NOT followed until you call PHYSFS_permitSymbolicLinks(). That's left to
* your own discretion, as following a symlink can allow for access outside
* the write dir and search paths. For portability, there is no mechanism for
* creating new symlinks in PhysicsFS.
*
* The write dir is not included in the search path unless you specifically
* add it. While you CAN change the write dir as many times as you like,
* you should probably set it once and stick to it. Remember that your
* program will not have permission to write in every directory on Unix and
* NT systems.
*
* All files are opened in binary mode; there is no endline conversion for
* textfiles. Other than that, PhysicsFS has some convenience functions for
* platform-independence. There is a function to tell you the current
* platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),
* which is needed only to set up your search/write paths. There is a
* function to tell you what CD-ROM drives contain accessible discs, and a
* function to recommend a good search path, etc.
*
* A recommended order for the search path is the write dir, then the base dir,
* then the cdrom dir, then any archives discovered. Quake 3 does something
* like this, but moves the archives to the start of the search path. Build
* Engine games, like Duke Nukem 3D and Blood, place the archives last, and
* use the base dir for both searching and writing. There is a helper
* function (PHYSFS_setSaneConfig()) that puts together a basic configuration
* for you, based on a few parameters. Also see the comments on
* PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
* are and how they can help you determine an optimal search path.
*
* PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points
* in the search path. If a zipfile contains "maps/level.map" and you mount
* that archive at "mods/mymod", then you would have to open
* "mods/mymod/maps/level.map" to access the file, even though "mods/mymod"
* isn't actually specified in the .zip file. Unlike the Unix mentality of
* mounting a filesystem, "mods/mymod" doesn't actually have to exist when
* mounting the zipfile. It's a "virtual" directory. The mounting mechanism
* allows the developer to seperate archives in the tree and avoid trampling
* over files when added new archives, such as including mod support in a
* game...keeping external content on a tight leash in this manner can be of
* utmost importance to some applications.
*
* PhysicsFS is mostly thread safe. The error messages returned by
* PHYSFS_getLastError are unique by thread, and library-state-setting
* functions are mutex'd. For efficiency, individual file accesses are
* not locked, so you can not safely read/write/seek/close/etc the same
* file from two threads at the same time. Other race conditions are bugs
* that should be reported/patched.
*
* While you CAN use stdio/syscall file access in a program that has PHYSFS_*
* calls, doing so is not recommended, and you can not use system
* filehandles with PhysicsFS and vice versa.
*
* Note that archives need not be named as such: if you have a ZIP file and
* rename it with a .PKG extension, the file will still be recognized as a
* ZIP archive by PhysicsFS; the file's contents are used to determine its
* type where possible.
*
* Currently supported archive types:
* - .ZIP (pkZip/WinZip/Info-ZIP compatible)
* - .GRP (Build Engine groupfile archives)
* - .PAK (Quake I/II archive format)
* - .HOG (Descent I/II HOG file archives)
* - .MVL (Descent II movielib archives)
* - .WAD (DOOM engine archives)
*
*
* String policy for PhysicsFS 2.0 and later:
*
* PhysicsFS 1.0 could only deal with null-terminated ASCII strings. All high
* ASCII chars resulted in undefined behaviour, and there was no Unicode
* support at all. PhysicsFS 2.0 supports Unicode without breaking binary
* compatibility with the 1.0 API by using UTF-8 encoding of all strings
* passed in and out of the library.
*
* All strings passed through PhysicsFS are in null-terminated UTF-8 format.
* This means that if all you care about is English (ASCII characters <= 127)
* then you just use regular C strings. If you care about Unicode (and you
* should!) then you need to figure out what your platform wants, needs, and
* offers. If you are on Windows and build with Unicode support, your TCHAR
* strings are two bytes per character (this is called "UCS-2 encoding"). You
* should convert them to UTF-8 before handing them to PhysicsFS with
* PHYSFS_utf8FromUcs2(). If you're using Unix or Mac OS X, your wchar_t
* strings are four bytes per character ("UCS-4 encoding"). Use
* PHYSFS_utf8FromUcs4(). Mac OS X can give you UTF-8 directly from a
* CFString, and many Unixes generally give you C strings in UTF-8 format
* everywhere. If you have a single-byte high ASCII charset, like so-many
* European "codepages" you may be out of luck. We'll convert from "Latin1"
* to UTF-8 only, and never back to Latin1. If you're above ASCII 127, all
* bets are off: move to Unicode or use your platform's facilities. Passing a
* C string with high-ASCII data that isn't UTF-8 encoded will NOT do what
* you expect!
*
* Naturally, there's also PHYSFS_utf8ToUcs2() and PHYSFS_utf8ToUcs4() to get
* data back into a format you like. Behind the scenes, PhysicsFS will use
* Unicode where possible: the UTF-8 strings on Windows will be converted
* and used with the multibyte Windows APIs, for example.
*
* PhysicsFS offers basic encoding conversion support, but not a whole string
* library. Get your stuff into whatever format you can work with.
*
* Some platforms and archivers don't offer full Unicode support behind the
* scenes. For example, OS/2 only offers "codepages" and the filesystem
* itself doesn't support multibyte encodings. We make an earnest effort to
* convert to/from the current locale here, but all bets are off if
* you want to hand an arbitrary Japanese character through to these systems.
* Modern OSes (Mac OS X, Linux, Windows, PocketPC, etc) should all be fine.
* Many game-specific archivers are seriously unprepared for Unicode (the
* Descent HOG/MVL and Build Engine GRP archivers, for example, only offer a
* DOS 8.3 filename, for example). Nothing can be done for these, but they
* tend to be legacy formats for existing content that was all ASCII (and
* thus, valid UTF-8) anyhow. Other formats, like .ZIP, don't explicitly
* offer Unicode support, but unofficially expect filenames to be UTF-8
* encoded, and thus Just Work. Most everything does the right thing without
* bothering you, but it's good to be aware of these nuances in case they
* don't.
*
*
* Other stuff:
*
* Please see the file LICENSE.txt in the source's root directory for licensing
* and redistribution rights.
*
* Please see the file CREDITS.txt in the source's root directory for a more or
* less complete list of who's responsible for this.
*
* \author Ryan C. Gordon.
*/
#ifndef _INCLUDE_PHYSFS_H_
#define _INCLUDE_PHYSFS_H_
#ifdef __cplusplus
extern "C" {
#endif
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
#if (defined _MSC_VER)
#define __EXPORT__ __declspec(dllexport)
#elif (__GNUC__ >= 3)
#define __EXPORT__ __attribute__((visibility("default")))
#else
#define __EXPORT__
#endif
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
/**
* \typedef PHYSFS_uint8
* \brief An unsigned, 8-bit integer type.
*/
typedef unsigned char PHYSFS_uint8;
/**
* \typedef PHYSFS_sint8
* \brief A signed, 8-bit integer type.
*/
typedef signed char PHYSFS_sint8;
/**
* \typedef PHYSFS_uint16
* \brief An unsigned, 16-bit integer type.
*/
typedef unsigned short PHYSFS_uint16;
/**
* \typedef PHYSFS_sint16
* \brief A signed, 16-bit integer type.
*/
typedef signed short PHYSFS_sint16;
/**
* \typedef PHYSFS_uint32
* \brief An unsigned, 32-bit integer type.
*/
typedef unsigned int PHYSFS_uint32;
/**
* \typedef PHYSFS_sint32
* \brief A signed, 32-bit integer type.
*/
typedef signed int PHYSFS_sint32;
/**
* \typedef PHYSFS_uint64
* \brief An unsigned, 64-bit integer type.
* \warning on platforms without any sort of 64-bit datatype, this is
* equivalent to PHYSFS_uint32!
*/
/**
* \typedef PHYSFS_sint64
* \brief A signed, 64-bit integer type.
* \warning on platforms without any sort of 64-bit datatype, this is
* equivalent to PHYSFS_sint32!
*/
#if (defined PHYSFS_NO_64BIT_SUPPORT) /* oh well. */
typedef PHYSFS_uint32 PHYSFS_uint64;
typedef PHYSFS_sint32 PHYSFS_sint64;
#elif (defined _MSC_VER)
typedef signed __int64 PHYSFS_sint64;
typedef unsigned __int64 PHYSFS_uint64;
#else
typedef unsigned long long PHYSFS_uint64;
typedef signed long long PHYSFS_sint64;
#endif
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
/* Make sure the types really have the right sizes */
#define PHYSFS_COMPILE_TIME_ASSERT(name, x) \
typedef int PHYSFS_dummy_ ## name[(x) * 2 - 1]
PHYSFS_COMPILE_TIME_ASSERT(uint8, sizeof(PHYSFS_uint8) == 1);
PHYSFS_COMPILE_TIME_ASSERT(sint8, sizeof(PHYSFS_sint8) == 1);
PHYSFS_COMPILE_TIME_ASSERT(uint16, sizeof(PHYSFS_uint16) == 2);
PHYSFS_COMPILE_TIME_ASSERT(sint16, sizeof(PHYSFS_sint16) == 2);
PHYSFS_COMPILE_TIME_ASSERT(uint32, sizeof(PHYSFS_uint32) == 4);
PHYSFS_COMPILE_TIME_ASSERT(sint32, sizeof(PHYSFS_sint32) == 4);
#ifndef PHYSFS_NO_64BIT_SUPPORT
PHYSFS_COMPILE_TIME_ASSERT(uint64, sizeof(PHYSFS_uint64) == 8);
PHYSFS_COMPILE_TIME_ASSERT(sint64, sizeof(PHYSFS_sint64) == 8);
#endif
#undef PHYSFS_COMPILE_TIME_ASSERT
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
/**
* \struct PHYSFS_File
* \brief A PhysicsFS file handle.
*
* You get a pointer to one of these when you open a file for reading,
* writing, or appending via PhysicsFS.
*
* As you can see from the lack of meaningful fields, you should treat this
* as opaque data. Don't try to manipulate the file handle, just pass the
* pointer you got, unmolested, to various PhysicsFS APIs.
*
* \sa PHYSFS_openRead
* \sa PHYSFS_openWrite
* \sa PHYSFS_openAppend
* \sa PHYSFS_close
* \sa PHYSFS_read
* \sa PHYSFS_write
* \sa PHYSFS_seek
* \sa PHYSFS_tell
* \sa PHYSFS_eof
* \sa PHYSFS_setBuffer
* \sa PHYSFS_flush
*/
typedef struct PHYSFS_File
{
void *opaque; /**< That's all you get. Don't touch. */
} PHYSFS_File;
/**
* \def PHYSFS_file
* \brief 1.0 API compatibility define.
*
* PHYSFS_file is identical to PHYSFS_File. This #define is here for backwards
* compatibility with the 1.0 API, which had an inconsistent capitalization
* convention in this case. New code should use PHYSFS_File, as this #define
* may go away someday.
*
* \sa PHYSFS_File
*/
#define PHYSFS_file PHYSFS_File
/**
* \struct PHYSFS_ArchiveInfo
* \brief Information on various PhysicsFS-supported archives.
*
* This structure gives you details on what sort of archives are supported
* by this implementation of PhysicsFS. Archives tend to be things like
* ZIP files and such.
*
* \warning Not all binaries are created equal! PhysicsFS can be built with
* or without support for various archives. You can check with
* PHYSFS_supportedArchiveTypes() to see if your archive type is
* supported.
*
* \sa PHYSFS_supportedArchiveTypes
*/
typedef struct PHYSFS_ArchiveInfo
{
const char *extension; /**< Archive file extension: "ZIP", for example. */
const char *description; /**< Human-readable archive description. */
const char *author; /**< Person who did support for this archive. */
const char *url; /**< URL related to this archive */
} PHYSFS_ArchiveInfo;
/**
* \struct PHYSFS_Version
* \brief Information the version of PhysicsFS in use.
*
* Represents the library's version as three levels: major revision
* (increments with massive changes, additions, and enhancements),
* minor revision (increments with backwards-compatible changes to the
* major revision), and patchlevel (increments with fixes to the minor
* revision).
*
* \sa PHYSFS_VERSION
* \sa PHYSFS_getLinkedVersion
*/
typedef struct PHYSFS_Version
{
PHYSFS_uint8 major; /**< major revision */
PHYSFS_uint8 minor; /**< minor revision */
PHYSFS_uint8 patch; /**< patchlevel */
} PHYSFS_Version;
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
#define PHYSFS_VER_MAJOR 2
#define PHYSFS_VER_MINOR 0
#define PHYSFS_VER_PATCH 3
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
/* PhysicsFS state stuff ... */
/**
* \def PHYSFS_VERSION(x)
* \brief Macro to determine PhysicsFS version program was compiled against.
*
* This macro fills in a PHYSFS_Version structure with the version of the
* library you compiled against. This is determined by what header the
* compiler uses. Note that if you dynamically linked the library, you might
* have a slightly newer or older version at runtime. That version can be
* determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,
* is not a macro.
*
* \param x A pointer to a PHYSFS_Version struct to initialize.
*
* \sa PHYSFS_Version
* \sa PHYSFS_getLinkedVersion
*/
#define PHYSFS_VERSION(x) \
{ \
(x)->major = PHYSFS_VER_MAJOR; \
(x)->minor = PHYSFS_VER_MINOR; \
(x)->patch = PHYSFS_VER_PATCH; \
}
/**
* \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)
* \brief Get the version of PhysicsFS that is linked against your program.
*
* If you are using a shared library (DLL) version of PhysFS, then it is
* possible that it will be different than the version you compiled against.
*
* This is a real function; the macro PHYSFS_VERSION tells you what version
* of PhysFS you compiled against:
*
* \code
* PHYSFS_Version compiled;
* PHYSFS_Version linked;
*
* PHYSFS_VERSION(&compiled);
* PHYSFS_getLinkedVersion(&linked);
* printf("We compiled against PhysFS version %d.%d.%d ...\n",
* compiled.major, compiled.minor, compiled.patch);
* printf("But we linked against PhysFS version %d.%d.%d.\n",
* linked.major, linked.minor, linked.patch);
* \endcode
*
* This function may be called safely at any time, even before PHYSFS_init().
*
* \sa PHYSFS_VERSION
*/
__EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
/**
* \fn int PHYSFS_init(const char *argv0)
* \brief Initialize the PhysicsFS library.
*
* This must be called before any other PhysicsFS function.
*
* This should be called prior to any attempts to change your process's
* current working directory.
*
* \param argv0 the argv[0] string passed to your program's mainline.
* This may be NULL on most platforms (such as ones without a
* standard main() function), but you should always try to pass
* something in here. Unix-like systems such as Linux _need_ to
* pass argv[0] from main() in here.
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_deinit
* \sa PHYSFS_isInit
*/
__EXPORT__ int PHYSFS_init(const char *argv0);
/**
* \fn int PHYSFS_deinit(void)
* \brief Deinitialize the PhysicsFS library.
*
* This closes any files opened via PhysicsFS, blanks the search/write paths,
* frees memory, and invalidates all of your file handles.
*
* Note that this call can FAIL if there's a file open for writing that
* refuses to close (for example, the underlying operating system was
* buffering writes to network filesystem, and the fileserver has crashed,
* or a hard drive has failed, etc). It is usually best to close all write
* handles yourself before calling this function, so that you can gracefully
* handle a specific failure.
*
* Once successfully deinitialized, PHYSFS_init() can be called again to
* restart the subsystem. All default API states are restored at this
* point, with the exception of any custom allocator you might have
* specified, which survives between initializations.
*
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
* undefined, and probably badly screwed up.
*
* \sa PHYSFS_init
* \sa PHYSFS_isInit
*/
__EXPORT__ int PHYSFS_deinit(void);
/**
* \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)
* \brief Get a list of supported archive types.
*
* Get a list of archive types supported by this implementation of PhysicFS.
* These are the file formats usable for search path entries. This is for
* informational purposes only. Note that the extension listed is merely
* convention: if we list "ZIP", you can open a PkZip-compatible archive
* with an extension of "XYZ", if you like.
*
* The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
* with a NULL entry to signify the end of the list:
*
* \code
* PHYSFS_ArchiveInfo **i;
*
* for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
* {
* printf("Supported archive: [%s], which is [%s].\n",
* (*i)->extension, (*i)->description);
* }
* \endcode
*
* The return values are pointers to static internal memory, and should
* be considered READ ONLY, and never freed.
*
* \return READ ONLY Null-terminated array of READ ONLY structures.
*/
__EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
/**
* \fn void PHYSFS_freeList(void *listVar)
* \brief Deallocate resources of lists returned by PhysicsFS.
*
* Certain PhysicsFS functions return lists of information that are
* dynamically allocated. Use this function to free those resources.
*
* \param listVar List of information specified as freeable by this function.
*
* \sa PHYSFS_getCdRomDirs
* \sa PHYSFS_enumerateFiles
* \sa PHYSFS_getSearchPath
*/
__EXPORT__ void PHYSFS_freeList(void *listVar);
/**
* \fn const char *PHYSFS_getLastError(void)
* \brief Get human-readable error information.
*
* Get the last PhysicsFS error message as a human-readable, null-terminated
* string. This will be NULL if there's been no error since the last call to
* this function. The pointer returned by this call points to an internal
* buffer. Each thread has a unique error state associated with it, but each
* time a new error message is set, it will overwrite the previous one
* associated with that thread. It is safe to call this function at anytime,
* even before PHYSFS_init().
*
* It is not wise to expect a specific string of characters here, since the
* error message may be localized into an unfamiliar language. These strings
* are meant to be passed on directly to the user.
*
* \return READ ONLY string of last error message.
*/
__EXPORT__ const char *PHYSFS_getLastError(void);
/**
* \fn const char *PHYSFS_getDirSeparator(void)
* \brief Get platform-dependent dir separator string.
*
* This returns "\\" on win32, "/" on Unix, and ":" on MacOS. It may be more
* than one character, depending on the platform, and your code should take
* that into account. Note that this is only useful for setting up the
* search/write paths, since access into those dirs always use '/'
* (platform-independent notation) to separate directories. This is also
* handy for getting platform-independent access when using stdio calls.
*
* \return READ ONLY null-terminated string of platform's dir separator.
*/
__EXPORT__ const char *PHYSFS_getDirSeparator(void);
/**
* \fn void PHYSFS_permitSymbolicLinks(int allow)
* \brief Enable or disable following of symbolic links.
*
* Some physical filesystems and archives contain files that are just pointers
* to other files. On the physical filesystem, opening such a link will
* (transparently) open the file that is pointed to.
*
* By default, PhysicsFS will check if a file is really a symlink during open
* calls and fail if it is. Otherwise, the link could take you outside the
* write and search paths, and compromise security.
*
* If you want to take that risk, call this function with a non-zero parameter.
* Note that this is more for sandboxing a program's scripting language, in
* case untrusted scripts try to compromise the system. Generally speaking,
* a user could very well have a legitimate reason to set up a symlink, so
* unless you feel there's a specific danger in allowing them, you should
* permit them.
*
* Symlinks are only explicitly checked when dealing with filenames
* in platform-independent notation. That is, when setting up your
* search and write paths, etc, symlinks are never checked for.
*
* Symbolic link permission can be enabled or disabled at any time after
* you've called PHYSFS_init(), and is disabled by default.
*
* \param allow nonzero to permit symlinks, zero to deny linking.
*
* \sa PHYSFS_symbolicLinksPermitted
*/
__EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
/* !!! FIXME: const this? */
/**
* \fn char **PHYSFS_getCdRomDirs(void)
* \brief Get an array of paths to available CD-ROM drives.
*
* The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
* whatnot on Unix). Dirs are only returned if there is a disc ready and
* accessible in the drive. So if you've got two drives (D: and E:), and only
* E: has a disc in it, then that's all you get. If the user inserts a disc
* in D: and you call this function again, you get both drives. If, on a
* Unix box, the user unmounts a disc and remounts it elsewhere, the next
* call to this function will reflect that change.
*
* This function refers to "CD-ROM" media, but it really means "inserted disc
* media," such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs. It looks for
* filesystems, and as such won't report an audio CD, unless there's a
* mounted filesystem track on it.
*
* The returned value is an array of strings, with a NULL entry to signify the
* end of the list:
*
* \code
* char **cds = PHYSFS_getCdRomDirs();
* char **i;
*
* for (i = cds; *i != NULL; i++)
* printf("cdrom dir [%s] is available.\n", *i);
*
* PHYSFS_freeList(cds);
* \endcode
*
* This call may block while drives spin up. Be forewarned.
*
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
*
* \return Null-terminated array of null-terminated strings.
*
* \sa PHYSFS_getCdRomDirsCallback
*/
__EXPORT__ char **PHYSFS_getCdRomDirs(void);
/**
* \fn const char *PHYSFS_getBaseDir(void)
* \brief Get the path where the application resides.
*
* Helper function.
*
* Get the "base dir". This is the directory where the application was run
* from, which is probably the installation directory, and may or may not
* be the process's current working directory.
*
* You should probably use the base dir in your search path.
*
* \return READ ONLY string of base dir in platform-dependent notation.
*
* \sa PHYSFS_getUserDir
*/
__EXPORT__ const char *PHYSFS_getBaseDir(void);
/**
* \fn const char *PHYSFS_getUserDir(void)
* \brief Get the path where user's home directory resides.
*
* Helper function.
*
* Get the "user dir". This is meant to be a suggestion of where a specific
* user of the system can store files. On Unix, this is her home directory.
* On systems with no concept of multiple home directories (MacOS, win95),
* this will default to something like "C:\mybasedir\users\username"
* where "username" will either be the login name, or "default" if the
* platform doesn't support multiple users, either.
*
* You should probably use the user dir as the basis for your write dir, and
* also put it near the beginning of your search path.
*
* \return READ ONLY string of user dir in platform-dependent notation.
*
* \sa PHYSFS_getBaseDir
*/
__EXPORT__ const char *PHYSFS_getUserDir(void);
/**
* \fn const char *PHYSFS_getWriteDir(void)
* \brief Get path where PhysicsFS will allow file writing.
*
* Get the current write dir. The default write dir is NULL.
*
* \return READ ONLY string of write dir in platform-dependent notation,
* OR NULL IF NO WRITE PATH IS CURRENTLY SET.
*
* \sa PHYSFS_setWriteDir
*/
__EXPORT__ const char *PHYSFS_getWriteDir(void);
/**
* \fn int PHYSFS_setWriteDir(const char *newDir)
* \brief Tell PhysicsFS where it may write files.
*
* Set a new write dir. This will override the previous setting.
*
* This call will fail (and fail to change the write dir) if the current
* write dir still has files open in it.
*
* \param newDir The new directory to be the root of the write dir,
* specified in platform-dependent notation. Setting to NULL
* disables the write dir, so no files can be opened for
* writing via PhysicsFS.
* \return non-zero on success, zero on failure. All attempts to open a file
* for writing via PhysicsFS will fail until this call succeeds.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_getWriteDir
*/
__EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
/**
* \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
* \brief Add an archive or directory to the search path.
*
* This is a legacy call in PhysicsFS 2.0, equivalent to:
* PHYSFS_mount(newDir, NULL, appendToPath);
*
* You must use this and not PHYSFS_mount if binary compatibility with
* PhysicsFS 1.0 is important (which it may not be for many people).
*
* \sa PHYSFS_mount
* \sa PHYSFS_removeFromSearchPath
* \sa PHYSFS_getSearchPath
*/
__EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
/**
* \fn int PHYSFS_removeFromSearchPath(const char *oldDir)
* \brief Remove a directory or archive from the search path.
*
* This must be a (case-sensitive) match to a dir or archive already in the
* search path, specified in platform-dependent notation.
*
* This call will fail (and fail to remove from the path) if the element still
* has files open in it.
*
* \param oldDir dir/archive to remove.
* \return nonzero on success, zero on failure.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_addToSearchPath
* \sa PHYSFS_getSearchPath
*/
__EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
/**
* \fn char **PHYSFS_getSearchPath(void)
* \brief Get the current search path.
*
* The default search path is an empty list.
*
* The returned value is an array of strings, with a NULL entry to signify the
* end of the list:
*
* \code
* char **i;
*
* for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
* printf("[%s] is in the search path.\n", *i);
* \endcode
*
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
*
* \return Null-terminated array of null-terminated strings. NULL if there
* was a problem (read: OUT OF MEMORY).
*
* \sa PHYSFS_getSearchPathCallback
* \sa PHYSFS_addToSearchPath
* \sa PHYSFS_removeFromSearchPath
*/
__EXPORT__ char **PHYSFS_getSearchPath(void);
/**
* \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)
* \brief Set up sane, default paths.
*
* Helper function.
*
* The write dir will be set to "userdir/.organization/appName", which is
* created if it doesn't exist.
*
* The above is sufficient to make sure your program's configuration directory
* is separated from other clutter, and platform-independent. The period
* before "mygame" even hides the directory on Unix systems.
*
* The search path will be:
*
* - The Write Dir (created if it doesn't exist)
* - The Base Dir (PHYSFS_getBaseDir())
* - All found CD-ROM dirs (optionally)
*
* These directories are then searched for files ending with the extension
* (archiveExt), which, if they are valid and supported archives, will also
* be added to the search path. If you specified "PKG" for (archiveExt), and
* there's a file named data.PKG in the base dir, it'll be checked. Archives
* can either be appended or prepended to the search path in alphabetical
* order, regardless of which directories they were found in.
*
* All of this can be accomplished from the application, but this just does it
* all for you. Feel free to add more to the search path manually, too.
*
* \param organization Name of your company/group/etc to be used as a
* dirname, so keep it small, and no-frills.
*
* \param appName Program-specific name of your program, to separate it
* from other programs using PhysicsFS.
*
* \param archiveExt File extension used by your program to specify an
* archive. For example, Quake 3 uses "pk3", even though
* they are just zipfiles. Specify NULL to not dig out
* archives automatically. Do not specify the '.' char;
* If you want to look for ZIP files, specify "ZIP" and
* not ".ZIP" ... the archive search is case-insensitive.
*
* \param includeCdRoms Non-zero to include CD-ROMs in the search path, and
* (if (archiveExt) != NULL) search them for archives.
* This may cause a significant amount of blocking
* while discs are accessed, and if there are no discs
* in the drive (or even not mounted on Unix systems),
* then they may not be made available anyhow. You may
* want to specify zero and handle the disc setup
* yourself.
*
* \param archivesFirst Non-zero to prepend the archives to the search path.
* Zero to append them. Ignored if !(archiveExt).
*
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
const char *appName,
const char *archiveExt,
int includeCdRoms,
int archivesFirst);
/* Directory management stuff ... */
/**
* \fn int PHYSFS_mkdir(const char *dirName)
* \brief Create a directory.
*
* This is specified in platform-independent notation in relation to the
* write dir. All missing parent directories are also created if they
* don't exist.
*
* So if you've got the write dir set to "C:\mygame\writedir" and call
* PHYSFS_mkdir("downloads/maps") then the directories
* "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
* will be created if possible. If the creation of "maps" fails after we
* have successfully created "downloads", then the function leaves the
* created directory behind and reports failure.
*
* \param dirName New dir to create.
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_delete
*/
__EXPORT__ int PHYSFS_mkdir(const char *dirName);
/**
* \fn int PHYSFS_delete(const char *filename)
* \brief Delete a file or directory.
*
* (filename) is specified in platform-independent notation in relation to the
* write dir.
*
* A directory must be empty before this call can delete it.
*
* Deleting a symlink will remove the link, not what it points to, regardless
* of whether you "permitSymLinks" or not.
*
* So if you've got the write dir set to "C:\mygame\writedir" and call
* PHYSFS_delete("downloads/maps/level1.map") then the file
* "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
* physical filesystem, if it exists and the operating system permits the
* deletion.
*
* Note that on Unix systems, deleting a file may be successful, but the
* actual file won't be removed until all processes that have an open
* filehandle to it (including your program) close their handles.
*
* Chances are, the bits that make up the file still exist, they are just
* made available to be written over at a later point. Don't consider this
* a security method or anything. :)
*
* \param filename Filename to delete.
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_delete(const char *filename);
/**
* \fn const char *PHYSFS_getRealDir(const char *filename)
* \brief Figure out where in the search path a file resides.
*
* The file is specified in platform-independent notation. The returned
* filename will be the element of the search path where the file was found,
* which may be a directory, or an archive. Even if there are multiple
* matches in different parts of the search path, only the first one found
* is used, just like when opening a file.
*
* So, if you look for "maps/level1.map", and C:\\mygame is in your search
* path and C:\\mygame\\maps\\level1.map exists, then "C:\mygame" is returned.
*
* If a any part of a match is a symbolic link, and you've not explicitly
* permitted symlinks, then it will be ignored, and the search for a match
* will continue.
*
* If you specify a fake directory that only exists as a mount point, it'll
* be associated with the first archive mounted there, even though that
* directory isn't necessarily contained in a real archive.
*
* \param filename file to look for.
* \return READ ONLY string of element of search path containing the
* the file in question. NULL if not found.
*/
__EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
/**
* \fn char **PHYSFS_enumerateFiles(const char *dir)
* \brief Get a file listing of a search path's directory.
*
* Matching directories are interpolated. That is, if "C:\mydir" is in the
* search path and contains a directory "savegames" that contains "x.sav",
* "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path
* that has a "savegames" subdirectory with "w.sav", then the following code:
*
* \code
* char **rc = PHYSFS_enumerateFiles("savegames");
* char **i;
*
* for (i = rc; *i != NULL; i++)
* printf(" * We've got [%s].\n", *i);
*
* PHYSFS_freeList(rc);
* \endcode
*
* \...will print:
*
* \verbatim
* We've got [x.sav].
* We've got [y.sav].
* We've got [z.sav].
* We've got [w.sav].\endverbatim
*
* Feel free to sort the list however you like. We only promise there will
* be no duplicates, but not what order the final list will come back in.
*
* Don't forget to call PHYSFS_freeList() with the return value from this
* function when you are done with it.
*
* \param dir directory in platform-independent notation to enumerate.
* \return Null-terminated array of null-terminated strings.
*
* \sa PHYSFS_enumerateFilesCallback
*/
__EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
/**
* \fn int PHYSFS_exists(const char *fname)
* \brief Determine if a file exists in the search path.
*
* Reports true if there is an entry anywhere in the search path by the
* name of (fname).
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
* might end up further down in the search path than expected.
*
* \param fname filename in platform-independent notation.
* \return non-zero if filename exists. zero otherwise.
*
* \sa PHYSFS_isDirectory
* \sa PHYSFS_isSymbolicLink
*/
__EXPORT__ int PHYSFS_exists(const char *fname);
/**
* \fn int PHYSFS_isDirectory(const char *fname)
* \brief Determine if a file in the search path is really a directory.
*
* Determine if the first occurence of (fname) in the search path is
* really a directory entry.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
* might end up further down in the search path than expected.
*
* \param fname filename in platform-independent notation.
* \return non-zero if filename exists and is a directory. zero otherwise.
*
* \sa PHYSFS_exists
* \sa PHYSFS_isSymbolicLink
*/
__EXPORT__ int PHYSFS_isDirectory(const char *fname);
/**
* \fn int PHYSFS_isSymbolicLink(const char *fname)
* \brief Determine if a file in the search path is really a symbolic link.
*
* Determine if the first occurence of (fname) in the search path is
* really a symbolic link.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
* this function will always return 0 in that case.
*
* \param fname filename in platform-independent notation.
* \return non-zero if filename exists and is a symlink. zero otherwise.
*
* \sa PHYSFS_exists
* \sa PHYSFS_isDirectory
*/
__EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
/**
* \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
* \brief Get the last modification time of a file.
*
* The modtime is returned as a number of seconds since the epoch
* (Jan 1, 1970). The exact derivation and accuracy of this time depends on
* the particular archiver. If there is no reasonable way to obtain this
* information for a particular archiver, or there was some sort of error,
* this function returns (-1).
*
* \param filename filename to check, in platform-independent notation.
* \return last modified time of the file. -1 if it can't be determined.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
/* i/o stuff... */
/**
* \fn PHYSFS_File *PHYSFS_openWrite(const char *filename)
* \brief Open a file for writing.
*
* Open a file for writing, in platform-independent notation and in relation
* to the write dir as the root of the writable filesystem. The specified
* file is created if it doesn't exist. If it does exist, it is truncated to
* zero bytes, and the writing offset is set to the start.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
* \param filename File to open.
* \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_openRead
* \sa PHYSFS_openAppend
* \sa PHYSFS_write
* \sa PHYSFS_close
*/
__EXPORT__ PHYSFS_File *PHYSFS_openWrite(const char *filename);
/**
* \fn PHYSFS_File *PHYSFS_openAppend(const char *filename)
* \brief Open a file for appending.
*
* Open a file for writing, in platform-independent notation and in relation
* to the write dir as the root of the writable filesystem. The specified
* file is created if it doesn't exist. If it does exist, the writing offset
* is set to the end of the file, so the first write will be the byte after
* the end.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
* \param filename File to open.
* \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_openRead
* \sa PHYSFS_openWrite
* \sa PHYSFS_write
* \sa PHYSFS_close
*/
__EXPORT__ PHYSFS_File *PHYSFS_openAppend(const char *filename);
/**
* \fn PHYSFS_File *PHYSFS_openRead(const char *filename)
* \brief Open a file for reading.
*
* Open a file for reading, in platform-independent notation. The search path
* is checked one at a time until a matching file is found, in which case an
* abstract filehandle is associated with it, and reading may be done.
* The reading offset is set to the first byte of the file.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
* \param filename File to open.
* \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_openWrite
* \sa PHYSFS_openAppend
* \sa PHYSFS_read
* \sa PHYSFS_close
*/
__EXPORT__ PHYSFS_File *PHYSFS_openRead(const char *filename);
/**
* \fn int PHYSFS_close(PHYSFS_File *handle)
* \brief Close a PhysicsFS filehandle.
*
* This call is capable of failing if the operating system was buffering
* writes to the physical media, and, now forced to write those changes to
* physical media, can not store the data for some reason. In such a case,
* the filehandle stays open. A well-written program should ALWAYS check the
* return value from the close call in addition to every writing call!
*
* \param handle handle returned from PHYSFS_open*().
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_openRead
* \sa PHYSFS_openWrite
* \sa PHYSFS_openAppend
*/
__EXPORT__ int PHYSFS_close(PHYSFS_File *handle);
/**
* \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
* \brief Read data from a PhysicsFS filehandle
*
* The file must be opened for reading.
*
* \param handle handle returned from PHYSFS_openRead().
* \param buffer buffer to store read data into.
* \param objSize size in bytes of objects being read from (handle).
* \param objCount number of (objSize) objects to read from (handle).
* \return number of objects read. PHYSFS_getLastError() can shed light on
* the reason this might be < (objCount), as can PHYSFS_eof().
* -1 if complete failure.
*
* \sa PHYSFS_eof
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle,
void *buffer,
PHYSFS_uint32 objSize,
PHYSFS_uint32 objCount);
/**
* \fn PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle, const void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
* \brief Write data to a PhysicsFS filehandle
*
* The file must be opened for writing.
*
* \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
* \param buffer buffer of bytes to write to (handle).
* \param objSize size in bytes of objects being written to (handle).
* \param objCount number of (objSize) objects to write to (handle).
* \return number of objects written. PHYSFS_getLastError() can shed light on
* the reason this might be < (objCount). -1 if complete failure.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle,
const void *buffer,
PHYSFS_uint32 objSize,
PHYSFS_uint32 objCount);
/* File position stuff... */
/**
* \fn int PHYSFS_eof(PHYSFS_File *handle)
* \brief Check for end-of-file state on a PhysicsFS filehandle.
*
* Determine if the end of file has been reached in a PhysicsFS filehandle.
*
* \param handle handle returned from PHYSFS_openRead().
* \return nonzero if EOF, zero if not.
*
* \sa PHYSFS_read
* \sa PHYSFS_tell
*/
__EXPORT__ int PHYSFS_eof(PHYSFS_File *handle);
/**
* \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle)
* \brief Determine current position within a PhysicsFS filehandle.
*
* \param handle handle returned from PHYSFS_open*().
* \return offset in bytes from start of file. -1 if error occurred.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_seek
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle);
/**
* \fn int PHYSFS_seek(PHYSFS_File *handle, PHYSFS_uint64 pos)
* \brief Seek to a new position within a PhysicsFS filehandle.
*
* The next read or write will occur at that place. Seeking past the
* beginning or end of the file is not allowed, and causes an error.
*
* \param handle handle returned from PHYSFS_open*().
* \param pos number of bytes from start of file to seek to.
* \return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_tell
*/
__EXPORT__ int PHYSFS_seek(PHYSFS_File *handle, PHYSFS_uint64 pos);
/**
* \fn PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle)
* \brief Get total length of a file in bytes.
*
* Note that if the file size can't be determined (since the archive is
* "streamed" or whatnot) than this will report (-1). Also note that if
* another process/thread is writing to this file at the same time, then
* the information this function supplies could be incorrect before you
* get it. Use with caution, or better yet, don't use at all.
*
* \param handle handle returned from PHYSFS_open*().
* \return size in bytes of the file. -1 if can't be determined.
*
* \sa PHYSFS_tell
* \sa PHYSFS_seek
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle);
/* Buffering stuff... */
/**
* \fn int PHYSFS_setBuffer(PHYSFS_File *handle, PHYSFS_uint64 bufsize)
* \brief Set up buffering for a PhysicsFS file handle.
*
* Define an i/o buffer for a file handle. A memory block of (bufsize) bytes
* will be allocated and associated with (handle).
*
* For files opened for reading, up to (bufsize) bytes are read from (handle)
* and stored in the internal buffer. Calls to PHYSFS_read() will pull
* from this buffer until it is empty, and then refill it for more reading.
* Note that compressed files, like ZIP archives, will decompress while
* buffering, so this can be handy for offsetting CPU-intensive operations.
* The buffer isn't filled until you do your next read.
*
* For files opened for writing, data will be buffered to memory until the
* buffer is full or the buffer is flushed. Closing a handle implicitly
* causes a flush...check your return values!
*
* Seeking, etc transparently accounts for buffering.
*
* You can resize an existing buffer by calling this function more than once
* on the same file. Setting the buffer size to zero will free an existing
* buffer.
*
* PhysicsFS file handles are unbuffered by default.
*
* Please check the return value of this function! Failures can include
* not being able to seek backwards in a read-only file when removing the
* buffer, not being able to allocate the buffer, and not being able to
* flush the buffer to disk, among other unexpected problems.
*
* \param handle handle returned from PHYSFS_open*().
* \param bufsize size, in bytes, of buffer to allocate.
* \return nonzero if successful, zero on error.
*
* \sa PHYSFS_flush
* \sa PHYSFS_read
* \sa PHYSFS_write
* \sa PHYSFS_close
*/
__EXPORT__ int PHYSFS_setBuffer(PHYSFS_File *handle, PHYSFS_uint64 bufsize);
/**
* \fn int PHYSFS_flush(PHYSFS_File *handle)
* \brief Flush a buffered PhysicsFS file handle.
*
* For buffered files opened for writing, this will put the current contents
* of the buffer to disk and flag the buffer as empty if possible.
*
* For buffered files opened for reading or unbuffered files, this is a safe
* no-op, and will report success.
*
* \param handle handle returned from PHYSFS_open*().
* \return nonzero if successful, zero on error.
*
* \sa PHYSFS_setBuffer
* \sa PHYSFS_close
*/
__EXPORT__ int PHYSFS_flush(PHYSFS_File *handle);
/* Byteorder stuff... */
/**
* \fn PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val)
* \brief Swap littleendian signed 16 to platform's native byte order.
*
* Take a 16-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val);
/**
* \fn PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val)
* \brief Swap littleendian unsigned 16 to platform's native byte order.
*
* Take a 16-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val);
/**
* \fn PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val)
* \brief Swap littleendian signed 32 to platform's native byte order.
*
* Take a 32-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val);
/**
* \fn PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val)
* \brief Swap littleendian unsigned 32 to platform's native byte order.
*
* Take a 32-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val);
/**
* \fn PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val)
* \brief Swap littleendian signed 64 to platform's native byte order.
*
* Take a 64-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val);
/**
* \fn PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val)
* \brief Swap littleendian unsigned 64 to platform's native byte order.
*
* Take a 64-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val);
/**
* \fn PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val)
* \brief Swap bigendian signed 16 to platform's native byte order.
*
* Take a 16-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val);
/**
* \fn PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val)
* \brief Swap bigendian unsigned 16 to platform's native byte order.
*
* Take a 16-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val);
/**
* \fn PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val)
* \brief Swap bigendian signed 32 to platform's native byte order.
*
* Take a 32-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val);
/**
* \fn PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val)
* \brief Swap bigendian unsigned 32 to platform's native byte order.
*
* Take a 32-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*/
__EXPORT__ PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val);
/**
* \fn PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val)
* \brief Swap bigendian signed 64 to platform's native byte order.
*
* Take a 64-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val);
/**
* \fn PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val)
* \brief Swap bigendian unsigned 64 to platform's native byte order.
*
* Take a 64-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* \param val value to convert
* \return converted value.
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val);
/**
* \fn int PHYSFS_readSLE16(PHYSFS_File *file, PHYSFS_sint16 *val)
* \brief Read and convert a signed 16-bit littleendian value.
*
* Convenience function. Read a signed 16-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_readSLE16(PHYSFS_File *file, PHYSFS_sint16 *val);
/**
* \fn int PHYSFS_readULE16(PHYSFS_File *file, PHYSFS_uint16 *val)
* \brief Read and convert an unsigned 16-bit littleendian value.
*
* Convenience function. Read an unsigned 16-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
*/
__EXPORT__ int PHYSFS_readULE16(PHYSFS_File *file, PHYSFS_uint16 *val);
/**
* \fn int PHYSFS_readSBE16(PHYSFS_File *file, PHYSFS_sint16 *val)
* \brief Read and convert a signed 16-bit bigendian value.
*
* Convenience function. Read a signed 16-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_readSBE16(PHYSFS_File *file, PHYSFS_sint16 *val);
/**
* \fn int PHYSFS_readUBE16(PHYSFS_File *file, PHYSFS_uint16 *val)
* \brief Read and convert an unsigned 16-bit bigendian value.
*
* Convenience function. Read an unsigned 16-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
*/
__EXPORT__ int PHYSFS_readUBE16(PHYSFS_File *file, PHYSFS_uint16 *val);
/**
* \fn int PHYSFS_readSLE32(PHYSFS_File *file, PHYSFS_sint32 *val)
* \brief Read and convert a signed 32-bit littleendian value.
*
* Convenience function. Read a signed 32-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_readSLE32(PHYSFS_File *file, PHYSFS_sint32 *val);
/**
* \fn int PHYSFS_readULE32(PHYSFS_File *file, PHYSFS_uint32 *val)
* \brief Read and convert an unsigned 32-bit littleendian value.
*
* Convenience function. Read an unsigned 32-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
*/
__EXPORT__ int PHYSFS_readULE32(PHYSFS_File *file, PHYSFS_uint32 *val);
/**
* \fn int PHYSFS_readSBE32(PHYSFS_File *file, PHYSFS_sint32 *val)
* \brief Read and convert a signed 32-bit bigendian value.
*
* Convenience function. Read a signed 32-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_readSBE32(PHYSFS_File *file, PHYSFS_sint32 *val);
/**
* \fn int PHYSFS_readUBE32(PHYSFS_File *file, PHYSFS_uint32 *val)
* \brief Read and convert an unsigned 32-bit bigendian value.
*
* Convenience function. Read an unsigned 32-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
*/
__EXPORT__ int PHYSFS_readUBE32(PHYSFS_File *file, PHYSFS_uint32 *val);
/**
* \fn int PHYSFS_readSLE64(PHYSFS_File *file, PHYSFS_sint64 *val)
* \brief Read and convert a signed 64-bit littleendian value.
*
* Convenience function. Read a signed 64-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_readSLE64(PHYSFS_File *file, PHYSFS_sint64 *val);
/**
* \fn int PHYSFS_readULE64(PHYSFS_File *file, PHYSFS_uint64 *val)
* \brief Read and convert an unsigned 64-bit littleendian value.
*
* Convenience function. Read an unsigned 64-bit littleendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_readULE64(PHYSFS_File *file, PHYSFS_uint64 *val);
/**
* \fn int PHYSFS_readSBE64(PHYSFS_File *file, PHYSFS_sint64 *val)
* \brief Read and convert a signed 64-bit bigendian value.
*
* Convenience function. Read a signed 64-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_readSBE64(PHYSFS_File *file, PHYSFS_sint64 *val);
/**
* \fn int PHYSFS_readUBE64(PHYSFS_File *file, PHYSFS_uint64 *val)
* \brief Read and convert an unsigned 64-bit bigendian value.
*
* Convenience function. Read an unsigned 64-bit bigendian value from a
* file and convert it to the platform's native byte order.
*
* \param file PhysicsFS file handle from which to read.
* \param val pointer to where value should be stored.
* \return zero on failure, non-zero on success. If successful, (*val) will
* store the result. On failure, you can find out what went wrong
* from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_readUBE64(PHYSFS_File *file, PHYSFS_uint64 *val);
/**
* \fn int PHYSFS_writeSLE16(PHYSFS_File *file, PHYSFS_sint16 val)
* \brief Convert and write a signed 16-bit littleendian value.
*
* Convenience function. Convert a signed 16-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeSLE16(PHYSFS_File *file, PHYSFS_sint16 val);
/**
* \fn int PHYSFS_writeULE16(PHYSFS_File *file, PHYSFS_uint16 val)
* \brief Convert and write an unsigned 16-bit littleendian value.
*
* Convenience function. Convert an unsigned 16-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeULE16(PHYSFS_File *file, PHYSFS_uint16 val);
/**
* \fn int PHYSFS_writeSBE16(PHYSFS_File *file, PHYSFS_sint16 val)
* \brief Convert and write a signed 16-bit bigendian value.
*
* Convenience function. Convert a signed 16-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeSBE16(PHYSFS_File *file, PHYSFS_sint16 val);
/**
* \fn int PHYSFS_writeUBE16(PHYSFS_File *file, PHYSFS_uint16 val)
* \brief Convert and write an unsigned 16-bit bigendian value.
*
* Convenience function. Convert an unsigned 16-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeUBE16(PHYSFS_File *file, PHYSFS_uint16 val);
/**
* \fn int PHYSFS_writeSLE32(PHYSFS_File *file, PHYSFS_sint32 val)
* \brief Convert and write a signed 32-bit littleendian value.
*
* Convenience function. Convert a signed 32-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeSLE32(PHYSFS_File *file, PHYSFS_sint32 val);
/**
* \fn int PHYSFS_writeULE32(PHYSFS_File *file, PHYSFS_uint32 val)
* \brief Convert and write an unsigned 32-bit littleendian value.
*
* Convenience function. Convert an unsigned 32-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeULE32(PHYSFS_File *file, PHYSFS_uint32 val);
/**
* \fn int PHYSFS_writeSBE32(PHYSFS_File *file, PHYSFS_sint32 val)
* \brief Convert and write a signed 32-bit bigendian value.
*
* Convenience function. Convert a signed 32-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeSBE32(PHYSFS_File *file, PHYSFS_sint32 val);
/**
* \fn int PHYSFS_writeUBE32(PHYSFS_File *file, PHYSFS_uint32 val)
* \brief Convert and write an unsigned 32-bit bigendian value.
*
* Convenience function. Convert an unsigned 32-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*/
__EXPORT__ int PHYSFS_writeUBE32(PHYSFS_File *file, PHYSFS_uint32 val);
/**
* \fn int PHYSFS_writeSLE64(PHYSFS_File *file, PHYSFS_sint64 val)
* \brief Convert and write a signed 64-bit littleendian value.
*
* Convenience function. Convert a signed 64-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_writeSLE64(PHYSFS_File *file, PHYSFS_sint64 val);
/**
* \fn int PHYSFS_writeULE64(PHYSFS_File *file, PHYSFS_uint64 val)
* \brief Convert and write an unsigned 64-bit littleendian value.
*
* Convenience function. Convert an unsigned 64-bit value from the platform's
* native byte order to littleendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_writeULE64(PHYSFS_File *file, PHYSFS_uint64 val);
/**
* \fn int PHYSFS_writeSBE64(PHYSFS_File *file, PHYSFS_sint64 val)
* \brief Convert and write a signed 64-bit bigending value.
*
* Convenience function. Convert a signed 64-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_writeSBE64(PHYSFS_File *file, PHYSFS_sint64 val);
/**
* \fn int PHYSFS_writeUBE64(PHYSFS_File *file, PHYSFS_uint64 val)
* \brief Convert and write an unsigned 64-bit bigendian value.
*
* Convenience function. Convert an unsigned 64-bit value from the platform's
* native byte order to bigendian and write it to a file.
*
* \param file PhysicsFS file handle to which to write.
* \param val Value to convert and write.
* \return zero on failure, non-zero on success. On failure, you can
* find out what went wrong from PHYSFS_getLastError().
*
* \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
* any sort of 64-bit support.
*/
__EXPORT__ int PHYSFS_writeUBE64(PHYSFS_File *file, PHYSFS_uint64 val);
/* Everything above this line is part of the PhysicsFS 1.0 API. */
/**
* \fn int PHYSFS_isInit(void)
* \brief Determine if the PhysicsFS library is initialized.
*
* Once PHYSFS_init() returns successfully, this will return non-zero.
* Before a successful PHYSFS_init() and after PHYSFS_deinit() returns
* successfully, this will return zero. This function is safe to call at
* any time.
*
* \return non-zero if library is initialized, zero if library is not.
*
* \sa PHYSFS_init
* \sa PHYSFS_deinit
*/
__EXPORT__ int PHYSFS_isInit(void);
/**
* \fn int PHYSFS_symbolicLinksPermitted(void)
* \brief Determine if the symbolic links are permitted.
*
* This reports the setting from the last call to PHYSFS_permitSymbolicLinks().
* If PHYSFS_permitSymbolicLinks() hasn't been called since the library was
* last initialized, symbolic links are implicitly disabled.
*
* \return non-zero if symlinks are permitted, zero if not.
*
* \sa PHYSFS_permitSymbolicLinks
*/
__EXPORT__ int PHYSFS_symbolicLinksPermitted(void);
/**
* \struct PHYSFS_Allocator
* \brief PhysicsFS allocation function pointers.
*
* (This is for limited, hardcore use. If you don't immediately see a need
* for it, you can probably ignore this forever.)
*
* You create one of these structures for use with PHYSFS_setAllocator.
* Allocators are assumed to be reentrant by the caller; please mutex
* accordingly.
*
* Allocations are always discussed in 64-bits, for future expansion...we're
* on the cusp of a 64-bit transition, and we'll probably be allocating 6
* gigabytes like it's nothing sooner or later, and I don't want to change
* this again at that point. If you're on a 32-bit platform and have to
* downcast, it's okay to return NULL if the allocation is greater than
* 4 gigabytes, since you'd have to do so anyhow.
*
* \sa PHYSFS_setAllocator
*/
typedef struct PHYSFS_Allocator
{
int (*Init)(void); /**< Initialize. Can be NULL. Zero on failure. */
void (*Deinit)(void); /**< Deinitialize your allocator. Can be NULL. */
void *(*Malloc)(PHYSFS_uint64); /**< Allocate like malloc(). */
void *(*Realloc)(void *, PHYSFS_uint64); /**< Reallocate like realloc(). */
void (*Free)(void *); /**< Free memory from Malloc or Realloc. */
} PHYSFS_Allocator;
/**
* \fn int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator)
* \brief Hook your own allocation routines into PhysicsFS.
*
* (This is for limited, hardcore use. If you don't immediately see a need
* for it, you can probably ignore this forever.)
*
* By default, PhysicsFS will use whatever is reasonable for a platform
* to manage dynamic memory (usually ANSI C malloc/realloc/calloc/free, but
* some platforms might use something else), but in some uncommon cases, the
* app might want more control over the library's memory management. This
* lets you redirect PhysicsFS to use your own allocation routines instead.
* You can only call this function before PHYSFS_init(); if the library is
* initialized, it'll reject your efforts to change the allocator mid-stream.
* You may call this function after PHYSFS_deinit() if you are willing to
* shut down the library and restart it with a new allocator; this is a safe
* and supported operation. The allocator remains intact between deinit/init
* calls. If you want to return to the platform's default allocator, pass a
* NULL in here.
*
* If you aren't immediately sure what to do with this function, you can
* safely ignore it altogether.
*
* \param allocator Structure containing your allocator's entry points.
* \return zero on failure, non-zero on success. This call only fails
* when used between PHYSFS_init() and PHYSFS_deinit() calls.
*/
__EXPORT__ int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator);
/**
* \fn int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath)
* \brief Add an archive or directory to the search path.
*
* If this is a duplicate, the entry is not added again, even though the
* function succeeds. You may not add the same archive to two different
* mountpoints: duplicate checking is done against the archive and not the
* mountpoint.
*
* When you mount an archive, it is added to a virtual file system...all files
* in all of the archives are interpolated into a single hierachical file
* tree. Two archives mounted at the same place (or an archive with files
* overlapping another mountpoint) may have overlapping files: in such a case,
* the file earliest in the search path is selected, and the other files are
* inaccessible to the application. This allows archives to be used to
* override previous revisions; you can use the mounting mechanism to place
* archives at a specific point in the file tree and prevent overlap; this
* is useful for downloadable mods that might trample over application data
* or each other, for example.
*
* The mountpoint does not need to exist prior to mounting, which is different
* than those familiar with the Unix concept of "mounting" may not expect.
* As well, more than one archive can be mounted to the same mountpoint, or
* mountpoints and archive contents can overlap...the interpolation mechanism
* still functions as usual.
*
* \param newDir directory or archive to add to the path, in
* platform-dependent notation.
* \param mountPoint Location in the interpolated tree that this archive
* will be "mounted", in platform-independent notation.
* NULL or "" is equivalent to "/".
* \param appendToPath nonzero to append to search path, zero to prepend.
* \return nonzero if added to path, zero on failure (bogus archive, dir
* missing, etc). Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*
* \sa PHYSFS_removeFromSearchPath
* \sa PHYSFS_getSearchPath
* \sa PHYSFS_getMountPoint
*/
__EXPORT__ int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath);
/**
* \fn int PHYSFS_getMountPoint(const char *dir)
* \brief Determine a mounted archive's mountpoint.
*
* You give this function the name of an archive or dir you successfully
* added to the search path, and it reports the location in the interpolated
* tree where it is mounted. Files mounted with a NULL mountpoint or through
* PHYSFS_addToSearchPath() will report "/". The return value is READ ONLY
* and valid until the archive is removed from the search path.
*
* \param dir directory or archive previously added to the path, in
* platform-dependent notation. This must match the string
* used when adding, even if your string would also reference
* the same file with a different string of characters.
* \return READ-ONLY string of mount point if added to path, NULL on failure
* (bogus archive, etc) Specifics of the error can be gleaned from
* PHYSFS_getLastError().
*
* \sa PHYSFS_removeFromSearchPath
* \sa PHYSFS_getSearchPath
* \sa PHYSFS_getMountPoint
*/
__EXPORT__ const char *PHYSFS_getMountPoint(const char *dir);
/**
* \typedef PHYSFS_StringCallback
* \brief Function signature for callbacks that report strings.
*
* These are used to report a list of strings to an original caller, one
* string per callback. All strings are UTF-8 encoded. Functions should not
* try to modify or free the string's memory.
*
* These callbacks are used, starting in PhysicsFS 1.1, as an alternative to
* functions that would return lists that need to be cleaned up with
* PHYSFS_freeList(). The callback means that the library doesn't need to
* allocate an entire list and all the strings up front.
*
* Be aware that promises data ordering in the list versions are not
* necessarily so in the callback versions. Check the documentation on
* specific APIs, but strings may not be sorted as you expect.
*
* \param data User-defined data pointer, passed through from the API
* that eventually called the callback.
* \param str The string data about which the callback is meant to inform.
*
* \sa PHYSFS_getCdRomDirsCallback
* \sa PHYSFS_getSearchPathCallback
*/
typedef void (*PHYSFS_StringCallback)(void *data, const char *str);
/**
* \typedef PHYSFS_EnumFilesCallback
* \brief Function signature for callbacks that enumerate files.
*
* These are used to report a list of directory entries to an original caller,
* one file/dir/symlink per callback. All strings are UTF-8 encoded.
* Functions should not try to modify or free any string's memory.
*
* These callbacks are used, starting in PhysicsFS 1.1, as an alternative to
* functions that would return lists that need to be cleaned up with
* PHYSFS_freeList(). The callback means that the library doesn't need to
* allocate an entire list and all the strings up front.
*
* Be aware that promises data ordering in the list versions are not
* necessarily so in the callback versions. Check the documentation on
* specific APIs, but strings may not be sorted as you expect.
*
* \param data User-defined data pointer, passed through from the API
* that eventually called the callback.
* \param origdir A string containing the full path, in platform-independent
* notation, of the directory containing this file. In most
* cases, this is the directory on which you requested
* enumeration, passed in the callback for your convenience.
* \param fname The filename that is being enumerated. It may not be in
* alphabetical order compared to other callbacks that have
* fired, and it will not contain the full path. You can
* recreate the fullpath with $origdir/$fname ... The file
* can be a subdirectory, a file, a symlink, etc.
*
* \sa PHYSFS_enumerateFilesCallback
*/
typedef void (*PHYSFS_EnumFilesCallback)(void *data, const char *origdir,
const char *fname);
/**
* \fn void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d)
* \brief Enumerate CD-ROM directories, using an application-defined callback.
*
* Internally, PHYSFS_getCdRomDirs() just calls this function and then builds
* a list before returning to the application, so functionality is identical
* except for how the information is represented to the application.
*
* Unlike PHYSFS_getCdRomDirs(), this function does not return an array.
* Rather, it calls a function specified by the application once per
* detected disc:
*
* \code
*
* static void foundDisc(void *data, const char *cddir)
* {
* printf("cdrom dir [%s] is available.\n", cddir);
* }
*
* // ...
* PHYSFS_getCdRomDirsCallback(foundDisc, NULL);
* \endcode
*
* This call may block while drives spin up. Be forewarned.
*
* \param c Callback function to notify about detected drives.
* \param d Application-defined data passed to callback. Can be NULL.
*
* \sa PHYSFS_StringCallback
* \sa PHYSFS_getCdRomDirs
*/
__EXPORT__ void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d);
/**
* \fn void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d)
* \brief Enumerate the search path, using an application-defined callback.
*
* Internally, PHYSFS_getSearchPath() just calls this function and then builds
* a list before returning to the application, so functionality is identical
* except for how the information is represented to the application.
*
* Unlike PHYSFS_getSearchPath(), this function does not return an array.
* Rather, it calls a function specified by the application once per
* element of the search path:
*
* \code
*
* static void printSearchPath(void *data, const char *pathItem)
* {
* printf("[%s] is in the search path.\n", pathItem);
* }
*
* // ...
* PHYSFS_getSearchPathCallback(printSearchPath, NULL);
* \endcode
*
* Elements of the search path are reported in order search priority, so the
* first archive/dir that would be examined when looking for a file is the
* first element passed through the callback.
*
* \param c Callback function to notify about search path elements.
* \param d Application-defined data passed to callback. Can be NULL.
*
* \sa PHYSFS_StringCallback
* \sa PHYSFS_getSearchPath
*/
__EXPORT__ void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d);
/**
* \fn void PHYSFS_enumerateFilesCallback(const char *dir, PHYSFS_EnumFilesCallback c, void *d)
* \brief Get a file listing of a search path's directory, using an application-defined callback.
*
* Internally, PHYSFS_enumerateFiles() just calls this function and then builds
* a list before returning to the application, so functionality is identical
* except for how the information is represented to the application.
*
* Unlike PHYSFS_enumerateFiles(), this function does not return an array.
* Rather, it calls a function specified by the application once per
* element of the search path:
*
* \code
*
* static void printDir(void *data, const char *origdir, const char *fname)
* {
* printf(" * We've got [%s] in [%s].\n", fname, origdir);
* }
*
* // ...
* PHYSFS_enumerateFilesCallback("/some/path", printDir, NULL);
* \endcode
*
* Items sent to the callback are not guaranteed to be in any order whatsoever.
* There is no sorting done at this level, and if you need that, you should
* probably use PHYSFS_enumerateFiles() instead, which guarantees
* alphabetical sorting. This form reports whatever is discovered in each
* archive before moving on to the next. Even within one archive, we can't
* guarantee what order it will discover data. <em>Any sorting you find in
* these callbacks is just pure luck. Do not rely on it.</em>
*
* \param dir Directory, in platform-independent notation, to enumerate.
* \param c Callback function to notify about search path elements.
* \param d Application-defined data passed to callback. Can be NULL.
*
* \sa PHYSFS_EnumFilesCallback
* \sa PHYSFS_enumerateFiles
*/
__EXPORT__ void PHYSFS_enumerateFilesCallback(const char *dir,
PHYSFS_EnumFilesCallback c,
void *d);
/**
* \fn void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst, PHYSFS_uint64 len)
* \brief Convert a UCS-4 string to a UTF-8 string.
*
* UCS-4 strings are 32-bits per character: \c wchar_t on Unix.
*
* To ensure that the destination buffer is large enough for the conversion,
* please allocate a buffer that is the same size as the source buffer. UTF-8
* never uses more than 32-bits per character, so while it may shrink a UCS-4
* string, it will never expand it.
*
* Strings that don't fit in the destination buffer will be truncated, but
* will always be null-terminated and never have an incomplete UTF-8
* sequence at the end. If the buffer length is 0, this function does nothing.
*
* \param src Null-terminated source string in UCS-4 format.
* \param dst Buffer to store converted UTF-8 string.
* \param len Size, in bytes, of destination buffer.
*/
__EXPORT__ void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst,
PHYSFS_uint64 len);
/**
* \fn void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-8 string to a UCS-4 string.
*
* UCS-4 strings are 32-bits per character: \c wchar_t on Unix.
*
* To ensure that the destination buffer is large enough for the conversion,
* please allocate a buffer that is four times the size of the source buffer.
* UTF-8 uses from one to four bytes per character, but UCS-4 always uses
* four, so an entirely low-ASCII string will quadruple in size!
*
* Strings that don't fit in the destination buffer will be truncated, but
* will always be null-terminated and never have an incomplete UCS-4
* sequence at the end. If the buffer length is 0, this function does nothing.
*
* \param src Null-terminated source string in UTF-8 format.
* \param dst Buffer to store converted UCS-4 string.
* \param len Size, in bytes, of destination buffer.
*/
__EXPORT__ void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst,
PHYSFS_uint64 len);
/**
* \fn void PHYSFS_utf8FromUcs2(const PHYSFS_uint16 *src, char *dst, PHYSFS_uint64 len)
* \brief Convert a UCS-2 string to a UTF-8 string.
*
* UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
* with Unicode support.
*
* To ensure that the destination buffer is large enough for the conversion,
* please allocate a buffer that is double the size of the source buffer.
* UTF-8 never uses more than 32-bits per character, so while it may shrink
* a UCS-2 string, it may also expand it.
*
* Strings that don't fit in the destination buffer will be truncated, but
* will always be null-terminated and never have an incomplete UTF-8
* sequence at the end. If the buffer length is 0, this function does nothing.
*
* Please note that UCS-2 is not UTF-16; we do not support the "surrogate"
* values at this time.
*
* \param src Null-terminated source string in UCS-2 format.
* \param dst Buffer to store converted UTF-8 string.
* \param len Size, in bytes, of destination buffer.
*/
__EXPORT__ void PHYSFS_utf8FromUcs2(const PHYSFS_uint16 *src, char *dst,
PHYSFS_uint64 len);
/**
* \fn PHYSFS_utf8ToUcs2(const char *src, PHYSFS_uint16 *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-8 string to a UCS-2 string.
*
* UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
* with Unicode support.
*
* To ensure that the destination buffer is large enough for the conversion,
* please allocate a buffer that is double the size of the source buffer.
* UTF-8 uses from one to four bytes per character, but UCS-2 always uses
* two, so an entirely low-ASCII string will double in size!
*
* Strings that don't fit in the destination buffer will be truncated, but
* will always be null-terminated and never have an incomplete UCS-2
* sequence at the end. If the buffer length is 0, this function does nothing.
*
* Please note that UCS-2 is not UTF-16; we do not support the "surrogate"
* values at this time.
*
* \param src Null-terminated source string in UTF-8 format.
* \param dst Buffer to store converted UCS-2 string.
* \param len Size, in bytes, of destination buffer.
*/
__EXPORT__ void PHYSFS_utf8ToUcs2(const char *src, PHYSFS_uint16 *dst,
PHYSFS_uint64 len);
/**
* \fn void PHYSFS_utf8FromLatin1(const char *src, char *dst, PHYSFS_uint64 len)
* \brief Convert a UTF-8 string to a Latin1 string.
*
* Latin1 strings are 8-bits per character: a popular "high ASCII"
* encoding.
*
* To ensure that the destination buffer is large enough for the conversion,
* please allocate a buffer that is double the size of the source buffer.
* UTF-8 expands latin1 codepoints over 127 from 1 to 2 bytes, so the string
* may grow in some cases.
*
* Strings that don't fit in the destination buffer will be truncated, but
* will always be null-terminated and never have an incomplete UTF-8
* sequence at the end. If the buffer length is 0, this function does nothing.
*
* Please note that we do not supply a UTF-8 to Latin1 converter, since Latin1
* can't express most Unicode codepoints. It's a legacy encoding; you should
* be converting away from it at all times.
*
* \param src Null-terminated source string in Latin1 format.
* \param dst Buffer to store converted UTF-8 string.
* \param len Size, in bytes, of destination buffer.
*/
__EXPORT__ void PHYSFS_utf8FromLatin1(const char *src, char *dst,
PHYSFS_uint64 len);
/* Everything above this line is part of the PhysicsFS 2.0 API. */
#ifdef __cplusplus
}
#endif
#endif /* !defined _INCLUDE_PHYSFS_H_ */
/* end of physfs.h ... */
|