src/physfs.h
author Ryan C. Gordon <icculus@icculus.org>
Sat, 12 Aug 2017 02:19:22 -0400
changeset 1559 aaee2b83291f
parent 1555 5495a0e50b5e
child 1560 6db57d6bff9a
permissions -rw-r--r--
Reworked enumeration to be more powerful. Now callbacks can stop further enumeration and report errors, if they had a catastrophic issue or just found what they needed and don't need to process any more items. Also, the actual enumerators can report errors instead of silently dropping items. This led to several other fixes as all these implementations got audited and reworked. The original, non-callback enumerator now returns NULL if it can't produce a complete list instead of dropping items and returning a partial list.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1070
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
     1
/**
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
     2
 * \file physfs.h
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
     3
 *
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
     4
 * Main header file for PhysicsFS.
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
     5
 */
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     6
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     7
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     8
 * \mainpage PhysicsFS
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     9
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
    10
 * The latest version of PhysicsFS can be found at:
1373
527ef3c6a2d6 HTTPS all the things.
Ryan C. Gordon <icculus@icculus.org>
parents: 1350
diff changeset
    11
 *     https://icculus.org/physfs/
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
    12
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    13
 * PhysicsFS; a portable, flexible file i/o abstraction.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    14
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    15
 * This API gives you access to a system file system in ways superior to the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    16
 *  stdio or system i/o calls. The brief benefits:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    17
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    18
 *   - It's portable.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    19
 *   - It's safe. No file access is permitted outside the specified dirs.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    20
 *   - It's flexible. Archives (.ZIP files) can be used transparently as
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    21
 *      directory structures.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    22
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    23
 * With PhysicsFS, you have a single writing directory and multiple
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    24
 *  directories (the "search path") for reading. You can think of this as a
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    25
 *  filesystem within a filesystem. If (on Windows) you were to set the
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    26
 *  writing directory to "C:\MyGame\MyWritingDirectory", then no PHYSFS calls
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    27
 *  could touch anything above this directory, including the "C:\MyGame" and
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    28
 *  "C:\" directories. This prevents an application's internal scripting
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    29
 *  language from piddling over c:\\config.sys, for example. If you'd rather
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    30
 *  give PHYSFS full access to the system's REAL file system, set the writing
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    31
 *  dir to "C:\", but that's generally A Bad Thing for several reasons.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    32
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
 * Drive letters are hidden in PhysicsFS once you set up your initial paths.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    34
 *  The search path creates a single, hierarchical directory structure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    35
 *  Not only does this lend itself well to general abstraction with archives,
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    36
 *  it also gives better support to operating systems like MacOS and Unix.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    37
 *  Generally speaking, you shouldn't ever hardcode a drive letter; not only
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    38
 *  does this hurt portability to non-Microsoft OSes, but it limits your win32
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    39
 *  users to a single drive, too. Use the PhysicsFS abstraction functions and
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    40
 *  allow user-defined configuration options, too. When opening a file, you
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    41
 *  specify it like it was on a Unix filesystem: if you want to write to
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    42
 *  "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    43
 *  "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    44
 *  abstraction across all platforms. Specifying a file in this way is termed
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    45
 *  "platform-independent notation" in this documentation. Specifying a
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    46
 *  a filename in a form such as "C:\mydir\myfile" or
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    47
 *  "MacOS hard drive:My Directory:My File" is termed "platform-dependent
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    48
 *  notation". The only time you use platform-dependent notation is when
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    49
 *  setting up your write directory and search path; after that, all file
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    50
 *  access into those directories are done with platform-independent notation.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    51
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    52
 * All files opened for writing are opened in relation to the write directory,
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    53
 *  which is the root of the writable filesystem. When opening a file for
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    54
 *  reading, PhysicsFS goes through the search path. This is NOT the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    55
 *  same thing as the PATH environment variable. An application using
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    56
 *  PhysicsFS specifies directories to be searched which may be actual
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    57
 *  directories, or archive files that contain files and subdirectories of
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    58
 *  their own. See the end of these docs for currently supported archive
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    59
 *  formats.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    60
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    61
 * Once the search path is defined, you may open files for reading. If you've
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    62
 *  got the following search path defined (to use a win32 example again):
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    63
 *
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    64
 *  - C:\\mygame
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    65
 *  - C:\\mygame\\myuserfiles
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    66
 *  - D:\\mygamescdromdatafiles
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    67
 *  - C:\\mygame\\installeddatafiles.zip
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    68
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    69
 * Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    70
 *  separator, lack of drive letter, and lack of dir separator at the start of
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    71
 *  the string; this is platform-independent notation) will check for
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    72
 *  C:\\mygame\\textfiles\\myfile.txt, then
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    73
 *  C:\\mygame\\myuserfiles\\textfiles\\myfile.txt, then
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    74
 *  D:\\mygamescdromdatafiles\\textfiles\\myfile.txt, then, finally, for
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    75
 *  textfiles\\myfile.txt inside of C:\\mygame\\installeddatafiles.zip.
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    76
 *  Remember that most archive types and platform filesystems store their
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    77
 *  filenames in a case-sensitive manner, so you should be careful to specify
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
    78
 *  it correctly.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    79
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    80
 * Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    81
 *  elements. Not only are these meaningless on MacOS Classic and/or Unix,
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    82
 *  they are a security hole. Also, symbolic links (which can be found in
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    83
 *  some archive types and directly in the filesystem on Unix platforms) are
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    84
 *  NOT followed until you call PHYSFS_permitSymbolicLinks(). That's left to
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    85
 *  your own discretion, as following a symlink can allow for access outside
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    86
 *  the write dir and search paths. For portability, there is no mechanism for
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
    87
 *  creating new symlinks in PhysicsFS.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    88
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    89
 * The write dir is not included in the search path unless you specifically
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    90
 *  add it. While you CAN change the write dir as many times as you like,
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    91
 *  you should probably set it once and stick to it. Remember that your
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    92
 *  program will not have permission to write in every directory on Unix and
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    93
 *  NT systems.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    94
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    95
 * All files are opened in binary mode; there is no endline conversion for
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    96
 *  textfiles. Other than that, PhysicsFS has some convenience functions for
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
    97
 *  platform-independence. There is a function to tell you the current
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    98
 *  platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
    99
 *  which is needed only to set up your search/write paths. There is a
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   100
 *  function to tell you what CD-ROM drives contain accessible discs, and a
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   101
 *  function to recommend a good search path, etc.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   102
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   103
 * A recommended order for the search path is the write dir, then the base dir,
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   104
 *  then the cdrom dir, then any archives discovered. Quake 3 does something
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   105
 *  like this, but moves the archives to the start of the search path. Build
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   106
 *  Engine games, like Duke Nukem 3D and Blood, place the archives last, and
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   107
 *  use the base dir for both searching and writing. There is a helper
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   108
 *  function (PHYSFS_setSaneConfig()) that puts together a basic configuration
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   109
 *  for you, based on a few parameters. Also see the comments on
1242
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   110
 *  PHYSFS_getBaseDir(), and PHYSFS_getPrefDir() for info on what those
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   111
 *  are and how they can help you determine an optimal search path.
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   112
 *
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   113
 * PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   114
 *  in the search path. If a zipfile contains "maps/level.map" and you mount
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   115
 *  that archive at "mods/mymod", then you would have to open
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   116
 *  "mods/mymod/maps/level.map" to access the file, even though "mods/mymod"
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   117
 *  isn't actually specified in the .zip file. Unlike the Unix mentality of
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   118
 *  mounting a filesystem, "mods/mymod" doesn't actually have to exist when
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   119
 *  mounting the zipfile. It's a "virtual" directory. The mounting mechanism
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   120
 *  allows the developer to seperate archives in the tree and avoid trampling
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   121
 *  over files when added new archives, such as including mod support in a
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   122
 *  game...keeping external content on a tight leash in this manner can be of
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   123
 *  utmost importance to some applications.
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   124
 *
147
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   125
 * PhysicsFS is mostly thread safe. The error messages returned by
1240
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   126
 *  PHYSFS_getLastError() are unique by thread, and library-state-setting
147
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   127
 *  functions are mutex'd. For efficiency, individual file accesses are 
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   128
 *  not locked, so you can not safely read/write/seek/close/etc the same 
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   129
 *  file from two threads at the same time. Other race conditions are bugs 
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   130
 *  that should be reported/patched.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   131
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   132
 * While you CAN use stdio/syscall file access in a program that has PHYSFS_*
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   133
 *  calls, doing so is not recommended, and you can not use system
