physfs.h
author Ryan C. Gordon <icculus@icculus.org>
Sun, 26 Sep 2004 00:25:04 +0000
changeset 648 5c993684b8f2
parent 646 86be93f03eb7
child 650 298b8bb26775
permissions -rw-r--r--
Cleaned up archiver interface to not deal with DirHandles anymore, which simplifies things, removes some responsibility and code duplication from the archivers, and trims some malloc pressure. Also ripped up the allocation hook code a little. We'll try to screw with memory locking later, since it makes everything ugly and complex. Oh well.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     1
/** \file physfs.h */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     2
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     3
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     4
 * \mainpage PhysicsFS
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     5
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     6
 * The latest version of PhysicsFS can be found at:
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     7
 *     http://icculus.org/physfs/
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
     8
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     9
 * PhysicsFS; a portable, flexible file i/o abstraction.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    10
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    11
 * 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
    12
 *  stdio or system i/o calls. The brief benefits:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    13
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    14
 *   - 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
    15
 *   - 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
    16
 *   - It's flexible. Archives (.ZIP files) can be used transparently as
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    17
 *      directory structures.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    18
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    19
 * This system is largely inspired by Quake 3's PK3 files and the related
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    20
 *  fs_* cvars. If you've ever tinkered with these, then this API will be
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    21
 *  familiar to you.
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
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    81
 *  elements. Not only are these meaningless on MacOS and/or Unix, they are a
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    82
 *  security hole. Also, symbolic links (which can be found in some archive
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    83
 *  types and directly in the filesystem on Unix platforms) are NOT followed
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    84
 *  until you call PHYSFS_permitSymbolicLinks(). That's left to your own
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    85
 *  discretion, as following a symlink can allow for access outside the write
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    86
 *  dir and search paths. There is no mechanism for creating new symlinks in
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    87
 *  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
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   110
 *  PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
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
 *
147
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   113
 * PhysicsFS is mostly thread safe. The error messages returned by
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   114
 *  PHYSFS_getLastError are unique by thread, and library-state-setting
5e1eda65ceb3 Updated comment on thread safety.
Ryan C. Gordon <icculus@icculus.org>
parents: 137
diff changeset
   115
 *  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
   116
 *  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
   117
 *  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
   118
 *  that should be reported/patched.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   119
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   120
 * 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
   121
 *  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
   122
 *  filehandles with PhysicsFS and vice versa.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   123
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   124
 * 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
   125
 *  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
   126
 *  ZIP archive by PhysicsFS; the file's contents are used to determine its
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   127
 *  type.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   128
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   129
 * Currently supported archive types:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   130
 *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   131
 *   - .GRP (Build Engine groupfile archives)
559
6fa9e48b537c Forgot to mention qpak in the docs.
Ryan C. Gordon <icculus@icculus.org>
parents: 553
diff changeset
   132
 *   - .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
   133
 *   - .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
   134
 *   - .MVL (Descent II movielib archives)
