src/physfs.h
author Ryan C. Gordon <icculus@icculus.org>
Wed, 27 Sep 2017 11:54:25 -0400
changeset 1613 ebe0ee3b7810
parent 1610 d4eea8657f2a
child 1618 0bbfaf6c5508
permissions -rw-r--r--
Bumped version to 3.0.0!
icculus@1070
     1
/**
icculus@1070
     2
 * \file physfs.h
icculus@1070
     3
 *
icculus@1070
     4
 * Main header file for PhysicsFS.
icculus@1070
     5
 */
icculus@265
     6
icculus@1
     7
/**
icculus@265
     8
 * \mainpage PhysicsFS
icculus@265
     9
 *
icculus@265
    10
 * The latest version of PhysicsFS can be found at:
icculus@1373
    11
 *     https://icculus.org/physfs/
icculus@265
    12
 *
icculus@1
    13
 * PhysicsFS; a portable, flexible file i/o abstraction.
icculus@1
    14
 *
icculus@1
    15
 * This API gives you access to a system file system in ways superior to the
icculus@1
    16
 *  stdio or system i/o calls. The brief benefits:
icculus@1
    17
 *
icculus@1
    18
 *   - It's portable.
icculus@2
    19
 *   - It's safe. No file access is permitted outside the specified dirs.
icculus@1
    20
 *   - It's flexible. Archives (.ZIP files) can be used transparently as
icculus@1
    21
 *      directory structures.
icculus@1
    22
 *
icculus@6
    23
 * With PhysicsFS, you have a single writing directory and multiple
icculus@6
    24
 *  directories (the "search path") for reading. You can think of this as a
icculus@6
    25
 *  filesystem within a filesystem. If (on Windows) you were to set the
icculus@6
    26
 *  writing directory to "C:\MyGame\MyWritingDirectory", then no PHYSFS calls
icculus@6
    27
 *  could touch anything above this directory, including the "C:\MyGame" and
icculus@6
    28
 *  "C:\" directories. This prevents an application's internal scripting
icculus@625
    29
 *  language from piddling over c:\\config.sys, for example. If you'd rather
icculus@6
    30
 *  give PHYSFS full access to the system's REAL file system, set the writing
icculus@6
    31
 *  dir to "C:\", but that's generally A Bad Thing for several reasons.
icculus@1
    32
 *
icculus@1
    33
 * Drive letters are hidden in PhysicsFS once you set up your initial paths.
icculus@6
    34
 *  The search path creates a single, hierarchical directory structure.
icculus@1
    35
 *  Not only does this lend itself well to general abstraction with archives,
icculus@1
    36
 *  it also gives better support to operating systems like MacOS and Unix.
icculus@1
    37
 *  Generally speaking, you shouldn't ever hardcode a drive letter; not only
icculus@1
    38
 *  does this hurt portability to non-Microsoft OSes, but it limits your win32
icculus@1
    39
 *  users to a single drive, too. Use the PhysicsFS abstraction functions and
icculus@1
    40
 *  allow user-defined configuration options, too. When opening a file, you
icculus@1
    41
 *  specify it like it was on a Unix filesystem: if you want to write to
icculus@6
    42
 *  "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to
icculus@1
    43
 *  "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
icculus@2
    44
 *  abstraction across all platforms. Specifying a file in this way is termed
icculus@6
    45
 *  "platform-independent notation" in this documentation. Specifying a
icculus@6
    46
 *  a filename in a form such as "C:\mydir\myfile" or
icculus@6
    47
 *  "MacOS hard drive:My Directory:My File" is termed "platform-dependent
icculus@6
    48
 *  notation". The only time you use platform-dependent notation is when
icculus@6
    49
 *  setting up your write directory and search path; after that, all file
icculus@6
    50
 *  access into those directories are done with platform-independent notation.
icculus@1
    51
 *
icculus@6
    52
 * All files opened for writing are opened in relation to the write directory,
icculus@1
    53
 *  which is the root of the writable filesystem. When opening a file for
icculus@6
    54
 *  reading, PhysicsFS goes through the search path. This is NOT the
icculus@1
    55
 *  same thing as the PATH environment variable. An application using
icculus@1
    56
 *  PhysicsFS specifies directories to be searched which may be actual
icculus@1
    57
 *  directories, or archive files that contain files and subdirectories of
icculus@1
    58
 *  their own. See the end of these docs for currently supported archive
icculus@1
    59
 *  formats.
icculus@1
    60
 *
icculus@6
    61
 * Once the search path is defined, you may open files for reading. If you've
icculus@1
    62
 *  got the following search path defined (to use a win32 example again):
icculus@1
    63
 *
icculus@625
    64
 *  - C:\\mygame
icculus@625
    65
 *  - C:\\mygame\\myuserfiles
icculus@625
    66
 *  - D:\\mygamescdromdatafiles
icculus@625
    67
 *  - C:\\mygame\\installeddatafiles.zip
icculus@1
    68
 *
icculus@6
    69
 * Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory
icculus@2
    70
 *  separator, lack of drive letter, and lack of dir separator at the start of
icculus@2
    71
 *  the string; this is platform-independent notation) will check for
icculus@625
    72
 *  C:\\mygame\\textfiles\\myfile.txt, then
icculus@625
    73
 *  C:\\mygame\\myuserfiles\\textfiles\\myfile.txt, then
icculus@625
    74
 *  D:\\mygamescdromdatafiles\\textfiles\\myfile.txt, then, finally, for
icculus@625
    75
 *  textfiles\\myfile.txt inside of C:\\mygame\\installeddatafiles.zip.
icculus@625
    76
 *  Remember that most archive types and platform filesystems store their
icculus@625
    77
 *  filenames in a case-sensitive manner, so you should be careful to specify
icculus@625
    78
 *  it correctly.
icculus@1
    79
 *
icculus@6
    80
 * Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir
icculus@679
    81
 *  elements. Not only are these meaningless on MacOS Classic and/or Unix,
icculus@679
    82
 *  they are a security hole. Also, symbolic links (which can be found in
icculus@679
    83
 *  some archive types and directly in the filesystem on Unix platforms) are
icculus@679
    84
 *  NOT followed until you call PHYSFS_permitSymbolicLinks(). That's left to
icculus@679
    85
 *  your own discretion, as following a symlink can allow for access outside
icculus@679
    86
 *  the write dir and search paths. For portability, there is no mechanism for
icculus@679
    87
 *  creating new symlinks in PhysicsFS.
icculus@1
    88
 *
icculus@6
    89
 * The write dir is not included in the search path unless you specifically
icculus@6
    90
 *  add it. While you CAN change the write dir as many times as you like,
icculus@6
    91
 *  you should probably set it once and stick to it. Remember that your
icculus@6
    92
 *  program will not have permission to write in every directory on Unix and
icculus@6
    93
 *  NT systems.
icculus@1
    94
 *
icculus@1
    95
 * All files are opened in binary mode; there is no endline conversion for
icculus@1
    96
 *  textfiles. Other than that, PhysicsFS has some convenience functions for
icculus@3
    97
 *  platform-independence. There is a function to tell you the current
icculus@6
    98
 *  platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),
icculus@3
    99
 *  which is needed only to set up your search/write paths. There is a
icculus@3
   100
 *  function to tell you what CD-ROM drives contain accessible discs, and a
icculus@3
   101
 *  function to recommend a good search path, etc.
icculus@1
   102
 *
icculus@6
   103
 * A recommended order for the search path is the write dir, then the base dir,
icculus@6
   104
 *  then the cdrom dir, then any archives discovered. Quake 3 does something
icculus@3
   105
 *  like this, but moves the archives to the start of the search path. Build
icculus@3
   106
 *  Engine games, like Duke Nukem 3D and Blood, place the archives last, and
icculus@6
   107
 *  use the base dir for both searching and writing. There is a helper
icculus@6
   108
 *  function (PHYSFS_setSaneConfig()) that puts together a basic configuration
icculus@3
   109
 *  for you, based on a few parameters. Also see the comments on
icculus@1242
   110
 *  PHYSFS_getBaseDir(), and PHYSFS_getPrefDir() for info on what those
icculus@6
   111
 *  are and how they can help you determine an optimal search path.
icculus@6
   112
 *
icculus@679
   113
 * PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points
icculus@679
   114
 *  in the search path. If a zipfile contains "maps/level.map" and you mount
icculus@679
   115
 *  that archive at "mods/mymod", then you would have to open
icculus@679
   116
 *  "mods/mymod/maps/level.map" to access the file, even though "mods/mymod"
icculus@679
   117
 *  isn't actually specified in the .zip file. Unlike the Unix mentality of
icculus@679
   118
 *  mounting a filesystem, "mods/mymod" doesn't actually have to exist when
icculus@679
   119
 *  mounting the zipfile. It's a "virtual" directory. The mounting mechanism
icculus@679
   120
 *  allows the developer to seperate archives in the tree and avoid trampling
icculus@679
   121
 *  over files when added new archives, such as including mod support in a
icculus@679
   122
 *  game...keeping external content on a tight leash in this manner can be of
icculus@679
   123
 *  utmost importance to some applications.
icculus@679
   124
 *
icculus@1562
   125
 * PhysicsFS is mostly thread safe. The errors returned by
icculus@1562
   126
 *  PHYSFS_getLastErrorCode() are unique by thread, and library-state-setting
icculus@147
   127
 *  functions are mutex'd. For efficiency, individual file accesses are 
icculus@147
   128
 *  not locked, so you can not safely read/write/seek/close/etc the same 
icculus@147
   129
 *  file from two threads at the same time. Other race conditions are bugs 
icculus@147
   130
 *  that should be reported/patched.
icculus@1
   131
 *
icculus@3
   132
 * While you CAN use stdio/syscall file access in a program that has PHYSFS_*
icculus@1562
   133
 *  calls, doing so is not recommended, and you can not directly use system
icculus@1562
   134
 *  filehandles with PhysicsFS and vice versa (but as of PhysicsFS 2.1, you
icculus@1562
   135
 *  can wrap them in a PHYSFS_Io interface yourself if you wanted to).
icculus@1
   136
 *
icculus@1
   137
 * Note that archives need not be named as such: if you have a ZIP file and
icculus@3
   138
 *  rename it with a .PKG extension, the file will still be recognized as a
icculus@1
   139
 *  ZIP archive by PhysicsFS; the file's contents are used to determine its
icculus@679
   140
 *  type where possible.
icculus@1
   141
 *
icculus@1
   142
 * Currently supported archive types:
icculus@1
   143
 *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)
icculus@1069
   144
 *   - .7Z  (7zip archives)
icculus@1069
   145
 *   - .ISO (ISO9660 files, CD-ROM images)
icculus@265
   146
 *   - .GRP (Build Engine groupfile archives)
icculus@559
   147
 *   - .PAK (Quake I/II archive format)
icculus@553
   148
 *   - .HOG (Descent I/II HOG file archives)
icculus@553
   149
 *   - .MVL (Descent II movielib archives)
icculus@609
   150
 *   - .WAD (DOOM engine archives)
bertolaccinifrancesco@1391
   151
 *   - .VDF (Gothic I/II engine archives)
icculus@1610
   152
 *   - .SLB (Independence War archives)
icculus@785
   153
 *
icculus@785
   154
 * String policy for PhysicsFS 2.0 and later:
icculus@785
   155
 *
icculus@807
   156
 * PhysicsFS 1.0 could only deal with null-terminated ASCII strings. All high
icculus@807
   157
 *  ASCII chars resulted in undefined behaviour, and there was no Unicode
icculus@807
   158
 *  support at all. PhysicsFS 2.0 supports Unicode without breaking binary
icculus@807
   159
 *  compatibility with the 1.0 API by using UTF-8 encoding of all strings
icculus@807
   160
 *  passed in and out of the library.
icculus@785
   161
 *
icculus@785
   162
 * All strings passed through PhysicsFS are in null-terminated UTF-8 format.
icculus@785
   163
 *  This means that if all you care about is English (ASCII characters <= 127)
icculus@785
   164
 *  then you just use regular C strings. If you care about Unicode (and you
icculus@785
   165
 *  should!) then you need to figure out what your platform wants, needs, and
icculus@1094
   166
 *  offers. If you are on Windows before Win2000 and build with Unicode
icculus@1094
   167
 *  support, your TCHAR strings are two bytes per character (this is called
icculus@1094
   168
 *  "UCS-2 encoding"). Any modern Windows uses UTF-16, which is two bytes
icculus@1094
   169
 *  per character for most characters, but some characters are four. You
icculus@785
   170
 *  should convert them to UTF-8 before handing them to PhysicsFS with
icculus@1209
   171
 *  PHYSFS_utf8FromUtf16(), which handles both UTF-16 and UCS-2. If you're
icculus@1209
   172
 *  using Unix or Mac OS X, your wchar_t strings are four bytes per character
icculus@1593
   173
 *  ("UCS-4 encoding", sometimes called "UTF-32"). Use PHYSFS_utf8FromUcs4().
icculus@1593
   174
 *  Mac OS X can give you UTF-8 directly from a CFString or NSString, and many
icculus@1593
   175
 *  Unixes generally give you C strings in UTF-8 format everywhere. If you
icculus@1593
   176
 *  have a single-byte high ASCII charset, like so-many European "codepages"
icculus@1593
   177
 *  you may be out of luck. We'll convert from "Latin1" to UTF-8 only, and
icculus@1593
   178
 *  never back to Latin1. If you're above ASCII 127, all bets are off: move
icculus@1593
   179
 *  to Unicode or use your platform's facilities. Passing a C string with
icculus@1593
   180
 *  high-ASCII data that isn't UTF-8 encoded will NOT do what you expect!
icculus@1094
   181
 *
icculus@1094
   182
 * Naturally, there's also PHYSFS_utf8ToUcs2(), PHYSFS_utf8ToUtf16(), and
icculus@1094
   183
 *  PHYSFS_utf8ToUcs4() to get data back into a format you like. Behind the
icculus@1094
   184
 *  scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on
icculus@1094
   185
 *  Windows will be converted and used with the multibyte Windows APIs, for
icculus@1094
   186
 *  example.
icculus@785
   187
 *
icculus@785
   188
 * PhysicsFS offers basic encoding conversion support, but not a whole string
icculus@785
   189
 *  library. Get your stuff into whatever format you can work with.
icculus@785
   190
 *
icculus@1395
   191
 * Most platforms supported by PhysicsFS 2.1 and later fully support Unicode.
icculus@1395
   192
 *  Some older platforms have been dropped (Windows 95, Mac OS 9). Some, like
icculus@1395
   193
 *  OS/2, might be able to convert to a local codepage or will just fail to
icculus@1395
   194
 *  open/create the file. Modern OSes (macOS, Linux, Windows, etc) should all
icculus@1395
   195
 *  be fine.
icculus@1197
   196
 *
icculus@1197
   197
 * Many game-specific archivers are seriously unprepared for Unicode (the
icculus@807
   198
 *  Descent HOG/MVL and Build Engine GRP archivers, for example, only offer a
icculus@807
   199
 *  DOS 8.3 filename, for example). Nothing can be done for these, but they
icculus@807
   200
 *  tend to be legacy formats for existing content that was all ASCII (and
icculus@807
   201
 *  thus, valid UTF-8) anyhow. Other formats, like .ZIP, don't explicitly
icculus@807
   202
 *  offer Unicode support, but unofficially expect filenames to be UTF-8
icculus@807
   203
 *  encoded, and thus Just Work. Most everything does the right thing without
icculus@807
   204
 *  bothering you, but it's good to be aware of these nuances in case they
icculus@807
   205
 *  don't.
icculus@807
   206
 *
icculus@785
   207
 *
icculus@785
   208
 * Other stuff:
icculus@785
   209
 *
icculus@1272
   210
 * Please see the file LICENSE.txt in the source's root directory for
icculus@1209
   211
 *  licensing and redistribution rights.
icculus@1209
   212
 *
icculus@1209
   213
 * Please see the file CREDITS.txt in the source's "docs" directory for
icculus@1209
   214
 *  a more or less complete list of who's responsible for this.
icculus@265
   215
 *
icculus@265
   216
 *  \author Ryan C. Gordon.
icculus@1
   217
 */
icculus@1
   218
icculus@1
   219
#ifndef _INCLUDE_PHYSFS_H_
icculus@1
   220
#define _INCLUDE_PHYSFS_H_
icculus@1
   221
icculus@1
   222
#ifdef __cplusplus
icculus@1
   223