147
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   134
 *  filehandles with PhysicsFS and vice versa.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   135
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   136
 * Note that archives need not be named as such: if you have a ZIP file and
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   137
 *  rename it with a .PKG extension, the file will still be recognized as a
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   138
 *  ZIP archive by PhysicsFS; the file's contents are used to determine its
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   139
 *  type where possible.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   140
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   141
 * Currently supported archive types:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   142
 *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)
1069
2f0de4ad18a5 Added some missing file types to the documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 1054
diff changeset
   143
 *   - .7Z  (7zip archives)
2f0de4ad18a5 Added some missing file types to the documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 1054
diff changeset
   144
 *   - .ISO (ISO9660 files, CD-ROM images)
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   145
 *   - .GRP (Build Engine groupfile archives)
559
6fa9e48b537c Forgot to mention qpak in the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 553
diff changeset
   146
 *   - .PAK (Quake I/II archive format)
553
4338d9c0bbcd Descent I/II HOG and MVL archive support (thanks, Bradley Bell!).
Ryan C. Gordon <icculus@icculus.org>
parents: 529
diff changeset
   147
 *   - .HOG (Descent I/II HOG file archives)
4338d9c0bbcd Descent I/II HOG and MVL archive support (thanks, Bradley Bell!).
Ryan C. Gordon <icculus@icculus.org>
parents: 529
diff changeset
   148
 *   - .MVL (Descent II movielib archives)
609
3a91332776e0 Added Doom WAD support.
Ryan C. Gordon <icculus@icculus.org>
parents: 588
diff changeset
   149
 *   - .WAD (DOOM engine archives)
1391
06aa5aca8518 Add support for VDF
Francesco Bertolaccini <bertolaccinifrancesco@gmail.com>
parents: 1383
diff changeset
   150
 *   - .VDF (Gothic I/II engine archives)
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   151
 *
785
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   152
 *
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   153
 * String policy for PhysicsFS 2.0 and later:
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   154
 *
807
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   155
 * PhysicsFS 1.0 could only deal with null-terminated ASCII strings. All high
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   156
 *  ASCII chars resulted in undefined behaviour, and there was no Unicode
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   157
 *  support at all. PhysicsFS 2.0 supports Unicode without breaking binary
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   158
 *  compatibility with the 1.0 API by using UTF-8 encoding of all strings
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   159
 *  passed in and out of the library.
785
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   160
 *
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   161
 * All strings passed through PhysicsFS are in null-terminated UTF-8 format.
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   162
 *  This means that if all you care about is English (ASCII characters <= 127)
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   163
 *  then you just use regular C strings. If you care about Unicode (and you
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   164
 *  should!) then you need to figure out what your platform wants, needs, and
1094
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   165
 *  offers. If you are on Windows before Win2000 and build with Unicode
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   166
 *  support, your TCHAR strings are two bytes per character (this is called
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   167
 *  "UCS-2 encoding"). Any modern Windows uses UTF-16, which is two bytes
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   168
 *  per character for most characters, but some characters are four. You
785
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   169
 *  should convert them to UTF-8 before handing them to PhysicsFS with
1209
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   170
 *  PHYSFS_utf8FromUtf16(), which handles both UTF-16 and UCS-2. If you're
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   171
 *  using Unix or Mac OS X, your wchar_t strings are four bytes per character
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   172
 *  ("UCS-4 encoding"). Use PHYSFS_utf8FromUcs4(). Mac OS X can give you UTF-8
1094
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   173
 *  directly from a CFString or NSString, and many Unixes generally give you C
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   174
 *  strings in UTF-8 format everywhere. If you have a single-byte high ASCII
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   175
 *  charset, like so-many European "codepages" you may be out of luck. We'll
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   176
 *  convert from "Latin1" to UTF-8 only, and never back to Latin1. If you're
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   177
 *  above ASCII 127, all bets are off: move to Unicode or use your platform's
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   178
 *  facilities. Passing a C string with high-ASCII data that isn't UTF-8
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   179
 *  encoded will NOT do what you expect!
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   180
 *
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   181
 * Naturally, there's also PHYSFS_utf8ToUcs2(), PHYSFS_utf8ToUtf16(), and
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   182
 *  PHYSFS_utf8ToUcs4() to get data back into a format you like. Behind the
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   183
 *  scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   184
 *  Windows will be converted and used with the multibyte Windows APIs, for
aa12a958cc47 Added UTF-16 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1092
diff changeset
   185
 *  example.
785
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   186
 *
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   187
 * PhysicsFS offers basic encoding conversion support, but not a whole string
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   188
 *  library. Get your stuff into whatever format you can work with.
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   189
 *
1395
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   190
 * Most platforms supported by PhysicsFS 2.1 and later fully support Unicode.
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   191
 *  Some older platforms have been dropped (Windows 95, Mac OS 9). Some, like
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   192
 *  OS/2, might be able to convert to a local codepage or will just fail to
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   193
 *  open/create the file. Modern OSes (macOS, Linux, Windows, etc) should all
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   194
 *  be fine.
1197
65f35dc8f84c Removed OS/2 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1196
diff changeset
   195
 *
65f35dc8f84c Removed OS/2 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 1196
diff changeset
   196
 * Many game-specific archivers are seriously unprepared for Unicode (the
807
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   197
 *  Descent HOG/MVL and Build Engine GRP archivers, for example, only offer a
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   198
 *  DOS 8.3 filename, for example). Nothing can be done for these, but they
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   199
 *  tend to be legacy formats for existing content that was all ASCII (and
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   200
 *  thus, valid UTF-8) anyhow. Other formats, like .ZIP, don't explicitly
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   201
 *  offer Unicode support, but unofficially expect filenames to be UTF-8
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   202
 *  encoded, and thus Just Work. Most everything does the right thing without
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   203
 *  bothering you, but it's good to be aware of these nuances in case they
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   204
 *  don't.
570b8e53495a More ranting and raving about Unicode.
Ryan C. Gordon <icculus@icculus.org>
parents: 799
diff changeset
   205
 *
785
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   206
 *
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   207
 * Other stuff:
1ea0f6549eb2 Initial Unicode work.
Ryan C. Gordon <icculus@icculus.org>
parents: 779
diff changeset
   208
 *
1272
41d62d118b2f Fixed comment.
Ryan C. Gordon <icculus@icculus.org>
parents: 1254
diff changeset
   209
 * Please see the file LICENSE.txt in the source's root directory for
1209
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   210
 *  licensing and redistribution rights.
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   211
 *
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   212
 * Please see the file CREDITS.txt in the source's "docs" directory for