609
3a91332776e0 Added Doom WAD support.
Ryan C. Gordon <icculus@icculus.org>
parents: 588
diff changeset
   135
 *   - .WAD (DOOM engine archives)
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   136
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   137
 * Please see the file LICENSE in the source's root directory for licensing
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   138
 *  and redistribution rights.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   139
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   140
 * Please see the file CREDITS in the source's root directory for a complete
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   141
 *  list of who's responsible for this.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   142
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   143
 *  \author Ryan C. Gordon.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   144
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   145
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   146
#ifndef _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   147
#define _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   148
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   149
#ifdef __cplusplus
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   150
extern "C" {
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   151
#endif
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   152
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   153
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   154
#if (defined _MSC_VER)
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   155
#define __EXPORT__ __declspec(dllexport)
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   156
#else
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   157
#define __EXPORT__
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   158
#endif
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   159
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   160
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   161
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   162
 * \typedef PHYSFS_uint8
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   163
 * \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
   164
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   165
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
   166
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   167
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   168
 * \typedef PHYSFS_sint8
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   169
 * \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
   170
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   171
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
   172
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   173
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   174
 * \typedef PHYSFS_uint16
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   175
 * \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
   176
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   177
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
   178
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   179
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   180
 * \typedef PHYSFS_sint16
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   181
 * \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
   182
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   183
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
   184
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   185
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   186
 * \typedef PHYSFS_uint32
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   187
 * \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
   188
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   189
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
   190
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   191
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   192
 * \typedef PHYSFS_sint32
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   193
 * \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
   194
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   195
typedef signed int            PHYSFS_sint32;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   196
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   197
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   198
 * \typedef PHYSFS_uint64
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   199
 * \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
   200
 * \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
   201
 *           equivalent to PHYSFS_uint32!
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   202
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   203
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   204
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   205
 * \typedef PHYSFS_sint64
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   206
 * \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
   207
 * \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
   208
 *           equivalent to PHYSFS_sint32!
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   209
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   210
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   211
194
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   212
#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
   213
typedef PHYSFS_uint32         PHYSFS_uint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   214
typedef PHYSFS_sint32         PHYSFS_sint64;
194
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   215
#elif (defined _MSC_VER)
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   216
typedef signed __int64        PHYSFS_sint64;
09c353d30cd4 Patches for correctness and cleaner win32 support.
Ryan C. Gordon <icculus@icculus.org>
parents: 178
diff changeset
   217
typedef unsigned __int64      PHYSFS_uint64;
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   218
#else
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   219
typedef unsigned long long    PHYSFS_uint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   220
typedef signed long long      PHYSFS_sint64;
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   221
#endif
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   222
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   223
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   224
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   225
/* Make sure the types really have the right sizes */
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   226
#define PHYSFS_COMPILE_TIME_ASSERT(name, x)               \
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   227
       typedef int PHYSFS_dummy_ ## name[(x) * 2 - 1]
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   228
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   229
PHYSFS_COMPILE_TIME_ASSERT(uint8, sizeof(PHYSFS_uint8) == 1);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   230
PHYSFS_COMPILE_TIME_ASSERT(sint8, sizeof(PHYSFS_sint8) == 1);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   231
PHYSFS_COMPILE_TIME_ASSERT(uint16, sizeof(PHYSFS_uint16) == 2);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   232
PHYSFS_COMPILE_TIME_ASSERT(sint16, sizeof(PHYSFS_sint16) == 2);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   233
PHYSFS_COMPILE_TIME_ASSERT(uint32, sizeof(PHYSFS_uint32) == 4);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   234
PHYSFS_COMPILE_TIME_ASSERT(sint32, sizeof(PHYSFS_sint32) == 4);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   235
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   236
#ifndef PHYSFS_NO_64BIT_SUPPORT
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   237
PHYSFS_COMPILE_TIME_ASSERT(uint64, sizeof(PHYSFS_uint64) == 8);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   238
PHYSFS_COMPILE_TIME_ASSERT(sint64, sizeof(PHYSFS_sint64) == 8);
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   239
#endif
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   240
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   241
#undef PHYSFS_COMPILE_TIME_ASSERT
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   242
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   243
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   244
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
   245
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   246
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   247
 * \struct PHYSFS_file
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   248
 * \brief A PhysicsFS file handle.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   249
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   250
 * 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
   251
 *  writing, or appending via PhysicsFS.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   252
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   253
 * 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
   254
 *  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
   255
 *  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
   256
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   257
 * \sa PHYSFS_openRead
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   258
 * \sa PHYSFS_openWrite
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   259
 * \sa PHYSFS_openAppend
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   260
 * \sa PHYSFS_close
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   261
 * \sa PHYSFS_read
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   262
 * \sa PHYSFS_write
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   263
 * \sa PHYSFS_seek
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   264
 * \sa PHYSFS_tell
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   265
 * \sa PHYSFS_eof
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   266
 * \sa PHYSFS_setBuffer
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   267
 * \sa PHYSFS_flush
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
typedef struct
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   270
{
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   271
    void *opaque;  /**< That's all you get. Don't touch. */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   272
} PHYSFS_file;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   273
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   274
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   275
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   276
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   277
 * \struct PHYSFS_ArchiveInfo
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   278
 * \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
   279
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   280
 * 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
   281
 *  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
   282
 *  ZIP files and such.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   283
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   284
 * \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
   285
 *          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
   286
 *          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
   287
 *          supported.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   288
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   289
 * \sa PHYSFS_supportedArchiveTypes
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   290
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   291
typedef struct
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   292
{
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   293
    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
   294
    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
   295
    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
   296
    const char *url;         /**< URL related to this archive */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   297
} PHYSFS_ArchiveInfo;
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   298
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   299
265
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
 * \struct PHYSFS_Version
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   302
 * \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
   303
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   304
 * 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
   305
 *  (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
   306
 *  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
   307
 *  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
   308
 *  revision).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   309
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   310
 * \sa PHYSFS_VERSION
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   311
 * \sa PHYFS_getLinkedVersion
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   312
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   313
typedef struct
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   314
{
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   315
    PHYSFS_uint8 major; /**< major revision */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   316
    PHYSFS_uint8 minor; /**< minor revision */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   317
    PHYSFS_uint8 patch; /**< patchlevel */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   318
} PHYSFS_Version;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   319
265
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
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
   321
#define PHYSFS_VER_MAJOR 1
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
   322
#define PHYSFS_VER_MINOR 0
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
   323
#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
   324
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   325
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   326
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   327
/* PhysicsFS state stuff ... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   328
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   329
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   330
 * \def PHYSFS_VERSION(x)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   331
 * \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
   332
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   333
 * 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
   334
 *  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
   335
 *  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
   336
 *  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
   337
 *  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
   338
 *  is not a macro.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   339
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   340
 * \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
   341
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   342
 * \sa PHYSFS_Version
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   343
 * \sa PHYSFS_getLinkedVersion
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   344
 */
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   345
#define PHYSFS_VERSION(x) \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   346
{ \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   347
    (x)->major = PHYSFS_VER_MAJOR; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   348
    (x)->minor = PHYSFS_VER_MINOR; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   349
    (x)->patch = PHYSFS_VER_PATCH; \
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   350
}
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   351
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
/**
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   354
 * \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
   355
 * \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
   356
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   357
 * 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
   358
 *  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
   359
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   360
 * 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
   361
 *  of PhysFS you compiled against:
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   362
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   363
 * \code
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   364
 * PHYSFS_Version compiled;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   365
 * PHYSFS_Version linked;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   366
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   367
 * PHYSFS_VERSION(&compiled);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   368
 * PHYSFS_getLinkedVersion(&linked);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   369
 * 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
   370
 *           compiled.major, compiled.minor, compiled.patch);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   371
 * 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
   372
 *           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
   373
 * \endcode
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   374
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   375
 * 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
   376
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   377
 * \sa PHYSFS_VERSION
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   378
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   379
__EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   380
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   381
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   382
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   383
 * \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
   384
 * \brief Initialize the PhysicsFS library.
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
 * 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
   387
 *
23
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   388
 * 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
   389
 *  current working directory.
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   390
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   391
 *   \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
   392
 *          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
   393
 *          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
   394
 *          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
   395
 *          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
   396
 *  \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
   397
 *          gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   398
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   399
 * \sa PHYSFS_deinit
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   400
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   401
__EXPORT__ 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
   402
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   403
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   404
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   405
 * \fn int PHYSFS_deinit(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   406
 * \brief Deinitialize the PhysicsFS library.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   407
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   408
 * 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
   409
 *  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
   410
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   411
 * 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
   412
 *  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
   413
 *  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
   414
 *  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
   415
 *  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
   416
 *  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
   417
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   418
 * Once successfully deinitialized, PHYSFS_init() can be called again to
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   419
 *  restart the subsystem. All defaults API states are restored at this
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   420
 *  point.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   421
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   422
 *  \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
   423
 *          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
   424
 *          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
   425
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   426
 * \sa PHYSFS_init
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   427
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   428
__EXPORT__ 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
   429
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   430
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   431
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   432
 * \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
   433
 * \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
   434
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   435
 * 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
   436
 *  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
   437
 *  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
   438
 *  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
   439
 *  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
   440
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   441
 * 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
   442
 *  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
   443
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   444
 * \code
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   445
 * PHYSFS_ArchiveInfo **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   446
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   447
 * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   448
 * {
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   449
 *     printf("Supported archive: [%s], which is [%s].\n",
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   450
 *              i->extension, i->description);
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   451
 * }
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   452
 * \endcode
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   453
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   454
 * The return values are pointers to static internal memory, and should
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   455
 *  be considered READ ONLY, and never freed.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   456
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   457
 *   \return READ ONLY Null-terminated array of READ ONLY structures.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   458
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   459
__EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   460
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   461
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   462
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   463
 * \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
   464
 * \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
   465
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   466
 * 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
   467
 *  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
   468
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   469
 *   \param listVar List of information specified as freeable by this function.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   470
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   471
 * \sa PHYSFS_getCdRomDirs
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   472
 * \sa PHYSFS_enumerateFiles
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   473
 * \sa PHYSFS_getSearchPath
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   474
 */
128
31f754165105 Patched to fix a namespace issue.
Ryan C. Gordon <icculus@icculus.org>
parents: 126
diff changeset
   475
__EXPORT__ void PHYSFS_freeList(void *listVar);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   476
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   477
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   478
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   479
 * \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
   480
 * \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
   481
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   482
 * Get the last PhysicsFS error message as a null-terminated string.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   483
 *  This will be NULL if there's been no error since the last call to this
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   484
 *  function. The pointer returned by this call points to an internal buffer.
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   485
 *  Each thread has a unique error state associated with it, but each time
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   486
 *  a new error message is set, it will overwrite the previous one associated
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   487
 *  with that thread. It is safe to call this function at anytime, even
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   488
 *  before PHYSFS_init().
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   489
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   490
 *   \return READ ONLY string of last error message.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   491
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   492
__EXPORT__ const char *PHYSFS_getLastError(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   493
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   494
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
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 const char *PHYSFS_getDirSeparator(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   497
 * \brief Get platform-dependent dir separator string.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   498
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   499
 * This returns "\\\\" on win32, "/" on Unix, and ":" on MacOS. It may be more
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   500
 *  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
   501
 *  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
   502
 *  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
   503
 *  (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
   504
 *  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
   505
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   506
 *   \return READ ONLY null-terminated string of platform's dir separator.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   507
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   508
__EXPORT__ const char *PHYSFS_getDirSeparator(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   509
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   510
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   511
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   512
 * \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
   513
 * \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
   514
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   515
 * 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
   516
 *  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
   517
 *  (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
   518
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   519
 * 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
   520
 *  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
   521
 *  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
   522
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   523
 * 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
   524
 *  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
   525
 *  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
   526
 *  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
   527
 *  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
   528
 *  permit them.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   529
 *
39
bc29e1ee7ef6 Lots of bugfixes, enhancements, and corrections due to the work on
Ryan C. Gordon <icculus@icculus.org>
parents: 33
diff changeset
   530
 * 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
   531
 *  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
   532
 *  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
   533
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   534
 * 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
   535
 *  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
   536
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   537
 *   \param allow nonzero to permit symlinks, zero to deny linking.
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   538
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   539
__EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   540
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   541
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   542
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   543
 * \fn char **PHYSFS_getCdRomDirs(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   544
 * \brief Get an array of paths to available CD-ROM drives.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   545
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   546
 * 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
   547
 *  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
   548
 *  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
   549
 *  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
   550
 *  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
   551
 *  Unix box, the user unmounts a disc and remounts it elsewhere, the next
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   552
 *  call to this function will reflect that change. Fun.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   553
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   554
 * 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
   555
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   556
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   557
 * \code
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   558
 * char **cds = PHYSFS_getCdRomDirs();
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   559
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   560
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   561
 * for (i = cds; *i != NULL; i++)
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   562
 *     printf("cdrom dir [%s] is available.\n", *i);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   563
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   564
 * PHYSFS_freeList(cds);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   565
 * \endcode
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   566
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   567
 * This call may block while drives spin up. Be forewarned.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   568
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   569
 * 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
   570
 *  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
   571
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   572
 *   \return Null-terminated array of null-terminated strings.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   573
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   574
__EXPORT__ char **PHYSFS_getCdRomDirs(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   575
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   576
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   577
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   578
 * \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
   579
 * \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
   580
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   581
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   582
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   583
 * 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
   584
 *  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
   585
 *  be the process's current working directory.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   586
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   587
 * You should probably use the base dir in your search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   588
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   589
 *  \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
   590
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   591
 * \sa PHYSFS_getUserDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   592
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   593
__EXPORT__ const char *PHYSFS_getBaseDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   594
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   595
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   596
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   597
 * \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
   598
 * \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
   599
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   600
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   601
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   602
 * 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
   603
 *  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
   604
 *  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
   605
 *  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
   606
 *  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
   607
 *  platform doesn't support multiple users, either.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   608
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   609
 * You should probably use the user dir as the basis for your write dir, and
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   610
 *  also put it near the beginning of your search path.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   611
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   612
 *  \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
   613
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   614
 * \sa PHYSFS_getBaseDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   615
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   616
__EXPORT__ const char *PHYSFS_getUserDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   617
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   618
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   619
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   620
 * \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
   621
 * \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
   622
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   623
 * Get the current write dir. The default write dir is NULL.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   624
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   625
 *  \return READ ONLY string of write dir in platform-dependent notation,
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   626
 *           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
   627
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   628
 * \sa PHYSFS_setWriteDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   629
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   630
__EXPORT__ const char *PHYSFS_getWriteDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   631
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   632
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   633
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   634
 * \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
   635
 * \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
   636
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   637
 * Set a new write dir. This will override the previous setting. If the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   638
 *  directory or a parent directory doesn't exist in the physical filesystem,
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   639
 *  PhysicsFS will attempt to create them as needed.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   640
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   641
 * 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
   642
 *  write dir still has files open in it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   643
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   644
 *   \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
   645
 *                   specified in platform-dependent notation. Setting to NULL
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   646
 *                   disables the write dir, so no files can be opened for
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   647
 *                   writing via PhysicsFS.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   648
 *  \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
   649
 *           for writing via PhysicsFS will fail until this call succeeds.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   650
 *           Specifics of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   651
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   652
 * \sa PHYSFS_getWriteDir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   653
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   654
__EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   655
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   656
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   657
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   658
 * \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   659
 * \brief Add an archive or directory to the search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   660
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   661
 * If this is a duplicate, the entry is not added again, even though the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   662
 *  function succeeds.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   663
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   664
 *   \param newDir directory or archive to add to the path, in
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   665
 *                   platform-dependent notation.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   666
 *   \param appendToPath nonzero to append to search path, zero to prepend.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   667
 *  \return nonzero if added to path, zero on failure (bogus archive, dir
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   668
 *                   missing, etc). Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   669
 *                   gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   670
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   671
 * \sa PHYSFS_removeFromSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   672
 * \sa PHYSFS_getSearchPath
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   673
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   674
__EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   675
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   676
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   677
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   678
 * \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
   679
 * \brief Remove a directory or archive from the search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   680
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   681
 * This must be a (case-sensitive) match to a dir or archive already in the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   682
 *  search path, specified in platform-dependent notation.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   683
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   684
 * This call will fail (and fail to remove from the path) if the element still
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   685
 *  has files open in it.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   686
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   687
 *    \param oldDir dir/archive to remove.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   688
 *   \return nonzero on success, zero on failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   689
 *            Specifics of the error can be gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   690
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   691
 * \sa PHYSFS_addToSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   692
 * \sa PHYSFS_getSearchPath
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   693
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   694
__EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   695
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   696
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   697
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   698
 * \fn char **PHYSFS_getSearchPath(void)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   699
 * \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
   700
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   701
 * The default search path is an empty list.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   702
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   703
 * 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
   704
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   705
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   706
 * \code
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   707
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   708
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   709
 * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   710
 *     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
   711
 * \endcode
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   712
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   713
 * 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
   714
 *  resources by calling PHYSFS_freeList() with the returned pointer.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   715
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   716
 *   \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
   717
 *            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
   718
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   719
 * \sa PHYSFS_addToSearchPath
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   720
 * \sa PHYSFS_removeFromSearchPath
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   721
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   722
__EXPORT__ char **PHYSFS_getSearchPath(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   723
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
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   726
 * \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
   727
 * \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
   728
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   729
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   730
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   731
 * The write dir will be set to "userdir/.organization/appName", which is
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   732
 *  created if it doesn't exist.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   733
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   734
 * The above is sufficient to make sure your program's configuration directory
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   735
 *  is separated from other clutter, and platform-independent. The period
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   736
 *  before "mygame" even hides the directory on Unix systems.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   737
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   738
 *  The search path will be:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   739
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   740
 *    - The Write Dir (created if it doesn't exist)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   741
 *    - The Base Dir (PHYSFS_getBaseDir())
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   742
 *    - All found CD-ROM dirs (optionally)
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   743
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   744
 * These directories are then searched for files ending with the extension
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   745
 *  (archiveExt), which, if they are valid and supported archives, will also
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   746
 *  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
   747
 *  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
   748
 *  can either be appended or prepended to the search path in alphabetical
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   749
 *  order, regardless of which directories they were found in.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   750
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   751
 * 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
   752
 *  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
   753
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   754
 *    \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
   755
 *                         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
   756
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   757
 *    \param appName Program-specific name of your program, to separate it
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   758
 *                   from other programs using PhysicsFS.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   759
 *
397
12ff23d3d716 Fixed a typo in the documentation.
Ryan C. Gordon <icculus@icculus.org>
parents: 322
diff changeset
   760
 *    \param archiveExt File extension used by your program to specify an
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   761
 *                      archive. For example, Quake 3 uses "pk3", even though
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   762
 *                      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
   763
 *                      archives automatically. Do not specify the '.' char;
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   764
 *                      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
   765
 *                      not ".ZIP" ... the archive search is case-insensitive.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   766
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   767
 *    \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
   768
 *                         (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
   769
 *                         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
   770
 *                         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
   771
 *                         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
   772
 *                         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
   773
 *                         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
   774
 *                         yourself.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   775
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   776
 *    \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
   777
 *                          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
   778
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   779
 *  \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
   780
 *          gleaned from PHYSFS_getLastError().
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   781
 */
101
bd18e17ad6ad Changed PHYSFS_setSaneConfig()'s behaviour. API BREAKAGE.
Ryan C. Gordon <icculus@icculus.org>
parents: 99
diff changeset
   782
__EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
bd18e17ad6ad Changed PHYSFS_setSaneConfig()'s behaviour. API BREAKAGE.
Ryan C. Gordon <icculus@icculus.org>
parents: 99
diff changeset
   783
                                    const char *appName,
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   784
                                    const char *archiveExt,
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   785
                                    int includeCdRoms,
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   786
                                    int archivesFirst);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   787
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   788
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   789
/* Directory management stuff ... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   790
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   791
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   792
 * \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
   793
 * \brief Create a directory.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   794
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   795
 * 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
   796
 *  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
   797
 *  don't exist.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   798
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   799
 * 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
   800
 *  PHYSFS_mkdir("downloads/maps") then the directories
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   801
 *  "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
   802
 *  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
   803
 *  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
   804
 *  created directory behind and reports failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   805
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   806
 *   \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
   807
 *  \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
   808
 *          gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   809
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   810
 * \sa PHYSFS_delete
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   811
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   812
__EXPORT__ int PHYSFS_mkdir(const char *dirName);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   813
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   814
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   815
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   816
 * \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
   817
 * \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
   818
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   819
 * (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
   820
 *  write dir.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   821
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   822
 * A directory must be empty before this call can delete it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   823
 *
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
   824
 * 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
   825
 *  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
   826
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   827
 * 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
   828
 *  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
   829
 *  "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   830
 *  physical filesystem, if it exists and the operating system permits the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   831
 *  deletion.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   832
 *
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   833
 * 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
   834
 *  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
   835
 *  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
   836
 *
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
   837
 * 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
   838
 *  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
   839
 *  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
   840
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   841
 *   \param filename Filename to delete.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   842
 *  \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
   843
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   844
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   845
__EXPORT__ int PHYSFS_delete(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   846
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   847
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   848
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   849
 * \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
   850
 * \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
   851
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   852
 * 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
   853
 *  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
   854
 *  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
   855
 *  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
   856
 *  is used, just like when opening a file.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   857
 *
625
60b5f566a258 Last minute changes, fixes, and build system updates for 1.0.
Ryan C. Gordon <icculus@icculus.org>
parents: 609
diff changeset
   858
 * 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
   859
 *  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
   860
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   861
 * 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
   862
 *  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
   863
 *  will continue.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   864
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   865
 *     \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
   866
 *    \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
   867
 *             the file in question. NULL if not found.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   868
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   869
__EXPORT__ 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
   870
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   871
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   872
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   873
 * \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
   874
 * \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
   875
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   876
 * 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
   877
 *  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
   878
 *  "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
   879
 *  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
   880
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   881
 * \code
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   882
 * char **rc = PHYSFS_enumerateFiles("savegames");
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   883
 * char **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   884
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   885
 * 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
   886
 *     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
   887
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   888
 * PHYSFS_freeList(rc);
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   889
 * \endcode
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   890
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   891
 *  ...will print:
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   892
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   893
 * \verbatim
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   894
 * We've got [x.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   895
 * We've got [y.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   896
 * 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
   897
 * We've got [w.sav].\endverbatim
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   898
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   899
 * Feel free to sort the list however you like. We only promise there will
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   900
 *  be no duplicates, but not what order the final list will come back in.
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   901
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   902
 * 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
   903
 *  function when you are done with it.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   904
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   905
 *    \param dir directory in platform-independent notation to enumerate.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   906
 *   \return Null-terminated array of null-terminated strings.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   907
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   908
__EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   909
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   910
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   911
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   912
 * \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
   913
 * \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
   914
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   915
 * 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
   916
 *  name of (fname).
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   917
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   918
 * 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
   919
 *  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
   920
 *  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
   921
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   922
 *    \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
   923
 *   \return non-zero if filename exists. zero otherwise.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   924
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   925
 * \sa PHYSFS_isDirectory
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   926
 * \sa PHYSFS_isSymbolicLink
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   927
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   928
__EXPORT__ 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
   929
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   930
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   931
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   932
 * \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
   933
 * \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
   934
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   935
 * 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
   936
 *  really a directory entry.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   937
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   938
 * 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
   939
 *  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
   940
 *  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
   941
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   942
 *    \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
   943
 *   \return non-zero if filename exists and is a directory.  zero otherwise.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   944
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   945
 * \sa PHYSFS_exists
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   946
 * \sa PHYSFS_isSymbolicLink
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   947
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   948
__EXPORT__ int PHYSFS_isDirectory(const char *fname);
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   949
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   950
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   951
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   952
 * \fn int PHYSFS_isSymbolicLink(const char *fname)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   953
 * \brief Determine if a file in the search path is really a symbolic link.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   954
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   955
 * 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
   956
 *  really a symbolic link.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   957
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   958
 * 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
   959
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   960
 *  this function will always return 0 in that case.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   961
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   962
 *    \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
   963
 *   \return non-zero if filename exists and is a symlink.  zero otherwise.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   964
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   965
 * \sa PHYSFS_exists
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   966
 * \sa PHYSFS_isDirectory
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   967
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
   968
__EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   969
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   970
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   971
/**
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   972
 * \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   973
 * \brief Get the last modification time of a file.
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   974
 *
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   975
 * The modtime is returned as a number of seconds since the epoch
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   976
 *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   977
 *  the particular archiver. If there is no reasonable way to obtain this
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   978
 *  information for a particular archiver, or there was some sort of error,
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   979
 *  this function returns (-1).
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   980
 *
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   981
 *   \param filename filename to check, in platform-independent notation.
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   982
 *  \return last modified time of the file. -1 if it can't be determined.
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   983
 */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   984
__EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   985
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   986
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   987
/* i/o stuff... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   988
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
   989
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   990
 * \fn PHYSFS_file *PHYSFS_openWrite(const char *filename)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   991
 * \brief Open a file for writing.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
   992
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   993
 * Open a file for writing, in platform-independent notation and in relation
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   994
 *  to the write dir as the root of the writable filesystem. The specified
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   995
 *  file is created if it doesn't exist. If it does exist, it is truncated to
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   996
 *  zero bytes, and the writing offset is set to the start.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   997
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   998
 * 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
   999
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1000
 *  symlink with this function will fail in such a case.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1001
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1002
 *   \param filename File to open.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1003
 *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1004
 *           of the error can be gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1005
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1006
 * \sa PHYSFS_openRead
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1007
 * \sa PHYSFS_openAppend
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1008
 * \sa PHYSFS_write
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1009
 * \sa PHYSFS_close
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1010
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
  1011
__EXPORT__ PHYSFS_file *PHYSFS_openWrite(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1012
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1013
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1014
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1015
 * \fn PHYSFS_file *PHYSFS_openAppend(const char *filename)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1016
 * \brief Open a file for appending.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1017
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1018
 * Open a file for writing, in platform-independent notation and in relation
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
  1019
 *  to the write dir as the root of the writable filesystem. The specified
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1020
 *  file is created if it doesn't exist. If it does exist, the writing offset
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1021
 *  is set to the end of the file, so the first write will be the byte after
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1022
 *  the end.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1023
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1024
 * 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
  1025
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1026
 *  symlink with this function will fail in such a case.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1027
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1028
 *   \param filename File to open.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1029
 *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1030
 *           of the error can be gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1031
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1032
 * \sa PHYSFS_openRead
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1033
 * \sa PHYSFS_openWrite
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1034
 * \sa PHYSFS_write
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1035
 * \sa PHYSFS_close
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1036
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
  1037
__EXPORT__ PHYSFS_file *PHYSFS_openAppend(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1038
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1039
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1040
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1041
 * \fn PHYSFS_file *PHYSFS_openRead(const char *filename)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1042
 * \brief Open a file for reading.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1043
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1044
 * Open a file for reading, in platform-independent notation. The search path
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1045
 *  is checked one at a time until a matching file is found, in which case an
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1046
 *  abstract filehandle is associated with it, and reading may be done.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1047
 *  The reading offset is set to the first byte of the file.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1048
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1049
 * 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
  1050
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1051
 *  symlink with this function will fail in such a case.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
  1052
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1053
 *   \param filename File to open.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1054
 *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1055
 *           of the error can be gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1056
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1057
 * \sa PHYSFS_openWrite
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1058
 * \sa PHYSFS_openAppend
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1059
 * \sa PHYSFS_read
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1060
 * \sa PHYSFS_close
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1061
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
  1062
__EXPORT__ PHYSFS_file *PHYSFS_openRead(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1063
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1064
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
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 int PHYSFS_close(PHYSFS_file *handle)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1067
 * \brief Close a PhysicsFS filehandle.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1068
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1069
 * This call is capable of failing if the operating system was buffering
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1070
 *  writes to the physical media, and, now forced to write those changes to
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1071
 *  physical media, can not store the data for some reason. In such a case,
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1072
 *  the filehandle stays open. A well-written program should ALWAYS check the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1073
 *  return value from the close call in addition to every writing call!
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1074
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1075
 *   \param handle handle returned from PHYSFS_open*().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1076
 *  \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
  1077
 *          gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1078
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1079
 * \sa PHYSFS_openRead
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1080
 * \sa PHYSFS_openWrite
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1081
 * \sa PHYSFS_openAppend
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1082
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
  1083
__EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1084
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1085
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1086
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1087
 * \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1088
 * \brief Read data from a PhysicsFS filehandle
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1089
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1090
 * The file must be opened for reading.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1091
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1092
 *   \param handle handle returned from PHYSFS_openRead().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1093
 *   \param buffer buffer to store read data into.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1094
 *   \param objSize size in bytes of objects being read from (handle).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1095
 *   \param objCount number of (objSize) objects to read from (handle).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1096
 *  \return number of objects read. PHYSFS_getLastError() can shed light on
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
  1097
 *           the reason this might be < (objCount), as can PHYSFS_eof().
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
  1098
 *            -1 if complete failure.
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1099
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1100
 * \sa PHYSFS_eof
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1101
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1102
__EXPORT__ PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1103
                                     void *buffer,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1104
                                     PHYSFS_uint32 objSize,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1105
                                     PHYSFS_uint32 objCount);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1106
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1107
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1108
 * \fn PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle, const void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1109
 * \brief Write data to a PhysicsFS filehandle
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1110
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1111
 * The file must be opened for writing.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1112
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1113
 *   \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1114
 *   \param buffer buffer to store read data into.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1115
 *   \param objSize size in bytes of objects being read from (handle).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1116
 *   \param objCount number of (objSize) objects to read from (handle).
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1117
 *  \return number of objects written. PHYSFS_getLastError() can shed light on
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
  1118
 *           the reason this might be < (objCount). -1 if complete failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1119
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1120
__EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1121
                                      const void *buffer,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1122
                                      PHYSFS_uint32 objSize,
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1123
                                      PHYSFS_uint32 objCount);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1124
508
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
  1125
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
  1126
/* File position stuff... */
0e75524a96af Added buffering API.
Ryan C. Gordon <icculus@icculus.org>
parents: 397
diff changeset
  1127
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1128
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1129
 * \fn int PHYSFS_eof(PHYSFS_file *handle)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1130
 * \brief Check for end-of-file state on a PhysicsFS filehandle.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1131
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1132
 * Determine if the end of file has been reached in a PhysicsFS filehandle.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1133
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1134
 *   \param handle handle returned from PHYSFS_openRead().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1135
 *  \return nonzero if EOF, zero if not.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1136
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1137
 * \sa PHYSFS_read
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1138
 * \sa PHYSFS_tell
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1139
 */
74
a4a5066fb640 Compiles and runs on Visual C. What an uphill climb THAT was.
Ryan C. Gordon <icculus@icculus.org>
parents: 69
diff changeset
  1140
__EXPORT__ int PHYSFS_eof(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1141
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1142
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1143
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1144
 * \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1145
 * \brief Determine current position within a PhysicsFS filehandle.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1146
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1147
 *   \param handle handle returned from PHYSFS_open*().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1148
 *  \return offset in bytes from start of file. -1 if error occurred.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1149
 *           Specifics of the error can be gleaned from PHYSFS_getLastError().
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1150
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1151
 * \sa PHYSFS_seek
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1152
 */
132
b53fa5093749 Added typedefs and platform-specific i/o.
Ryan C. Gordon <icculus@icculus.org>
parents: 128
diff changeset
  1153
__EXPORT__ PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1154
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1155
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1156
/**
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1157
 * \fn int PHYSFS_seek(PHYSFS_file *handle, PHYSFS_uint64 pos)
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1158
 * \brief Seek to a new position within a PhysicsFS filehandle.
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1159
 *
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1160
 * The next read or write will occur at that place. Seeking past the
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1161
 *  beginning or end of the file is not allowed, and causes an error.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
  1162
 *
265
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240
diff changeset
  1163
 *   \param handle handle returned from PHYSFS_open*().
6187d310b2c0 Lots of tweaks and revisions for Doxygen support.
Ryan C. Gordon <icculus@icculus.org>
parents: 240