extern "C" {
icculus@1
   224
#endif
icculus@1
   225
icculus@1024
   226
#if defined(PHYSFS_DECL)
icculus@1024
   227
/* do nothing. */
icculus@1024
   228
#elif (defined _MSC_VER)
icculus@1024
   229
#define PHYSFS_DECL __declspec(dllexport)
icculus@991
   230
#elif (defined __SUNPRO_C)
icculus@1024
   231
#define PHYSFS_DECL __global
icculus@994
   232
#elif ((__GNUC__ >= 3) && (!__EMX__) && (!sun))
icculus@1024
   233
#define PHYSFS_DECL __attribute__((visibility("default")))
icculus@74
   234
#else
icculus@1024
   235
#define PHYSFS_DECL
icculus@74
   236
#endif
icculus@74
   237
icculus@1099
   238
#if defined(PHYSFS_DEPRECATED)
icculus@1099
   239
/* do nothing. */
icculus@1099
   240
#elif (__GNUC__ >= 4)  /* technically, this arrived in gcc 3.1, but oh well. */
icculus@1099
   241
#define PHYSFS_DEPRECATED __attribute__((deprecated))
icculus@1099
   242
#else
icculus@1099
   243
#define PHYSFS_DEPRECATED
icculus@1099
   244
#endif
icculus@1099
   245
icculus@1025
   246
#if 0  /* !!! FIXME: look into this later. */
icculus@1025
   247
#if defined(PHYSFS_CALL)
icculus@1025
   248
/* do nothing. */
icculus@1025
   249
#elif defined(__WIN32__) && !defined(__GNUC__)
icculus@1025
   250
#define PHYSFS_CALL __cdecl
icculus@1395
   251
#elif defined(__OS2__) || defined(OS2) /* should work across all compilers. */
icculus@1395
   252
#define PHYSFS_CALL _System
icculus@1025
   253
#else
icculus@1025
   254
#define PHYSFS_CALL
icculus@1025
   255
#endif
icculus@1025
   256
#endif
icculus@1025
   257
icculus@265
   258
/**
icculus@265
   259
 * \typedef PHYSFS_uint8
icculus@265
   260
 * \brief An unsigned, 8-bit integer type.
icculus@265
   261
 */
icculus@132
   262
typedef unsigned char         PHYSFS_uint8;
icculus@265
   263
icculus@265
   264
/**
icculus@265
   265
 * \typedef PHYSFS_sint8
icculus@265
   266
 * \brief A signed, 8-bit integer type.
icculus@265
   267
 */
icculus@132
   268
typedef signed char           PHYSFS_sint8;
icculus@265
   269
icculus@265
   270
/**
icculus@265
   271
 * \typedef PHYSFS_uint16
icculus@265
   272
 * \brief An unsigned, 16-bit integer type.
icculus@265
   273
 */
icculus@132
   274
typedef unsigned short        PHYSFS_uint16;
icculus@265
   275
icculus@265
   276
/**
icculus@265
   277
 * \typedef PHYSFS_sint16
icculus@265
   278
 * \brief A signed, 16-bit integer type.
icculus@265
   279
 */
icculus@132
   280
typedef signed short          PHYSFS_sint16;
icculus@265
   281
icculus@265
   282
/**
icculus@265
   283
 * \typedef PHYSFS_uint32
icculus@265
   284
 * \brief An unsigned, 32-bit integer type.
icculus@265
   285
 */
icculus@132
   286
typedef unsigned int          PHYSFS_uint32;
icculus@265
   287
icculus@265
   288
/**
icculus@265
   289
 * \typedef PHYSFS_sint32
icculus@265
   290
 * \brief A signed, 32-bit integer type.
icculus@265
   291
 */
icculus@132
   292
typedef signed int            PHYSFS_sint32;
icculus@132
   293
icculus@265
   294
/**
icculus@265
   295
 * \typedef PHYSFS_uint64
icculus@265
   296
 * \brief An unsigned, 64-bit integer type.
icculus@265
   297
 * \warning on platforms without any sort of 64-bit datatype, this is
icculus@265
   298
 *           equivalent to PHYSFS_uint32!
icculus@265
   299
 */
icculus@265
   300
icculus@265
   301
/**
icculus@265
   302
 * \typedef PHYSFS_sint64
icculus@265
   303
 * \brief A signed, 64-bit integer type.
icculus@265
   304
 * \warning on platforms without any sort of 64-bit datatype, this is
icculus@265
   305
 *           equivalent to PHYSFS_sint32!
icculus@265
   306
 */
icculus@265
   307
icculus@265
   308
icculus@194
   309
#if (defined PHYSFS_NO_64BIT_SUPPORT)  /* oh well. */
icculus@132
   310
typedef PHYSFS_uint32         PHYSFS_uint64;
icculus@132
   311
typedef PHYSFS_sint32         PHYSFS_sint64;
icculus@194
   312
#elif (defined _MSC_VER)
icculus@194
   313
typedef signed __int64        PHYSFS_sint64;
icculus@194
   314
typedef unsigned __int64      PHYSFS_uint64;
icculus@132
   315
#else
icculus@132
   316
typedef unsigned long long    PHYSFS_uint64;
icculus@132
   317
typedef signed long long      PHYSFS_sint64;
icculus@132
   318
#endif
icculus@132
   319
icculus@265
   320
icculus@265
   321
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
icculus@132
   322
/* Make sure the types really have the right sizes */
icculus@1542
   323
#define PHYSFS_COMPILE_TIME_ASSERT(name, x) \
icculus@1542
   324
       typedef int PHYSFS_compile_time_assert_##name[(x) * 2 - 1]
icculus@132
   325
icculus@1542
   326
PHYSFS_COMPILE_TIME_ASSERT(uint8IsOneByte, sizeof(PHYSFS_uint8) == 1);
icculus@1542
   327
PHYSFS_COMPILE_TIME_ASSERT(sint8IsOneByte, sizeof(PHYSFS_sint8) == 1);
icculus@1542
   328
PHYSFS_COMPILE_TIME_ASSERT(uint16IsTwoBytes, sizeof(PHYSFS_uint16) == 2);
icculus@1542
   329
PHYSFS_COMPILE_TIME_ASSERT(sint16IsTwoBytes, sizeof(PHYSFS_sint16) == 2);
icculus@1542
   330
PHYSFS_COMPILE_TIME_ASSERT(uint32IsFourBytes, sizeof(PHYSFS_uint32) == 4);
icculus@1542
   331
PHYSFS_COMPILE_TIME_ASSERT(sint32IsFourBytes, sizeof(PHYSFS_sint32) == 4);
icculus@132
   332
icculus@132
   333
#ifndef PHYSFS_NO_64BIT_SUPPORT
icculus@1542
   334
PHYSFS_COMPILE_TIME_ASSERT(uint64IsEightBytes, sizeof(PHYSFS_uint64) == 8);
icculus@1542
   335
PHYSFS_COMPILE_TIME_ASSERT(sint64IsEightBytes, sizeof(PHYSFS_sint64) == 8);
icculus@132
   336
#endif
icculus@132
   337
icculus@132
   338
#undef PHYSFS_COMPILE_TIME_ASSERT
icculus@132
   339
icculus@265
   340
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
icculus@132
   341
icculus@132
   342
icculus@265
   343
/**
icculus@654
   344
 * \struct PHYSFS_File
icculus@265
   345
 * \brief A PhysicsFS file handle.
icculus@265
   346
 *
icculus@265
   347
 * You get a pointer to one of these when you open a file for reading,
icculus@265
   348
 *  writing, or appending via PhysicsFS.
icculus@265
   349
 *
icculus@265
   350
 * As you can see from the lack of meaningful fields, you should treat this
icculus@265
   351
 *  as opaque data. Don't try to manipulate the file handle, just pass the
icculus@265
   352
 *  pointer you got, unmolested, to various PhysicsFS APIs.
icculus@265
   353
 *
icculus@265
   354
 * \sa PHYSFS_openRead
icculus@265
   355
 * \sa PHYSFS_openWrite
icculus@265
   356
 * \sa PHYSFS_openAppend
icculus@265
   357
 * \sa PHYSFS_close
icculus@265
   358
 * \sa PHYSFS_read
icculus@265
   359
 * \sa PHYSFS_write
icculus@265
   360
 * \sa PHYSFS_seek
icculus@265
   361
 * \sa PHYSFS_tell
icculus@265
   362
 * \sa PHYSFS_eof
icculus@508
   363
 * \sa PHYSFS_setBuffer
icculus@508
   364
 * \sa PHYSFS_flush
icculus@265
   365
 */
icculus@943
   366
typedef struct PHYSFS_File
icculus@3
   367
{
icculus@265
   368
    void *opaque;  /**< That's all you get. Don't touch. */
icculus@654
   369
} PHYSFS_File;
icculus@3
   370
icculus@830
   371
icculus@830
   372
/**
icculus@830
   373
 * \def PHYSFS_file
icculus@830
   374
 * \brief 1.0 API compatibility define.
icculus@830
   375
 *
icculus@830
   376
 * PHYSFS_file is identical to PHYSFS_File. This #define is here for backwards
icculus@830
   377
 *  compatibility with the 1.0 API, which had an inconsistent capitalization
icculus@830
   378
 *  convention in this case. New code should use PHYSFS_File, as this #define
icculus@830
   379
 *  may go away someday.
icculus@830
   380
 *
icculus@830
   381
 * \sa PHYSFS_File
icculus@830
   382
 */
icculus@830
   383
#define PHYSFS_file PHYSFS_File
icculus@265
   384
icculus@265
   385
icculus@265
   386
/**
icculus@265
   387
 * \struct PHYSFS_ArchiveInfo
icculus@265
   388
 * \brief Information on various PhysicsFS-supported archives.
icculus@265
   389
 *
icculus@265
   390
 * This structure gives you details on what sort of archives are supported
icculus@265
   391
 *  by this implementation of PhysicsFS. Archives tend to be things like
icculus@265
   392
 *  ZIP files and such.
icculus@265
   393
 *
icculus@265
   394
 * \warning Not all binaries are created equal! PhysicsFS can be built with
icculus@265
   395
 *          or without support for various archives. You can check with
icculus@265
   396
 *          PHYSFS_supportedArchiveTypes() to see if your archive type is
icculus@265
   397
 *          supported.
icculus@265
   398
 *
icculus@265
   399
 * \sa PHYSFS_supportedArchiveTypes
icculus@1322
   400
 * \sa PHYSFS_registerArchiver
icculus@1322
   401
 * \sa PHYSFS_deregisterArchiver
icculus@265
   402
 */
icculus@943
   403
typedef struct PHYSFS_ArchiveInfo
icculus@3
   404
{
icculus@265
   405
    const char *extension;   /**< Archive file extension: "ZIP", for example. */
icculus@265
   406
    const char *description; /**< Human-readable archive description. */
icculus@265
   407
    const char *author;      /**< Person who did support for this archive. */
icculus@265
   408
    const char *url;         /**< URL related to this archive */
icculus@1326
   409
    int supportsSymlinks;    /**< non-zero if archive offers symbolic links. */
icculus@3
   410
} PHYSFS_ArchiveInfo;
icculus@3
   411
icculus@508
   412
icculus@265
   413
/**
icculus@265
   414
 * \struct PHYSFS_Version
icculus@265
   415
 * \brief Information the version of PhysicsFS in use.
icculus@265
   416
 *
icculus@265
   417
 * Represents the library's version as three levels: major revision
icculus@265
   418
 *  (increments with massive changes, additions, and enhancements),
icculus@265
   419
 *  minor revision (increments with backwards-compatible changes to the
icculus@265
   420
 *  major revision), and patchlevel (increments with fixes to the minor
icculus@265
   421
 *  revision).
icculus@265
   422
 *
icculus@265
   423
 * \sa PHYSFS_VERSION
icculus@779
   424
 * \sa PHYSFS_getLinkedVersion
icculus@265
   425
 */
icculus@943
   426
typedef struct PHYSFS_Version
icculus@6
   427
{
icculus@265
   428
    PHYSFS_uint8 major; /**< major revision */
icculus@265
   429
    PHYSFS_uint8 minor; /**< minor revision */
icculus@265
   430
    PHYSFS_uint8 patch; /**< patchlevel */
icculus@6
   431
} PHYSFS_Version;
icculus@6
   432
icculus@1026
   433
icculus@265
   434
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
icculus@1613
   435
#define PHYSFS_VER_MAJOR 3
icculus@1613
   436
#define PHYSFS_VER_MINOR 0
icculus@1613
   437
#define PHYSFS_VER_PATCH 0
icculus@265
   438
#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
icculus@6
   439
icculus@508
   440
icculus@508
   441
/* PhysicsFS state stuff ... */
icculus@508
   442
icculus@6
   443
/**
icculus@265
   444
 * \def PHYSFS_VERSION(x)
icculus@265
   445
 * \brief Macro to determine PhysicsFS version program was compiled against.
icculus@265
   446
 *
icculus@265
   447
 * This macro fills in a PHYSFS_Version structure with the version of the
icculus@265
   448
 *  library you compiled against. This is determined by what header the
icculus@265
   449
 *  compiler uses. Note that if you dynamically linked the library, you might
icculus@265
   450
 *  have a slightly newer or older version at runtime. That version can be
icculus@265
   451
 *  determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,
icculus@265
   452
 *  is not a macro.
icculus@265
   453
 *
icculus@265
   454
 * \param x A pointer to a PHYSFS_Version struct to initialize.
icculus@265
   455
 *
icculus@265
   456
 * \sa PHYSFS_Version
icculus@265
   457
 * \sa PHYSFS_getLinkedVersion
icculus@265
   458
 */
icculus@265
   459
#define PHYSFS_VERSION(x) \
icculus@265
   460
{ \
icculus@265
   461
    (x)->major = PHYSFS_VER_MAJOR; \
icculus@265
   462
    (x)->minor = PHYSFS_VER_MINOR; \
icculus@265
   463
    (x)->patch = PHYSFS_VER_PATCH; \
icculus@265
   464
}
icculus@265
   465
icculus@265
   466
icculus@265
   467
/**
icculus@265
   468
 * \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)
icculus@265
   469
 * \brief Get the version of PhysicsFS that is linked against your program.
icculus@265
   470
 *
icculus@265
   471
 * If you are using a shared library (DLL) version of PhysFS, then it is
icculus@265
   472
 *  possible that it will be different than the version you compiled against.
icculus@6
   473
 *
icculus@6
   474
 * This is a real function; the macro PHYSFS_VERSION tells you what version
icculus@6
   475
 *  of PhysFS you compiled against:
icculus@6
   476
 *
icculus@265
   477
 * \code
icculus@6
   478
 * PHYSFS_Version compiled;
icculus@6
   479
 * PHYSFS_Version linked;
icculus@6
   480
 *
icculus@6
   481
 * PHYSFS_VERSION(&compiled);
icculus@6
   482
 * PHYSFS_getLinkedVersion(&linked);
icculus@6
   483
 * printf("We compiled against PhysFS version %d.%d.%d ...\n",
icculus@6
   484
 *           compiled.major, compiled.minor, compiled.patch);
icculus@6
   485
 * printf("But we linked against PhysFS version %d.%d.%d.\n",
icculus@6
   486
 *           linked.major, linked.minor, linked.patch);
icculus@265
   487
 * \endcode
icculus@6
   488
 *
icculus@6
   489
 * This function may be called safely at any time, even before PHYSFS_init().
icculus@265
   490
 *
icculus@265
   491
 * \sa PHYSFS_VERSION
icculus@6
   492
 */
icculus@1024
   493
PHYSFS_DECL void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
icculus@6
   494
icculus@6
   495
icculus@2
   496
/**
icculus@265
   497
 * \fn int PHYSFS_init(const char *argv0)
icculus@265
   498
 * \brief Initialize the PhysicsFS library.
icculus@265
   499
 *
icculus@265
   500
 * This must be called before any other PhysicsFS function.
icculus@2
   501
 *
icculus@23
   502
 * This should be called prior to any attempts to change your process's
icculus@23
   503
 *  current working directory.
icculus@23
   504
 *
icculus@265
   505
 *   \param argv0 the argv[0] string passed to your program's mainline.
icculus@265
   506
 *          This may be NULL on most platforms (such as ones without a
icculus@265
   507
 *          standard main() function), but you should always try to pass
icculus@265
   508
 *          something in here. Unix-like systems such as Linux _need_ to
icculus@265
   509
 *          pass argv[0] from main() in here.
icculus@265
   510
 *  \return nonzero on success, zero on error. Specifics of the error can be
icculus@2
   511
 *          gleaned from PHYSFS_getLastError().
icculus@265
   512
 *
icculus@265
   513
 * \sa PHYSFS_deinit
icculus@876
   514
 * \sa PHYSFS_isInit
icculus@2
   515
 */
icculus@1024
   516
PHYSFS_DECL int PHYSFS_init(const char *argv0);
icculus@2
   517
icculus@2
   518
icculus@2
   519
/**
icculus@265
   520
 * \fn int PHYSFS_deinit(void)
icculus@265
   521
 * \brief Deinitialize the PhysicsFS library.
icculus@265
   522
 *
icculus@265
   523
 * This closes any files opened via PhysicsFS, blanks the search/write paths,
icculus@265
   524
 *  frees memory, and invalidates all of your file handles.
icculus@2
   525
 *
icculus@15
   526
 * Note that this call can FAIL if there's a file open for writing that
icculus@15
   527
 *  refuses to close (for example, the underlying operating system was
icculus@15
   528
 *  buffering writes to network filesystem, and the fileserver has crashed,
icculus@15
   529
 *  or a hard drive has failed, etc). It is usually best to close all write
icculus@15
   530
 *  handles yourself before calling this function, so that you can gracefully
icculus@15
   531
 *  handle a specific failure.
icculus@2
   532
 *
icculus@15
   533
 * Once successfully deinitialized, PHYSFS_init() can be called again to
icculus@897
   534
 *  restart the subsystem. All default API states are restored at this
icculus@897
   535
 *  point, with the exception of any custom allocator you might have
icculus@897
   536
 *  specified, which survives between initializations.
icculus@6
   537
 *
icculus@265
   538
 *  \return nonzero on success, zero on error. Specifics of the error can be
icculus@2
   539
 *          gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
icculus@2
   540
 *          undefined, and probably badly screwed up.
icculus@265
   541
 *
icculus@265
   542
 * \sa PHYSFS_init
icculus@876
   543
 * \sa PHYSFS_isInit
icculus@2
   544
 */
icculus@1024
   545
PHYSFS_DECL int PHYSFS_deinit(void);
icculus@2
   546
icculus@1
   547
icculus@1
   548
/**
icculus@265
   549
 * \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)
icculus@265
   550
 * \brief Get a list of supported archive types.
icculus@265
   551
 *
icculus@3
   552
 * Get a list of archive types supported by this implementation of PhysicFS.
icculus@3
   553
 *  These are the file formats usable for search path entries. This is for
icculus@3
   554
 *  informational purposes only. Note that the extension listed is merely
icculus@3
   555
 *  convention: if we list "ZIP", you can open a PkZip-compatible archive
icculus@3
   556
 *  with an extension of "XYZ", if you like.
icculus@3
   557
 *
icculus@6
   558
 * The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
icculus@6
   559
 *  with a NULL entry to signify the end of the list:
icculus@3
   560
 *
icculus@265
   561
 * \code
icculus@3
   562
 * PHYSFS_ArchiveInfo **i;
icculus@3
   563
 *
icculus@3
   564
 * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
icculus@3
   565
 * {
icculus@3
   566
 *     printf("Supported archive: [%s], which is [%s].\n",
icculus@944
   567
 *              (*i)->extension, (*i)->description);
icculus@3
   568
 * }
icculus@265
   569
 * \endcode
icculus@3
   570
 *
icculus@1277
   571
 * The return values are pointers to internal memory, and should
icculus@1277
   572
 *  be considered READ ONLY, and never freed. The returned values are
icculus@1322
   573
 *  valid until the next call to PHYSFS_deinit(), PHYSFS_registerArchiver(),
icculus@1322
   574
 *  or PHYSFS_deregisterArchiver().
icculus@3
   575
 *
icculus@265
   576
 *   \return READ ONLY Null-terminated array of READ ONLY structures.
icculus@1322
   577
 *
icculus@1322
   578
 * \sa PHYSFS_registerArchiver
icculus@1322
   579
 * \sa PHYSFS_deregisterArchiver
icculus@3
   580
 */
icculus@1024
   581
PHYSFS_DECL const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
icculus@3
   582
icculus@3
   583
icculus@3
   584
/**
icculus@265
   585
 * \fn void PHYSFS_freeList(void *listVar)
icculus@265
   586
 * \brief Deallocate resources of lists returned by PhysicsFS.
icculus@265
   587
 *
icculus@3
   588
 * Certain PhysicsFS functions return lists of information that are
icculus@3
   589
 *  dynamically allocated. Use this function to free those resources.
icculus@3
   590
 *
icculus@975
   591
 * It is safe to pass a NULL here, but doing so will cause a crash in versions
icculus@975
   592
 *  before PhysicsFS 2.1.0.
icculus@975
   593
 *
icculus@265
   594
 *   \param listVar List of information specified as freeable by this function.
icculus@975
   595
 *                  Passing NULL is safe; it is a valid no-op.
icculus@265
   596
 *
icculus@265
   597
 * \sa PHYSFS_getCdRomDirs
icculus@265
   598
 * \sa PHYSFS_enumerateFiles
icculus@265
   599
 * \sa PHYSFS_getSearchPath
icculus@3
   600
 */
icculus@1024
   601
PHYSFS_DECL void PHYSFS_freeList(void *listVar);
icculus@3
   602
icculus@3
   603
icculus@3
   604
/**
icculus@265
   605
 * \fn const char *PHYSFS_getLastError(void)
icculus@265
   606
 * \brief Get human-readable error information.
icculus@265
   607
 *
icculus@1560
   608
 * \deprecated Use PHYSFS_getLastErrorCode() and PHYSFS_getErrorByCode() instead.
icculus@1560
   609
 *
icculus@1240
   610
 * \warning As of PhysicsFS 2.1, this function has been nerfed.
icculus@1240
   611
 *          Before PhysicsFS 2.1, this function was the only way to get
icculus@1240
   612
 *          error details beyond a given function's basic return value.
icculus@1240
   613
 *          This was meant to be a human-readable string in one of several
icculus@1240
   614
 *          languages, and was not useful for application parsing. This was
icculus@1240
   615
 *          a problem, because the developer and not the user chose the
icculus@1240
   616
 *          language at compile time, and the PhysicsFS maintainers had
icculus@1240
   617
 *          to (poorly) maintain a significant amount of localization work.
icculus@1240
   618
 *          The app couldn't parse the strings, even if they counted on a
icculus@1240
   619
 *          specific language, since some were dynamically generated.
icculus@1240
   620
 *          In 2.1 and later, this always returns a static string in
icculus@1240
   621
 *          English; you may use it as a key string for your own
icculus@1240
   622
 *          localizations if you like, as we'll promise not to change
icculus@1240
   623
 *          existing error strings. Also, if your application wants to
icculus@1240
   624
 *          look at specific errors, we now offer a better option:
icculus@1240
   625
 *          use PHYSFS_getLastErrorCode() instead.
icculus@1240
   626
 *
icculus@687
   627
 * Get the last PhysicsFS error message as a human-readable, null-terminated
icculus@1240
   628
 *  string. This will return NULL if there's been no error since the last call
icculus@1240
   629
 *  to this function. The pointer returned by this call points to an internal
icculus@687
   630
 *  buffer. Each thread has a unique error state associated with it, but each
icculus@687
   631
 *  time a new error message is set, it will overwrite the previous one
icculus@687
   632
 *  associated with that thread. It is safe to call this function at anytime,
icculus@687
   633
 *  even before PHYSFS_init().
icculus@687
   634
 *
icculus@1240
   635
 * PHYSFS_getLastError() and PHYSFS_getLastErrorCode() both reset the same
icculus@1240
   636
 *  thread-specific error state. Calling one will wipe out the other's
icculus@1240
   637
 *  data. If you need both, call PHYSFS_getLastErrorCode(), then pass that
icculus@1240
   638
 *  value to PHYSFS_getErrorByCode().
icculus@1240
   639
 *
icculus@1240
   640
 * As of PhysicsFS 2.1, this function only presents text in the English
icculus@1240
   641
 *  language, but the strings are static, so you can use them as keys into
icculus@1240
   642
 *  your own localization dictionary. These strings are meant to be passed on
icculus@1240
   643
 *  directly to the user.
icculus@1240
   644
 *
icculus@1240
   645
 * Generally, applications should only concern themselves with whether a
icculus@1240
   646
 *  given function failed; however, if your code require more specifics, you
icculus@1240
   647
 *  should use PHYSFS_getLastErrorCode() instead of this function.
icculus@1
   648
 *
icculus@265
   649
 *   \return READ ONLY string of last error message.
icculus@1240
   650
 *
icculus@1240
   651
 * \sa PHYSFS_getLastErrorCode
icculus@1240
   652
 * \sa PHYSFS_getErrorByCode
icculus@1
   653
 */
icculus@1560
   654
PHYSFS_DECL const char *PHYSFS_getLastError(void) PHYSFS_DEPRECATED;
icculus@1
   655
icculus@1
   656
icculus@1
   657
/**
icculus@265
   658
 * \fn const char *PHYSFS_getDirSeparator(void)
icculus@265
   659
 * \brief Get platform-dependent dir separator string.
icculus@1
   660
 *
icculus@882
   661
 * This returns "\\" on win32, "/" on Unix, and ":" on MacOS. It may be more
icculus@265
   662
 *  than one character, depending on the platform, and your code should take
icculus@265
   663
 *  that into account. Note that this is only useful for setting up the
icculus@265
   664
 *  search/write paths, since access into those dirs always use '/'
icculus@265
   665
 *  (platform-independent notation) to separate directories. This is also
icculus@265
   666
 *  handy for getting platform-independent access when using stdio calls.
icculus@265
   667
 *
icculus@265
   668
 *   \return READ ONLY null-terminated string of platform's dir separator.
icculus@1
   669
 */
icculus@1024
   670
PHYSFS_DECL const char *PHYSFS_getDirSeparator(void);
icculus@1
   671
icculus@1
   672
icculus@1
   673
/**
icculus@265
   674
 * \fn void PHYSFS_permitSymbolicLinks(int allow)
icculus@265
   675
 * \brief Enable or disable following of symbolic links.
icculus@265
   676
 *
icculus@265
   677
 * Some physical filesystems and archives contain files that are just pointers
icculus@265
   678
 *  to other files. On the physical filesystem, opening such a link will
icculus@265
   679
 *  (transparently) open the file that is pointed to.
icculus@15
   680
 *
icculus@15
   681
 * By default, PhysicsFS will check if a file is really a symlink during open
icculus@15
   682
 *  calls and fail if it is. Otherwise, the link could take you outside the
icculus@15
   683
 *  write and search paths, and compromise security.
icculus@15
   684
 *
icculus@15
   685
 * If you want to take that risk, call this function with a non-zero parameter.
icculus@15
   686
 *  Note that this is more for sandboxing a program's scripting language, in
icculus@15
   687
 *  case untrusted scripts try to compromise the system. Generally speaking,
icculus@15
   688
 *  a user could very well have a legitimate reason to set up a symlink, so
icculus@15
   689
 *  unless you feel there's a specific danger in allowing them, you should
icculus@15
   690
 *  permit them.
icculus@15
   691
 *
icculus@39
   692
 * Symlinks are only explicitly checked when dealing with filenames
icculus@39
   693
 *  in platform-independent notation. That is, when setting up your
icculus@39
   694
 *  search and write paths, etc, symlinks are never checked for.
icculus@39
   695
 *
icculus@1125
   696
 * Please note that PHYSFS_stat() will always check the path specified; if
icculus@1125
   697
 *  that path is a symlink, it will not be followed in any case. If symlinks
icculus@1125
   698
 *  aren't permitted through this function, PHYSFS_stat() ignores them, and
icculus@1125
   699
 *  would treat the query as if the path didn't exist at all.
icculus@1125
   700
 *
icculus@265
   701
 * Symbolic link permission can be enabled or disabled at any time after
icculus@265
   702
 *  you've called PHYSFS_init(), and is disabled by default.
icculus@15
   703
 *
icculus@265
   704
 *   \param allow nonzero to permit symlinks, zero to deny linking.
icculus@877
   705
 *
icculus@877
   706
 * \sa PHYSFS_symbolicLinksPermitted
icculus@15
   707
 */
icculus@1024
   708
PHYSFS_DECL void PHYSFS_permitSymbolicLinks(int allow);
icculus@15
   709
icculus@15
   710
icculus@15
   711
/**
icculus@265
   712
 * \fn char **PHYSFS_getCdRomDirs(void)
icculus@265
   713
 * \brief Get an array of paths to available CD-ROM drives.
icculus@1
   714
 *
icculus@6
   715
 * The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
icculus@6
   716
 *  whatnot on Unix). Dirs are only returned if there is a disc ready and
icculus@1
   717
 *  accessible in the drive. So if you've got two drives (D: and E:), and only
icculus@1
   718
 *  E: has a disc in it, then that's all you get. If the user inserts a disc
icculus@1
   719
 *  in D: and you call this function again, you get both drives. If, on a
icculus@1
   720
 *  Unix box, the user unmounts a disc and remounts it elsewhere, the next
icculus@881
   721
 *  call to this function will reflect that change.
icculus@881
   722
 *
icculus@881
   723
 * This function refers to "CD-ROM" media, but it really means "inserted disc
icculus@881
   724
 *  media," such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs. It looks for
icculus@881
   725
 *  filesystems, and as such won't report an audio CD, unless there's a
icculus@881
   726
 *  mounted filesystem track on it.
icculus@1
   727
 *
icculus@1
   728
 * The returned value is an array of strings, with a NULL entry to signify the
icculus@1
   729
 *  end of the list:
icculus@1
   730
 *
icculus@265
   731
 * \code
icculus@8
   732
 * char **cds = PHYSFS_getCdRomDirs();
icculus@1
   733
 * char **i;
icculus@1
   734
 *
icculus@8
   735
 * for (i = cds; *i != NULL; i++)
icculus@6
   736
 *     printf("cdrom dir [%s] is available.\n", *i);
icculus@1
   737
 *
icculus@8
   738
 * PHYSFS_freeList(cds);
icculus@265
   739
 * \endcode
icculus@8
   740
 *
icculus@1
   741
 * This call may block while drives spin up. Be forewarned.
icculus@1
   742
 *
icculus@3
   743
 * When you are done with the returned information, you may dispose of the
icculus@3
   744
 *  resources by calling PHYSFS_freeList() with the returned pointer.
icculus@3
   745
 *
icculus@265
   746
 *   \return Null-terminated array of null-terminated strings.
icculus@687
   747
 *
icculus@687
   748
 * \sa PHYSFS_getCdRomDirsCallback
icculus@1
   749
 */
icculus@1024
   750
PHYSFS_DECL char **PHYSFS_getCdRomDirs(void);
icculus@1
   751
icculus@1
   752
icculus@1
   753
/**
icculus@265
   754
 * \fn const char *PHYSFS_getBaseDir(void)
icculus@265
   755
 * \brief Get the path where the application resides.
icculus@265
   756
 *
icculus@1
   757
 * Helper function.
icculus@1
   758
 *
icculus@6
   759
 * Get the "base dir". This is the directory where the application was run
icculus@3
   760
 *  from, which is probably the installation directory, and may or may not
icculus@3
   761
 *  be the process's current working directory.
icculus@1
   762
 *
icculus@6
   763
 * You should probably use the base dir in your search path.
icculus@1
   764
 *
icculus@265
   765
 *  \return READ ONLY string of base dir in platform-dependent notation.
icculus@265
   766
 *
icculus@1242
   767
 * \sa PHYSFS_getPrefDir
icculus@1
   768
 */
icculus@1024
   769
PHYSFS_DECL const char *PHYSFS_getBaseDir(void);
icculus@1
   770
icculus@1
   771
icculus@1
   772
/**
icculus@265
   773
 * \fn const char *PHYSFS_getUserDir(void)
icculus@265
   774
 * \brief Get the path where user's home directory resides.
icculus@265
   775
 *
icculus@1242
   776
 * \deprecated As of PhysicsFS 2.1, you probably want PHYSFS_getPrefDir().
icculus@1242
   777
 *
icculus@1
   778
 * Helper function.
icculus@1
   779
 *
icculus@6
   780
 * Get the "user dir". This is meant to be a suggestion of where a specific
icculus@1
   781
 *  user of the system can store files. On Unix, this is her home directory.
icculus@3
   782
 *  On systems with no concept of multiple home directories (MacOS, win95),
icculus@6
   783
 *  this will default to something like "C:\mybasedir\users\username"
icculus@3
   784
 *  where "username" will either be the login name, or "default" if the
icculus@3
   785
 *  platform doesn't support multiple users, either.
icculus@1
   786
 *
icculus@265
   787
 *  \return READ ONLY string of user dir in platform-dependent notation.
icculus@265
   788
 *
icculus@265
   789
 * \sa PHYSFS_getBaseDir
icculus@1242
   790
 * \sa PHYSFS_getPrefDir
icculus@1
   791
 */
icculus@1242
   792
PHYSFS_DECL const char *PHYSFS_getUserDir(void) PHYSFS_DEPRECATED;
icculus@1
   793
icculus@1
   794
icculus@1
   795
/**
icculus@265
   796
 * \fn const char *PHYSFS_getWriteDir(void)
icculus@265
   797
 * \brief Get path where PhysicsFS will allow file writing.
icculus@265
   798
 *
icculus@6
   799
 * Get the current write dir. The default write dir is NULL.
icculus@1
   800
 *
icculus@265
   801
 *  \return READ ONLY string of write dir in platform-dependent notation,
icculus@1
   802
 *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.
icculus@265
   803
 *
icculus@265
   804
 * \sa PHYSFS_setWriteDir
icculus@1
   805
 */
icculus@1024
   806
PHYSFS_DECL const char *PHYSFS_getWriteDir(void);
icculus@1
   807
icculus@1
   808
icculus@1
   809
/**
icculus@265
   810
 * \fn int PHYSFS_setWriteDir(const char *newDir)
icculus@265
   811
 * \brief Tell PhysicsFS where it may write files.
icculus@265
   812
 *
icculus@762
   813
 * Set a new write dir. This will override the previous setting.
icculus@1
   814
 *
icculus@6
   815
 * This call will fail (and fail to change the write dir) if the current
icculus@6
   816
 *  write dir still has files open in it.
icculus@1
   817
 *
icculus@265
   818
 *   \param newDir The new directory to be the root of the write dir,
icculus@3
   819
 *                   specified in platform-dependent notation. Setting to NULL
icculus@6
   820
 *                   disables the write dir, so no files can be opened for
icculus@1
   821
 *                   writing via PhysicsFS.
icculus@265
   822
 *  \return non-zero on success, zero on failure. All attempts to open a file
icculus@1
   823
 *           for writing via PhysicsFS will fail until this call succeeds.
icculus@1562
   824
 *           Use PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@1
   825
 *
icculus@265
   826
 * \sa PHYSFS_getWriteDir
icculus@1
   827
 */
icculus@1024
   828
PHYSFS_DECL int PHYSFS_setWriteDir(const char *newDir);
icculus@1
   829
icculus@1
   830
icculus@1
   831
/**
icculus@679
   832
 * \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
icculus@679
   833
 * \brief Add an archive or directory to the search path.
icculus@265
   834
 *
icculus@1110
   835
 * \deprecated As of PhysicsFS 2.0, use PHYSFS_mount() instead. This
icculus@1110
   836
 *             function just wraps it anyhow.
icculus@1110
   837
 *
icculus@1110
   838
 * This function is equivalent to:
icculus@1110
   839
 *
icculus@1110
   840
 * \code
icculus@1110
   841
 *  PHYSFS_mount(newDir, NULL, appendToPath);
icculus@1110
   842
 * \endcode
icculus@679
   843
 *
icculus@687
   844
 * You must use this and not PHYSFS_mount if binary compatibility with
icculus@687
   845
 *  PhysicsFS 1.0 is important (which it may not be for many people).
icculus@687
   846
 *
icculus@679
   847
 * \sa PHYSFS_mount
icculus@265
   848
 * \sa PHYSFS_removeFromSearchPath
icculus@265
   849
 * \sa PHYSFS_getSearchPath
icculus@1
   850
 */
icculus@1110
   851
PHYSFS_DECL int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
icculus@1110
   852
                                        PHYSFS_DEPRECATED;
icculus@1
   853
icculus@1
   854
/**
icculus@265
   855
 * \fn int PHYSFS_removeFromSearchPath(const char *oldDir)
icculus@265
   856
 * \brief Remove a directory or archive from the search path.
icculus@1
   857
 *
icculus@1110
   858
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_unmount() instead. This
icculus@1110
   859
 *             function just wraps it anyhow. There's no functional difference
icculus@1110
   860
 *             except the vocabulary changed from "adding to the search path"
icculus@1110
   861
 *             to "mounting" when that functionality was extended, and thus
icculus@1110
   862
 *             the preferred way to accomplish this function's work is now
icculus@1110
   863
 *             called "unmounting."
icculus@1110
   864
 *
icculus@1110
   865
 * This function is equivalent to:
icculus@1110
   866
 *
icculus@1110
   867
 * \code
icculus@1110
   868
 *  PHYSFS_unmount(oldDir);
icculus@1110
   869
 * \endcode
icculus@1110
   870
 *
icculus@1110
   871
 * You must use this and not PHYSFS_unmount if binary compatibility with
icculus@1110
   872
 *  PhysicsFS 1.0 is important (which it may not be for many people).
icculus@265
   873
 *
icculus@265
   874
 * \sa PHYSFS_addToSearchPath
icculus@265
   875
 * \sa PHYSFS_getSearchPath
icculus@1110
   876
 * \sa PHYSFS_unmount
icculus@1
   877
 */
icculus@1110
   878
PHYSFS_DECL int PHYSFS_removeFromSearchPath(const char *oldDir)
icculus@1110
   879
                                            PHYSFS_DEPRECATED;
icculus@1
   880
icculus@1
   881
icculus@1
   882
/**
icculus@265
   883
 * \fn char **PHYSFS_getSearchPath(void)
icculus@265
   884
 * \brief Get the current search path.
icculus@265
   885
 *
icculus@265
   886
 * The default search path is an empty list.
icculus@1
   887
 *
icculus@1
   888
 * The returned value is an array of strings, with a NULL entry to signify the
icculus@1
   889
 *  end of the list:
icculus@1
   890
 *
icculus@265
   891
 * \code
icculus@1
   892
 * char **i;
icculus@1
   893
 *
icculus@1
   894
 * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
icculus@1
   895
 *     printf("[%s] is in the search path.\n", *i);
icculus@265
   896
 * \endcode
icculus@1
   897
 *
icculus@3
   898
 * When you are done with the returned information, you may dispose of the
icculus@3
   899
 *  resources by calling PHYSFS_freeList() with the returned pointer.
icculus@1
   900
 *
icculus@265
   901
 *   \return Null-terminated array of null-terminated strings. NULL if there
icculus@6
   902
 *            was a problem (read: OUT OF MEMORY).
icculus@265
   903
 *
icculus@687
   904
 * \sa PHYSFS_getSearchPathCallback
icculus@265
   905
 * \sa PHYSFS_addToSearchPath
icculus@265
   906
 * \sa PHYSFS_removeFromSearchPath
icculus@1
   907
 */
icculus@1024
   908
PHYSFS_DECL char **PHYSFS_getSearchPath(void);
icculus@1
   909
icculus@1
   910
icculus@1
   911
/**
icculus@265
   912
 * \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)
icculus@265
   913
 * \brief Set up sane, default paths.
icculus@265
   914
 *
icculus@1
   915
 * Helper function.
icculus@1
   916
 *
icculus@1274
   917
 * The write dir will be set to the pref dir returned by
icculus@1274
   918
 *  \code PHYSFS_getPrefDir(organization, appName) \endcode, which is
icculus@265
   919
 *  created if it doesn't exist.
icculus@1
   920
 *
icculus@1
   921
 * The above is sufficient to make sure your program's configuration directory
icculus@1274
   922
 *  is separated from other clutter, and platform-independent.
icculus@1
   923
 *
icculus@1
   924
 *  The search path will be:
icculus@1
   925
 *
icculus@6
   926
 *    - The Write Dir (created if it doesn't exist)
icculus@6
   927
 *    - The Base Dir (PHYSFS_getBaseDir())
icculus@6
   928
 *    - All found CD-ROM dirs (optionally)
icculus@1
   929
 *
icculus@1
   930
 * These directories are then searched for files ending with the extension
icculus@1
   931
 *  (archiveExt), which, if they are valid and supported archives, will also
icculus@1
   932
 *  be added to the search path. If you specified "PKG" for (archiveExt), and
icculus@1
   933
 *  there's a file named data.PKG in the base dir, it'll be checked. Archives
icculus@1
   934
 *  can either be appended or prepended to the search path in alphabetical
icculus@1274
   935
 *  order, regardless of which directories they were found in. All archives
icculus@1274
   936
 *  are mounted in the root of the virtual file system ("/").
icculus@1
   937
 *
icculus@1
   938
 * All of this can be accomplished from the application, but this just does it
icculus@2
   939
 *  all for you. Feel free to add more to the search path manually, too.
icculus@1
   940
 *
icculus@265
   941
 *    \param organization Name of your company/group/etc to be used as a
icculus@101
   942
 *                         dirname, so keep it small, and no-frills.
icculus@101
   943
 *
icculus@265
   944
 *    \param appName Program-specific name of your program, to separate it
icculus@1
   945
 *                   from other programs using PhysicsFS.
icculus@1
   946
 *
icculus@397
   947
 *    \param archiveExt File extension used by your program to specify an
icculus@1
   948
 *                      archive. For example, Quake 3 uses "pk3", even though
icculus@1
   949
 *                      they are just zipfiles. Specify NULL to not dig out
icculus@8
   950
 *                      archives automatically. Do not specify the '.' char;
icculus@8
   951
 *                      If you want to look for ZIP files, specify "ZIP" and
icculus@8
   952
 *                      not ".ZIP" ... the archive search is case-insensitive.
icculus@1
   953
 *
icculus@265
   954
 *    \param includeCdRoms Non-zero to include CD-ROMs in the search path, and
icculus@2
   955
 *                         (if (archiveExt) != NULL) search them for archives.
icculus@2
   956
 *                         This may cause a significant amount of blocking
icculus@2
   957
 *                         while discs are accessed, and if there are no discs
icculus@2
   958
 *                         in the drive (or even not mounted on Unix systems),
icculus@2
   959
 *                         then they may not be made available anyhow. You may
icculus@2
   960
 *                         want to specify zero and handle the disc setup
icculus@2
   961
 *                         yourself.
icculus@1
   962
 *
icculus@265
   963
 *    \param archivesFirst Non-zero to prepend the archives to the search path.
icculus@1560
   964
 *                         Zero to append them. Ignored if !(archiveExt).
icculus@101
   965
 *
icculus@1562
   966
 *  \return nonzero on success, zero on error. Use PHYSFS_getLastErrorCode()
icculus@1562
   967
 *          to obtain the specific error.
icculus@1
   968
 */
icculus@1024
   969
PHYSFS_DECL int PHYSFS_setSaneConfig(const char *organization,
icculus@1024
   970
                                     const char *appName,
icculus@1024
   971
                                     const char *archiveExt,
icculus@1024
   972
                                     int includeCdRoms,
icculus@1024
   973
                                     int archivesFirst);
icculus@1
   974
icculus@1
   975
icculus@508
   976
/* Directory management stuff ... */
icculus@508
   977
icculus@1
   978
/**
icculus@265
   979
 * \fn int PHYSFS_mkdir(const char *dirName)
icculus@265
   980
 * \brief Create a directory.
icculus@265
   981
 *
icculus@265
   982
 * This is specified in platform-independent notation in relation to the
icculus@265
   983
 *  write dir. All missing parent directories are also created if they
icculus@265
   984
 *  don't exist.
icculus@1
   985
 *
icculus@6
   986
 * So if you've got the write dir set to "C:\mygame\writedir" and call
icculus@1
   987
 *  PHYSFS_mkdir("downloads/maps") then the directories
icculus@6
   988
 *  "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
icculus@3
   989
 *  will be created if possible. If the creation of "maps" fails after we
icculus@3
   990
 *  have successfully created "downloads", then the function leaves the
icculus@3
   991
 *  created directory behind and reports failure.
icculus@1
   992
 *
icculus@265
   993
 *   \param dirName New dir to create.
icculus@1562
   994
 *  \return nonzero on success, zero on error. Use
icculus@1562
   995
 *          PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@265
   996
 *
icculus@265
   997
 * \sa PHYSFS_delete
icculus@1
   998
 */
icculus@1024
   999
PHYSFS_DECL int PHYSFS_mkdir(const char *dirName);
icculus@1
  1000
icculus@1
  1001
icculus@1
  1002
/**
icculus@265
  1003
 * \fn int PHYSFS_delete(const char *filename)
icculus@265
  1004
 * \brief Delete a file or directory.
icculus@265
  1005
 *
icculus@265
  1006
 * (filename) is specified in platform-independent notation in relation to the
icculus@265
  1007
 *  write dir.
icculus@1
  1008
 *
icculus@3
  1009
 * A directory must be empty before this call can delete it.
icculus@1
  1010
 *
icculus@137
  1011
 * Deleting a symlink will remove the link, not what it points to, regardless
icculus@137
  1012
 *  of whether you "permitSymLinks" or not.
icculus@137
  1013
 *
icculus@6
  1014
 * So if you've got the write dir set to "C:\mygame\writedir" and call
icculus@1
  1015
 *  PHYSFS_delete("downloads/maps/level1.map") then the file
icculus@6
  1016
 *  "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
icculus@1
  1017
 *  physical filesystem, if it exists and the operating system permits the
icculus@1
  1018
 *  deletion.
icculus@1
  1019
 *
icculus@2
  1020
 * Note that on Unix systems, deleting a file may be successful, but the
icculus@2
  1021
 *  actual file won't be removed until all processes that have an open
icculus@2
  1022
 *  filehandle to it (including your program) close their handles.
icculus@2
  1023
 *
icculus@137
  1024
 * Chances are, the bits that make up the file still exist, they are just
icculus@137
  1025
 *  made available to be written over at a later point. Don't consider this
icculus@137
  1026
 *  a security method or anything.  :)
icculus@137
  1027
 *
icculus@265
  1028
 *   \param filename Filename to delete.
icculus@1562
  1029
 *  \return nonzero on success, zero on error. Use PHYSFS_getLastErrorCode()
icculus@1562
  1030
 *          to obtain the specific error.
icculus@1
  1031
 */
icculus@1024
  1032
PHYSFS_DECL int PHYSFS_delete(const char *filename);
icculus@1
  1033
icculus@1
  1034
icculus@1
  1035
/**
icculus@265
  1036
 * \fn const char *PHYSFS_getRealDir(const char *filename)
icculus@265
  1037
 * \brief Figure out where in the search path a file resides.
icculus@265
  1038
 *
icculus@265
  1039
 * The file is specified in platform-independent notation. The returned
icculus@265
  1040
 *  filename will be the element of the search path where the file was found,
icculus@265
  1041
 *  which may be a directory, or an archive. Even if there are multiple
icculus@265
  1042
 *  matches in different parts of the search path, only the first one found
icculus@265
  1043
 *  is used, just like when opening a file.
icculus@1
  1044
 *
icculus@625
  1045
 * So, if you look for "maps/level1.map", and C:\\mygame is in your search
icculus@625
  1046
 *  path and C:\\mygame\\maps\\level1.map exists, then "C:\mygame" is returned.
icculus@1
  1047
 *
icculus@15
  1048
 * If a any part of a match is a symbolic link, and you've not explicitly
icculus@15
  1049
 *  permitted symlinks, then it will be ignored, and the search for a match
icculus@15
  1050
 *  will continue.
icculus@2
  1051
 *
icculus@687
  1052
 * If you specify a fake directory that only exists as a mount point, it'll
icculus@687
  1053
 *  be associated with the first archive mounted there, even though that
icculus@687
  1054
 *  directory isn't necessarily contained in a real archive.
icculus@687
  1055
 *
icculus@1122
  1056
 * \warning This will return NULL if there is no real directory associated
icculus@1122
  1057
 *          with (filename). Specifically, PHYSFS_mountIo(),
icculus@1122
  1058
 *          PHYSFS_mountMemory(), and PHYSFS_mountHandle() will return NULL
icculus@1122
  1059
 *          even if the filename is found in the search path. Plan accordingly.
icculus@1122
  1060
 *
icculus@265
  1061
 *     \param filename file to look for.
icculus@265
  1062
 *    \return READ ONLY string of element of search path containing the
icculus@3
  1063
 *             the file in question. NULL if not found.
icculus@1
  1064
 */
icculus@1024
  1065
PHYSFS_DECL const char *PHYSFS_getRealDir(const char *filename);
icculus@3
  1066
icculus@3
  1067
icculus@3
  1068
/**
icculus@265
  1069
 * \fn char **PHYSFS_enumerateFiles(const char *dir)
icculus@265
  1070
 * \brief Get a file listing of a search path's directory.
icculus@3
  1071
 *
icculus@1559
  1072
 * \warning In PhysicsFS versions prior to 2.1, this function would return
icculus@1559
  1073
 *          as many items as it could in the face of a failure condition
icculus@1559
  1074
 *          (out of memory, disk i/o error, etc). Since this meant apps
icculus@1559
  1075
 *          couldn't distinguish between complete success and partial failure,
icculus@1559
  1076
 *          and since the function could always return NULL to report
icculus@1559
  1077
 *          catastrophic failures anyway, in PhysicsFS 2.1 this function's
icculus@1559
  1078
 *          policy changed: it will either return a list of complete results
icculus@1559
  1079
 *          or it will return NULL for any failure of any kind, so we can
icculus@1559
  1080
 *          guarantee that the enumeration ran to completion and has no gaps
icculus@1559
  1081
 *          in its results.
icculus@1559
  1082
 *
icculus@265
  1083
 * Matching directories are interpolated. That is, if "C:\mydir" is in the
icculus@265
  1084
 *  search path and contains a directory "savegames" that contains "x.sav",
icculus@265
  1085
 *  "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path
icculus@265
  1086
 *  that has a "savegames" subdirectory with "w.sav", then the following code:
icculus@265
  1087
 *
icculus@265
  1088
 * \code
icculus@3
  1089
 * char **rc = PHYSFS_enumerateFiles("savegames");
icculus@3
  1090
 * char **i;
icculus@3
  1091
 *
icculus@3
  1092
 * for (i = rc; *i != NULL; i++)
icculus@265
  1093
 *     printf(" * We've got [%s].\n", *i);
icculus@3
  1094
 *
icculus@3
  1095
 * PHYSFS_freeList(rc);
icculus@265
  1096
 * \endcode
icculus@3
  1097
 *
icculus@1070
  1098
 *  \...will print:
icculus@3
  1099
 *
icculus@265
  1100
 * \verbatim
icculus@3
  1101
 * We've got [x.sav].
icculus@3
  1102
 * We've got [y.sav].
icculus@3
  1103
 * We've got [z.sav].
icculus@265
  1104
 * We've got [w.sav].\endverbatim
icculus@3
  1105
 *
icculus@1350
  1106
 * Feel free to sort the list however you like. However, the returned data
icculus@1350
  1107
 *  will always contain no duplicates, and will be always sorted in alphabetic
icculus@1561
  1108
 *  (rather: case-sensitive Unicode) order for you.
icculus@6
  1109
 *
icculus@3
  1110
 * Don't forget to call PHYSFS_freeList() with the return value from this
icculus@3
  1111
 *  function when you are done with it.
icculus@3
  1112
 *
icculus@265
  1113
 *    \param dir directory in platform-independent notation to enumerate.
icculus@1559
  1114
 *   \return Null-terminated array of null-terminated strings, or NULL for
icculus@1559
  1115
 *           failure cases.
icculus@1559
  1116
 *
icculus@1559
  1117
 * \sa PHYSFS_enumerate
icculus@3
  1118
 */
icculus@1024
  1119
PHYSFS_DECL char **PHYSFS_enumerateFiles(const char *dir);
icculus@1
  1120
icculus@1
  1121
icculus@1
  1122
/**
icculus@265
  1123
 * \fn int PHYSFS_exists(const char *fname)
icculus@265
  1124
 * \brief Determine if a file exists in the search path.
icculus@265
  1125
 *
icculus@265
  1126
 * Reports true if there is an entry anywhere in the search path by the
icculus@15
  1127
 *  name of (fname).
icculus@15
  1128
 *
icculus@15
  1129
 * Note that entries that are symlinks are ignored if
icculus@15
  1130
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
icculus@15
  1131
 *  might end up further down in the search path than expected.
icculus@15
  1132
 *
icculus@265
  1133
 *    \param fname filename in platform-independent notation.
icculus@265
  1134
 *   \return non-zero if filename exists. zero otherwise.
icculus@15
  1135
 */
icculus@1024
  1136
PHYSFS_DECL int PHYSFS_exists(const char *fname);
icculus@15
  1137
icculus@15
  1138
icculus@15
  1139
/**
icculus@265
  1140
 * \fn int PHYSFS_isDirectory(const char *fname)
icculus@265
  1141
 * \brief Determine if a file in the search path is really a directory.
icculus@265
  1142
 *
icculus@1125
  1143
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_stat() instead. This
icculus@1125
  1144
 *             function just wraps it anyhow.
icculus@1125
  1145
 *
icculus@15
  1146
 * Determine if the first occurence of (fname) in the search path is
icculus@15
  1147
 *  really a directory entry.
icculus@15
  1148
 *
icculus@15
  1149
 * Note that entries that are symlinks are ignored if
icculus@15
  1150
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
icculus@15
  1151
 *  might end up further down in the search path than expected.
icculus@15
  1152
 *
icculus@265
  1153
 *    \param fname filename in platform-independent notation.
icculus@265
  1154
 *   \return non-zero if filename exists and is a directory.  zero otherwise.
icculus@265
  1155
 *
icculus@1125
  1156
 * \sa PHYSFS_stat
icculus@265
  1157
 * \sa PHYSFS_exists
icculus@15
  1158
 */
icculus@1125
  1159
PHYSFS_DECL int PHYSFS_isDirectory(const char *fname) PHYSFS_DEPRECATED;
icculus@15
  1160
icculus@15
  1161
icculus@15
  1162
/**
icculus@265
  1163
 * \fn int PHYSFS_isSymbolicLink(const char *fname)
icculus@265
  1164
 * \brief Determine if a file in the search path is really a symbolic link.
icculus@265
  1165
 *
icculus@1125
  1166
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_stat() instead. This
icculus@1125
  1167
 *             function just wraps it anyhow.
icculus@1125
  1168
 *
icculus@15
  1169
 * Determine if the first occurence of (fname) in the search path is
icculus@15
  1170
 *  really a symbolic link.
icculus@15
  1171
 *
icculus@15
  1172
 * Note that entries that are symlinks are ignored if
icculus@15
  1173
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
icculus@15
  1174
 *  this function will always return 0 in that case.
icculus@15
  1175
 *
icculus@265
  1176
 *    \param fname filename in platform-independent notation.
icculus@265
  1177
 *   \return non-zero if filename exists and is a symlink.  zero otherwise.
icculus@265
  1178
 *
icculus@1125
  1179
 * \sa PHYSFS_stat
icculus@265
  1180
 * \sa PHYSFS_exists
icculus@15
  1181
 */
icculus@1125
  1182
PHYSFS_DECL int PHYSFS_isSymbolicLink(const char *fname) PHYSFS_DEPRECATED;
icculus@15
  1183
icculus@15
  1184
icculus@15
  1185
/**
icculus@508
  1186
 * \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
icculus@508
  1187
 * \brief Get the last modification time of a file.
icculus@508
  1188
 *
icculus@1111
  1189
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_stat() instead. This
icculus@1111
  1190
 *             function just wraps it anyhow.
icculus@1111
  1191
 *
icculus@1105
  1192
 * The modtime is returned as a number of seconds since the Unix epoch
icculus@1105
  1193
 *  (midnight, Jan 1, 1970). The exact derivation and accuracy of this time
icculus@1105
  1194
 *  depends on the particular archiver. If there is no reasonable way to
icculus@1105
  1195
 *  obtain this information for a particular archiver, or there was some sort
icculus@1105
  1196
 *  of error, this function returns (-1).
icculus@1105
  1197
 *
icculus@1111
  1198
 * You must use this and not PHYSFS_stat() if binary compatibility with
icculus@1111
  1199
 *  PhysicsFS 2.0 is important (which it may not be for many people).
icculus@508
  1200
 *
icculus@508
  1201
 *   \param filename filename to check, in platform-independent notation.
icculus@1075
  1202
 *  \return last modified time of the file. -1 if it can't be determined.
icculus@1091
  1203
 *
icculus@1105
  1204
 * \sa PHYSFS_stat
icculus@508
  1205
 */
icculus@1105
  1206
PHYSFS_DECL PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
icculus@1105
  1207
                                                PHYSFS_DEPRECATED;
icculus@508
  1208
icculus@508
  1209
icculus@508
  1210
/* i/o stuff... */
icculus@508
  1211
icculus@508
  1212
/**
icculus@654
  1213
 * \fn PHYSFS_File *PHYSFS_openWrite(const char *filename)
icculus@265
  1214
 * \brief Open a file for writing.
icculus@265
  1215
 *
icculus@1
  1216
 * Open a file for writing, in platform-independent notation and in relation
icculus@6
  1217
 *  to the write dir as the root of the writable filesystem. The specified
icculus@1
  1218
 *  file is created if it doesn't exist. If it does exist, it is truncated to
icculus@1
  1219
 *  zero bytes, and the writing offset is set to the start.
icculus@1
  1220
 *
icculus@15
  1221
 * Note that entries that are symlinks are ignored if
icculus@15
  1222
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
icculus@15
  1223
 *  symlink with this function will fail in such a case.
icculus@15
  1224
 *
icculus@265
  1225
 *   \param filename File to open.
icculus@1562
  1226
 *  \return A valid PhysicsFS filehandle on success, NULL on error. Use
icculus@1562
  1227
 *          PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@265
  1228
 *
icculus@265
  1229
 * \sa PHYSFS_openRead
icculus@265
  1230
 * \sa PHYSFS_openAppend
icculus@265
  1231
 * \sa PHYSFS_write
icculus@265
  1232
 * \sa PHYSFS_close
icculus@1
  1233
 */
icculus@1024
  1234
PHYSFS_DECL PHYSFS_File *PHYSFS_openWrite(const char *filename);
icculus@1
  1235
icculus@1
  1236
icculus@1
  1237
/**
icculus@654
  1238
 * \fn PHYSFS_File *PHYSFS_openAppend(const char *filename)
icculus@265
  1239
 * \brief Open a file for appending.
icculus@265
  1240
 *
icculus@1
  1241
 * Open a file for writing, in platform-independent notation and in relation
icculus@6
  1242
 *  to the write dir as the root of the writable filesystem. The specified
icculus@1
  1243
 *  file is created if it doesn't exist. If it does exist, the writing offset
icculus@1
  1244
 *  is set to the end of the file, so the first write will be the byte after
icculus@1
  1245
 *  the end.
icculus@1
  1246
 *
icculus@15
  1247
 * Note that entries that are symlinks are ignored if
icculus@15
  1248
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
icculus@15
  1249
 *  symlink with this function will fail in such a case.
icculus@15
  1250
 *
icculus@265
  1251
 *   \param filename File to open.
icculus@1562
  1252
 *  \return A valid PhysicsFS filehandle on success, NULL on error. Use
icculus@1562
  1253
 *          PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@265
  1254
 *
icculus@265
  1255
 * \sa PHYSFS_openRead
icculus@265
  1256
 * \sa PHYSFS_openWrite
icculus@265
  1257
 * \sa PHYSFS_write
icculus@265
  1258
 * \sa PHYSFS_close
icculus@1
  1259
 */
icculus@1024
  1260
PHYSFS_DECL PHYSFS_File *PHYSFS_openAppend(const char *filename);
icculus@1
  1261
icculus@1
  1262
icculus@1
  1263
/**
icculus@654
  1264
 * \fn PHYSFS_File *PHYSFS_openRead(const char *filename)
icculus@265
  1265
 * \brief Open a file for reading.
icculus@265
  1266
 *
icculus@1
  1267
 * Open a file for reading, in platform-independent notation. The search path
icculus@1
  1268
 *  is checked one at a time until a matching file is found, in which case an
icculus@1
  1269
 *  abstract filehandle is associated with it, and reading may be done.
icculus@1
  1270
 *  The reading offset is set to the first byte of the file.
icculus@1
  1271
 *
icculus@15
  1272
 * Note that entries that are symlinks are ignored if
icculus@15
  1273
 *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
icculus@15
  1274
 *  symlink with this function will fail in such a case.
icculus@15
  1275
 *
icculus@265
  1276
 *   \param filename File to open.
icculus@1562
  1277
 *  \return A valid PhysicsFS filehandle on success, NULL on error.
icculus@1562
  1278
 *          Use PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@265
  1279
 *
icculus@265
  1280
 * \sa PHYSFS_openWrite
icculus@265
  1281
 * \sa PHYSFS_openAppend
icculus@265
  1282
 * \sa PHYSFS_read
icculus@265
  1283
 * \sa PHYSFS_close
icculus@1
  1284
 */
icculus@1024
  1285
PHYSFS_DECL PHYSFS_File *PHYSFS_openRead(const char *filename);
icculus@1
  1286
icculus@1
  1287
icculus@1
  1288
/**
icculus@654
  1289
 * \fn int PHYSFS_close(PHYSFS_File *handle)
icculus@265
  1290
 * \brief Close a PhysicsFS filehandle.
icculus@1
  1291
 *
icculus@265
  1292
 * This call is capable of failing if the operating system was buffering
icculus@265
  1293
 *  writes to the physical media, and, now forced to write those changes to
icculus@265
  1294
 *  physical media, can not store the data for some reason. In such a case,
icculus@265
  1295
 *  the filehandle stays open. A well-written program should ALWAYS check the
icculus@265
  1296
 *  return value from the close call in addition to every writing call!
icculus@265
  1297
 *
icculus@265
  1298
 *   \param handle handle returned from PHYSFS_open*().
icculus@1562
  1299
 *  \return nonzero on success, zero on error. Use PHYSFS_getLastErrorCode()
icculus@1562
  1300
 *          to obtain the specific error.
icculus@265
  1301
 *
icculus@265
  1302
 * \sa PHYSFS_openRead
icculus@265
  1303
 * \sa PHYSFS_openWrite
icculus@265
  1304
 * \sa PHYSFS_openAppend
icculus@1
  1305
 */
icculus@1024
  1306
PHYSFS_DECL int PHYSFS_close(PHYSFS_File *handle);
icculus@1
  1307
icculus@1
  1308
icculus@1
  1309
/**
icculus@654
  1310
 * \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
icculus@265
  1311
 * \brief Read data from a PhysicsFS filehandle
icculus@1
  1312
 *
icculus@265
  1313
 * The file must be opened for reading.
icculus@265
  1314
 *
icculus@1098
  1315
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_readBytes() instead. This
icculus@1098
  1316
 *             function just wraps it anyhow. This function never clarified
icculus@1098
  1317
 *             what would happen if you managed to read a partial object, so
icculus@1098
  1318
 *             working at the byte level makes this cleaner for everyone,
icculus@1118
  1319
 *             especially now that PHYSFS_Io interfaces can be supplied by the
icculus@1098
  1320
 *             application.
icculus@1098
  1321
 *
icculus@265
  1322
 *   \param handle handle returned from PHYSFS_openRead().
icculus@265
  1323
 *   \param buffer buffer to store read data into.
icculus@265
  1324
 *   \param objSize size in bytes of objects being read from (handle).
icculus@265
  1325
 *   \param objCount number of (objSize) objects to read from (handle).
icculus@1562
  1326
 *  \return number of objects read. PHYSFS_getLastErrorCode() can shed light
icculus@1562
  1327
 *          on the reason this might be < (objCount), as can PHYSFS_eof().
icculus@1562
  1328
 *          -1 if complete failure.
icculus@265
  1329
 *
icculus@1098
  1330
 * \sa PHYSFS_readBytes
icculus@265
  1331
 * \sa PHYSFS_eof
icculus@1
  1332
 */
icculus@1024
  1333
PHYSFS_DECL PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle,
icculus@1024
  1334
                                      void *buffer,
icculus@1024
  1335
                                      PHYSFS_uint32 objSize,
icculus@1099
  1336
                                      PHYSFS_uint32 objCount)