141eb73da2c5 Minor updates to the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 1202
diff changeset
   213
 *  a more or less complete list of who's responsible for this.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   214
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   215
 *  \author Ryan C. Gordon.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   216
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   217
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   218
#ifndef _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   219
#define _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   220
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   221
#ifdef __cplusplus
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   222
extern "C" {
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   223
#endif
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   224
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   225
#if defined(PHYSFS_DECL)
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   226
/* do nothing. */
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   227
#elif (defined _MSC_VER)
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   228
#define PHYSFS_DECL __declspec(dllexport)
991
9748fd040468 Added the Sun Studio equivalent of -fvisibility=hidden
Ryan C. Gordon <icculus@icculus.org>
parents: 979
diff changeset
   229
#elif (defined __SUNPRO_C)
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   230
#define PHYSFS_DECL __global
994
4413637bdcf2 Corrected __EXPORT__ test for Solaris.
Ryan C. Gordon <icculus@icculus.org>
parents: 991
diff changeset
   231
#elif ((__GNUC__ >= 3) && (!__EMX__) && (!sun))
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   232
#define PHYSFS_DECL __attribute__((visibility("default")))
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   233
#else
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   234
#define PHYSFS_DECL
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   235
#endif
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   236
1099
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   237
#if defined(PHYSFS_DEPRECATED)
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   238
/* do nothing. */
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   239
#elif (__GNUC__ >= 4)  /* technically, this arrived in gcc 3.1, but oh well. */
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   240
#define PHYSFS_DEPRECATED __attribute__((deprecated))
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   241
#else
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   242
#define PHYSFS_DEPRECATED
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   243
#endif
fd12454c37ee Added PHYSFS_DEPRECATED.
Ryan C. Gordon <icculus@icculus.org>
parents: 1098
diff changeset
   244
1025
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   245
#if 0  /* !!! FIXME: look into this later. */
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   246
#if defined(PHYSFS_CALL)
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   247
/* do nothing. */
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   248
#elif defined(__WIN32__) && !defined(__GNUC__)
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   249
#define PHYSFS_CALL __cdecl
1395
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   250
#elif defined(__OS2__) || defined(OS2) /* should work across all compilers. */
2b5c79f64d59 os2: added OS/2 support back in.
Ryan C. Gordon <icculus@icculus.org>
parents: 1391
diff changeset
   251
#define PHYSFS_CALL _System
1025
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   252
#else
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   253
#define PHYSFS_CALL
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   254
#endif
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   255
#endif
b91967e1dc40 Added some (disabled!) calling conventions stuff.
Ryan C. Gordon <icculus@icculus.org>
parents: 1024
diff changeset
   256
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   257
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   258
 * \typedef PHYSFS_uint8
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   259
 * \brief An unsigned, 8-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   260
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   261
typedef unsigned char         PHYSFS_uint8;
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   262
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   263
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   264
 * \typedef PHYSFS_sint8
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   265
 * \brief A signed, 8-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   266
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   267
typedef signed char           PHYSFS_sint8;
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   268
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   269
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   270
 * \typedef PHYSFS_uint16
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   271
 * \brief An unsigned, 16-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   272
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   273
typedef unsigned short        PHYSFS_uint16;
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   274
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   275
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   276
 * \typedef PHYSFS_sint16
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   277
 * \brief A signed, 16-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   278
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   279
typedef signed short          PHYSFS_sint16;
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   280
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   281
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   282
 * \typedef PHYSFS_uint32
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   283
 * \brief An unsigned, 32-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   284
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   285
typedef unsigned int          PHYSFS_uint32;
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   286
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   287
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   288
 * \typedef PHYSFS_sint32
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   289
 * \brief A signed, 32-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   290
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   291
typedef signed int            PHYSFS_sint32;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   292
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   293
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   294
 * \typedef PHYSFS_uint64
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   295
 * \brief An unsigned, 64-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   296
 * \warning on platforms without any sort of 64-bit datatype, this is
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   297
 *           equivalent to PHYSFS_uint32!
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   298
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   299
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   300
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   301
 * \typedef PHYSFS_sint64
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   302
 * \brief A signed, 64-bit integer type.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   303
 * \warning on platforms without any sort of 64-bit datatype, this is
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   304
 *           equivalent to PHYSFS_sint32!
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   305
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   306
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   307
194
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   308
#if (defined PHYSFS_NO_64BIT_SUPPORT)  /* oh well. */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   309
typedef PHYSFS_uint32         PHYSFS_uint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   310
typedef PHYSFS_sint32         PHYSFS_sint64;
194
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   311
#elif (defined _MSC_VER)
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   312
typedef signed __int64        PHYSFS_sint64;
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   313
typedef unsigned __int64      PHYSFS_uint64;
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   314
#else
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   315
typedef unsigned long long    PHYSFS_uint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   316
typedef signed long long      PHYSFS_sint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   317
#endif
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   318
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   319
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   320
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   321
/* Make sure the types really have the right sizes */
1542
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   322
#define PHYSFS_COMPILE_TIME_ASSERT(name, x) \
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   323
       typedef int PHYSFS_compile_time_assert_##name[(x) * 2 - 1]
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   324
1542
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   325
PHYSFS_COMPILE_TIME_ASSERT(uint8IsOneByte, sizeof(PHYSFS_uint8) == 1);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   326
PHYSFS_COMPILE_TIME_ASSERT(sint8IsOneByte, sizeof(PHYSFS_sint8) == 1);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   327
PHYSFS_COMPILE_TIME_ASSERT(uint16IsTwoBytes, sizeof(PHYSFS_uint16) == 2);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   328
PHYSFS_COMPILE_TIME_ASSERT(sint16IsTwoBytes, sizeof(PHYSFS_sint16) == 2);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   329
PHYSFS_COMPILE_TIME_ASSERT(uint32IsFourBytes, sizeof(PHYSFS_uint32) == 4);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   330
PHYSFS_COMPILE_TIME_ASSERT(sint32IsFourBytes, sizeof(PHYSFS_sint32) == 4);
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   331
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   332
#ifndef PHYSFS_NO_64BIT_SUPPORT
1542
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   333
PHYSFS_COMPILE_TIME_ASSERT(uint64IsEightBytes, sizeof(PHYSFS_uint64) == 8);
1027fe6accf1 windows: Patched to compile! (...?)
Ryan C. Gordon <icculus@icculus.org>
parents: 1533
diff changeset
   334
PHYSFS_COMPILE_TIME_ASSERT(sint64IsEightBytes, sizeof(PHYSFS_sint64) == 8);
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   335
#endif
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   336
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   337
#undef PHYSFS_COMPILE_TIME_ASSERT
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   338
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   339
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   340
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   341
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   342
/**
654
c0ae01de361d Changed PHYSFS_file to PHYSFS_File to match rest of API's naming
Ryan C. Gordon <icculus@icculus.org>
parents: 650
diff changeset
   343
 * \struct PHYSFS_File
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   344
 * \brief A PhysicsFS file handle.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   345
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   346
 * You get a pointer to one of these when you open a file for reading,
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   347
 *  writing, or appending via PhysicsFS.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   348
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   349
 * As you can see from the lack of meaningful fields, you should treat this
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   350
 *  as opaque data. Don't try to manipulate the file handle, just pass the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   351
 *  pointer you got, unmolested, to various PhysicsFS APIs.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   352
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   353
 * \sa PHYSFS_openRead
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   354
 * \sa PHYSFS_openWrite
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   355
 * \sa PHYSFS_openAppend
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   356
 * \sa PHYSFS_close
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   357
 * \sa PHYSFS_read
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   358
 * \sa PHYSFS_write
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   359
 * \sa PHYSFS_seek
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   360
 * \sa PHYSFS_tell
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   361
 * \sa PHYSFS_eof
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   362
 * \sa PHYSFS_setBuffer
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   363
 * \sa PHYSFS_flush
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   364
 */
943
5df593de06e2 Added struct typedefs that you can predeclare without including physfs.h
Ryan C. Gordon <icculus@icculus.org>
parents: 897
diff changeset
   365
typedef struct PHYSFS_File
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   366
{
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   367
    void *opaque;  /**< That's all you get. Don't touch. */
654
c0ae01de361d Changed PHYSFS_file to PHYSFS_File to match rest of API's naming
Ryan C. Gordon <icculus@icculus.org>
parents: 650
diff changeset
   368
} PHYSFS_File;
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   369
830
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   370
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   371
/**
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   372
 * \def PHYSFS_file
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   373
 * \brief 1.0 API compatibility define.
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   374
 *
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   375
 * PHYSFS_file is identical to PHYSFS_File. This #define is here for backwards
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   376
 *  compatibility with the 1.0 API, which had an inconsistent capitalization
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   377
 *  convention in this case. New code should use PHYSFS_File, as this #define
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   378
 *  may go away someday.
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   379
 *
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   380
 * \sa PHYSFS_File
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   381
 */
adf9646a3b77 Changed PHYSFS_file from a typedef to a #define for legacy code.
Ryan C. Gordon <icculus@icculus.org>
parents: 828
diff changeset
   382
#define PHYSFS_file PHYSFS_File
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   383
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   384
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   385
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   386
 * \struct PHYSFS_ArchiveInfo
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   387
 * \brief Information on various PhysicsFS-supported archives.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   388
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   389
 * This structure gives you details on what sort of archives are supported
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   390
 *  by this implementation of PhysicsFS. Archives tend to be things like
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   391
 *  ZIP files and such.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   392
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   393
 * \warning Not all binaries are created equal! PhysicsFS can be built with
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   394
 *          or without support for various archives. You can check with
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   395
 *          PHYSFS_supportedArchiveTypes() to see if your archive type is
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   396
 *          supported.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   397
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   398
 * \sa PHYSFS_supportedArchiveTypes
1322
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   399
 * \sa PHYSFS_registerArchiver
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   400
 * \sa PHYSFS_deregisterArchiver
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   401
 */
943
5df593de06e2 Added struct typedefs that you can predeclare without including physfs.h
Ryan C. Gordon <icculus@icculus.org>
parents: 897
diff changeset
   402
typedef struct PHYSFS_ArchiveInfo
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   403
{
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   404
    const char *extension;   /**< Archive file extension: "ZIP", for example. */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   405
    const char *description; /**< Human-readable archive description. */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   406
    const char *author;      /**< Person who did support for this archive. */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   407
    const char *url;         /**< URL related to this archive */
1326
ac0fac4fe6d6 Moved supportsSymlinks into PHYSFS_ArchiveInfo.
Ryan C. Gordon <icculus@icculus.org>
parents: 1325
diff changeset
   408
    int supportsSymlinks;    /**< non-zero if archive offers symbolic links. */
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   409
} PHYSFS_ArchiveInfo;
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   410
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   411
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   412
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   413
 * \struct PHYSFS_Version
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   414
 * \brief Information the version of PhysicsFS in use.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   415
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   416
 * Represents the library's version as three levels: major revision
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   417
 *  (increments with massive changes, additions, and enhancements),
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   418
 *  minor revision (increments with backwards-compatible changes to the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   419
 *  major revision), and patchlevel (increments with fixes to the minor
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   420
 *  revision).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   421
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   422
 * \sa PHYSFS_VERSION
779
7acc8a8abdf6 Fixed typo in Doxygen comment.
Ryan C. Gordon <icculus@icculus.org>
parents: 772
diff changeset
   423
 * \sa PHYSFS_getLinkedVersion
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   424
 */
943
5df593de06e2 Added struct typedefs that you can predeclare without including physfs.h
Ryan C. Gordon <icculus@icculus.org>
parents: 897
diff changeset
   425
typedef struct PHYSFS_Version
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   426
{
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   427
    PHYSFS_uint8 major; /**< major revision */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   428
    PHYSFS_uint8 minor; /**< minor revision */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   429
    PHYSFS_uint8 patch; /**< patchlevel */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   430
} PHYSFS_Version;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   431
1026
1648054f2986 Initial SWIG work.
Ryan C. Gordon <icculus@icculus.org>
parents: 1025
diff changeset
   432
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   433
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
956
3da716cfe09f Upped version to 2.0.0!
Ryan C. Gordon <icculus@icculus.org>
parents: 944
diff changeset
   434
#define PHYSFS_VER_MAJOR 2
974
5cabc31eb563 Bumped version number (although we're probably far from a real 2.1.0 release).
Ryan C. Gordon <icculus@icculus.org>
parents: 973
diff changeset
   435
#define PHYSFS_VER_MINOR 1
956
3da716cfe09f Upped version to 2.0.0!
Ryan C. Gordon <icculus@icculus.org>
parents: 944
diff changeset
   436
#define PHYSFS_VER_PATCH 0
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   437
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   438
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   439
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   440
/* PhysicsFS state stuff ... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   441
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   442
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   443
 * \def PHYSFS_VERSION(x)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   444
 * \brief Macro to determine PhysicsFS version program was compiled against.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   445
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   446
 * This macro fills in a PHYSFS_Version structure with the version of the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   447
 *  library you compiled against. This is determined by what header the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   448
 *  compiler uses. Note that if you dynamically linked the library, you might
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   449
 *  have a slightly newer or older version at runtime. That version can be
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   450
 *  determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   451
 *  is not a macro.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   452
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   453
 * \param x A pointer to a PHYSFS_Version struct to initialize.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   454
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   455
 * \sa PHYSFS_Version
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   456
 * \sa PHYSFS_getLinkedVersion
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   457
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   458
#define PHYSFS_VERSION(x) \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   459
{ \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   460
    (x)->major = PHYSFS_VER_MAJOR; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   461
    (x)->minor = PHYSFS_VER_MINOR; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   462
    (x)->patch = PHYSFS_VER_PATCH; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   463
}
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   464
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   465
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   466
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   467
 * \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   468
 * \brief Get the version of PhysicsFS that is linked against your program.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   469
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   470
 * If you are using a shared library (DLL) version of PhysFS, then it is
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   471
 *  possible that it will be different than the version you compiled against.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   472
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   473
 * This is a real function; the macro PHYSFS_VERSION tells you what version
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   474
 *  of PhysFS you compiled against:
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   475
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   476
 * \code
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   477
 * PHYSFS_Version compiled;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   478
 * PHYSFS_Version linked;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   479
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   480
 * PHYSFS_VERSION(&compiled);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   481
 * PHYSFS_getLinkedVersion(&linked);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   482
 * printf("We compiled against PhysFS version %d.%d.%d ...\n",
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   483
 *           compiled.major, compiled.minor, compiled.patch);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   484
 * printf("But we linked against PhysFS version %d.%d.%d.\n",
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   485
 *           linked.major, linked.minor, linked.patch);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   486
 * \endcode
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   487
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   488
 * This function may be called safely at any time, even before PHYSFS_init().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   489
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   490
 * \sa PHYSFS_VERSION
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   491
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   492
PHYSFS_DECL void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   493
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   494
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   495
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   496
 * \fn int PHYSFS_init(const char *argv0)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   497
 * \brief Initialize the PhysicsFS library.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   498
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   499
 * This must be called before any other PhysicsFS function.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   500
 *
23
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   501
 * This should be called prior to any attempts to change your process's
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   502
 *  current working directory.
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   503
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   504
 *   \param argv0 the argv[0] string passed to your program's mainline.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   505
 *          This may be NULL on most platforms (such as ones without a
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   506
 *          standard main() function), but you should always try to pass
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   507
 *          something in here. Unix-like systems such as Linux _need_ to
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   508
 *          pass argv[0] from main() in here.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   509
 *  \return nonzero on success, zero on error. Specifics of the error can be
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   510
 *          gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   511
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   512
 * \sa PHYSFS_deinit
876
0d8e41a5c831 Added PHYSFS_isInit() function.
Ryan C. Gordon <icculus@icculus.org>
parents: 872
diff changeset
   513
 * \sa PHYSFS_isInit
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   514
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   515
PHYSFS_DECL int PHYSFS_init(const char *argv0);
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   516
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   517
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   518
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   519
 * \fn int PHYSFS_deinit(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   520
 * \brief Deinitialize the PhysicsFS library.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   521
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   522
 * This closes any files opened via PhysicsFS, blanks the search/write paths,
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   523
 *  frees memory, and invalidates all of your file handles.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   524
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   525
 * Note that this call can FAIL if there's a file open for writing that
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   526
 *  refuses to close (for example, the underlying operating system was
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   527
 *  buffering writes to network filesystem, and the fileserver has crashed,
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   528
 *  or a hard drive has failed, etc). It is usually best to close all write
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   529
 *  handles yourself before calling this function, so that you can gracefully
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   530
 *  handle a specific failure.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   531
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   532
 * Once successfully deinitialized, PHYSFS_init() can be called again to
897
4adcb2c5567b Minor documentation fix.
Ryan C. Gordon <icculus@icculus.org>
parents: 882
diff changeset
   533
 *  restart the subsystem. All default API states are restored at this
4adcb2c5567b Minor documentation fix.
Ryan C. Gordon <icculus@icculus.org>
parents: 882
diff changeset
   534
 *  point, with the exception of any custom allocator you might have
4adcb2c5567b Minor documentation fix.
Ryan C. Gordon <icculus@icculus.org>
parents: 882
diff changeset
   535
 *  specified, which survives between initializations.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   536
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   537
 *  \return nonzero on success, zero on error. Specifics of the error can be
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   538
 *          gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   539
 *          undefined, and probably badly screwed up.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   540
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   541
 * \sa PHYSFS_init
876
0d8e41a5c831 Added PHYSFS_isInit() function.
Ryan C. Gordon <icculus@icculus.org>
parents: 872
diff changeset
   542
 * \sa PHYSFS_isInit
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   543
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   544
PHYSFS_DECL int PHYSFS_deinit(void);
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   545
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   546
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   547
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   548
 * \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   549
 * \brief Get a list of supported archive types.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   550
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   551
 * Get a list of archive types supported by this implementation of PhysicFS.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   552
 *  These are the file formats usable for search path entries. This is for
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   553
 *  informational purposes only. Note that the extension listed is merely
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   554
 *  convention: if we list "ZIP", you can open a PkZip-compatible archive
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   555
 *  with an extension of "XYZ", if you like.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   556
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   557
 * The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   558
 *  with a NULL entry to signify the end of the list:
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   559
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   560
 * \code
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   561
 * PHYSFS_ArchiveInfo **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   562
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   563
 * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   564
 * {
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   565
 *     printf("Supported archive: [%s], which is [%s].\n",
944
4a814e7fee5d Corrected example code in the docs (thanks, Olivier!).
Ryan C. Gordon <icculus@icculus.org>
parents: 943
diff changeset
   566
 *              (*i)->extension, (*i)->description);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   567
 * }
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   568
 * \endcode
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   569
 *
1277
f6996bfaec19 Made archiver list dynamic, in preparation for external archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1275
diff changeset
   570
 * The return values are pointers to internal memory, and should
f6996bfaec19 Made archiver list dynamic, in preparation for external archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1275
diff changeset
   571
 *  be considered READ ONLY, and never freed. The returned values are
1322
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   572
 *  valid until the next call to PHYSFS_deinit(), PHYSFS_registerArchiver(),
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   573
 *  or PHYSFS_deregisterArchiver().
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   574
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   575
 *   \return READ ONLY Null-terminated array of READ ONLY structures.
1322
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   576
 *
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   577
 * \sa PHYSFS_registerArchiver
5476917b8ddf Allow application-supplied archivers.
Ryan C. Gordon <icculus@icculus.org>
parents: 1319
diff changeset
   578
 * \sa PHYSFS_deregisterArchiver
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   579
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   580
PHYSFS_DECL const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   581
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   582
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   583
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   584
 * \fn void PHYSFS_freeList(void *listVar)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   585
 * \brief Deallocate resources of lists returned by PhysicsFS.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   586
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   587
 * Certain PhysicsFS functions return lists of information that are
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   588
 *  dynamically allocated. Use this function to free those resources.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   589
 *
975
653a53e51931 PHYSFS_freeList(NULL) is now a safe no-op.
Ryan C. Gordon <icculus@icculus.org>
parents: 974
diff changeset
   590
 * It is safe to pass a NULL here, but doing so will cause a crash in versions
653a53e51931 PHYSFS_freeList(NULL) is now a safe no-op.
Ryan C. Gordon <icculus@icculus.org>
parents: 974
diff changeset
   591
 *  before PhysicsFS 2.1.0.
653a53e51931 PHYSFS_freeList(NULL) is now a safe no-op.
Ryan C. Gordon <icculus@icculus.org>
parents: 974
diff changeset
   592
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   593
 *   \param listVar List of information specified as freeable by this function.
975
653a53e51931 PHYSFS_freeList(NULL) is now a safe no-op.
Ryan C. Gordon <icculus@icculus.org>
parents: 974
diff changeset
   594
 *                  Passing NULL is safe; it is a valid no-op.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   595
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   596
 * \sa PHYSFS_getCdRomDirs
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   597
 * \sa PHYSFS_enumerateFiles
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   598
 * \sa PHYSFS_getSearchPath
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   599
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   600
PHYSFS_DECL void PHYSFS_freeList(void *listVar);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   601
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   602
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   603
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   604
 * \fn const char *PHYSFS_getLastError(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   605
 * \brief Get human-readable error information.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   606
 *
1240
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   607
 * \warning As of PhysicsFS 2.1, this function has been nerfed.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   608
 *          Before PhysicsFS 2.1, this function was the only way to get
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   609
 *          error details beyond a given function's basic return value.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   610
 *          This was meant to be a human-readable string in one of several
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   611
 *          languages, and was not useful for application parsing. This was
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   612
 *          a problem, because the developer and not the user chose the
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   613
 *          language at compile time, and the PhysicsFS maintainers had
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   614
 *          to (poorly) maintain a significant amount of localization work.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   615
 *          The app couldn't parse the strings, even if they counted on a
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   616
 *          specific language, since some were dynamically generated.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   617
 *          In 2.1 and later, this always returns a static string in
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   618
 *          English; you may use it as a key string for your own
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   619
 *          localizations if you like, as we'll promise not to change
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   620
 *          existing error strings. Also, if your application wants to
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   621
 *          look at specific errors, we now offer a better option:
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   622
 *          use PHYSFS_getLastErrorCode() instead.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   623
 *
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   624
 * Get the last PhysicsFS error message as a human-readable, null-terminated
1240
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   625
 *  string. This will return NULL if there's been no error since the last call
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   626
 *  to this function. The pointer returned by this call points to an internal
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   627
 *  buffer. Each thread has a unique error state associated with it, but each
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   628
 *  time a new error message is set, it will overwrite the previous one
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   629
 *  associated with that thread. It is safe to call this function at anytime,
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   630
 *  even before PHYSFS_init().
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   631
 *
1240
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   632
 * PHYSFS_getLastError() and PHYSFS_getLastErrorCode() both reset the same
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   633
 *  thread-specific error state. Calling one will wipe out the other's
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   634
 *  data. If you need both, call PHYSFS_getLastErrorCode(), then pass that
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   635
 *  value to PHYSFS_getErrorByCode().
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   636
 *
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   637
 * As of PhysicsFS 2.1, this function only presents text in the English
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   638
 *  language, but the strings are static, so you can use them as keys into
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   639
 *  your own localization dictionary. These strings are meant to be passed on
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   640
 *  directly to the user.
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   641
 *
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   642
 * Generally, applications should only concern themselves with whether a
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   643
 *  given function failed; however, if your code require more specifics, you
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   644
 *  should use PHYSFS_getLastErrorCode() instead of this function.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   645
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   646
 *   \return READ ONLY string of last error message.
1240
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   647
 *
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   648
 * \sa PHYSFS_getLastErrorCode
22d4d1bd4e21 Reworked the error reporting API. Now we use error codes instead of strings.
Ryan C. Gordon <icculus@icculus.org>
parents: 1209
diff changeset
   649
 * \sa PHYSFS_getErrorByCode
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   650
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   651
PHYSFS_DECL const char *PHYSFS_getLastError(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   652
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   653
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   654
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   655
 * \fn const char *PHYSFS_getDirSeparator(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   656
 * \brief Get platform-dependent dir separator string.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   657
 *
882
4dc4aba15d1e Fixed Doxygen comment (this was probably a Doxygen bug that was since fixed).
Ryan C. Gordon <icculus@icculus.org>
parents: 881
diff changeset
   658
 * This returns "\\" on win32, "/" on Unix, and ":" on MacOS. It may be more
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   659
 *  than one character, depending on the platform, and your code should take
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   660
 *  that into account. Note that this is only useful for setting up the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   661
 *  search/write paths, since access into those dirs always use '/'
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   662
 *  (platform-independent notation) to separate directories. This is also
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   663
 *  handy for getting platform-independent access when using stdio calls.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   664
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   665
 *   \return READ ONLY null-terminated string of platform's dir separator.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   666
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   667
PHYSFS_DECL const char *PHYSFS_getDirSeparator(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   668
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   669
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   670
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   671
 * \fn void PHYSFS_permitSymbolicLinks(int allow)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   672
 * \brief Enable or disable following of symbolic links.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   673
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   674
 * Some physical filesystems and archives contain files that are just pointers
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   675
 *  to other files. On the physical filesystem, opening such a link will
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   676
 *  (transparently) open the file that is pointed to.
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   677
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   678
 * By default, PhysicsFS will check if a file is really a symlink during open
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   679
 *  calls and fail if it is. Otherwise, the link could take you outside the
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   680
 *  write and search paths, and compromise security.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   681
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   682
 * If you want to take that risk, call this function with a non-zero parameter.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   683
 *  Note that this is more for sandboxing a program's scripting language, in
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   684
 *  case untrusted scripts try to compromise the system. Generally speaking,
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   685
 *  a user could very well have a legitimate reason to set up a symlink, so
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   686
 *  unless you feel there's a specific danger in allowing them, you should
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   687
 *  permit them.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   688
 *
39
bc29e1ee7ef6 Lots of bugfixes, enhancements, and corrections due to the work on
Ryan C. Gordon <icculus@icculus.org>
parents: 33
diff changeset
   689
 * Symlinks are only explicitly checked when dealing with filenames
bc29e1ee7ef6 Lots of bugfixes, enhancements, and corrections due to the work on
Ryan C. Gordon <icculus@icculus.org>
parents: 33
diff changeset
   690
 *  in platform-independent notation. That is, when setting up your
bc29e1ee7ef6 Lots of bugfixes, enhancements, and corrections due to the work on
Ryan C. Gordon <icculus@icculus.org>
parents: 33
diff changeset
   691
 *  search and write paths, etc, symlinks are never checked for.
bc29e1ee7ef6 Lots of bugfixes, enhancements, and corrections due to the work on
Ryan C. Gordon <icculus@icculus.org>
parents: 33
diff changeset
   692
 *
1125
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
   693
 * Please note that PHYSFS_stat() will always check the path specified; if
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
   694
 *  that path is a symlink, it will not be followed in any case. If symlinks
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
   695
 *  aren't permitted through this function, PHYSFS_stat() ignores them, and
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
   696
 *  would treat the query as if the path didn't exist at all.
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
   697
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   698
 * Symbolic link permission can be enabled or disabled at any time after
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   699
 *  you've called PHYSFS_init(), and is disabled by default.
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   700
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   701
 *   \param allow nonzero to permit symlinks, zero to deny linking.
877
99c2fd8e689d Added PHYSFS_symbolicLinksPermitted().
Ryan C. Gordon <icculus@icculus.org>
parents: 876
diff changeset
   702
 *
99c2fd8e689d Added PHYSFS_symbolicLinksPermitted().
Ryan C. Gordon <icculus@icculus.org>
parents: 876
diff changeset
   703
 * \sa PHYSFS_symbolicLinksPermitted
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   704
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   705
PHYSFS_DECL void PHYSFS_permitSymbolicLinks(int allow);
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   706
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   707
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   708
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   709
 * \fn char **PHYSFS_getCdRomDirs(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   710
 * \brief Get an array of paths to available CD-ROM drives.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   711
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   712
 * The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   713
 *  whatnot on Unix). Dirs are only returned if there is a disc ready and
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   714
 *  accessible in the drive. So if you've got two drives (D: and E:), and only
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   715
 *  E: has a disc in it, then that's all you get. If the user inserts a disc
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   716
 *  in D: and you call this function again, you get both drives. If, on a
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   717
 *  Unix box, the user unmounts a disc and remounts it elsewhere, the next
881
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   718
 *  call to this function will reflect that change.
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   719
 *
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   720
 * This function refers to "CD-ROM" media, but it really means "inserted disc
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   721
 *  media," such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs. It looks for
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   722
 *  filesystems, and as such won't report an audio CD, unless there's a
57622b68ebf1 Improved Doxygen comments.
Ryan C. Gordon <icculus@icculus.org>
parents: 880
diff changeset
   723
 *  mounted filesystem track on it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   724
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   725
 * The returned value is an array of strings, with a NULL entry to signify the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   726
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   727
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   728
 * \code
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   729
 * char **cds = PHYSFS_getCdRomDirs();
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   730
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   731
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   732
 * for (i = cds; *i != NULL; i++)
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   733
 *     printf("cdrom dir [%s] is available.\n", *i);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   734
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   735
 * PHYSFS_freeList(cds);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   736
 * \endcode
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   737
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   738
 * This call may block while drives spin up. Be forewarned.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   739
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   740
 * When you are done with the returned information, you may dispose of the
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   741
 *  resources by calling PHYSFS_freeList() with the returned pointer.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   742
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   743
 *   \return Null-terminated array of null-terminated strings.
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   744
 *
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   745
 * \sa PHYSFS_getCdRomDirsCallback
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   746
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   747
PHYSFS_DECL char **PHYSFS_getCdRomDirs(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   748
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   749
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   750
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   751
 * \fn const char *PHYSFS_getBaseDir(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   752
 * \brief Get the path where the application resides.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   753
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   754
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   755
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   756
 * Get the "base dir". This is the directory where the application was run
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   757
 *  from, which is probably the installation directory, and may or may not
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   758
 *  be the process's current working directory.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   759
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   760
 * You should probably use the base dir in your search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   761
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   762
 *  \return READ ONLY string of base dir in platform-dependent notation.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   763
 *
1242
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   764
 * \sa PHYSFS_getPrefDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   765
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   766
PHYSFS_DECL const char *PHYSFS_getBaseDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   767
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   768
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   769
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   770
 * \fn const char *PHYSFS_getUserDir(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   771
 * \brief Get the path where user's home directory resides.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   772
 *
1242
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   773
 * \deprecated As of PhysicsFS 2.1, you probably want PHYSFS_getPrefDir().
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   774
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   775
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   776
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   777
 * Get the "user dir". This is meant to be a suggestion of where a specific
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   778
 *  user of the system can store files. On Unix, this is her home directory.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   779
 *  On systems with no concept of multiple home directories (MacOS, win95),
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   780
 *  this will default to something like "C:\mybasedir\users\username"
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   781
 *  where "username" will either be the login name, or "default" if the
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   782
 *  platform doesn't support multiple users, either.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   783
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   784
 *  \return READ ONLY string of user dir in platform-dependent notation.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   785
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   786
 * \sa PHYSFS_getBaseDir
1242
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   787
 * \sa PHYSFS_getPrefDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   788
 */
1242
1e6db80d2393 Added PHYSFS_getPrefDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 1240
diff changeset
   789
PHYSFS_DECL const char *PHYSFS_getUserDir(void) PHYSFS_DEPRECATED;
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   790
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   791
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   792
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   793
 * \fn const char *PHYSFS_getWriteDir(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   794
 * \brief Get path where PhysicsFS will allow file writing.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   795
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   796
 * Get the current write dir. The default write dir is NULL.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   797
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   798
 *  \return READ ONLY string of write dir in platform-dependent notation,
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   799
 *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   800
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   801
 * \sa PHYSFS_setWriteDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   802
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   803
PHYSFS_DECL const char *PHYSFS_getWriteDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   804
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   805
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   806
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   807
 * \fn int PHYSFS_setWriteDir(const char *newDir)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   808
 * \brief Tell PhysicsFS where it may write files.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   809
 *
762
63f2585b5a5e Fixed documentation for PHYSFS_setWriteDir().
Ryan C. Gordon <icculus@icculus.org>
parents: 754
diff changeset
   810
 * Set a new write dir. This will override the previous setting.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   811
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   812
 * This call will fail (and fail to change the write dir) if the current
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   813
 *  write dir still has files open in it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   814
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   815
 *   \param newDir The new directory to be the root of the write dir,
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   816
 *                   specified in platform-dependent notation. Setting to NULL
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   817
 *                   disables the write dir, so no files can be opened for
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   818
 *                   writing via PhysicsFS.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   819
 *  \return non-zero on success, zero on failure. All attempts to open a file
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   820
 *           for writing via PhysicsFS will fail until this call succeeds.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   821
 *           Specifics of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   822
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   823
 * \sa PHYSFS_getWriteDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   824
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   825
PHYSFS_DECL int PHYSFS_setWriteDir(const char *newDir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   826
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   827
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   828
/**
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   829
 * \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   830
 * \brief Add an archive or directory to the search path.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   831
 *
1110
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   832
 * \deprecated As of PhysicsFS 2.0, use PHYSFS_mount() instead. This
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   833
 *             function just wraps it anyhow.
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   834
 *
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   835
 * This function is equivalent to:
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   836
 *
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   837
 * \code
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   838
 *  PHYSFS_mount(newDir, NULL, appendToPath);
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   839
 * \endcode
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   840
 *
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   841
 * You must use this and not PHYSFS_mount if binary compatibility with
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   842
 *  PhysicsFS 1.0 is important (which it may not be for many people).
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   843
 *
679
ae75b5548364 First chunk of PHYSFS_mount() implementation. Incomplete!
Ryan C. Gordon <icculus@icculus.org>
parents: 669
diff changeset
   844
 * \sa PHYSFS_mount
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   845
 * \sa PHYSFS_removeFromSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   846
 * \sa PHYSFS_getSearchPath
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   847
 */
1110
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   848
PHYSFS_DECL int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   849
                                        PHYSFS_DEPRECATED;
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   850
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   851
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   852
 * \fn int PHYSFS_removeFromSearchPath(const char *oldDir)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   853
 * \brief Remove a directory or archive from the search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   854
 *
1110
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   855
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_unmount() instead. This
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   856
 *             function just wraps it anyhow. There's no functional difference
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   857
 *             except the vocabulary changed from "adding to the search path"
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   858
 *             to "mounting" when that functionality was extended, and thus
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   859
 *             the preferred way to accomplish this function's work is now
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   860
 *             called "unmounting."
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   861
 *
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   862
 * This function is equivalent to:
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   863
 *
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   864
 * \code
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   865
 *  PHYSFS_unmount(oldDir);
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   866
 * \endcode
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   867
 *
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   868
 * You must use this and not PHYSFS_unmount if binary compatibility with
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   869
 *  PhysicsFS 1.0 is important (which it may not be for many people).
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   870
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   871
 * \sa PHYSFS_addToSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   872
 * \sa PHYSFS_getSearchPath
1110
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   873
 * \sa PHYSFS_unmount
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   874
 */
1110
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   875
PHYSFS_DECL int PHYSFS_removeFromSearchPath(const char *oldDir)
803e5e8a0ff8 Added PHYSFS_unmount(), deprecated addToSearchPath and removeFromSearchPath.
Ryan C. Gordon <icculus@icculus.org>
parents: 1106
diff changeset
   876
                                            PHYSFS_DEPRECATED;
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   877
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   878
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   879
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   880
 * \fn char **PHYSFS_getSearchPath(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   881
 * \brief Get the current search path.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   882
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   883
 * The default search path is an empty list.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   884
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   885
 * The returned value is an array of strings, with a NULL entry to signify the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   886
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   887
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   888
 * \code
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   889
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   890
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   891
 * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   892
 *     printf("[%s] is in the search path.\n", *i);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   893
 * \endcode
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   894
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   895
 * When you are done with the returned information, you may dispose of the
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   896
 *  resources by calling PHYSFS_freeList() with the returned pointer.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   897
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   898
 *   \return Null-terminated array of null-terminated strings. NULL if there
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   899
 *            was a problem (read: OUT OF MEMORY).
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   900
 *
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
   901
 * \sa PHYSFS_getSearchPathCallback
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   902
 * \sa PHYSFS_addToSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   903
 * \sa PHYSFS_removeFromSearchPath
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   904
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   905
PHYSFS_DECL char **PHYSFS_getSearchPath(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   906
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   907
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   908
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   909
 * \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   910
 * \brief Set up sane, default paths.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   911
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   912
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   913
 *
1274
db0abc54e263 Updated docs on PHYSFS_setSaneConfig().
Ryan C. Gordon <icculus@icculus.org>
parents: 1273
diff changeset
   914
 * The write dir will be set to the pref dir returned by
db0abc54e263 Updated docs on PHYSFS_setSaneConfig().
Ryan C. Gordon <icculus@icculus.org>
parents: 1273
diff changeset
   915
 *  \code PHYSFS_getPrefDir(organization, appName) \endcode, which is
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   916
 *  created if it doesn't exist.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   917
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   918
 * The above is sufficient to make sure your program's configuration directory
1274
db0abc54e263 Updated docs on PHYSFS_setSaneConfig().
Ryan C. Gordon <icculus@icculus.org>
parents: 1273
diff changeset
   919
 *  is separated from other clutter, and platform-independent.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   920
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   921
 *  The search path will be:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   922
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   923
 *    - The Write Dir (created if it doesn't exist)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   924
 *    - The Base Dir (PHYSFS_getBaseDir())
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   925
 *    - All found CD-ROM dirs (optionally)
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   926
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   927
 * These directories are then searched for files ending with the extension
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   928
 *  (archiveExt), which, if they are valid and supported archives, will also
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   929
 *  be added to the search path. If you specified "PKG" for (archiveExt), and
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   930
 *  there's a file named data.PKG in the base dir, it'll be checked. Archives
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   931
 *  can either be appended or prepended to the search path in alphabetical
1274
db0abc54e263 Updated docs on PHYSFS_setSaneConfig().
Ryan C. Gordon <icculus@icculus.org>
parents: 1273
diff changeset
   932
 *  order, regardless of which directories they were found in. All archives
db0abc54e263 Updated docs on PHYSFS_setSaneConfig().
Ryan C. Gordon <icculus@icculus.org>
parents: 1273
diff changeset
   933
 *  are mounted in the root of the virtual file system ("/").
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   934
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   935
 * All of this can be accomplished from the application, but this just does it
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   936
 *  all for you. Feel free to add more to the search path manually, too.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   937
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   938
 *    \param organization Name of your company/group/etc to be used as a
101
bd18e17ad6ad Changed PHYSFS_setSaneConfig()'s behaviour. API BREAKAGE.
Ryan C. Gordon <icculus@icculus.org>
parents: 99
diff changeset
   939
 *                         dirname, so keep it small, and no-frills.
bd18e17ad6ad Changed PHYSFS_setSaneConfig()'s behaviour. API BREAKAGE.
Ryan C. Gordon <icculus@icculus.org>
parents: 99
diff changeset
   940
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   941
 *    \param appName Program-specific name of your program, to separate it
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   942
 *                   from other programs using PhysicsFS.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   943
 *
397
12ff23d3d716 Fixed a typo in the documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 322
diff changeset
   944
 *    \param archiveExt File extension used by your program to specify an
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   945
 *                      archive. For example, Quake 3 uses "pk3", even though
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   946
 *                      they are just zipfiles. Specify NULL to not dig out
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   947
 *                      archives automatically. Do not specify the '.' char;
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   948
 *                      If you want to look for ZIP files, specify "ZIP" and
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   949
 *                      not ".ZIP" ... the archive search is case-insensitive.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   950
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   951
 *    \param includeCdRoms Non-zero to include CD-ROMs in the search path, and
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   952
 *                         (if (archiveExt) != NULL) search them for archives.
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   953
 *                         This may cause a significant amount of blocking
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   954
 *                         while discs are accessed, and if there are no discs
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   955
 *                         in the drive (or even not mounted on Unix systems),
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   956
 *                         then they may not be made available anyhow. You may
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   957
 *                         want to specify zero and handle the disc setup
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   958
 *                         yourself.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   959
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   960
 *    \param archivesFirst Non-zero to prepend the archives to the search path.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   961
 *                          Zero to append them. Ignored if !(archiveExt).
101
bd18e17ad6ad Changed PHYSFS_setSaneConfig()'s behaviour. API BREAKAGE.
Ryan C. Gordon <icculus@icculus.org>
parents: 99
diff changeset
   962
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   963
 *  \return nonzero on success, zero on error. Specifics of the error can be
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   964
 *          gleaned from PHYSFS_getLastError().
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   965
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   966
PHYSFS_DECL int PHYSFS_setSaneConfig(const char *organization,
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   967
                                     const char *appName,
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   968
                                     const char *archiveExt,
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   969
                                     int includeCdRoms,
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   970
                                     int archivesFirst);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   971
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   972
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   973
/* Directory management stuff ... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   974
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   975
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   976
 * \fn int PHYSFS_mkdir(const char *dirName)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   977
 * \brief Create a directory.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   978
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   979
 * This is specified in platform-independent notation in relation to the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   980
 *  write dir. All missing parent directories are also created if they
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   981
 *  don't exist.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   982
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   983
 * So if you've got the write dir set to "C:\mygame\writedir" and call
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   984
 *  PHYSFS_mkdir("downloads/maps") then the directories
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   985
 *  "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   986
 *  will be created if possible. If the creation of "maps" fails after we
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   987
 *  have successfully created "downloads", then the function leaves the
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   988
 *  created directory behind and reports failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   989
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   990
 *   \param dirName New dir to create.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   991
 *  \return nonzero on success, zero on error. Specifics of the error can be
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   992
 *          gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   993
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   994
 * \sa PHYSFS_delete
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   995
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
   996
PHYSFS_DECL int PHYSFS_mkdir(const char *dirName);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   997
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   998
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   999
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1000
 * \fn int PHYSFS_delete(const char *filename)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1001
 * \brief Delete a file or directory.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1002
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1003
 * (filename) is specified in platform-independent notation in relation to the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1004
 *  write dir.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1005
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1006
 * A directory must be empty before this call can delete it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1007
 *
137
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1008
 * Deleting a symlink will remove the link, not what it points to, regardless
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1009
 *  of whether you "permitSymLinks" or not.
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1010
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
  1011
 * So if you've got the write dir set to "C:\mygame\writedir" and call
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1012
 *  PHYSFS_delete("downloads/maps/level1.map") then the file
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
  1013
 *  "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1014
 *  physical filesystem, if it exists and the operating system permits the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1015
 *  deletion.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1016
 *
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
  1017
 * Note that on Unix systems, deleting a file may be successful, but the
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
  1018
 *  actual file won't be removed until all processes that have an open
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
  1019
 *  filehandle to it (including your program) close their handles.
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
  1020
 *
137
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1021
 * Chances are, the bits that make up the file still exist, they are just
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1022
 *  made available to be written over at a later point. Don't consider this
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1023
 *  a security method or anything.  :)
66bddb94b6e0 Abstracted file deletion, so we don't rely on C library for it anymore.
Ryan C. Gordon <icculus@icculus.org>
parents: 132
diff changeset
  1024
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1025
 *   \param filename Filename to delete.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1026
 *  \return nonzero on success, zero on error. Specifics of the error can be
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1027
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1028
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
  1029
PHYSFS_DECL int PHYSFS_delete(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1030
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1031
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1032
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1033
 * \fn const char *PHYSFS_getRealDir(const char *filename)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1034
 * \brief Figure out where in the search path a file resides.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1035
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1036
 * The file is specified in platform-independent notation. The returned
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1037
 *  filename will be the element of the search path where the file was found,
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1038
 *  which may be a directory, or an archive. Even if there are multiple
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1039
 *  matches in different parts of the search path, only the first one found
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1040
 *  is used, just like when opening a file.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1041
 *
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
  1042
 * So, if you look for "maps/level1.map", and C:\\mygame is in your search
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
  1043
 *  path and C:\\mygame\\maps\\level1.map exists, then "C:\mygame" is returned.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1044
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1045
 * If a any part of a match is a symbolic link, and you've not explicitly
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1046
 *  permitted symlinks, then it will be ignored, and the search for a match
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1047
 *  will continue.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
  1048
 *
687
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
  1049
 * If you specify a fake directory that only exists as a mount point, it'll
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
  1050
 *  be associated with the first archive mounted there, even though that
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
  1051
 *  directory isn't necessarily contained in a real archive.
f76dffa43fa2 More mountpoint work and other cleanups.
Ryan C. Gordon <icculus@icculus.org>
parents: 683
diff changeset
  1052
 *
1122
a710d2a325a6 PHYSFS_getRealDir() can't report a path for things that aren't real files.
Ryan C. Gordon <icculus@icculus.org>
parents: 1120
diff changeset
  1053
 * \warning This will return NULL if there is no real directory associated
a710d2a325a6 PHYSFS_getRealDir() can't report a path for things that aren't real files.
Ryan C. Gordon <icculus@icculus.org>
parents: 1120
diff changeset
  1054
 *          with (filename). Specifically, PHYSFS_mountIo(),
a710d2a325a6 PHYSFS_getRealDir() can't report a path for things that aren't real files.
Ryan C. Gordon <icculus@icculus.org>
parents: 1120
diff changeset
  1055
 *          PHYSFS_mountMemory(), and PHYSFS_mountHandle() will return NULL
a710d2a325a6 PHYSFS_getRealDir() can't report a path for things that aren't real files.
Ryan C. Gordon <icculus@icculus.org>
parents: 1120
diff changeset
  1056
 *          even if the filename is found in the search path. Plan accordingly.
a710d2a325a6 PHYSFS_getRealDir() can't report a path for things that aren't real files.
Ryan C. Gordon <icculus@icculus.org>
parents: 1120
diff changeset
  1057
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1058
 *     \param filename file to look for.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1059
 *    \return READ ONLY string of element of search path containing the
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1060
 *             the file in question. NULL if not found.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1061
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
  1062
PHYSFS_DECL const char *PHYSFS_getRealDir(const char *filename);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1063
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1064
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1065
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1066
 * \fn char **PHYSFS_enumerateFiles(const char *dir)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1067
 * \brief Get a file listing of a search path's directory.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1068
 *
1559
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1069
 * \warning In PhysicsFS versions prior to 2.1, this function would return
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1070
 *          as many items as it could in the face of a failure condition
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1071
 *          (out of memory, disk i/o error, etc). Since this meant apps
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1072
 *          couldn't distinguish between complete success and partial failure,
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1073
 *          and since the function could always return NULL to report
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1074
 *          catastrophic failures anyway, in PhysicsFS 2.1 this function's
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1075
 *          policy changed: it will either return a list of complete results
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1076
 *          or it will return NULL for any failure of any kind, so we can
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1077
 *          guarantee that the enumeration ran to completion and has no gaps
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1078
 *          in its results.
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1079
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1080
 * Matching directories are interpolated. That is, if "C:\mydir" is in the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1081
 *  search path and contains a directory "savegames" that contains "x.sav",
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1082
 *  "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1083
 *  that has a "savegames" subdirectory with "w.sav", then the following code:
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1084
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1085
 * \code
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1086
 * char **rc = PHYSFS_enumerateFiles("savegames");
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1087
 * char **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1088
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1089
 * for (i = rc; *i != NULL; i++)
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1090
 *     printf(" * We've got [%s].\n", *i);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1091
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1092
 * PHYSFS_freeList(rc);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1093
 * \endcode
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1094
 *
1070
822d91dde8e8 Doxygen fixes (thanks, Patrick!)
Ryan C. Gordon <icculus@icculus.org>
parents: 1069
diff changeset
  1095
 *  \...will print:
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1096
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1097
 * \verbatim
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1098
 * We've got [x.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1099
 * We've got [y.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1100
 * We've got [z.sav].
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1101
 * We've got [w.sav].\endverbatim
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1102
 *
1350
b0fa354873f2 PHYSFS_enumerateFiles() actually promises sorting order, and always has.
Ryan C. Gordon <icculus@icculus.org>
parents: 1331
diff changeset
  1103
 * Feel free to sort the list however you like. However, the returned data
b0fa354873f2 PHYSFS_enumerateFiles() actually promises sorting order, and always has.
Ryan C. Gordon <icculus@icculus.org>
parents: 1331
diff changeset
  1104
 *  will always contain no duplicates, and will be always sorted in alphabetic
b0fa354873f2 PHYSFS_enumerateFiles() actually promises sorting order, and always has.
Ryan C. Gordon <icculus@icculus.org>
parents: 1331
diff changeset
  1105
 *  (rather: Unicode) order for you.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
  1106
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1107
 * Don't forget to call PHYSFS_freeList() with the return value from this
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1108
 *  function when you are done with it.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1109
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1110
 *    \param dir directory in platform-independent notation to enumerate.
1559
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1111
 *   \return Null-terminated array of null-terminated strings, or NULL for
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1112
 *           failure cases.
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1113
 *
aaee2b83291f Reworked enumeration to be more powerful.
Ryan C. Gordon <icculus@icculus.org>
parents: 1555
diff changeset
  1114
 * \sa PHYSFS_enumerate
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1115
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
  1116
PHYSFS_DECL char **PHYSFS_enumerateFiles(const char *dir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1117
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1118
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1119
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1120
 * \fn int PHYSFS_exists(const char *fname)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1121
 * \brief Determine if a file exists in the search path.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1122
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1123
 * Reports true if there is an entry anywhere in the search path by the
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1124
 *  name of (fname).
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1125
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1126
 * Note that entries that are symlinks are ignored if
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1127
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1128
 *  might end up further down in the search path than expected.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1129
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1130
 *    \param fname filename in platform-independent notation.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1131
 *   \return non-zero if filename exists. zero otherwise.
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1132
 */
1024
199e38498938 Renamed __EXPORT__ to PHYSFS_DECL.
Ryan C. Gordon <icculus@icculus.org>
parents: 994
diff changeset
  1133
PHYSFS_DECL int PHYSFS_exists(const char *fname);
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1134
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1135
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1136
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1137
 * \fn int PHYSFS_isDirectory(const char *fname)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1138
 * \brief Determine if a file in the search path is really a directory.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1139
 *
1125
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
  1140
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_stat() instead. This
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
  1141
 *             function just wraps it anyhow.
bcff76dbd9fd Removed isDirectory, isSymLink and exists methods from internal code.
Ryan C. Gordon <icculus@icculus.org>
parents: 1124
diff changeset
  1142
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1143
 * Determine if the first occurence of (fname) in the search path is
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1144
 *  really a directory entry.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1145
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1146
 * Note that entries that are symlinks are ignored if
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1147
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you