physfs.h
author Ryan C. Gordon <icculus@icculus.org>
Sun, 08 Jul 2001 13:57:28 +0000
changeset 23 bd6ba9c8717c
parent 15 418eacc97ac8
child 28 529214f57d1b
permissions -rw-r--r--
Initial debugging: dropped PhysicsFS routines into the Build engine, replacing Ken's groupfile management. Not finished, but lots of initial debugging is complete. More bugs, likely in OUR groupfile code, are waiting to be fixed, but the KenBuild editor runs without crashing (er...but the palette doesn't seem to be loading... :) ) --ryan.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     1
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     2
 * PhysicsFS; a portable, flexible file i/o abstraction.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     3
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     4
 * 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
     5
 *  stdio or system i/o calls. The brief benefits:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     6
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     7
 *   - 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
     8
 *   - 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
     9
 *   - It's flexible. Archives (.ZIP files) can be used transparently as
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    10
 *      directory structures.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    11
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    12
 * 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
    13
 *  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
    14
 *  familiar to you.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    15
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    16
 * 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
    17
 *  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
    18
 *  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
    19
 *  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
    20
 *  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
    21
 *  "C:\" directories. This prevents an application's internal scripting
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    22
 *  language from piddling over c:\config.sys, for example. If you'd rather
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    23
 *  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
    24
 *  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
    25
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    26
 * 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
    27
 *  The search path creates a single, hierarchical directory structure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    28
 *  Not only does this lend itself well to general abstraction with archives,
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    29
 *  it also gives better support to operating systems like MacOS and Unix.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    30
 *  Generally speaking, you shouldn't ever hardcode a drive letter; not only
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    31
 *  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
    32
 *  users to a single drive, too. Use the PhysicsFS abstraction functions and
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
 *  allow user-defined configuration options, too. When opening a file, you
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    34
 *  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
    35
 *  "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
    36
 *  "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
    37
 *  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
    38
 *  "platform-independent notation" in this documentation. Specifying a
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    39
 *  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
    40
 *  "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
    41
 *  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
    42
 *  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
    43
 *  access into those directories are done with platform-independent notation.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    44
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    45
 * 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
    46
 *  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
    47
 *  reading, PhysicsFS goes through the search path. This is NOT the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    48
 *  same thing as the PATH environment variable. An application using
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    49
 *  PhysicsFS specifies directories to be searched which may be actual
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    50
 *  directories, or archive files that contain files and subdirectories of
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    51
 *  their own. See the end of these docs for currently supported archive
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    52
 *  formats.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    53
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    54
 * 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
    55
 *  got the following search path defined (to use a win32 example again):
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    56
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    57
 *    C:\mygame
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    58
 *    C:\mygame\myuserfiles
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    59
 *    D:\mygamescdromdatafiles
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    60
 *    C:\mygame\installeddatafiles.zip
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    61
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    62
 * 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
    63
 *  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
    64
 *  the string; this is platform-independent notation) will check for
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    65
 *  C:\mygame\textfiles\myfile.txt, then
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    66
 *  C:\mygame\myuserfiles\textfiles\myfile.txt, then
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    67
 *  D:\mygamescdromdatafiles\textfiles\myfile.txt, then, finally, for
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    68
 *  textfiles\myfile.txt inside of C:\mygame\installeddatafiles.zip. Remember
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    69
 *  that most archive types and platform filesystems store their filenames in
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
    70
 *  a case-sensitive manner, so you should be careful to specify it correctly.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    71
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    72
 * 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
    73
 *  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
    74
 *  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
    75
 *  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
    76
 *  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
    77
 *  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
    78
 *  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
    79
 *  PhysicsFS.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    80
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    81
 * 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
    82
 *  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
    83
 *  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
    84
 *  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
    85
 *  NT systems.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    86
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    87
 * 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
    88
 *  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
    89
 *  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
    90
 *  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
    91
 *  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
    92
 *  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
    93
 *  function to recommend a good search path, etc.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    94
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
    95
 * 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
    96
 *  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
    97
 *  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
    98
 *  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
    99
 *  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
   100
 *  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
   101
 *  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
   102
 *  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
   103
 *  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
   104
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   105
 * PhysicsFS is (sort of) NOT thread safe! The error messages returned by
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   106
 *  PHYSFS_getLastError are unique by thread, but that's it. Generally
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   107
 *  speaking, we'd have to request a mutex at the start of each function,
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   108
 *  and release it before returning. Not only is this REALLY slow, it requires
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   109
 *  a thread lock portability layer to be written. All that work is only
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   110
 *  necessary as a safety if the calling application is poorly written.
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   111
 *  Generally speaking, it is safe to call most functions that don't set state
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   112
 *  simultaneously; you can read and write and open and close different files
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   113
 *  at the same time in different threads, but trying to set the write path in
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   114
 *  one thread while opening a file for writing in another will, at best,
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   115
 *  cause a polite error, but depending on the race condition results, you may
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   116
 *  get a segfault and crash, too. Use your head, and implement you own thread
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   117
 *  locks where needed. Also, consider if you REALLY need a multithreaded
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   118
 *  solution in the first place.
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
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   122
 *  filehandles with PhysicsFS filehandles and vice versa.
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)
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   131
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   132
 * Please see the file LICENSE in the source's root directory.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   133
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   134
 *  This file written by Ryan C. Gordon.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   135
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   136
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   137
#ifndef _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   138
#define _INCLUDE_PHYSFS_H_
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   139
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   140
#ifdef __cplusplus
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   141
extern "C" {
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   142
#endif
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   143
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   144
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   145
typedef struct __PHYSFS_FILE__
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   146
{
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   147
    void *opaque;
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   148
} PHYSFS_file;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   149
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   150
typedef struct __PHYSFS_ARCHIVEINFO__
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   151
{
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   152
    const char *extension;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   153
    const char *description;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   154
} PHYSFS_ArchiveInfo;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   155
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   156
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   157
/* functions... */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   158
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   159
typedef struct __PHYSFS_VERSION__
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   160
{
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   161
    int major;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   162
    int minor;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   163
    int patch;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   164
} PHYSFS_Version;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   165
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   166
#define PHYSFS_VER_MAJOR 0
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   167
#define PHYSFS_VER_MINOR 1
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   168
#define PHYSFS_VER_PATCH 0
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   169
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   170
#define PHYSFS_VERSION(x) { \
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   171
                            x->major = PHYSFS_VER_MAJOR; \
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   172
                            x->minor = PHYSFS_VER_MINOR; \
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   173
                            x->patch = PHYSFS_VER_PATCH; \
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   174
                          }
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   175
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   176
/**
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   177
 * Get the version of PhysicsFS that is linked against your program. If you
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   178
 *  are using a shared library (DLL) version of PhysFS, then it is possible
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   179
 *  that it will be different than the version you compiled against.
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   180
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   181
 * 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
   182
 *  of PhysFS you compiled against:
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   183
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   184
 * PHYSFS_Version compiled;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   185
 * PHYSFS_Version linked;
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   186
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   187
 * PHYSFS_VERSION(&compiled);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   188
 * PHYSFS_getLinkedVersion(&linked);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   189
 * 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
   190
 *           compiled.major, compiled.minor, compiled.patch);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   191
 * 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
   192
 *           linked.major, linked.minor, linked.patch);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   193
 *
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   194
 * This function may be called safely at any time, even before PHYSFS_init().
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   195
 */
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   196
void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   197
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   198
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   199
/**
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   200
 * Initialize PhysicsFS. This must be called before any other PhysicsFS
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   201
 *  function.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   202
 *
23
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   203
 * 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
   204
 *  current working directory.
bd6ba9c8717c Initial debugging: dropped PhysicsFS routines into the Build engine,
Ryan C. Gordon <icculus@icculus.org>
parents: 15
diff changeset
   205
 *
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   206
 *   @param argv0 the argv[0] string passed to your program's mainline.
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   207
 *  @return nonzero on success, zero on error. Specifics of the error can be
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   208
 *          gleaned from PHYSFS_getLastError().
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   209
 */
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   210
int PHYSFS_init(const char *argv0);
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   211
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   212
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   213
/**
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   214
 * Shutdown PhysicsFS. This closes any files opened via PhysicsFS, blanks the
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   215
 *  search/write paths, frees memory, and invalidates all of your handles.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   216
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   217
 * 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
   218
 *  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
   219
 *  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
   220
 *  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
   221
 *  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
   222
 *  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
   223
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   224
 * 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
   225
 *  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
   226
 *  point.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   227
 *
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   228
 *  @return nonzero on success, zero on error. Specifics of the error can be
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   229
 *          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
   230
 *          undefined, and probably badly screwed up.
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   231
 */
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   232
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
   233
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   234
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   235
/**
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   236
 * 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
   237
 *  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
   238
 *  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
   239
 *  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
   240
 *  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
   241
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   242
 * 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
   243
 *  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
   244
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   245
 * PHYSFS_ArchiveInfo **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   246
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   247
 * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   248
 * {
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   249
 *     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
   250
 *              i->extension, i->description);
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   251
 * }
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   252
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   253
 * 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
   254
 *  be considered READ ONLY, and never freed.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   255
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   256
 *   @return READ ONLY Null-terminated array of READ ONLY structures.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   257
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   258
const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   259
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   260
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   261
/**
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   262
 * 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
   263
 *  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
   264
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   265
 *   @param list List of information specified as freeable by this function.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   266
 */
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   267
void PHYSFS_freeList(void *list);
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   268
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   269
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   270
/**
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   271
 * Get the last PhysicsFS error message as a null-terminated string.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   272
 *  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
   273
 *  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
   274
 *  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
   275
 *  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
   276
 *  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
   277
 *  before PHYSFS_init().
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   278
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   279
 *   @return READ ONLY string of last error message.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   280
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   281
const char *PHYSFS_getLastError(void);
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   282
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   283
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   284
/**
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   285
 * Get a platform-dependent dir separator. This is "\\" on win32, "/" on Unix,
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   286
 *  and ":" on MacOS. It may be more than one character, depending on the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   287
 *  platform, and your code should take that into account. Note that this is
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   288
 *  only useful for setting up the search/write paths, since access into those
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   289
 *  dirs always use '/' (platform-independent notation) to separate
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   290
 *  directories. This is also handy for getting platform-independent access
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   291
 *  when using stdio calls.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   292
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   293
 *   @return READ ONLY null-terminated string of platform's dir separator.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   294
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   295
const char *PHYSFS_getDirSeparator(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   296
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   297
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   298
/**
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   299
 * Enable symbolic links. Some physical filesystems and archives contain
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   300
 *  files that are just pointers to other files. On the physical filesystem,
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   301
 *  opening such a link will (transparently) open the file that is pointed to.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   302
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   303
 * 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
   304
 *  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
   305
 *  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
   306
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   307
 * 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
   308
 *  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
   309
 *  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
   310
 *  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
   311
 *  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
   312
 *  permit them.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   313
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   314
 * Symbolic link permission can be enabled or disabled at any time, and is
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   315
 *  disabled by default.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   316
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   317
 *   @param allow nonzero to permit symlinks, zero to deny linking.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   318
 */
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   319
void PHYSFS_permitSymbolicLinks(int allow);
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   320
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   321
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   322
/**
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   323
 * Get an array of dirs to available CD-ROM drives.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   324
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   325
 * 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
   326
 *  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
   327
 *  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
   328
 *  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
   329
 *  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
   330
 *  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
   331
 *  call to this function will reflect that change. Fun.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   332
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   333
 * 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
   334
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   335
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   336
 * char **cds = PHYSFS_getCdRomDirs();
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   337
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   338
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   339
 * for (i = cds; *i != NULL; i++)
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   340
 *     printf("cdrom dir [%s] is available.\n", *i);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   341
 *
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   342
 * PHYSFS_freeList(cds);
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   343
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   344
 * This call may block while drives spin up. Be forewarned.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   345
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   346
 * 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
   347
 *  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
   348
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   349
 *   @return Null-terminated array of null-terminated strings.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   350
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   351
char **PHYSFS_getCdRomDirs(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   352
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   353
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   354
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   355
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   356
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   357
 * 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
   358
 *  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
   359
 *  be the process's current working directory.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   360
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   361
 * You should probably use the base dir in your search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   362
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   363
 *  @return READ ONLY string of base dir in platform-dependent notation.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   364
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   365
const char *PHYSFS_getBaseDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   366
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   367
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   368
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   369
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   370
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   371
 * 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
   372
 *  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
   373
 *  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
   374
 *  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
   375
 *  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
   376
 *  platform doesn't support multiple users, either.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   377
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   378
 * 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
   379
 *  also put it near the beginning of your search path.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   380
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   381
 *  @return READ ONLY string of user dir in platform-dependent notation.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   382
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   383
const char *PHYSFS_getUserDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   384
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   385
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   386
/**
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   387
 * Get the current write dir. The default write dir is NULL.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   388
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   389
 *  @return READ ONLY string of write dir in platform-dependent notation,
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   390
 *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   391
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   392
const char *PHYSFS_getWriteDir(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   393
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   394
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   395
/**
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   396
 * 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
   397
 *  directory or a parent directory doesn't exist in the physical filesystem,
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   398
 *  PhysicsFS will attempt to create them as needed.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   399
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   400
 * 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
   401
 *  write dir still has files open in it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   402
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   403
 *   @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
   404
 *                   specified in platform-dependent notation. Setting to NULL
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   405
 *                   disables the write dir, so no files can be opened for
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   406
 *                   writing via PhysicsFS.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   407
 *  @return non-zero on success, zero on failure. All attempts to open a file
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   408
 *           for writing via PhysicsFS will fail until this call succeeds.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   409
 *           Specifics of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   410
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   411
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   412
int PHYSFS_setWriteDir(const char *newDir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   413
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   414
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   415
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   416
 * Add a directory or archive to the search path. If this is a duplicate, the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   417
 *  entry is not added again, even though the function succeeds.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   418
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   419
 *   @param newDir directory or archive to add to the path, in
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   420
 *                   platform-dependent notation.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   421
 *   @param appendToPath nonzero to append to search path, zero to prepend.
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   422
 *  @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
   423
 *                   missing, etc). Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   424
 *                   gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   425
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   426
int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   427
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   428
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   429
/**
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   430
 * Remove a directory or archive from the search path.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   431
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   432
 * 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
   433
 *  search path, specified in platform-dependent notation.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   434
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   435
 * 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
   436
 *  has files open in it.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   437
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   438
 *    @param oldDir dir/archive to remove.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   439
 *   @return nonzero on success, zero on failure.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   440
 *            Specifics of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   441
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   442
int PHYSFS_removeFromSearchPath(const char *oldDir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   443
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   444
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   445
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   446
 * Get the current search path. The default search path is an empty list.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   447
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   448
 * 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
   449
 *  end of the list:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   450
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   451
 * char **i;
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   452
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   453
 * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   454
 *     printf("[%s] is in the search path.\n", *i);
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   455
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   456
 * 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
   457
 *  resources by calling PHYSFS_freeList() with the returned pointer.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   458
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   459
 *   @return Null-terminated array of null-terminated strings. NULL if there
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   460
 *            was a problem (read: OUT OF MEMORY).
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   461
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   462
char **PHYSFS_getSearchPath(void);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   463
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   464
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   465
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   466
 * Helper function.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   467
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   468
 * Set up sane, default paths. The write dir will be set to
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   469
 *  "userdir/.appName", which is created if it doesn't exist.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   470
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   471
 * The above is sufficient to make sure your program's configuration directory
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   472
 *  is separated from other clutter, and platform-independent. The period
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   473
 *  before "mygame" even hides the directory on Unix systems.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   474
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   475
 *  The search path will be:
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   476
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   477
 *    - The Write Dir (created if it doesn't exist)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   478
 *    - The Write Dir/appName (created if it doesn't exist)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   479
 *    - The Base Dir (PHYSFS_getBaseDir())
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   480
 *    - The Base Dir/appName (if it exists)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   481
 *    - All found CD-ROM dirs (optionally)
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   482
 *    - All found CD-ROM dirs/appName (optionally, and if they exist)
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   483
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   484
 * These directories are then searched for files ending with the extension
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   485
 *  (archiveExt), which, if they are valid and supported archives, will also
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   486
 *  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
   487
 *  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
   488
 *  can either be appended or prepended to the search path in alphabetical
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   489
 *  order, regardless of which directories they were found in.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   490
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   491
 * 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
   492
 *  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
   493
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   494
 *    @param appName Program-specific name of your program, to separate it
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   495
 *                   from other programs using PhysicsFS.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   496
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   497
 *    @param archiveExt File extention used by your program to specify an
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   498
 *                      archive. For example, Quake 3 uses "pk3", even though
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   499
 *                      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
   500
 *                      archives automatically. Do not specify the '.' char;
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   501
 *                      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
   502
 *                      not ".ZIP" ... the archive search is case-insensitive.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   503
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   504
 *    @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
   505
 *                         (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
   506
 *                         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
   507
 *                         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
   508
 *                         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
   509
 *                         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
   510
 *                         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
   511
 *                         yourself.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   512
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   513
 *    @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
   514
 *                          Zero to append them. Ignored if !(archiveExt).
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   515
 *  @return nonzero on success, zero on error. Specifics of the error can be
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   516
 *          gleaned from PHYSFS_getLastError().
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   517
 */
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   518
int PHYSFS_setSaneConfig(const char *appName, const char *archiveExt,
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   519
                          int includeCdRoms, int archivesFirst);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   520
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   521
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   522
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   523
 * Create a directory. This is specified in platform-independent notation in
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   524
 *  relation to the write dir. All missing parent directories are also
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   525
 *  created if they don't exist.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   526
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   527
 * 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
   528
 *  PHYSFS_mkdir("downloads/maps") then the directories
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   529
 *  "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
   530
 *  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
   531
 *  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
   532
 *  created directory behind and reports failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   533
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   534
 *   @param dirname New dir to create.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   535
 *  @return nonzero on success, zero on error. Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   536
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   537
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   538
int PHYSFS_mkdir(const char *dirName);
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   539
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   540
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   541
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   542
 * Delete a file or directory. This is specified in platform-independent
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   543
 *  notation in relation to the write dir.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   544
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   545
 * A directory must be empty before this call can delete it.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   546
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   547
 * 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
   548
 *  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
   549
 *  "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   550
 *  physical filesystem, if it exists and the operating system permits the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   551
 *  deletion.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   552
 *
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   553
 * 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
   554
 *  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
   555
 *  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
   556
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   557
 *   @param filename Filename to delete.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   558
 *  @return nonzero on success, zero on error. Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   559
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   560
 */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   561