icculus@1099
  1337
                                        PHYSFS_DEPRECATED;
icculus@1
  1338
icculus@1
  1339
/**
icculus@654
  1340
 * \fn PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle, const void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
icculus@265
  1341
 * \brief Write data to a PhysicsFS filehandle
icculus@1
  1342
 *
icculus@265
  1343
 * The file must be opened for writing.
icculus@265
  1344
 *
icculus@1098
  1345
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_writeBytes() instead. This
icculus@1098
  1346
 *             function just wraps it anyhow. This function never clarified
icculus@1098
  1347
 *             what would happen if you managed to write a partial object, so
icculus@1098
  1348
 *             working at the byte level makes this cleaner for everyone,
icculus@1118
  1349
 *             especially now that PHYSFS_Io interfaces can be supplied by the
icculus@1098
  1350
 *             application.
icculus@1098
  1351
 *
icculus@265
  1352
 *   \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
icculus@1086
  1353
 *   \param buffer buffer of bytes to write to (handle).
icculus@1086
  1354
 *   \param objSize size in bytes of objects being written to (handle).
icculus@1086
  1355
 *   \param objCount number of (objSize) objects to write to (handle).
icculus@1562
  1356
 *  \return number of objects written. PHYSFS_getLastErrorCode() can shed
icculus@1562
  1357
 *          light on the reason this might be < (objCount). -1 if complete
icculus@1562
  1358
 *          failure.
icculus@1098
  1359
 *
icculus@1098
  1360
 * \sa PHYSFS_writeBytes
icculus@1
  1361
 */