int PHYSFS_delete(const char *filename);
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   562
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   563
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   564
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   565
 * Figure out where in the search path a file resides. The file is specified
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   566
 *  in platform-independent notation. The returned filename will be the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   567
 *  element of the search path where the file was found, which may be a
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   568
 *  directory, or an archive. Even if there are multiple matches in different
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   569
 *  parts of the search path, only the first one found is used, just like
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   570
 *  when opening a file.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   571
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   572
 * So, if you look for "maps/level1.map", and C:\mygame is in your search
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   573
 *  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
   574
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   575
 * 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
   576
 *  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
   577
 *  will continue.
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   578
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   579
 *     @param filename file to look for.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   580
 *    @return READ ONLY string of element of search path containing the
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   581
 *             the file in question. NULL if not found.
1
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
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
   584
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   585
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   586
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   587
/**
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   588
 * Get a file listing of a search path's directory. Matching directories are
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   589
 *  interpolated. That is, if "C:\mydir" is in the search path and contains a
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   590
 *  directory "savegames" that contains "x.sav", "y.sav", and "z.sav", and
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   591
 *  there is also a "C:\userdir" in the search path that has a "savegames"
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   592
 *  subdirectory with "w.sav", then the following code:
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   593
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   594
 * ------------------------------------------------
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   595
 * char **rc = PHYSFS_enumerateFiles("savegames");
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   596
 * char **i;
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   597
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   598
 * for (i = rc; *i != NULL; i++)
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   599
 *     printf("We've got [%s].\n", *i);
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   600
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   601
 * PHYSFS_freeList(rc);
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   602
 * ------------------------------------------------
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   603
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   604
 *  ...will print:
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   605
 *
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   606
 * ------------------------------------------------
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   607
 * We've got [x.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   608
 * We've got [y.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   609
 * We've got [z.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   610
 * We've got [w.sav].
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   611
 * ------------------------------------------------
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   612
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   613
 * 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
   614
 *  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
   615
 *
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   616
 * 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
   617
 *  function when you are done with it.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   618
 *
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   619
 *    @param dir directory in platform-independent notation to enumerate.
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   620
 *   @return Null-terminated array of null-terminated strings.
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   621
 */