icculus@1024
  1362
PHYSFS_DECL PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle,
icculus@1024
  1363
                                       const void *buffer,
icculus@1024
  1364
                                       PHYSFS_uint32 objSize,
icculus@1099
  1365
                                       PHYSFS_uint32 objCount)
icculus@1099
  1366
                                        PHYSFS_DEPRECATED;
icculus@1
  1367
icculus@508
  1368
icculus@508
  1369
/* File position stuff... */
icculus@508
  1370
icculus@1
  1371
/**
icculus@654
  1372
 * \fn int PHYSFS_eof(PHYSFS_File *handle)
icculus@265
  1373
 * \brief Check for end-of-file state on a PhysicsFS filehandle.
icculus@265
  1374
 *
icculus@1
  1375
 * Determine if the end of file has been reached in a PhysicsFS filehandle.
icculus@1
  1376
 *
icculus@265
  1377
 *   \param handle handle returned from PHYSFS_openRead().
icculus@265
  1378
 *  \return nonzero if EOF, zero if not.
icculus@265
  1379
 *
icculus@265
  1380
 * \sa PHYSFS_read
icculus@265
  1381
 * \sa PHYSFS_tell
icculus@1
  1382
 */
icculus@1024
  1383
PHYSFS_DECL int PHYSFS_eof(PHYSFS_File *handle);
icculus@1
  1384
icculus@1
  1385
icculus@1
  1386
/**
icculus@654
  1387
 * \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle)
icculus@265
  1388
 * \brief Determine current position within a PhysicsFS filehandle.
icculus@1
  1389
 *
icculus@265
  1390
 *   \param handle handle returned from PHYSFS_open*().
icculus@1075
  1391
 *  \return offset in bytes from start of file. -1 if error occurred.
icculus@1562
  1392
 *           Use PHYSFS_getLastErrorCode() to obtain the specific error.
icculus@265
  1393
 *
icculus@265
  1394
 * \sa PHYSFS_seek
icculus@1
  1395
 */
icculus@1024
  1396
PHYSFS_DECL PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle);
icculus@1
  1397
icculus@1
  1398
icculus@1
  1399
/**
icculus@654
  1400
 * \fn int PHYSFS_seek(PHYSFS_File *handle, PHYSFS_uint64 pos)
icculus@265
  1401
 * \brief Seek to a new position within a PhysicsFS filehandle.
icculus@1
  1402
 *
icculus@265
  1403
 * The next read or write will occur at that place. Seeking past the
icculus@265
  1404
 *  beginning or end of the file is not allowed, and causes an error.
icculus@265
  1405
 *
icculus@265
  1406
 *   \param handle handle returned from PHYSFS_open*().
icculus@265
  1407
 *   \param pos number of bytes from start of file to seek to.
icculus@1562
  1408
 *  \return nonzero on success, zero on error. Use PHYSFS_getLastErrorCode()
icculus@1562
  1409
 *          to obtain the specific error.
icculus@265
  1410
 *
icculus@265
  1411
 * \sa PHYSFS_tell
icculus@1
  1412
 */
icculus@1024
  1413
PHYSFS_DECL int PHYSFS_seek(PHYSFS_File *handle, PHYSFS_uint64 pos);
icculus@2
  1414
icculus@28
  1415
icculus@28
  1416
/**
icculus@654
  1417
 * \fn PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle)
icculus@265
  1418
 * \brief Get total length of a file in bytes.
icculus@28
  1419
 *
icculus@1118
  1420
 * Note that if another process/thread is writing to this file at the same
icculus@1118
  1421
 *  time, then the information this function supplies could be incorrect
icculus@1118
  1422
 *  before you get it. Use with caution, or better yet, don't use at all.
icculus@265
  1423
 *
icculus@265
  1424
 *   \param handle handle returned from PHYSFS_open*().
icculus@1075
  1425
 *  \return size in bytes of the file. -1 if can't be determined.
icculus@265
  1426
 *
icculus@265
  1427
 * \sa PHYSFS_tell
icculus@265
  1428
 * \sa PHYSFS_seek
icculus@28
  1429
 */
icculus@1024
  1430
PHYSFS_DECL PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle);
icculus@28
  1431
icculus@178
  1432
icculus@508
  1433
/* Buffering stuff... */
icculus@508
  1434
icculus@508
  1435
/**
icculus@654
  1436
 * \fn int PHYSFS_setBuffer(PHYSFS_File *handle, PHYSFS_uint64 bufsize)
icculus@508
  1437
 * \brief Set up buffering for a PhysicsFS file handle.
icculus@508
  1438
 *
icculus@508
  1439
 * Define an i/o buffer for a file handle. A memory block of (bufsize) bytes
icculus@508
  1440
 *  will be allocated and associated with (handle).
icculus@508
  1441
 *
icculus@508
  1442
 * For files opened for reading, up to (bufsize) bytes are read from (handle)
icculus@508
  1443
 *  and stored in the internal buffer. Calls to PHYSFS_read() will pull
icculus@508
  1444
 *  from this buffer until it is empty, and then refill it for more reading.
icculus@508
  1445
 *  Note that compressed files, like ZIP archives, will decompress while
icculus@508
  1446
 *  buffering, so this can be handy for offsetting CPU-intensive operations.
icculus@508
  1447
 *  The buffer isn't filled until you do your next read.
icculus@508
  1448
 *
icculus@508
  1449
 * For files opened for writing, data will be buffered to memory until the
icculus@508
  1450
 *  buffer is full or the buffer is flushed. Closing a handle implicitly
icculus@508
  1451
 *  causes a flush...check your return values!
icculus@508
  1452
 *
icculus@508
  1453
 * Seeking, etc transparently accounts for buffering.
icculus@508
  1454
 *
icculus@508
  1455
 * You can resize an existing buffer by calling this function more than once
icculus@508
  1456
 *  on the same file. Setting the buffer size to zero will free an existing
icculus@508
  1457
 *  buffer.
icculus@508
  1458
 *
icculus@508
  1459
 * PhysicsFS file handles are unbuffered by default.
icculus@508
  1460
 *
icculus@508
  1461
 * Please check the return value of this function! Failures can include
icculus@508
  1462
 *  not being able to seek backwards in a read-only file when removing the
icculus@508
  1463
 *  buffer, not being able to allocate the buffer, and not being able to
icculus@508
  1464
 *  flush the buffer to disk, among other unexpected problems.
icculus@508
  1465
 *
icculus@508
  1466
 *   \param handle handle returned from PHYSFS_open*().
icculus@508
  1467
 *   \param bufsize size, in bytes, of buffer to allocate.
icculus@508
  1468
 *  \return nonzero if successful, zero on error.
icculus@508
  1469
 *
icculus@508
  1470
 * \sa PHYSFS_flush
icculus@508
  1471
 * \sa PHYSFS_read
icculus@508
  1472
 * \sa PHYSFS_write
icculus@508
  1473
 * \sa PHYSFS_close
icculus@508
  1474
 */
icculus@1024
  1475
PHYSFS_DECL int PHYSFS_setBuffer(PHYSFS_File *handle, PHYSFS_uint64 bufsize);
icculus@508
  1476
icculus@508
  1477
icculus@508
  1478
/**
icculus@654
  1479
 * \fn int PHYSFS_flush(PHYSFS_File *handle)
icculus@508
  1480
 * \brief Flush a buffered PhysicsFS file handle.
icculus@508
  1481
 *
icculus@508
  1482
 * For buffered files opened for writing, this will put the current contents
icculus@508
  1483
 *  of the buffer to disk and flag the buffer as empty if possible.
icculus@508
  1484
 *
icculus@508
  1485
 * For buffered files opened for reading or unbuffered files, this is a safe
icculus@508
  1486
 *  no-op, and will report success.
icculus@508
  1487
 *
icculus@508
  1488
 *   \param handle handle returned from PHYSFS_open*().
icculus@508
  1489
 *  \return nonzero if successful, zero on error.
icculus@508
  1490
 *
icculus@508
  1491
 * \sa PHYSFS_setBuffer
icculus@508
  1492
 * \sa PHYSFS_close
icculus@508
  1493
 */
icculus@1024
  1494
PHYSFS_DECL int PHYSFS_flush(PHYSFS_File *handle);
icculus@508
  1495
icculus@508
  1496
icculus@178
  1497
/* Byteorder stuff... */
icculus@178
  1498
icculus@178
  1499
/**
icculus@265
  1500
 * \fn PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val)
icculus@265
  1501
 * \brief Swap littleendian signed 16 to platform's native byte order.
icculus@265
  1502
 *
icculus@178
  1503
 * Take a 16-bit signed value in littleendian format and convert it to
icculus@178
  1504
 *  the platform's native byte order.
icculus@178
  1505
 *
icculus@265
  1506
 *    \param val value to convert
icculus@265
  1507
 *   \return converted value.
icculus@178
  1508
 */
icculus@1024
  1509
PHYSFS_DECL PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val);
icculus@178
  1510
icculus@178
  1511
icculus@178
  1512
/**
icculus@265
  1513
 * \fn PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val)
icculus@265
  1514
 * \brief Swap littleendian unsigned 16 to platform's native byte order.
icculus@265
  1515
 *
icculus@178
  1516
 * Take a 16-bit unsigned value in littleendian format and convert it to
icculus@178
  1517
 *  the platform's native byte order.
icculus@178
  1518
 *
icculus@265
  1519
 *    \param val value to convert
icculus@265
  1520
 *   \return converted value.
icculus@178
  1521
 */
icculus@1024
  1522
PHYSFS_DECL PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val);
icculus@178
  1523
icculus@178
  1524
/**
icculus@265
  1525
 * \fn PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val)
icculus@265
  1526
 * \brief Swap littleendian signed 32 to platform's native byte order.
icculus@265
  1527
 *
icculus@178
  1528
 * Take a 32-bit signed value in littleendian format and convert it to
icculus@178
  1529
 *  the platform's native byte order.
icculus@178
  1530
 *
icculus@265
  1531
 *    \param val value to convert
icculus@265
  1532
 *   \return converted value.
icculus@178
  1533
 */
icculus@1024
  1534
PHYSFS_DECL PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val);
icculus@178
  1535
icculus@178
  1536
icculus@178
  1537
/**
icculus@265
  1538
 * \fn PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val)
icculus@265
  1539
 * \brief Swap littleendian unsigned 32 to platform's native byte order.
icculus@265
  1540
 *
icculus@178
  1541
 * Take a 32-bit unsigned value in littleendian format and convert it to
icculus@178
  1542
 *  the platform's native byte order.
icculus@178
  1543
 *
icculus@265
  1544
 *    \param val value to convert
icculus@265
  1545
 *   \return converted value.
icculus@178
  1546
 */
icculus@1024
  1547
PHYSFS_DECL PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val);
icculus@178
  1548
icculus@178
  1549
/**
icculus@265
  1550
 * \fn PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val)
icculus@265
  1551
 * \brief Swap littleendian signed 64 to platform's native byte order.
icculus@265
  1552
 *
icculus@178
  1553
 * Take a 64-bit signed value in littleendian format and convert it to
icculus@178
  1554
 *  the platform's native byte order.
icculus@178
  1555
 *
icculus@265
  1556
 *    \param val value to convert
icculus@265
  1557
 *   \return converted value.
icculus@265
  1558
 *
icculus@1378
  1559
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@265
  1560
 *          any sort of 64-bit support.
icculus@178
  1561
 */
icculus@1024
  1562
PHYSFS_DECL PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val);
icculus@178
  1563
icculus@178
  1564
icculus@178
  1565
/**
icculus@265
  1566
 * \fn PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val)
icculus@265
  1567
 * \brief Swap littleendian unsigned 64 to platform's native byte order.
icculus@265
  1568
 *
icculus@178
  1569
 * Take a 64-bit unsigned value in littleendian format and convert it to
icculus@178
  1570
 *  the platform's native byte order.
icculus@178
  1571
 *
icculus@265
  1572
 *    \param val value to convert
icculus@265
  1573
 *   \return converted value.
icculus@265
  1574
 *
icculus@265
  1575
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@265
  1576
 *          any sort of 64-bit support.
icculus@178
  1577
 */
icculus@1024
  1578
PHYSFS_DECL PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val);
icculus@178
  1579
icculus@178
  1580
icculus@178
  1581
/**
icculus@265
  1582
 * \fn PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val)
icculus@265
  1583
 * \brief Swap bigendian signed 16 to platform's native byte order.
icculus@265
  1584
 *
icculus@178
  1585
 * Take a 16-bit signed value in bigendian format and convert it to
icculus@178
  1586
 *  the platform's native byte order.
icculus@178
  1587
 *
icculus@265
  1588
 *    \param val value to convert
icculus@265
  1589
 *   \return converted value.
icculus@178
  1590
 */
icculus@1024
  1591
PHYSFS_DECL PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val);
icculus@178
  1592
icculus@178
  1593
icculus@178
  1594
/**
icculus@265
  1595
 * \fn PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val)
icculus@265
  1596
 * \brief Swap bigendian unsigned 16 to platform's native byte order.
icculus@265
  1597
 *
icculus@178
  1598
 * Take a 16-bit unsigned value in bigendian format and convert it to
icculus@178
  1599
 *  the platform's native byte order.
icculus@178
  1600
 *
icculus@265
  1601
 *    \param val value to convert
icculus@265
  1602
 *   \return converted value.
icculus@178
  1603
 */
icculus@1024
  1604
PHYSFS_DECL PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val);
icculus@178
  1605
icculus@178
  1606
/**
icculus@265
  1607
 * \fn PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val)
icculus@265
  1608
 * \brief Swap bigendian signed 32 to platform's native byte order.
icculus@265
  1609
 *
icculus@178
  1610
 * Take a 32-bit signed value in bigendian format and convert it to
icculus@178
  1611
 *  the platform's native byte order.
icculus@178
  1612
 *
icculus@265
  1613
 *    \param val value to convert
icculus@265
  1614
 *   \return converted value.
icculus@178
  1615
 */
icculus@1024
  1616
PHYSFS_DECL PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val);
icculus@178
  1617
icculus@178
  1618
icculus@178
  1619
/**
icculus@265
  1620
 * \fn PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val)
icculus@265
  1621
 * \brief Swap bigendian unsigned 32 to platform's native byte order.
icculus@265
  1622
 *
icculus@178
  1623
 * Take a 32-bit unsigned value in bigendian format and convert it to
icculus@178
  1624
 *  the platform's native byte order.
icculus@178
  1625
 *
icculus@265
  1626
 *    \param val value to convert
icculus@265
  1627
 *   \return converted value.
icculus@178
  1628
 */
icculus@1024
  1629
PHYSFS_DECL PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val);
icculus@178
  1630
icculus@178
  1631
icculus@178
  1632
/**
icculus@265
  1633
 * \fn PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val)
icculus@265
  1634
 * \brief Swap bigendian signed 64 to platform's native byte order.
icculus@265
  1635
 *
icculus@178
  1636
 * Take a 64-bit signed value in bigendian format and convert it to
icculus@178
  1637
 *  the platform's native byte order.
icculus@178
  1638
 *
icculus@265
  1639
 *    \param val value to convert
icculus@265
  1640
 *   \return converted value.
icculus@265
  1641
 *
icculus@1378
  1642
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@265
  1643
 *          any sort of 64-bit support.
icculus@178
  1644
 */
icculus@1024
  1645
PHYSFS_DECL PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val);
icculus@178
  1646
icculus@178
  1647
icculus@178
  1648
/**
icculus@265
  1649
 * \fn PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val)
icculus@265
  1650
 * \brief Swap bigendian unsigned 64 to platform's native byte order.
icculus@265
  1651
 *
icculus@178
  1652
 * Take a 64-bit unsigned value in bigendian format and convert it to
icculus@178
  1653
 *  the platform's native byte order.
icculus@178
  1654
 *
icculus@265
  1655
 *    \param val value to convert
icculus@265
  1656
 *   \return converted value.
icculus@265
  1657
 *
icculus@265
  1658
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@265
  1659
 *          any sort of 64-bit support.
icculus@178
  1660
 */
icculus@1024
  1661
PHYSFS_DECL PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val);
icculus@178
  1662
icculus@322
  1663
icculus@322
  1664
/**
icculus@654
  1665
 * \fn int PHYSFS_readSLE16(PHYSFS_File *file, PHYSFS_sint16 *val)
icculus@322
  1666
 * \brief Read and convert a signed 16-bit littleendian value.
icculus@322
  1667
 *
icculus@322
  1668
 * Convenience function. Read a signed 16-bit littleendian value from a
icculus@322
  1669
 *  file and convert it to the platform's native byte order.
icculus@322
  1670
 *
icculus@322
  1671
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1672
 *    \param val pointer to where value should be stored.
icculus@322
  1673
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1674
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1675
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1676
 */
icculus@1024
  1677
PHYSFS_DECL int PHYSFS_readSLE16(PHYSFS_File *file, PHYSFS_sint16 *val);
icculus@322
  1678
icculus@322
  1679
icculus@322
  1680
/**
icculus@654
  1681
 * \fn int PHYSFS_readULE16(PHYSFS_File *file, PHYSFS_uint16 *val)
icculus@322
  1682
 * \brief Read and convert an unsigned 16-bit littleendian value.
icculus@322
  1683
 *
icculus@322
  1684
 * Convenience function. Read an unsigned 16-bit littleendian value from a
icculus@322
  1685
 *  file and convert it to the platform's native byte order.
icculus@322
  1686
 *
icculus@322
  1687
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1688
 *    \param val pointer to where value should be stored.
icculus@322
  1689
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1690
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1691
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1692
 *
icculus@322
  1693
 */
icculus@1024
  1694
PHYSFS_DECL int PHYSFS_readULE16(PHYSFS_File *file, PHYSFS_uint16 *val);
icculus@322
  1695
icculus@322
  1696
icculus@322
  1697