6
3662cbc014ef More updates, corrections, clarifications...
Ryan C. Gordon <icculus@icculus.org>
parents: 3
diff changeset
   622
char **PHYSFS_enumerateFiles(const char *dir);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   623
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   624
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   625
/**
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   626
 * Determine if there is an entry anywhere in the search path by the
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   627
 *  name of (fname).
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   628
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   629
 * 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
   630
 *  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
   631
 *  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
   632
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   633
 *    @param fname filename in platform-independent notation.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   634
 *   @return non-zero if filename exists. zero otherwise.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   635
 */
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   636
int PHYSFS_exists(const char *fname);
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   637
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   638
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   639
/**
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   640
 * 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
   641
 *  really a directory entry.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   642
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   643
 * 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
   644
 *  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
   645
 *  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
   646
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   647
 *    @param fname filename in platform-independent notation.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   648
 *   @return non-zero if filename exists and is a directory.  zero otherwise.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   649
 */
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   650
int PHYSFS_isDirectory(const char *fname);
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   651
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   652
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   653
/**
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   654
 * 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
   655
 *  really a symbolic link.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   656
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   657
 * 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
   658
 *  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
   659
 *  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
   660
 *
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   661
 *    @param fname filename in platform-independent notation.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   662
 *   @return non-zero if filename exists and is a symlink.  zero otherwise.
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   663
 */
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   664
int PHYSFS_isSymbolicLink(const char *fname);
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   665
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   666
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   667
/**
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   668
 * 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
   669
 *  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
   670
 *  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
   671
 *  zero bytes, and the writing offset is set to the start.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   672
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   673
 * 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
   674
 *  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
   675
 *  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
   676
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   677
 *   @param filename File to open.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   678
 *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   679
 *           of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   680
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   681
PHYSFS_file *PHYSFS_openWrite(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   682
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
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   685
 * 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
   686
 *  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
   687
 *  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
   688
 *  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
   689
 *  the end.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   690
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   691
 * 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
   692
 *  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
   693
 *  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
   694
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   695
 *   @param filename File to open.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   696
 *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   697
 *           of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   698
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   699
PHYSFS_file *PHYSFS_openAppend(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   700
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   701
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
 * Open a file for reading, in platform-independent notation. The search path
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   704
 *  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
   705
 *  abstract filehandle is associated with it, and reading may be done.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   706
 *  The reading offset is set to the first byte of the file.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   707
 *
15
418eacc97ac8 Tons of updates. Mostly implemented. Mostly compiling.
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
   708
 * 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
   709
 *  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
   710
 *  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
   711
 *
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   712
 *   @param filename File to open.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   713
 *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   714
 *           of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   715
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   716
PHYSFS_file *PHYSFS_openRead(const char *filename);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   717
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   718
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   719
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   720
 * Close a PhysicsFS filehandle. This call is capable of failing if the
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   721
 *  operating system was buffering writes to this file, and (now forced to
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   722
 *  write those changes to physical media) can not store the data for any
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   723
 *  reason. In such a case, the filehandle stays open. A well-written program
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   724
 *  should ALWAYS check the return value from the close call in addition to
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   725
 *  every writing call!
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   726
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   727
 *   @param handle handle returned from PHYSFS_open*().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   728
 *  @return nonzero on success, zero on error. Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   729
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   730
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   731
int PHYSFS_close(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   732
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
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   735
 * Read data from a PhysicsFS filehandle. The file must be opened for reading.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   736
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   737
 *   @param handle handle returned from PHYSFS_openRead().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   738
 *   @param buffer buffer to store read data into.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   739
 *   @param objSize size in bytes of objects being read from (handle).
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   740
 *   @param objCount number of (objSize) objects to read from (handle).
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   741
 *  @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
   742
 *           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
   743
 *            -1 if complete failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   744
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   745
int PHYSFS_read(PHYSFS_file *handle, void *buffer,
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   746
                unsigned int objSize, unsigned int objCount);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   747
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   748
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   749
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   750
 * Write data to a PhysicsFS filehandle. The file must be opened for writing.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   751
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   752
 *   @param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   753
 *   @param buffer buffer to store read data into.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   754
 *   @param objSize size in bytes of objects being read from (handle).
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   755
 *   @param objCount number of (objSize) objects to read from (handle).
8
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   756
 *  @return number of objects written. PHYSFS_getLastError() can shed light on
41e4c6031535 Typo fixes, clarifications, and corrections.
Ryan C. Gordon <icculus@icculus.org>
parents: 6
diff changeset
   757
 *           the reason this might be < (objCount). -1 if complete failure.
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   758
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   759
int PHYSFS_write(PHYSFS_file *handle, void *buffer,
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   760
                 unsigned int objSize, unsigned int objCount);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   761
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   762
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   763
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   764
 * 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
   765
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   766
 *   @param handle handle returned from PHYSFS_openRead().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   767
 *  @return nonzero if EOF, zero if not.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   768
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   769
int PHYSFS_eof(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   770
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   771
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   772
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   773
 * Determine current position within a PhysicsFS filehandle.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   774
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   775
 *   @param handle handle returned from PHYSFS_open*().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   776
 *  @return offset in bytes from start of file. -1 if error occurred.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   777
 *           Specifics of the error can be gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   778
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   779
int PHYSFS_tell(PHYSFS_file *handle);
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   780
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   781
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   782
/**
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   783
 * Seek to a new position within a PhysicsFS filehandle. The next read or write
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   784
 *  will occur at that place. Seeking past the beginning or end of the file is
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   785
 *  not allowed.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   786
 *
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   787
 *   @param handle handle returned from PHYSFS_open*().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   788
 *   @param pos number of bytes from start of file to seek to.
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   789
 *  @return nonzero on success, zero on error. Specifics of the error can be
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   790
 *          gleaned from PHYSFS_getLastError().
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   791
 */
3
0dd785321345 Boatloads of updates to the spec.
Ryan C. Gordon <icculus@icculus.org>
parents: 2
diff changeset
   792
int PHYSFS_seek(PHYSFS_file *handle, int pos);
2
24ba671694af Fixed typos, expanded documentation, added init and deinit functions, and
Ryan C. Gordon <icculus@icculus.org>
parents: 1
diff changeset
   793
1
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   794
#ifdef __cplusplus
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   795
}
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   796
#endif
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   797
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   798
#endif  /* !defined _INCLUDE_PHYSFS_H_ */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   799
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   800
/* end of physfs.h ... */
b5ce9d35fdb4 Initial revision
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   801