/**
icculus@654
  1698
 * \fn int PHYSFS_readSBE16(PHYSFS_File *file, PHYSFS_sint16 *val)
icculus@322
  1699
 * \brief Read and convert a signed 16-bit bigendian value.
icculus@322
  1700
 *
icculus@322
  1701
 * Convenience function. Read a signed 16-bit bigendian value from a
icculus@322
  1702
 *  file and convert it to the platform's native byte order.
icculus@322
  1703
 *
icculus@322
  1704
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1705
 *    \param val pointer to where value should be stored.
icculus@322
  1706
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1707
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1708
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1709
 */
icculus@1024
  1710
PHYSFS_DECL int PHYSFS_readSBE16(PHYSFS_File *file, PHYSFS_sint16 *val);
icculus@322
  1711
icculus@322
  1712
icculus@322
  1713
/**
icculus@654
  1714
 * \fn int PHYSFS_readUBE16(PHYSFS_File *file, PHYSFS_uint16 *val)
icculus@322
  1715
 * \brief Read and convert an unsigned 16-bit bigendian value.
icculus@322
  1716
 *
icculus@322
  1717
 * Convenience function. Read an unsigned 16-bit bigendian value from a
icculus@322
  1718
 *  file and convert it to the platform's native byte order.
icculus@322
  1719
 *
icculus@322
  1720
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1721
 *    \param val pointer to where value should be stored.
icculus@322
  1722
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1723
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1724
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1725
 *
icculus@322
  1726
 */
icculus@1024
  1727
PHYSFS_DECL int PHYSFS_readUBE16(PHYSFS_File *file, PHYSFS_uint16 *val);
icculus@322
  1728
icculus@322
  1729
icculus@322
  1730
/**
icculus@654
  1731
 * \fn int PHYSFS_readSLE32(PHYSFS_File *file, PHYSFS_sint32 *val)
icculus@322
  1732
 * \brief Read and convert a signed 32-bit littleendian value.
icculus@322
  1733
 *
icculus@322
  1734
 * Convenience function. Read a signed 32-bit littleendian value from a
icculus@322
  1735
 *  file and convert it to the platform's native byte order.
icculus@322
  1736
 *
icculus@322
  1737
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1738
 *    \param val pointer to where value should be stored.
icculus@322
  1739
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1740
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1741
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1742
 */
icculus@1024
  1743
PHYSFS_DECL int PHYSFS_readSLE32(PHYSFS_File *file, PHYSFS_sint32 *val);
icculus@322
  1744
icculus@322
  1745
icculus@322
  1746
/**
icculus@654
  1747
 * \fn int PHYSFS_readULE32(PHYSFS_File *file, PHYSFS_uint32 *val)
icculus@322
  1748
 * \brief Read and convert an unsigned 32-bit littleendian value.
icculus@322
  1749
 *
icculus@322
  1750
 * Convenience function. Read an unsigned 32-bit littleendian value from a
icculus@322
  1751
 *  file and convert it to the platform's native byte order.
icculus@322
  1752
 *
icculus@322
  1753
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1754
 *    \param val pointer to where value should be stored.
icculus@322
  1755
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1756
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1757
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1758
 *
icculus@322
  1759
 */
icculus@1024
  1760
PHYSFS_DECL int PHYSFS_readULE32(PHYSFS_File *file, PHYSFS_uint32 *val);
icculus@322
  1761
icculus@322
  1762
icculus@322
  1763
/**
icculus@654
  1764
 * \fn int PHYSFS_readSBE32(PHYSFS_File *file, PHYSFS_sint32 *val)
icculus@322
  1765
 * \brief Read and convert a signed 32-bit bigendian value.
icculus@322
  1766
 *
icculus@322
  1767
 * Convenience function. Read a signed 32-bit bigendian value from a
icculus@322
  1768
 *  file and convert it to the platform's native byte order.
icculus@322
  1769
 *
icculus@322
  1770
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1771
 *    \param val pointer to where value should be stored.
icculus@322
  1772
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1773
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1774
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1775
 */
icculus@1024
  1776
PHYSFS_DECL int PHYSFS_readSBE32(PHYSFS_File *file, PHYSFS_sint32 *val);
icculus@322
  1777
icculus@322
  1778
icculus@322
  1779
/**
icculus@654
  1780
 * \fn int PHYSFS_readUBE32(PHYSFS_File *file, PHYSFS_uint32 *val)
icculus@322
  1781
 * \brief Read and convert an unsigned 32-bit bigendian value.
icculus@322
  1782
 *
icculus@322
  1783
 * Convenience function. Read an unsigned 32-bit bigendian value from a
icculus@322
  1784
 *  file and convert it to the platform's native byte order.
icculus@322
  1785
 *
icculus@322
  1786
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1787
 *    \param val pointer to where value should be stored.
icculus@322
  1788
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1789
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1790
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1791
 *
icculus@322
  1792
 */
icculus@1024
  1793
PHYSFS_DECL int PHYSFS_readUBE32(PHYSFS_File *file, PHYSFS_uint32 *val);
icculus@322
  1794
icculus@322
  1795
icculus@322
  1796
/**
icculus@654
  1797
 * \fn int PHYSFS_readSLE64(PHYSFS_File *file, PHYSFS_sint64 *val)
icculus@322
  1798
 * \brief Read and convert a signed 64-bit littleendian value.
icculus@322
  1799
 *
icculus@322
  1800
 * Convenience function. Read a signed 64-bit littleendian value from a
icculus@322
  1801
 *  file and convert it to the platform's native byte order.
icculus@322
  1802
 *
icculus@322
  1803
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1804
 *    \param val pointer to where value should be stored.
icculus@322
  1805
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1806
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1807
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1808
 *
icculus@322
  1809
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@322
  1810
 *          any sort of 64-bit support.
icculus@322
  1811
 */
icculus@1024
  1812
PHYSFS_DECL int PHYSFS_readSLE64(PHYSFS_File *file, PHYSFS_sint64 *val);
icculus@322
  1813
icculus@322
  1814
icculus@322
  1815
/**
icculus@654
  1816
 * \fn int PHYSFS_readULE64(PHYSFS_File *file, PHYSFS_uint64 *val)
icculus@322
  1817
 * \brief Read and convert an unsigned 64-bit littleendian value.
icculus@322
  1818
 *
icculus@322
  1819
 * Convenience function. Read an unsigned 64-bit littleendian value from a
icculus@322
  1820
 *  file and convert it to the platform's native byte order.
icculus@322
  1821
 *
icculus@322
  1822
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1823
 *    \param val pointer to where value should be stored.
icculus@322
  1824
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1825
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1826
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1827
 *
icculus@322
  1828
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@322
  1829
 *          any sort of 64-bit support.
icculus@322
  1830
 */
icculus@1024
  1831
PHYSFS_DECL int PHYSFS_readULE64(PHYSFS_File *file, PHYSFS_uint64 *val);
icculus@322
  1832
icculus@322
  1833
icculus@322
  1834
/**
icculus@654
  1835
 * \fn int PHYSFS_readSBE64(PHYSFS_File *file, PHYSFS_sint64 *val)
icculus@322
  1836
 * \brief Read and convert a signed 64-bit bigendian value.
icculus@322
  1837
 *
icculus@322
  1838
 * Convenience function. Read a signed 64-bit bigendian value from a
icculus@322
  1839
 *  file and convert it to the platform's native byte order.
icculus@322
  1840
 *
icculus@322
  1841
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1842
 *    \param val pointer to where value should be stored.
icculus@322
  1843
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1844
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1845
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1846
 *
icculus@322
  1847
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@322
  1848
 *          any sort of 64-bit support.
icculus@322
  1849
 */
icculus@1024
  1850
PHYSFS_DECL int PHYSFS_readSBE64(PHYSFS_File *file, PHYSFS_sint64 *val);
icculus@322
  1851
icculus@322
  1852
icculus@322
  1853
/**
icculus@654
  1854
 * \fn int PHYSFS_readUBE64(PHYSFS_File *file, PHYSFS_uint64 *val)
icculus@322
  1855
 * \brief Read and convert an unsigned 64-bit bigendian value.
icculus@322
  1856
 *
icculus@322
  1857
 * Convenience function. Read an unsigned 64-bit bigendian value from a
icculus@322
  1858
 *  file and convert it to the platform's native byte order.
icculus@322
  1859
 *
icculus@322
  1860
 *    \param file PhysicsFS file handle from which to read.
icculus@322
  1861
 *    \param val pointer to where value should be stored.
icculus@322
  1862
 *   \return zero on failure, non-zero on success. If successful, (*val) will
icculus@322
  1863
 *           store the result. On failure, you can find out what went wrong
icculus@1562
  1864
 *           from PHYSFS_getLastErrorCode().
icculus@322
  1865
 *
icculus@322
  1866
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@322
  1867
 *          any sort of 64-bit support.
icculus@322
  1868
 */
icculus@1024
  1869
PHYSFS_DECL int PHYSFS_readUBE64(PHYSFS_File *file, PHYSFS_uint64 *val);
icculus@322
  1870
icculus@322
  1871
icculus@322
  1872
/**
icculus@654
  1873
 * \fn int PHYSFS_writeSLE16(PHYSFS_File *file, PHYSFS_sint16 val)
icculus@322
  1874
 * \brief Convert and write a signed 16-bit littleendian value.
icculus@322
  1875
 *
icculus@322
  1876
 * Convenience function. Convert a signed 16-bit value from the platform's
icculus@322
  1877
 *  native byte order to littleendian and write it to a file.
icculus@322
  1878
 *
icculus@322
  1879
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1880
 *    \param val Value to convert and write.
icculus@322
  1881
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1882
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1883
 */
icculus@1024
  1884
PHYSFS_DECL int PHYSFS_writeSLE16(PHYSFS_File *file, PHYSFS_sint16 val);
icculus@322
  1885
icculus@322
  1886
icculus@322
  1887
/**
icculus@654
  1888
 * \fn int PHYSFS_writeULE16(PHYSFS_File *file, PHYSFS_uint16 val)
icculus@322
  1889
 * \brief Convert and write an unsigned 16-bit littleendian value.
icculus@322
  1890
 *
icculus@322
  1891
 * Convenience function. Convert an unsigned 16-bit value from the platform's
icculus@322
  1892
 *  native byte order to littleendian and write it to a file.
icculus@322
  1893
 *
icculus@322
  1894
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1895
 *    \param val Value to convert and write.
icculus@322
  1896
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1897
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1898
 */
icculus@1024
  1899
PHYSFS_DECL int PHYSFS_writeULE16(PHYSFS_File *file, PHYSFS_uint16 val);
icculus@322
  1900
icculus@322
  1901
icculus@322
  1902
/**
icculus@654
  1903
 * \fn int PHYSFS_writeSBE16(PHYSFS_File *file, PHYSFS_sint16 val)
icculus@322
  1904
 * \brief Convert and write a signed 16-bit bigendian value.
icculus@322
  1905
 *
icculus@322
  1906
 * Convenience function. Convert a signed 16-bit value from the platform's
icculus@322
  1907
 *  native byte order to bigendian and write it to a file.
icculus@322
  1908
 *
icculus@322
  1909
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1910
 *    \param val Value to convert and write.
icculus@322
  1911
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1912
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1913
 */
icculus@1024
  1914
PHYSFS_DECL int PHYSFS_writeSBE16(PHYSFS_File *file, PHYSFS_sint16 val);
icculus@322
  1915
icculus@322
  1916
icculus@322
  1917
/**
icculus@654
  1918
 * \fn int PHYSFS_writeUBE16(PHYSFS_File *file, PHYSFS_uint16 val)
icculus@322
  1919
 * \brief Convert and write an unsigned 16-bit bigendian value.
icculus@322
  1920
 *
icculus@322
  1921
 * Convenience function. Convert an unsigned 16-bit value from the platform's
icculus@322
  1922
 *  native byte order to bigendian and write it to a file.
icculus@322
  1923
 *
icculus@322
  1924
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1925
 *    \param val Value to convert and write.
icculus@322
  1926
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1927
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1928
 */
icculus@1024
  1929
PHYSFS_DECL int PHYSFS_writeUBE16(PHYSFS_File *file, PHYSFS_uint16 val);
icculus@322
  1930
icculus@322
  1931
icculus@322
  1932
/**
icculus@654
  1933
 * \fn int PHYSFS_writeSLE32(PHYSFS_File *file, PHYSFS_sint32 val)
icculus@322
  1934
 * \brief Convert and write a signed 32-bit littleendian value.
icculus@322
  1935
 *
icculus@322
  1936
 * Convenience function. Convert a signed 32-bit value from the platform's
icculus@322
  1937
 *  native byte order to littleendian and write it to a file.
icculus@322
  1938
 *
icculus@322
  1939
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1940
 *    \param val Value to convert and write.
icculus@322
  1941
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1942
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1943
 */
icculus@1024
  1944
PHYSFS_DECL int PHYSFS_writeSLE32(PHYSFS_File *file, PHYSFS_sint32 val);
icculus@322
  1945
icculus@322
  1946
icculus@322
  1947
/**
icculus@654
  1948
 * \fn int PHYSFS_writeULE32(PHYSFS_File *file, PHYSFS_uint32 val)
icculus@322
  1949
 * \brief Convert and write an unsigned 32-bit littleendian value.
icculus@322
  1950
 *
icculus@322
  1951
 * Convenience function. Convert an unsigned 32-bit value from the platform's
icculus@322
  1952
 *  native byte order to littleendian and write it to a file.
icculus@322
  1953
 *
icculus@322
  1954
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1955
 *    \param val Value to convert and write.
icculus@322
  1956
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1957
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1958
 */
icculus@1024
  1959
PHYSFS_DECL int PHYSFS_writeULE32(PHYSFS_File *file, PHYSFS_uint32 val);
icculus@322
  1960
icculus@322
  1961
icculus@322
  1962
/**
icculus@654
  1963
 * \fn int PHYSFS_writeSBE32(PHYSFS_File *file, PHYSFS_sint32 val)
icculus@322
  1964
 * \brief Convert and write a signed 32-bit bigendian value.
icculus@322
  1965
 *
icculus@322
  1966
 * Convenience function. Convert a signed 32-bit value from the platform's
icculus@322
  1967
 *  native byte order to bigendian and write it to a file.
icculus@322
  1968
 *
icculus@322
  1969
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1970
 *    \param val Value to convert and write.
icculus@322
  1971
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1972
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1973
 */
icculus@1024
  1974
PHYSFS_DECL int PHYSFS_writeSBE32(PHYSFS_File *file, PHYSFS_sint32 val);
icculus@322
  1975
icculus@322
  1976
icculus@322
  1977
/**
icculus@654
  1978
 * \fn int PHYSFS_writeUBE32(PHYSFS_File *file, PHYSFS_uint32 val)
icculus@322
  1979
 * \brief Convert and write an unsigned 32-bit bigendian value.
icculus@322
  1980
 *
icculus@322
  1981
 * Convenience function. Convert an unsigned 32-bit value from the platform's
icculus@322
  1982
 *  native byte order to bigendian and write it to a file.
icculus@322
  1983
 *
icculus@322
  1984
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  1985
 *    \param val Value to convert and write.
icculus@322
  1986
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  1987
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  1988
 */
icculus@1024
  1989
PHYSFS_DECL int PHYSFS_writeUBE32(PHYSFS_File *file, PHYSFS_uint32 val);
icculus@322
  1990
icculus@322
  1991
icculus@322
  1992
/**
icculus@654
  1993
 * \fn int PHYSFS_writeSLE64(PHYSFS_File *file, PHYSFS_sint64 val)
icculus@322
  1994
 * \brief Convert and write a signed 64-bit littleendian value.
icculus@322
  1995
 *
icculus@322
  1996
 * Convenience function. Convert a signed 64-bit value from the platform's
icculus@322
  1997
 *  native byte order to littleendian and write it to a file.
icculus@322
  1998
 *
icculus@322
  1999
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  2000
 *    \param val Value to convert and write.
icculus@322
  2001
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  2002
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  2003
 *
icculus@1378
  2004
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@322
  2005
 *          any sort of 64-bit support.
icculus@322
  2006
 */
icculus@1024
  2007
PHYSFS_DECL int PHYSFS_writeSLE64(PHYSFS_File *file, PHYSFS_sint64 val);
icculus@322
  2008
icculus@322
  2009
icculus@322
  2010
/**
icculus@654
  2011
 * \fn int PHYSFS_writeULE64(PHYSFS_File *file, PHYSFS_uint64 val)
icculus@322
  2012
 * \brief Convert and write an unsigned 64-bit littleendian value.
icculus@322
  2013
 *
icculus@322
  2014
 * Convenience function. Convert an unsigned 64-bit value from the platform's
icculus@322
  2015
 *  native byte order to littleendian and write it to a file.
icculus@322
  2016
 *
icculus@322
  2017
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  2018
 *    \param val Value to convert and write.
icculus@322
  2019
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  2020
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  2021
 *
icculus@322
  2022
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@322
  2023
 *          any sort of 64-bit support.
icculus@322
  2024
 */
icculus@1024
  2025
PHYSFS_DECL int PHYSFS_writeULE64(PHYSFS_File *file, PHYSFS_uint64 val);
icculus@322
  2026
icculus@322
  2027
icculus@322
  2028
/**
icculus@654
  2029
 * \fn int PHYSFS_writeSBE64(PHYSFS_File *file, PHYSFS_sint64 val)
icculus@322
  2030
 * \brief Convert and write a signed 64-bit bigending value.
icculus@322
  2031
 *
icculus@322
  2032
 * Convenience function. Convert a signed 64-bit value from the platform's
icculus@322
  2033
 *  native byte order to bigendian and write it to a file.
icculus@322
  2034
 *
icculus@322
  2035
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  2036
 *    \param val Value to convert and write.
icculus@322
  2037
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  2038
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  2039
 *
icculus@1378
  2040
 * \warning Remember, PHYSFS_sint64 is only 32 bits on platforms without
icculus@322
  2041
 *          any sort of 64-bit support.
icculus@322
  2042
 */
icculus@1024
  2043
PHYSFS_DECL int PHYSFS_writeSBE64(PHYSFS_File *file, PHYSFS_sint64 val);
icculus@322
  2044
icculus@322
  2045
icculus@322
  2046
/**
icculus@654
  2047
 * \fn int PHYSFS_writeUBE64(PHYSFS_File *file, PHYSFS_uint64 val)
icculus@322
  2048
 * \brief Convert and write an unsigned 64-bit bigendian value.
icculus@322
  2049
 *
icculus@322
  2050
 * Convenience function. Convert an unsigned 64-bit value from the platform's
icculus@322
  2051
 *  native byte order to bigendian and write it to a file.
icculus@322
  2052
 *
icculus@322
  2053
 *    \param file PhysicsFS file handle to which to write.
icculus@322
  2054
 *    \param val Value to convert and write.
icculus@322
  2055
 *   \return zero on failure, non-zero on success. On failure, you can
icculus@1562
  2056
 *           find out what went wrong from PHYSFS_getLastErrorCode().
icculus@322
  2057
 *
icculus@322
  2058
 * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without
icculus@322
  2059
 *          any sort of 64-bit support.
icculus@322
  2060
 */
icculus@1024
  2061
PHYSFS_DECL int PHYSFS_writeUBE64(PHYSFS_File *file, PHYSFS_uint64 val);
icculus@322
  2062
icculus@322
  2063
icculus@644
  2064
/* Everything above this line is part of the PhysicsFS 1.0 API. */
icculus@644
  2065
icculus@644
  2066
/**
icculus@876
  2067
 * \fn int PHYSFS_isInit(void)
icculus@876
  2068
 * \brief Determine if the PhysicsFS library is initialized.
icculus@876
  2069
 *
icculus@876
  2070
 * Once PHYSFS_init() returns successfully, this will return non-zero.
icculus@876
  2071
 *  Before a successful PHYSFS_init() and after PHYSFS_deinit() returns
icculus@876
  2072
 *  successfully, this will return zero. This function is safe to call at
icculus@876
  2073
 *  any time.
icculus@876
  2074
 *
icculus@876
  2075
 *  \return non-zero if library is initialized, zero if library is not.
icculus@876
  2076
 *
icculus@876
  2077
 * \sa PHYSFS_init
icculus@876
  2078
 * \sa PHYSFS_deinit
icculus@876
  2079
 */
icculus@1024
  2080
PHYSFS_DECL int PHYSFS_isInit(void);
icculus@876
  2081
icculus@876
  2082
icculus@876
  2083
/**
icculus@877
  2084
 * \fn int PHYSFS_symbolicLinksPermitted(void)
icculus@877
  2085
 * \brief Determine if the symbolic links are permitted.
icculus@877
  2086
 *
icculus@877
  2087
 * This reports the setting from the last call to PHYSFS_permitSymbolicLinks().
icculus@877
  2088
 *  If PHYSFS_permitSymbolicLinks() hasn't been called since the library was
icculus@877
  2089
 *  last initialized, symbolic links are implicitly disabled.
icculus@877
  2090
 *
icculus@877
  2091
 *  \return non-zero if symlinks are permitted, zero if not.
icculus@877
  2092
 *
icculus@877
  2093
 * \sa PHYSFS_permitSymbolicLinks
icculus@877
  2094
 */
icculus@1024
  2095
PHYSFS_DECL int PHYSFS_symbolicLinksPermitted(void);
icculus@877
  2096
icculus@877
  2097
icculus@877
  2098
/**
icculus@751
  2099
 * \struct PHYSFS_Allocator
icculus@644
  2100
 * \brief PhysicsFS allocation function pointers.
icculus@644
  2101
 *
icculus@644
  2102
 * (This is for limited, hardcore use. If you don't immediately see a need
icculus@644
  2103
 *  for it, you can probably ignore this forever.)
icculus@644
  2104
 *
icculus@644
  2105
 * You create one of these structures for use with PHYSFS_setAllocator.
icculus@648
  2106
 *  Allocators are assumed to be reentrant by the caller; please mutex
icculus@648
  2107
 *  accordingly.
icculus@644
  2108
 *
icculus@747
  2109
 * Allocations are always discussed in 64-bits, for future expansion...we're
icculus@747
  2110
 *  on the cusp of a 64-bit transition, and we'll probably be allocating 6
icculus@747
  2111
 *  gigabytes like it's nothing sooner or later, and I don't want to change
icculus@747
  2112
 *  this again at that point. If you're on a 32-bit platform and have to
icculus@747
  2113
 *  downcast, it's okay to return NULL if the allocation is greater than
icculus@747
  2114
 *  4 gigabytes, since you'd have to do so anyhow.
icculus@747
  2115
 *
icculus@644
  2116
 * \sa PHYSFS_setAllocator
icculus@644
  2117
 */
icculus@943
  2118
typedef struct PHYSFS_Allocator
icculus@644
  2119
{
icculus@751
  2120
    int (*Init)(void);   /**< Initialize. Can be NULL. Zero on failure. */
icculus@751
  2121
    void (*Deinit)(void);  /**< Deinitialize your allocator. Can be NULL. */
icculus@751
  2122
    void *(*Malloc)(PHYSFS_uint64);  /**< Allocate like malloc(). */
icculus@751
  2123
    void *(*Realloc)(void *, PHYSFS_uint64); /**< Reallocate like realloc(). */
icculus@751
  2124
    void (*Free)(void *); /**< Free memory from Malloc or Realloc. */
icculus@650
  2125
} PHYSFS_Allocator;
icculus@644
  2126
icculus@644
  2127
icculus@644
  2128
/**
icculus@751
  2129
 * \fn int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator)
icculus@644
  2130
 * \brief Hook your own allocation routines into PhysicsFS.
icculus@644
  2131
 *
icculus@644
  2132
 * (This is for limited, hardcore use. If you don't immediately see a need
icculus@644
  2133
 *  for it, you can probably ignore this forever.)
icculus@644
  2134
 *
icculus@843
  2135
 * By default, PhysicsFS will use whatever is reasonable for a platform
icculus@1202
  2136
 *  to manage dynamic memory (usually ANSI C malloc/realloc/free, but
icculus@843
  2137
 *  some platforms might use something else), but in some uncommon cases, the
icculus@843
  2138
 *  app might want more control over the library's memory management. This
icculus@843
  2139
 *  lets you redirect PhysicsFS to use your own allocation routines instead.
icculus@843
  2140
 *  You can only call this function before PHYSFS_init(); if the library is
icculus@843
  2141
 *  initialized, it'll reject your efforts to change the allocator mid-stream.
icculus@843
  2142
 *  You may call this function after PHYSFS_deinit() if you are willing to
icculus@843
  2143
 *  shut down the library and restart it with a new allocator; this is a safe
icculus@843
  2144
 *  and supported operation. The allocator remains intact between deinit/init
icculus@843
  2145
 *  calls. If you want to return to the platform's default allocator, pass a
icculus@843
  2146
 *  NULL in here.
icculus@644
  2147
 *
icculus@644
  2148
 * If you aren't immediately sure what to do with this function, you can
icculus@644
  2149
 *  safely ignore it altogether.
icculus@644
  2150
 *
icculus@644
  2151
 *    \param allocator Structure containing your allocator's entry points.
icculus@644
  2152
 *   \return zero on failure, non-zero on success. This call only fails
icculus@644
  2153
 *           when used between PHYSFS_init() and PHYSFS_deinit() calls.
icculus@644
  2154
 */
icculus@1024
  2155
PHYSFS_DECL int PHYSFS_setAllocator(const PHYSFS_Allocator *allocator);
icculus@644
  2156
icculus@644
  2157
icculus@687
  2158
/**
icculus@881
  2159
 * \fn int PHYSFS_mount(const char *newDir, const char *mountPoint, int appendToPath)
icculus@687
  2160
 * \brief Add an archive or directory to the search path.
icculus@687
  2161
 *
icculus@687
  2162
 * If this is a duplicate, the entry is not added again, even though the
icculus@687
  2163
 *  function succeeds. You may not add the same archive to two different
icculus@687
  2164
 *  mountpoints: duplicate checking is done against the archive and not the
icculus@687
  2165
 *  mountpoint.
icculus@687
  2166
 *
icculus@687
  2167
 * When you mount an archive, it is added to a virtual file system...all files
icculus@687
  2168
 *  in all of the archives are interpolated into a single hierachical file
icculus@687
  2169
 *  tree. Two archives mounted at the same place (or an archive with files
icculus@687
  2170
 *  overlapping another mountpoint) may have overlapping files: in such a case,
icculus@687
  2171
 *  the file earliest in the search path is selected, and the other files are
icculus@687
  2172
 *  inaccessible to the application. This allows archives to be used to
icculus@687
  2173
 *  override previous revisions; you can use the mounting mechanism to place
icculus@687
  2174
 *  archives at a specific point in the file tree and prevent overlap; this
icculus@687
  2175
 *  is useful for downloadable mods that might trample over application data
icculus@687
  2176
 *  or each other, for example.
icculus@687
  2177
 *
icculus@687
  2178
 * The mountpoint does not need to exist prior to mounting, which is different
icculus@687
  2179
 *  than those familiar with the Unix concept of "mounting" may not expect.
icculus@687
  2180
 *  As well, more than one archive can be mounted to the same mountpoint, or
icculus@687
  2181
 *  mountpoints and archive contents can overlap...the interpolation mechanism
icculus@687
  2182
 *  still functions as usual.
icculus@687
  2183
 *
icculus@687
  2184
 *   \param newDir directory or archive to add to the path, in
icculus@687
  2185
 *                   platform-dependent notation.
icculus@687
  2186
 *   \param mountPoint Location in the interpolated tree that this archive
icculus@687
  2187
 *                     will be "mounted", in platform-independent notation.
icculus@687
  2188
 *                     NULL or "" is equivalent to "/".
icculus@687
  2189
 *   \param appendToPath nonzero to append to search path, zero to prepend.
icculus@687
  2190
 *  \return nonzero if added to path, zero on failure (bogus archive, dir
icculus@1562
  2191
 *          missing, etc). Use PHYSFS_getLastErrorCode() to obtain
icculus@1562
  2192
 *          the specific error.
icculus@687
  2193
 *
icculus@687
  2194
 * \sa PHYSFS_removeFromSearchPath
icculus@687
  2195
 * \sa PHYSFS_getSearchPath
icculus@687
  2196
 * \sa PHYSFS_getMountPoint
icculus@1118
  2197
 * \sa PHYSFS_mountIo
icculus@687
  2198
 */
icculus@1024
  2199
PHYSFS_DECL int PHYSFS_mount(const char *newDir,
icculus@1024
  2200
                             const char *mountPoint,
icculus@1024
  2201
                             int appendToPath);
icculus@687
  2202
icculus@687
  2203
/**
icculus@881
  2204
 * \fn int PHYSFS_getMountPoint(const char *dir)
icculus@687
  2205
 * \brief Determine a mounted archive's mountpoint.
icculus@687
  2206
 *
icculus@687
  2207
 * You give this function the name of an archive or dir you successfully
icculus@687
  2208
 *  added to the search path, and it reports the location in the interpolated
icculus@687
  2209
 *  tree where it is mounted. Files mounted with a NULL mountpoint or through
icculus@687
  2210
 *  PHYSFS_addToSearchPath() will report "/". The return value is READ ONLY
icculus@687
  2211
 *  and valid until the archive is removed from the search path.
icculus@687
  2212
 *
icculus@687
  2213
 *   \param dir directory or archive previously added to the path, in
icculus@687
  2214
 *              platform-dependent notation. This must match the string
icculus@687
  2215
 *              used when adding, even if your string would also reference
icculus@687
  2216
 *              the same file with a different string of characters.
icculus@687
  2217
 *  \return READ-ONLY string of mount point if added to path, NULL on failure
icculus@1562
  2218
 *          (bogus archive, etc). Use PHYSFS_getLastErrorCode() to obtain the
icculus@1562
  2219
 *          specific error.
icculus@687
  2220
 *
icculus@687
  2221
 * \sa PHYSFS_removeFromSearchPath
icculus@687
  2222
 * \sa PHYSFS_getSearchPath
icculus@687
  2223
 * \sa PHYSFS_getMountPoint
icculus@687
  2224
 */
icculus@1024
  2225
PHYSFS_DECL const char *PHYSFS_getMountPoint(const char *dir);
icculus@687
  2226
icculus@687
  2227
icculus@881
  2228
/**
icculus@881
  2229
 * \typedef PHYSFS_StringCallback
icculus@881
  2230
 * \brief Function signature for callbacks that report strings.
icculus@881
  2231
 *
icculus@881
  2232
 * These are used to report a list of strings to an original caller, one
icculus@881
  2233
 *  string per callback. All strings are UTF-8 encoded. Functions should not
icculus@881
  2234
 *  try to modify or free the string's memory.
icculus@881
  2235
 *
icculus@881
  2236
 * These callbacks are used, starting in PhysicsFS 1.1, as an alternative to
icculus@881
  2237
 *  functions that would return lists that need to be cleaned up with
icculus@881
  2238
 *  PHYSFS_freeList(). The callback means that the library doesn't need to
icculus@881
  2239
 *  allocate an entire list and all the strings up front.
icculus@881
  2240
 *
icculus@881
  2241
 * Be aware that promises data ordering in the list versions are not
icculus@881
  2242
 *  necessarily so in the callback versions. Check the documentation on
icculus@881
  2243
 *  specific APIs, but strings may not be sorted as you expect.
icculus@881
  2244
 *
icculus@881
  2245
 *    \param data User-defined data pointer, passed through from the API
icculus@881
  2246
 *                that eventually called the callback.
icculus@881
  2247
 *    \param str The string data about which the callback is meant to inform.
icculus@881
  2248
 *
icculus@881
  2249
 * \sa PHYSFS_getCdRomDirsCallback
icculus@881
  2250
 * \sa PHYSFS_getSearchPathCallback
icculus@881
  2251
 */
icculus@881
  2252
typedef void (*PHYSFS_StringCallback)(void *data, const char *str);
icculus@657
  2253
icculus@881
  2254
icculus@881
  2255
/**
icculus@881
  2256
 * \typedef PHYSFS_EnumFilesCallback
icculus@881
  2257
 * \brief Function signature for callbacks that enumerate files.
icculus@881
  2258
 *
icculus@1581
  2259
 * \warning As of PhysicsFS 2.1, Use PHYSFS_EnumerateCallback with
icculus@1559
  2260
 *  PHYSFS_enumerate() instead; it gives you more control over the process.
icculus@1559
  2261
 *
icculus@881
  2262
 * These are used to report a list of directory entries to an original caller,
icculus@881
  2263
 *  one file/dir/symlink per callback. All strings are UTF-8 encoded.
icculus@881
  2264
 *  Functions should not try to modify or free any string's memory.
icculus@881
  2265
 *
icculus@881
  2266
 * These callbacks are used, starting in PhysicsFS 1.1, as an alternative to
icculus@881
  2267
 *  functions that would return lists that need to be cleaned up with
icculus@881
  2268
 *  PHYSFS_freeList(). The callback means that the library doesn't need to
icculus@881
  2269
 *  allocate an entire list and all the strings up front.
icculus@881
  2270
 *
icculus@1559
  2271
 * Be aware that promised data ordering in the list versions are not
icculus@881
  2272
 *  necessarily so in the callback versions. Check the documentation on
icculus@1559
  2273
 *  specific APIs, but strings may not be sorted as you expect and you might
icculus@1559
  2274
 *  get duplicate strings.
icculus@881
  2275
 *
icculus@881
  2276
 *    \param data User-defined data pointer, passed through from the API
icculus@881
  2277
 *                that eventually called the callback.
icculus@881
  2278
 *    \param origdir A string containing the full path, in platform-independent
icculus@881
  2279
 *                   notation, of the directory containing this file. In most
icculus@881
  2280
 *                   cases, this is the directory on which you requested
icculus@881
  2281
 *                   enumeration, passed in the callback for your convenience.
icculus@881
  2282
 *    \param fname The filename that is being enumerated. It may not be in
icculus@881
  2283
 *                 alphabetical order compared to other callbacks that have
icculus@881
  2284
 *                 fired, and it will not contain the full path. You can
icculus@881
  2285
 *                 recreate the fullpath with $origdir/$fname ... The file
icculus@881
  2286
 *                 can be a subdirectory, a file, a symlink, etc.
icculus@881
  2287
 *
icculus@881
  2288
 * \sa PHYSFS_enumerateFilesCallback
icculus@881
  2289
 */
icculus@881
  2290
typedef void (*PHYSFS_EnumFilesCallback)(void *data, const char *origdir,
icculus@1563
  2291
                                         const char *fname);
icculus@881
  2292
icculus@881
  2293
icculus@881
  2294
/**
icculus@881
  2295
 * \fn void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d)
icculus@881
  2296
 * \brief Enumerate CD-ROM directories, using an application-defined callback.
icculus@881
  2297
 *
icculus@881
  2298
 * Internally, PHYSFS_getCdRomDirs() just calls this function and then builds
icculus@881
  2299
 *  a list before returning to the application, so functionality is identical
icculus@881
  2300
 *  except for how the information is represented to the application.
icculus@881
  2301
 *
icculus@881
  2302
 * Unlike PHYSFS_getCdRomDirs(), this function does not return an array.
icculus@881
  2303
 *  Rather, it calls a function specified by the application once per
icculus@881
  2304
 *  detected disc:
icculus@881
  2305
 *
icculus@881
  2306
 * \code
icculus@881
  2307
 *
icculus@881
  2308
 * static void foundDisc(void *data, const char *cddir)
icculus@881
  2309
 * {
icculus@881
  2310
 *     printf("cdrom dir [%s] is available.\n", cddir);
icculus@881
  2311
 * }
icculus@881
  2312
 *
icculus@881
  2313
 * // ...
icculus@881
  2314
 * PHYSFS_getCdRomDirsCallback(foundDisc, NULL);
icculus@881
  2315
 * \endcode
icculus@881
  2316
 *
icculus@881
  2317
 * This call may block while drives spin up. Be forewarned.
icculus@881
  2318
 *
icculus@881
  2319
 *    \param c Callback function to notify about detected drives.
icculus@881
  2320
 *    \param d Application-defined data passed to callback. Can be NULL.
icculus@881
  2321
 *
icculus@881
  2322
 * \sa PHYSFS_StringCallback
icculus@881
  2323
 * \sa PHYSFS_getCdRomDirs
icculus@881
  2324
 */
icculus@1024
  2325
PHYSFS_DECL void PHYSFS_getCdRomDirsCallback(PHYSFS_StringCallback c, void *d);
icculus@657
  2326
icculus@881
  2327
icculus@881
  2328
/**
icculus@881
  2329
 * \fn void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d)
icculus@881
  2330
 * \brief Enumerate the search path, using an application-defined callback.
icculus@881
  2331
 *
icculus@881
  2332
 * Internally, PHYSFS_getSearchPath() just calls this function and then builds
icculus@881
  2333
 *  a list before returning to the application, so functionality is identical
icculus@881
  2334
 *  except for how the information is represented to the application.
icculus@881
  2335
 *
icculus@881
  2336
 * Unlike PHYSFS_getSearchPath(), this function does not return an array.
icculus@881
  2337
 *  Rather, it calls a function specified by the application once per
icculus@881
  2338
 *  element of the search path:
icculus@881
  2339
 *
icculus@881
  2340
 * \code
icculus@881
  2341
 *
icculus@881
  2342
 * static void printSearchPath(void *data, const char *pathItem)
icculus@881
  2343
 * {
icculus@881
  2344
 *     printf("[%s] is in the search path.\n", pathItem);
icculus@881
  2345
 * }
icculus@881
  2346
 *
icculus@881
  2347
 * // ...
icculus@881
  2348
 * PHYSFS_getSearchPathCallback(printSearchPath, NULL);
icculus@881
  2349
 * \endcode
icculus@881
  2350
 *
icculus@881
  2351
 * Elements of the search path are reported in order search priority, so the
icculus@881
  2352
 *  first archive/dir that would be examined when looking for a file is the
icculus@881
  2353
 *  first element passed through the callback.
icculus@881
  2354
 *
icculus@881
  2355
 *    \param c Callback function to notify about search path elements.
icculus@881
  2356
 *    \param d Application-defined data passed to callback. Can be NULL.
icculus@881
  2357
 *
icculus@881
  2358
 * \sa PHYSFS_StringCallback
icculus@881
  2359
 * \sa PHYSFS_getSearchPath
icculus@881
  2360
 */
icculus@1024
  2361
PHYSFS_DECL void PHYSFS_getSearchPathCallback(PHYSFS_StringCallback c, void *d);
icculus@657
  2362
icculus@881
  2363
icculus@881
  2364
/**
icculus@881
  2365
 * \fn void PHYSFS_enumerateFilesCallback(const char *dir, PHYSFS_EnumFilesCallback c, void *d)
icculus@881
  2366
 * \brief Get a file listing of a search path's directory, using an application-defined callback.
icculus@881
  2367
 *
icculus@1559
  2368
 * \deprecated As of PhysicsFS 2.1, use PHYSFS_enumerate() instead. This
icculus@1559
  2369
 *  function has no way to report errors (or to have the callback signal an
icculus@1559
  2370
 *  error or request a stop), so if data will be lost, your callback has no
icculus@1559
  2371
 *  way to direct the process, and your calling app has no way to know.
icculus@1559
  2372
 *
icculus@1559
  2373
 * As of PhysicsFS 2.1, this function just wraps PHYSFS_enumerate() and
icculus@1559
  2374
 *  ignores errors. Consider using PHYSFS_enumerate() or
icculus@1559
  2375
 *  PHYSFS_enumerateFiles() instead.
icculus@1559
  2376
 *
icculus@1559
  2377
 * \sa PHYSFS_enumerate
icculus@1559
  2378
 * \sa PHYSFS_enumerateFiles
icculus@881
  2379
 * \sa PHYSFS_EnumFilesCallback
icculus@881
  2380
 */
icculus@1024
  2381
PHYSFS_DECL void PHYSFS_enumerateFilesCallback(const char *dir,
icculus@1024
  2382
                                               PHYSFS_EnumFilesCallback c,
icculus@1559
  2383
                                               void *d) PHYSFS_DEPRECATED;
icculus@657
  2384
icculus@785
  2385
/**
icculus@831
  2386
 * \fn void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst, PHYSFS_uint64 len)
icculus@785
  2387
 * \brief Convert a UCS-4 string to a UTF-8 string.
icculus@785
  2388
 *
icculus@1596
  2389
 * \warning This function will not report an error if there are invalid UCS-4
icculus@1596
  2390
 *          values in the source string. It will replace them with a '?'
icculus@1596
  2391
 *          character and continue on.
icculus@1596
  2392
 *
icculus@1593
  2393
 * UCS-4 (aka UTF-32) strings are 32-bits per character: \c wchar_t on Unix.
icculus@785
  2394
 *
icculus@785
  2395
 * To ensure that the destination buffer is large enough for the conversion,
icculus@785
  2396
 *  please allocate a buffer that is the same size as the source buffer. UTF-8
icculus@785
  2397
 *  never uses more than 32-bits per character, so while it may shrink a UCS-4
icculus@785
  2398
 *  string, it will never expand it.
icculus@785
  2399
 *
icculus@785
  2400
 * Strings that don't fit in the destination buffer will be truncated, but
icculus@785
  2401
 *  will always be null-terminated and never have an incomplete UTF-8
icculus@1092
  2402
 *  sequence at the end. If the buffer length is 0, this function does nothing.
icculus@785
  2403
 *
icculus@785
  2404
 *   \param src Null-terminated source string in UCS-4 format.
icculus@785
  2405
 *   \param dst Buffer to store converted UTF-8 string.
icculus@785
  2406
 *   \param len Size, in bytes, of destination buffer.
icculus@785
  2407
 */
icculus@1024
  2408
PHYSFS_DECL void PHYSFS_utf8FromUcs4(const PHYSFS_uint32 *src, char *dst,
icculus@1024
  2409
                                     PHYSFS_uint64 len);
icculus@785
  2410
icculus@785
  2411
/**
icculus@831
  2412
 * \fn void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst, PHYSFS_uint64 len)
icculus@785
  2413
 * \brief Convert a UTF-8 string to a UCS-4 string.
icculus@785
  2414
 *
icculus@1596
  2415
 * \warning This function will not report an error if there are invalid UTF-8
icculus@1596
  2416
 *          sequences in the source string. It will replace them with a '?'
icculus@1596
  2417
 *          character and continue on.
icculus@1596
  2418
 *
icculus@1593
  2419
 * UCS-4 (aka UTF-32) strings are 32-bits per character: \c wchar_t on Unix.
icculus@785
  2420
 *
icculus@785
  2421
 * To ensure that the destination buffer is large enough for the conversion,
icculus@785
  2422
 *  please allocate a buffer that is four times the size of the source buffer.
icculus@785
  2423
 *  UTF-8 uses from one to four bytes per character, but UCS-4 always uses
icculus@785
  2424
 *  four, so an entirely low-ASCII string will quadruple in size!
icculus@785
  2425
 *
icculus@785
  2426
 * Strings that don't fit in the destination buffer will be truncated, but
icculus@785
  2427
 *  will always be null-terminated and never have an incomplete UCS-4
icculus@1092
  2428
 *  sequence at the end. If the buffer length is 0, this function does nothing.
icculus@785
  2429
 *
icculus@785
  2430
 *   \param src Null-terminated source string in UTF-8 format.
icculus@785
  2431
 *   \param dst Buffer to store converted UCS-4 string.
icculus@785
  2432
 *   \param len Size, in bytes, of destination buffer.
icculus@785
  2433
 */
icculus@1024
  2434
PHYSFS_DECL void PHYSFS_utf8ToUcs4(const char *src, PHYSFS_uint32 *dst,
icculus@1024
  2435
                                   PHYSFS_uint64 len);
icculus@785
  2436
icculus@785
  2437
/**
icculus@831
  2438
 * \fn void PHYSFS_utf8FromUcs2(const PHYSFS_uint16 *src, char *dst, PHYSFS_uint64 len)
icculus@785
  2439
 * \brief Convert a UCS-2 string to a UTF-8 string.
icculus@785
  2440
 *
icculus@1094
  2441
 * \warning you almost certainly should use PHYSFS_utf8FromUtf16(), which
icculus@1094
  2442
 *  became available in PhysicsFS 2.1, unless you know what you're doing.
icculus@1094
  2443
 *
icculus@1596
  2444
 * \warning This function will not report an error if there are invalid UCS-2
icculus@1596
  2445
 *          values in the source string. It will replace them with a '?'
icculus@1596
  2446
 *          character and continue on.
icculus@1596
  2447
 *
icculus@785
  2448
 * UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
icculus@1094
  2449
 *  with Unicode support. Please note that modern versions of Windows use
icculus@1209
  2450
 *  UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You
icculus@1209
  2451
 *  almost certainly want PHYSFS_utf8FromUtf16() instead.
icculus@785
  2452
 *
icculus@785
  2453
 * To ensure that the destination buffer is large enough for the conversion,
icculus@785
  2454
 *  please allocate a buffer that is double the size of the source buffer.
icculus@785
  2455
 *  UTF-8 never uses more than 32-bits per character, so while it may shrink
icculus@785
  2456
 *  a UCS-2 string, it may also expand it.
icculus@785
  2457
 *
icculus@785
  2458
 * Strings that don't fit in the destination buffer will be truncated, but
icculus@785
  2459
 *  will always be null-terminated and never have an incomplete UTF-8
icculus@1092
  2460
 *  sequence at the end. If the buffer length is 0, this function does nothing.
icculus@785
  2461
 *
icculus@785
  2462
 *   \param src Null-terminated source string in UCS-2 format.
icculus@785
  2463
 *   \param dst Buffer to store converted UTF-8 string.
icculus@785
  2464
 *   \param len Size, in bytes, of destination buffer.
icculus@1094
  2465
 *
icculus@1094
  2466
 * \sa PHYSFS_utf8FromUtf16
icculus@785
  2467
 */
icculus@1024
  2468
PHYSFS_DECL void PHYSFS_utf8FromUcs2(const PHYSFS_uint16 *src, char *dst,
icculus@1024
  2469
                                     PHYSFS_uint64 len);
icculus@785
  2470
icculus@785
  2471
/**
icculus@831
  2472
 * \fn PHYSFS_utf8ToUcs2(const char *src, PHYSFS_uint16 *dst, PHYSFS_uint64 len)
icculus@785
  2473
 * \brief Convert a UTF-8 string to a UCS-2 string.
icculus@785
  2474
 *
icculus@1094
  2475
 * \warning you almost certainly should use PHYSFS_utf8ToUtf16(), which
icculus@1094
  2476
 *  became available in PhysicsFS 2.1, unless you know what you're doing.
icculus@1094
  2477
 *
icculus@1596
  2478
 * \warning This function will not report an error if there are invalid UTF-8
icculus@1596
  2479
 *          sequences in the source string. It will replace them with a '?'
icculus@1596
  2480
 *          character and continue on.
icculus@1596
  2481
 *
icculus@785
  2482
 * UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building
icculus@1094
  2483
 *  with Unicode support. Please note that modern versions of Windows use
icculus@1209
  2484
 *  UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You
icculus@1209
  2485
 *  almost certainly want PHYSFS_utf8ToUtf16() instead, but you need to
icculus@1209
  2486
 *  understand how that changes things, too.
icculus@785
  2487
 *
icculus@785
  2488
 * To ensure that the destination buffer is large enough for the conversion,
icculus@785
  2489
 *  please allocate a buffer that is double the size of the source buffer.
icculus@785
  2490
 *  UTF-8 uses from one to four bytes per character, but UCS-2 always uses
icculus@785
  2491
 *  two, so an entirely low-ASCII string will double in size!
icculus@785
  2492
 *
icculus@785
  2493
 * Strings that don't fit in the destination buffer will be truncated, but
icculus@785
  2494
 *  will always be null-terminated and never have an incomplete UCS-2
icculus@1092
  2495
 *  sequence at the end. If the buffer length is 0, this function does nothing.
icculus@785
  2496
 *
icculus@785
  2497
 *   \param src Null-terminated source string in UTF-8 format.
icculus@785
  2498
 *   \param dst Buffer to store converted UCS-2 string.
icculus@785
  2499
 *   \param len Size, in bytes, of destination buffer.
icculus@1094
  2500
 *
icculus@1094
  2501
 * \sa PHYSFS_utf8ToUtf16
icculus@785
  2502
 */
icculus@1024
  2503
PHYSFS_DECL void PHYSFS_utf8ToUcs2(const char *src, PHYSFS_uint16 *dst,
icculus@1024
  2504
                                   PHYSFS_uint64 len);
icculus@785
  2505
icculus@785
  2506
/**
icculus@828
  2507
 * \fn void PHYSFS_utf8FromLatin1(const char *src, char *dst, PHYSFS_uint64 len)
icculus@785
  2508
 * \brief Convert a UTF-8 string to a Latin1 string.
icculus@785
  2509
 *
icculus@1209
  2510
 * Latin1 strings are 8-bits per character: a popular "high ASCII" encoding.
icculus@785
  2511
 *
icculus@785
  2512
 * To ensure that the destination buffer is large enough for the conversion,
icculus@785
  2513
 *  please allocate a buffer that is double the size of the source buffer.
icculus@872
  2514
 *  UTF-8 expands latin1 codepoints over 127 from 1 to 2 bytes, so the string
icculus@785
  2515
 *  may grow in some cases.
icculus@785
  2516
 *
icculus@785
  2517
 * Strings that don't fit in the destination buffer will be truncated, but
icculus@785
  2518
 *  will always be null-terminated and never have an incomplete UTF-8
icculus@1092
  2519
 *  sequence at the end. If the buffer length is 0, this function does nothing.
icculus@785
  2520
 *
icculus@785
  2521
 * Please note that we do not supply a UTF-8 to Latin1 converter, since Latin1
icculus@785
  2522
 *  can't express most Unicode codepoints. It's a legacy encoding; you should
icculus@785
  2523
 *  be converting away from it at all times.
icculus@785
  2524
 *
icculus@785
  2525
 *   \param src Null-terminated source string in Latin1 format.
icculus@785
  2526
 *   \param dst Buffer to store converted UTF-8 string.
icculus@785
  2527
 *   \param len Size, in bytes, of destination buffer.
icculus@785
  2528
 */
icculus@1024
  2529
PHYSFS_DECL void PHYSFS_utf8FromLatin1(const char *src, char *dst,
icculus@1024
  2530
                                       PHYSFS_uint64 len);
icculus@657
  2531
icculus@644
  2532
/* Everything above this line is part of the PhysicsFS 2.0 API. */
icculus@644
  2533
icculus@973
  2534
/**
icculus@1597
  2535
 * \fn int PHYSFS_caseFold(const PHYSFS_uint32 from, PHYSFS_uint32 *to)
icculus@1597
  2536
 * \brief "Fold" a Unicode codepoint to a lowercase equivalent.
icculus@1597
  2537
 *
icculus@1597
  2538
 * (This is for limited, hardcore use. If you don't immediately see a need
icculus@1597
  2539
 *  for it, you can probably ignore this forever.)
icculus@1597
  2540
 *
icculus@1597
  2541
 * This will convert a Unicode codepoint into its lowercase equivalent.
icculus@1597
  2542
 *  Bogus codepoints and codepoints without a lowercase equivalent will
icculus@1597
  2543
 *  be returned unconverted.
icculus@1597
  2544
 *
icculus@1597
  2545
 * Note that you might get multiple codepoints in return! The German Eszett,
icculus@1597
  2546
 *  for example, will fold down to two lowercase latin 's' codepoints. The
icculus@1597
  2547
 *  theory is that if you fold two strings, one with an Eszett and one with
icculus@1597
  2548
 *  "SS" down, they will match.
icculus@1597
  2549
 *
icculus@1597
  2550
 * \warning Anyone that is a student of Unicode knows about the "Turkish I"
icculus@1597
  2551
 *          problem. This API does not handle it. Assume this one letter
icculus@1597
  2552
 *          in all of Unicode will definitely fold sort of incorrectly. If
icculus@1597
  2553
 *          you don't know what this is about, you can probably ignore this
icculus@1597
  2554
 *          problem for most of the planet, but perfection is impossible.
icculus@1597
  2555
 *
icculus@1597
  2556
 *   \param from The codepoint to fold.
icculus@1597
  2557
 *   \param to Buffer to store the folded codepoint values into. This should
icculus@1597
  2558
 *             point to space for at least 3 PHYSFS_uint32 slots.
icculus@1597
  2559
 *  \return The number of codepoints the folding produced. Between 1 and 3.
icculus@1597
  2560
 */
icculus@1597
  2561
PHYSFS_DECL int PHYSFS_caseFold(const PHYSFS_uint32 from, PHYSFS_uint32 *to);
icculus@1597
  2562
icculus@1597
  2563
icculus@1597
  2564
/**
icculus@1555
  2565
 * \fn int PHYSFS_utf8stricmp(const char *str1, const char *str2)
icculus@1555
  2566
 * \brief Case-insensitive compare of two UTF-8 strings.
icculus@1555
  2567
 *
icculus@1555
  2568
 * This is a strcasecmp/stricmp replacement that expects both strings
icculus@1555
  2569
 *  to be in UTF-8 encoding. It will do "case folding" to decide if the
icculus@1555
  2570
 *  Unicode codepoints in the strings match.
icculus@1555
  2571
 *
icculus@1593
  2572
 * If both strings are exclusively low-ASCII characters, this will do the
icculus@1593
  2573
 *  right thing, as that is also valid UTF-8. If there are any high-ASCII
icculus@1593
  2574
 *  chars, this will not do what you expect!
icculus@1593
  2575
 *
icculus@1555
  2576
 * It will report which string is "greater than" the other, but be aware that
icculus@1555
  2577
 *  this doesn't necessarily mean anything: 'a' may be "less than" 'b', but
icculus@1555
  2578
 *  a Japanese kuten has no meaningful alphabetically relationship to
icculus@1555
  2579
 *  a Greek lambda, but being able to assign a reliable "value" makes sorting
icculus@1555
  2580
 *  algorithms possible, if not entirely sane. Most cases should treat the
icculus@1555
  2581
 *  return value as "equal" or "not equal".
icculus@1555
  2582
 *
icculus@1555
  2583
 * Like stricmp, this expects both strings to be NULL-terminated.
icculus@1555
  2584
 *
icculus@1555
  2585
 *   \param str1 First string to compare.
icculus@1555
  2586
 *   \param str2 Second string to compare.
icculus@1555
  2587
 *  \return -1 if str1 is "less than" str2, 1 if "greater than", 0 if equal.
icculus@1555
  2588
 */
icculus@1555
  2589
PHYSFS_DECL int PHYSFS_utf8stricmp(const char *str1, const char *str2);
icculus@1555
  2590
icculus@1595
  2591
/**
icculus@1595
  2592
 * \fn int PHYSFS_utf16stricmp(const PHYSFS_uint16 *str1, const PHYSFS_uint16 *str2)
icculus@1595
  2593
 * \brief Case-insensitive compare of two UTF-16 strings.
icculus@1595
  2594
 *
icculus@1595
  2595
 * This is a strcasecmp/stricmp replacement that expects both strings
icculus@1595
  2596
 *  to be in UTF-16 encoding. It will do "case folding" to decide if the
icculus@1595
  2597
 *  Unicode codepoints in the strings match.
icculus@1595
  2598
 *
icculus@1595
  2599
 * It will report which string is "greater than" the other, but be aware that
icculus@1595
  2600
 *  this doesn't necessarily mean anything: 'a' may be "less than" 'b', but
icculus@1595
  2601
 *  a Japanese kuten has no meaningful alphabetically relationship to
icculus@1595
  2602
 *  a Greek lambda, but being able to assign a reliable "value" makes sorting
icculus@1595
  2603
 *  algorithms possible, if not entirely sane. Most cases should treat the
icculus@1595
  2604
 *  return value as "equal" or "not equal".
icculus@1595
  2605
 *
icculus@1595
  2606
 * Like stricmp, this expects both strings to be NULL-terminated.
icculus@1595
  2607
 *
icculus@1595
  2608
 *   \param str1 First string to compare.
icculus@1595
  2609
 *   \param str2 Second string to compare.
icculus@1595
  2610
 *  \return -1 if str1 is "less than" str2, 1 if "greater than", 0 if equal.
icculus@1595
  2611
 */
icculus@1595
  2612
PHYSFS_DECL int PHYSFS_utf16stricmp(const PHYSFS_uint16 *str1,
icculus@1595
  2613
                                    const PHYSFS_uint16 *str2);
icculus@1595
  2614
icculus@1595
  2615
/**
icculus@1595
  2616
 * \fn int PHYSFS_ucs4stricmp(const PHYSFS_uint32 *str1, const PHYSFS_uint32 *str2)
icculus@1595
  2617
 * \brief Case-insensitive compare of two UCS-4 strings.
icculus@1595
  2618
 *
icculus@1595
  2619
 * This is a strcasecmp/stricmp replacement that expects both strings
icculus@1595
  2620
 *  to be in UCS-4 (aka UTF-32) encoding. It will do "case folding" to decide
icculus@1595
  2621
 *  if the Unicode codepoints in the strings match.
icculus@1595
  2622
 *
icculus@1595
  2623
 * It will report which string is "greater than" the other, but be aware that
icculus@1595
  2624
 *  this doesn't necessarily mean anything: 'a' may be "less than" 'b', but
icculus@1595
  2625
 *  a Japanese kuten has no meaningful alphabetically relationship to
icculus@1595
  2626
 *  a Greek lambda, but being able to assign a reliable "value" makes sorting
icculus@1595
  2627
 *  algorithms possible, if not entirely sane. Most cases should treat the
icculus@1595
  2628
 *  return value as "equal" or "not equal".
icculus@1595
  2629
 *
icculus@1595
  2630
 * Like stricmp, this expects both strings to be NULL-terminated.
icculus@1595
  2631
 *
icculus@1595
  2632
 *   \param str1 First string to compare.
icculus@1595
  2633
 *   \param str2 Second string to compare.
icculus@1595
  2634
 *  \return -1 if str1 is "less than" str2, 1 if "greater than", 0 if equal.
icculus@1595
  2635
 */
icculus@1595
  2636
PHYSFS_DECL int PHYSFS_ucs4stricmp(const PHYSFS_uint32 *str1,
icculus@1595
  2637
                                   const PHYSFS_uint32 *str2);
icculus@1595
  2638
icculus@1591
  2639
icculus@1591
  2640
/**
icculus@1591
  2641
 * \typedef PHYSFS_EnumerateCallback
icculus@1591
  2642
 * \brief Possible return values from PHYSFS_EnumerateCallback.
icculus@1591
  2643
 *
icculus@1591
  2644
 * These values dictate if an enumeration callback should continue to fire,
icculus@1591
  2645
 *  or stop (and why it is stopping).
icculus@1591
  2646
 *
icculus@1591
  2647
 * \sa PHYSFS_EnumerateCallback
icculus@1591
  2648
 * \sa PHYSFS_enumerate
icculus@1591
  2649
 */
icculus@1591
  2650
typedef enum PHYSFS_EnumerateCallbackResult
icculus@1591
  2651
{
icculus@1591
  2652
    PHYSFS_ENUM_ERROR = -1,   /**< Stop enumerating, report error to app. */
icculus@1591
  2653
    PHYSFS_ENUM_STOP = 0,     /**< Stop enumerating, report success to app. */
icculus@1591
  2654
    PHYSFS_ENUM_OK = 1        /**< Keep enumerating, no problems */
icculus@1591
  2655
} PHYSFS_EnumerateCallbackResult;
icculus@1591
  2656
icculus@1559
  2657
/**
icculus@1559
  2658
 * \typedef PHYSFS_EnumerateCallback
icculus@1559
  2659
 * \brief Function signature for callbacks that enumerate and return results.
icculus@1559
  2660
 *
icculus@1559
  2661
 * This is the same thing as PHYSFS_EnumFilesCallback from PhysicsFS 2.0,
icculus@1559
  2662
 *  except it can return a result from the callback: namely: if you're looking
icculus@1559
  2663
 *  for something specific, once you find it, you can tell PhysicsFS to stop
icculus@1559
  2664
 *  enumerating further. This is used with PHYSFS_enumerate(), which we
icculus@1559
  2665
 *  hopefully got right this time.  :)
icculus@1559
  2666
 *
icculus@1559
  2667
 *    \param data User-defined data pointer, passed through from the API