physfs.h
 changeset 265 6187d310b2c0 parent 240 052041af9001 child 322 597af607e7d3
equal inserted replaced
264:73699494faf9 265:6187d310b2c0
     1 /**
     1 /** \file physfs.h */

     2

     3 /**

     4  * \mainpage PhysicsFS

     5  *

     6  * The latest version of PhysicsFS can be found at:

     7  *     http://icculus.org/physfs/

     8  *
     2  * PhysicsFS; a portable, flexible file i/o abstraction.
     9  * PhysicsFS; a portable, flexible file i/o abstraction.
     3  *
    10  *
     4  * This API gives you access to a system file system in ways superior to the
    11  * This API gives you access to a system file system in ways superior to the
     5  *  stdio or system i/o calls. The brief benefits:
    12  *  stdio or system i/o calls. The brief benefits:
     6  *
    13  *
   118  *  ZIP archive by PhysicsFS; the file's contents are used to determine its
   125  *  ZIP archive by PhysicsFS; the file's contents are used to determine its
   119  *  type.
   126  *  type.
   120  *
   127  *
   121  * Currently supported archive types:
   128  * Currently supported archive types:
   122  *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)
   129  *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)
   123  *
   130  *   - .GRP (Build Engine groupfile archives)
   124  * Please see the file LICENSE in the source's root directory.
   131  *
   125  *
   132  * Please see the file LICENSE in the source's root directory for licensing
   126  *  This file written by Ryan C. Gordon.
   133  *  and redistribution rights.

   134  *

   135  * Please see the file CREDITS in the source's root directory for a complete

   136  *  list of who's responsible for this.

   137  *

   138  *  \author Ryan C. Gordon.
   127  */
   139  */
   128
   140
   129 #ifndef _INCLUDE_PHYSFS_H_
   141 #ifndef _INCLUDE_PHYSFS_H_
   130 #define _INCLUDE_PHYSFS_H_
   142 #define _INCLUDE_PHYSFS_H_
   131
   143
   132 #ifdef __cplusplus
   144 #ifdef __cplusplus
   133 extern "C" {
   145 extern "C" {
   134 #endif
   146 #endif
   135
   147

   148 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
   136 #if (defined _MSC_VER)
   149 #if (defined _MSC_VER)
   137 #define __EXPORT__ __declspec(dllexport)
   150 #define __EXPORT__ __declspec(dllexport)
   138 #else
   151 #else
   139 #define __EXPORT__
   152 #define __EXPORT__
   140 #endif
   153 #endif
   141
   154 #endif  /* DOXYGEN_SHOULD_IGNORE_THIS */

   155

   156 /**

   157  * \typedef PHYSFS_uint8

   158  * \brief An unsigned, 8-bit integer type.

   159  */
   142 typedef unsigned char         PHYSFS_uint8;
   160 typedef unsigned char         PHYSFS_uint8;

   161

   162 /**

   163  * \typedef PHYSFS_sint8

   164  * \brief A signed, 8-bit integer type.

   165  */
   143 typedef signed char           PHYSFS_sint8;
   166 typedef signed char           PHYSFS_sint8;

   167

   168 /**

   169  * \typedef PHYSFS_uint16

   170  * \brief An unsigned, 16-bit integer type.

   171  */
   144 typedef unsigned short        PHYSFS_uint16;
   172 typedef unsigned short        PHYSFS_uint16;

   173

   174 /**

   175  * \typedef PHYSFS_sint16

   176  * \brief A signed, 16-bit integer type.

   177  */
   145 typedef signed short          PHYSFS_sint16;
   178 typedef signed short          PHYSFS_sint16;

   179

   180 /**

   181  * \typedef PHYSFS_uint32

   182  * \brief An unsigned, 32-bit integer type.

   183  */
   146 typedef unsigned int          PHYSFS_uint32;
   184 typedef unsigned int          PHYSFS_uint32;

   185

   186 /**

   187  * \typedef PHYSFS_sint32

   188  * \brief A signed, 32-bit integer type.

   189  */
   147 typedef signed int            PHYSFS_sint32;
   190 typedef signed int            PHYSFS_sint32;

   191

   192 /**

   193  * \typedef PHYSFS_uint64

   194  * \brief An unsigned, 64-bit integer type.

   195  * \warning on platforms without any sort of 64-bit datatype, this is

   196  *           equivalent to PHYSFS_uint32!

   197  */

   198

   199 /**

   200  * \typedef PHYSFS_sint64

   201  * \brief A signed, 64-bit integer type.

   202  * \warning on platforms without any sort of 64-bit datatype, this is

   203  *           equivalent to PHYSFS_sint32!

   204  */

   205
   148
   206
   149 #if (defined PHYSFS_NO_64BIT_SUPPORT)  /* oh well. */
   207 #if (defined PHYSFS_NO_64BIT_SUPPORT)  /* oh well. */
   150 typedef PHYSFS_uint32         PHYSFS_uint64;
   208 typedef PHYSFS_uint32         PHYSFS_uint64;
   151 typedef PHYSFS_sint32         PHYSFS_sint64;
   209 typedef PHYSFS_sint32         PHYSFS_sint64;
   152 #elif (defined _MSC_VER)
   210 #elif (defined _MSC_VER)
   155 #else
   213 #else
   156 typedef unsigned long long    PHYSFS_uint64;
   214 typedef unsigned long long    PHYSFS_uint64;
   157 typedef signed long long      PHYSFS_sint64;
   215 typedef signed long long      PHYSFS_sint64;
   158 #endif
   216 #endif
   159
   217

   218

   219 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
   160 /* Make sure the types really have the right sizes */
   220 /* Make sure the types really have the right sizes */
   161 #define PHYSFS_COMPILE_TIME_ASSERT(name, x)               \
   221 #define PHYSFS_COMPILE_TIME_ASSERT(name, x)               \
   162        typedef int PHYSFS_dummy_ ## name[(x) * 2 - 1]
   222        typedef int PHYSFS_dummy_ ## name[(x) * 2 - 1]
   163
   223
   164 PHYSFS_COMPILE_TIME_ASSERT(uint8, sizeof(PHYSFS_uint8) == 1);
   224 PHYSFS_COMPILE_TIME_ASSERT(uint8, sizeof(PHYSFS_uint8) == 1);
   173 PHYSFS_COMPILE_TIME_ASSERT(sint64, sizeof(PHYSFS_sint64) == 8);
   233 PHYSFS_COMPILE_TIME_ASSERT(sint64, sizeof(PHYSFS_sint64) == 8);
   174 #endif
   234 #endif
   175
   235
   176 #undef PHYSFS_COMPILE_TIME_ASSERT
   236 #undef PHYSFS_COMPILE_TIME_ASSERT
   177
   237
   178
   238 #endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
   179
   239
   180 typedef struct __PHYSFS_FILE__
   240

   241 /**

   242  * \struct PHYSFS_file

   243  * \brief A PhysicsFS file handle.

   244  *

   245  * You get a pointer to one of these when you open a file for reading,

   246  *  writing, or appending via PhysicsFS.

   247  *

   248  * As you can see from the lack of meaningful fields, you should treat this

   249  *  as opaque data. Don't try to manipulate the file handle, just pass the

   250  *  pointer you got, unmolested, to various PhysicsFS APIs.

   251  *

   252  * \sa PHYSFS_openRead

   253  * \sa PHYSFS_openWrite

   254  * \sa PHYSFS_openAppend

   255  * \sa PHYSFS_close

   256  * \sa PHYSFS_read

   257  * \sa PHYSFS_write

   258  * \sa PHYSFS_seek

   259  * \sa PHYSFS_tell

   260  * \sa PHYSFS_eof

   261  */

   262 typedef struct
   181 {
   263 {
   182     void *opaque;
   264     void *opaque;  /**< That's all you get. Don't touch. */
   183 } PHYSFS_file;
   265 } PHYSFS_file;
   184
   266
   185 typedef struct __PHYSFS_ARCHIVEINFO__
   267

   268

   269 /**

   270  * \struct PHYSFS_ArchiveInfo

   271  * \brief Information on various PhysicsFS-supported archives.

   272  *

   273  * This structure gives you details on what sort of archives are supported

   274  *  by this implementation of PhysicsFS. Archives tend to be things like

   275  *  ZIP files and such.

   276  *

   277  * \warning Not all binaries are created equal! PhysicsFS can be built with

   278  *          or without support for various archives. You can check with

   279  *          PHYSFS_supportedArchiveTypes() to see if your archive type is

   280  *          supported.

   281  *

   282  * \sa PHYSFS_supportedArchiveTypes

   283  */

   284 typedef struct
   186 {
   285 {
   187     const char *extension;
   286     const char *extension;   /**< Archive file extension: "ZIP", for example. */
   188     const char *description;
   287     const char *description; /**< Human-readable archive description. */
   189     const char *author;
   288     const char *author;      /**< Person who did support for this archive. */
   190     const char *url;
   289     const char *url;         /**< URL related to this archive */
   191 } PHYSFS_ArchiveInfo;
   290 } PHYSFS_ArchiveInfo;
   192
   291
   193
   292 /**
   194 /* functions... */
   293  * \struct PHYSFS_Version
   195
   294  * \brief Information the version of PhysicsFS in use.
   196 typedef struct __PHYSFS_VERSION__
   295  *

   296  * Represents the library's version as three levels: major revision

   297  *  (increments with massive changes, additions, and enhancements),

   298  *  minor revision (increments with backwards-compatible changes to the

   299  *  major revision), and patchlevel (increments with fixes to the minor

   300  *  revision).

   301  *

   302  * \sa PHYSFS_VERSION

   303  * \sa PHYFS_getLinkedVersion

   304  */

   305 typedef struct
   197 {
   306 {
   198     PHYSFS_uint8 major;
   307     PHYSFS_uint8 major; /**< major revision */
   199     PHYSFS_uint8 minor;
   308     PHYSFS_uint8 minor; /**< minor revision */
   200     PHYSFS_uint8 patch;
   309     PHYSFS_uint8 patch; /**< patchlevel */
   201 } PHYSFS_Version;
   310 } PHYSFS_Version;
   202
   311

   312 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
   203 #define PHYSFS_VER_MAJOR 0
   313 #define PHYSFS_VER_MAJOR 0
   204 #define PHYSFS_VER_MINOR 1
   314 #define PHYSFS_VER_MINOR 1
   205 #define PHYSFS_VER_PATCH 6
   315 #define PHYSFS_VER_PATCH 6
   206
   316 #endif  /* DOXYGEN_SHOULD_IGNORE_THIS */
   207 #define PHYSFS_VERSION(x) { \
   317
   208                             (x)->major = PHYSFS_VER_MAJOR; \
   318 /**
   209                             (x)->minor = PHYSFS_VER_MINOR; \
   319  * \def PHYSFS_VERSION(x)
   210                             (x)->patch = PHYSFS_VER_PATCH; \
   320  * \brief Macro to determine PhysicsFS version program was compiled against.
   211                           }
   321  *
   212
   322  * This macro fills in a PHYSFS_Version structure with the version of the
   213 /**
   323  *  library you compiled against. This is determined by what header the
   214  * Get the version of PhysicsFS that is linked against your program. If you
   324  *  compiler uses. Note that if you dynamically linked the library, you might
   215  *  are using a shared library (DLL) version of PhysFS, then it is possible
   325  *  have a slightly newer or older version at runtime. That version can be
   216  *  that it will be different than the version you compiled against.
   326  *  determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,

   327  *  is not a macro.

   328  *

   329  * \param x A pointer to a PHYSFS_Version struct to initialize.

   330  *

   331  * \sa PHYSFS_Version

   332  * \sa PHYSFS_getLinkedVersion

   333  */

   334 #define PHYSFS_VERSION(x) \

   335 { \

   336     (x)->major = PHYSFS_VER_MAJOR; \

   337     (x)->minor = PHYSFS_VER_MINOR; \

   338     (x)->patch = PHYSFS_VER_PATCH; \

   339 }

   340

   341

   342 /**

   343  * \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)

   344  * \brief Get the version of PhysicsFS that is linked against your program.

   345  *

   346  * If you are using a shared library (DLL) version of PhysFS, then it is

   347  *  possible that it will be different than the version you compiled against.
   217  *
   348  *
   218  * This is a real function; the macro PHYSFS_VERSION tells you what version
   349  * This is a real function; the macro PHYSFS_VERSION tells you what version
   219  *  of PhysFS you compiled against:
   350  *  of PhysFS you compiled against:
   220  *
   351  *

   352  * \code
   221  * PHYSFS_Version compiled;
   353  * PHYSFS_Version compiled;
   222  * PHYSFS_Version linked;
   354  * PHYSFS_Version linked;
   223  *
   355  *
   224  * PHYSFS_VERSION(&compiled);
   356  * PHYSFS_VERSION(&compiled);
   225  * PHYSFS_getLinkedVersion(&linked);
   357  * PHYSFS_getLinkedVersion(&linked);
   226  * printf("We compiled against PhysFS version %d.%d.%d ...\n",
   358  * printf("We compiled against PhysFS version %d.%d.%d ...\n",
   227  *           compiled.major, compiled.minor, compiled.patch);
   359  *           compiled.major, compiled.minor, compiled.patch);
   228  * printf("But we linked against PhysFS version %d.%d.%d.\n",
   360  * printf("But we linked against PhysFS version %d.%d.%d.\n",
   229  *           linked.major, linked.minor, linked.patch);
   361  *           linked.major, linked.minor, linked.patch);

   362  * \endcode
   230  *
   363  *
   231  * This function may be called safely at any time, even before PHYSFS_init().
   364  * This function may be called safely at any time, even before PHYSFS_init().

   365  *

   366  * \sa PHYSFS_VERSION
   232  */
   367  */
   233 __EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
   368 __EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
   234
   369
   235
   370
   236 /**
   371 /**
   237  * Initialize PhysicsFS. This must be called before any other PhysicsFS
   372  * \fn int PHYSFS_init(const char *argv0)
   238  *  function.
   373  * \brief Initialize the PhysicsFS library.

   374  *

   375  * This must be called before any other PhysicsFS function.
   239  *
   376  *
   240  * This should be called prior to any attempts to change your process's
   377  * This should be called prior to any attempts to change your process's
   241  *  current working directory.
   378  *  current working directory.
   242  *
   379  *
   243  *   @param argv0 the argv[0] string passed to your program's mainline.
   380  *   \param argv0 the argv[0] string passed to your program's mainline.
   244  *  @return nonzero on success, zero on error. Specifics of the error can be
   381  *          This may be NULL on most platforms (such as ones without a

   382  *          standard main() function), but you should always try to pass

   383  *          something in here. Unix-like systems such as Linux _need_ to

   384  *          pass argv[0] from main() in here.

   385  *  \return nonzero on success, zero on error. Specifics of the error can be
   245  *          gleaned from PHYSFS_getLastError().
   386  *          gleaned from PHYSFS_getLastError().

   387  *

   388  * \sa PHYSFS_deinit
   246  */
   389  */
   247 __EXPORT__ int PHYSFS_init(const char *argv0);
   390 __EXPORT__ int PHYSFS_init(const char *argv0);
   248
   391
   249
   392
   250 /**
   393 /**
   251  * Shutdown PhysicsFS. This closes any files opened via PhysicsFS, blanks the
   394  * \fn int PHYSFS_deinit(void)
   252  *  search/write paths, frees memory, and invalidates all of your handles.
   395  * \brief Deinitialize the PhysicsFS library.

   396  *

   397  * This closes any files opened via PhysicsFS, blanks the search/write paths,

   398  *  frees memory, and invalidates all of your file handles.
   253  *
   399  *
   254  * Note that this call can FAIL if there's a file open for writing that
   400  * Note that this call can FAIL if there's a file open for writing that
   255  *  refuses to close (for example, the underlying operating system was
   401  *  refuses to close (for example, the underlying operating system was
   256  *  buffering writes to network filesystem, and the fileserver has crashed,
   402  *  buffering writes to network filesystem, and the fileserver has crashed,
   257  *  or a hard drive has failed, etc). It is usually best to close all write
   403  *  or a hard drive has failed, etc). It is usually best to close all write
   260  *
   406  *
   261  * Once successfully deinitialized, PHYSFS_init() can be called again to
   407  * Once successfully deinitialized, PHYSFS_init() can be called again to
   262  *  restart the subsystem. All defaults API states are restored at this
   408  *  restart the subsystem. All defaults API states are restored at this
   263  *  point.
   409  *  point.
   264  *
   410  *
   265  *  @return nonzero on success, zero on error. Specifics of the error can be
   411  *  \return nonzero on success, zero on error. Specifics of the error can be
   266  *          gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
   412  *          gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
   267  *          undefined, and probably badly screwed up.
   413  *          undefined, and probably badly screwed up.

   414  *

   415  * \sa PHYSFS_init
   268  */
   416  */
   269 __EXPORT__ int PHYSFS_deinit(void);
   417 __EXPORT__ int PHYSFS_deinit(void);
   270
   418
   271
   419
   272 /**
   420 /**

   421  * \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)

   422  * \brief Get a list of supported archive types.

   423  *
   273  * Get a list of archive types supported by this implementation of PhysicFS.
   424  * Get a list of archive types supported by this implementation of PhysicFS.
   274  *  These are the file formats usable for search path entries. This is for
   425  *  These are the file formats usable for search path entries. This is for
   275  *  informational purposes only. Note that the extension listed is merely
   426  *  informational purposes only. Note that the extension listed is merely
   276  *  convention: if we list "ZIP", you can open a PkZip-compatible archive
   427  *  convention: if we list "ZIP", you can open a PkZip-compatible archive
   277  *  with an extension of "XYZ", if you like.
   428  *  with an extension of "XYZ", if you like.
   278  *
   429  *
   279  * The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
   430  * The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
   280  *  with a NULL entry to signify the end of the list:
   431  *  with a NULL entry to signify the end of the list:
   281  *
   432  *

   433  * \code
   282  * PHYSFS_ArchiveInfo **i;
   434  * PHYSFS_ArchiveInfo **i;
   283  *
   435  *
   284  * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
   436  * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
   285  * {
   437  * {
   286  *     printf("Supported archive: [%s], which is [%s].\n",
   438  *     printf("Supported archive: [%s], which is [%s].\n",
   287  *              i->extension, i->description);
   439  *              i->extension, i->description);
   288  * }
   440  * }

   441  * \endcode
   289  *
   442  *
   290  * The return values are pointers to static internal memory, and should
   443  * The return values are pointers to static internal memory, and should
   291  *  be considered READ ONLY, and never freed.
   444  *  be considered READ ONLY, and never freed.
   292  *
   445  *
   293  *   @return READ ONLY Null-terminated array of READ ONLY structures.
   446  *   \return READ ONLY Null-terminated array of READ ONLY structures.
   294  */
   447  */
   295 __EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
   448 __EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
   296
   449
   297
   450
   298 /**
   451 /**

   452  * \fn void PHYSFS_freeList(void *listVar)

   453  * \brief Deallocate resources of lists returned by PhysicsFS.

   454  *
   299  * Certain PhysicsFS functions return lists of information that are
   455  * Certain PhysicsFS functions return lists of information that are
   300  *  dynamically allocated. Use this function to free those resources.
   456  *  dynamically allocated. Use this function to free those resources.
   301  *
   457  *
   302  *   @param list List of information specified as freeable by this function.
   458  *   \param listVar List of information specified as freeable by this function.

   459  *

   460  * \sa PHYSFS_getCdRomDirs

   461  * \sa PHYSFS_enumerateFiles

   462  * \sa PHYSFS_getSearchPath
   303  */
   463  */
   304 __EXPORT__ void PHYSFS_freeList(void *listVar);
   464 __EXPORT__ void PHYSFS_freeList(void *listVar);
   305
   465
   306
   466
   307 /**
   467 /**

   468  * \fn const char *PHYSFS_getLastError(void)

   469  * \brief Get human-readable error information.

   470  *
   308  * Get the last PhysicsFS error message as a null-terminated string.
   471  * Get the last PhysicsFS error message as a null-terminated string.
   309  *  This will be NULL if there's been no error since the last call to this
   472  *  This will be NULL if there's been no error since the last call to this
   310  *  function. The pointer returned by this call points to an internal buffer.
   473  *  function. The pointer returned by this call points to an internal buffer.
   311  *  Each thread has a unique error state associated with it, but each time
   474  *  Each thread has a unique error state associated with it, but each time
   312  *  a new error message is set, it will overwrite the previous one associated
   475  *  a new error message is set, it will overwrite the previous one associated
   313  *  with that thread. It is safe to call this function at anytime, even
   476  *  with that thread. It is safe to call this function at anytime, even
   314  *  before PHYSFS_init().
   477  *  before PHYSFS_init().
   315  *
   478  *
   316  *   @return READ ONLY string of last error message.
   479  *   \return READ ONLY string of last error message.
   317  */
   480  */
   318 __EXPORT__ const char *PHYSFS_getLastError(void);
   481 __EXPORT__ const char *PHYSFS_getLastError(void);
   319
   482
   320
   483
   321 /**
   484 /**
   322  * Get a platform-dependent dir separator. This is "\\" on win32, "/" on Unix,
   485  * \fn const char *PHYSFS_getDirSeparator(void)
   323  *  and ":" on MacOS. It may be more than one character, depending on the
   486  * \brief Get platform-dependent dir separator string.
   324  *  platform, and your code should take that into account. Note that this is
   487  *
   325  *  only useful for setting up the search/write paths, since access into those
   488  * This returns "\\\\" on win32, "/" on Unix, and ":" on MacOS. It may be more
   326  *  dirs always use '/' (platform-independent notation) to separate
   489  *  than one character, depending on the platform, and your code should take
   327  *  directories. This is also handy for getting platform-independent access
   490  *  that into account. Note that this is only useful for setting up the
   328  *  when using stdio calls.
   491  *  search/write paths, since access into those dirs always use '/'
   329  *
   492  *  (platform-independent notation) to separate directories. This is also
   330  *   @return READ ONLY null-terminated string of platform's dir separator.
   493  *  handy for getting platform-independent access when using stdio calls.

   494  *

   495  *   \return READ ONLY null-terminated string of platform's dir separator.
   331  */
   496  */
   332 __EXPORT__ const char *PHYSFS_getDirSeparator(void);
   497 __EXPORT__ const char *PHYSFS_getDirSeparator(void);
   333
   498
   334
   499
   335 /**
   500 /**
   336  * Enable symbolic links. Some physical filesystems and archives contain
   501  * \fn void PHYSFS_permitSymbolicLinks(int allow)
   337  *  files that are just pointers to other files. On the physical filesystem,
   502  * \brief Enable or disable following of symbolic links.
   338  *  opening such a link will (transparently) open the file that is pointed to.
   503  *

   504  * Some physical filesystems and archives contain files that are just pointers

   505  *  to other files. On the physical filesystem, opening such a link will

   506  *  (transparently) open the file that is pointed to.
   339  *
   507  *
   340  * By default, PhysicsFS will check if a file is really a symlink during open
   508  * By default, PhysicsFS will check if a file is really a symlink during open
   341  *  calls and fail if it is. Otherwise, the link could take you outside the
   509  *  calls and fail if it is. Otherwise, the link could take you outside the
   342  *  write and search paths, and compromise security.
   510  *  write and search paths, and compromise security.
   343  *
   511  *
   350  *
   518  *
   351  * Symlinks are only explicitly checked when dealing with filenames
   519  * Symlinks are only explicitly checked when dealing with filenames
   352  *  in platform-independent notation. That is, when setting up your
   520  *  in platform-independent notation. That is, when setting up your
   353  *  search and write paths, etc, symlinks are never checked for.
   521  *  search and write paths, etc, symlinks are never checked for.
   354  *
   522  *
   355  * Symbolic link permission can be enabled or disabled at any time, and is
   523  * Symbolic link permission can be enabled or disabled at any time after
   356  *  disabled by default.
   524  *  you've called PHYSFS_init(), and is disabled by default.
   357  *
   525  *
   358  *   @param allow nonzero to permit symlinks, zero to deny linking.
   526  *   \param allow nonzero to permit symlinks, zero to deny linking.
   359  */
   527  */
   360 __EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
   528 __EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
   361
   529
   362
   530
   363 /**
   531 /**
   364  * Get an array of dirs to available CD-ROM drives.
   532  * \fn char **PHYSFS_getCdRomDirs(void)

   533  * \brief Get an array of paths to available CD-ROM drives.
   365  *
   534  *
   366  * The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
   535  * The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
   367  *  whatnot on Unix). Dirs are only returned if there is a disc ready and
   536  *  whatnot on Unix). Dirs are only returned if there is a disc ready and
   368  *  accessible in the drive. So if you've got two drives (D: and E:), and only
   537  *  accessible in the drive. So if you've got two drives (D: and E:), and only
   369  *  E: has a disc in it, then that's all you get. If the user inserts a disc
   538  *  E: has a disc in it, then that's all you get. If the user inserts a disc
   372  *  call to this function will reflect that change. Fun.
   541  *  call to this function will reflect that change. Fun.
   373  *
   542  *
   374  * The returned value is an array of strings, with a NULL entry to signify the
   543  * The returned value is an array of strings, with a NULL entry to signify the
   375  *  end of the list:
   544  *  end of the list:
   376  *
   545  *

   546  * \code
   377  * char **cds = PHYSFS_getCdRomDirs();
   547  * char **cds = PHYSFS_getCdRomDirs();
   378  * char **i;
   548  * char **i;
   379  *
   549  *
   380  * for (i = cds; *i != NULL; i++)
   550  * for (i = cds; *i != NULL; i++)
   381  *     printf("cdrom dir [%s] is available.\n", *i);
   551  *     printf("cdrom dir [%s] is available.\n", *i);
   382  *
   552  *
   383  * PHYSFS_freeList(cds);
   553  * PHYSFS_freeList(cds);

   554  * \endcode
   384  *
   555  *
   385  * This call may block while drives spin up. Be forewarned.
   556  * This call may block while drives spin up. Be forewarned.
   386  *
   557  *
   387  * When you are done with the returned information, you may dispose of the
   558  * When you are done with the returned information, you may dispose of the
   388  *  resources by calling PHYSFS_freeList() with the returned pointer.
   559  *  resources by calling PHYSFS_freeList() with the returned pointer.
   389  *
   560  *
   390  *   @return Null-terminated array of null-terminated strings.
   561  *   \return Null-terminated array of null-terminated strings.
   391  */
   562  */
   392 __EXPORT__ char **PHYSFS_getCdRomDirs(void);
   563 __EXPORT__ char **PHYSFS_getCdRomDirs(void);
   393
   564
   394
   565
   395 /**
   566 /**

   567  * \fn const char *PHYSFS_getBaseDir(void)

   568  * \brief Get the path where the application resides.

   569  *
   396  * Helper function.
   570  * Helper function.
   397  *
   571  *
   398  * Get the "base dir". This is the directory where the application was run
   572  * Get the "base dir". This is the directory where the application was run
   399  *  from, which is probably the installation directory, and may or may not
   573  *  from, which is probably the installation directory, and may or may not
   400  *  be the process's current working directory.
   574  *  be the process's current working directory.
   401  *
   575  *
   402  * You should probably use the base dir in your search path.
   576  * You should probably use the base dir in your search path.
   403  *
   577  *
   404  *  @return READ ONLY string of base dir in platform-dependent notation.
   578  *  \return READ ONLY string of base dir in platform-dependent notation.

   579  *

   580  * \sa PHYSFS_getUserDir
   405  */
   581  */
   406 __EXPORT__ const char *PHYSFS_getBaseDir(void);
   582 __EXPORT__ const char *PHYSFS_getBaseDir(void);
   407
   583
   408
   584
   409 /**
   585 /**

   586  * \fn const char *PHYSFS_getUserDir(void)

   587  * \brief Get the path where user's home directory resides.

   588  *
   410  * Helper function.
   589  * Helper function.
   411  *
   590  *
   412  * Get the "user dir". This is meant to be a suggestion of where a specific
   591  * Get the "user dir". This is meant to be a suggestion of where a specific
   413  *  user of the system can store files. On Unix, this is her home directory.
   592  *  user of the system can store files. On Unix, this is her home directory.
   414  *  On systems with no concept of multiple home directories (MacOS, win95),
   593  *  On systems with no concept of multiple home directories (MacOS, win95),
   417  *  platform doesn't support multiple users, either.
   596  *  platform doesn't support multiple users, either.
   418  *
   597  *
   419  * You should probably use the user dir as the basis for your write dir, and
   598  * You should probably use the user dir as the basis for your write dir, and
   420  *  also put it near the beginning of your search path.
   599  *  also put it near the beginning of your search path.
   421  *
   600  *
   422  *  @return READ ONLY string of user dir in platform-dependent notation.
   601  *  \return READ ONLY string of user dir in platform-dependent notation.

   602  *

   603  * \sa PHYSFS_getBaseDir
   423  */
   604  */
   424 __EXPORT__ const char *PHYSFS_getUserDir(void);
   605 __EXPORT__ const char *PHYSFS_getUserDir(void);
   425
   606
   426
   607
   427 /**
   608 /**

   609  * \fn const char *PHYSFS_getWriteDir(void)

   610  * \brief Get path where PhysicsFS will allow file writing.

   611  *
   428  * Get the current write dir. The default write dir is NULL.
   612  * Get the current write dir. The default write dir is NULL.
   429  *
   613  *
   430  *  @return READ ONLY string of write dir in platform-dependent notation,
   614  *  \return READ ONLY string of write dir in platform-dependent notation,
   431  *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.
   615  *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.

   616  *

   617  * \sa PHYSFS_setWriteDir
   432  */
   618  */
   433 __EXPORT__ const char *PHYSFS_getWriteDir(void);
   619 __EXPORT__ const char *PHYSFS_getWriteDir(void);
   434
   620
   435
   621
   436 /**
   622 /**

   623  * \fn int PHYSFS_setWriteDir(const char *newDir)

   624  * \brief Tell PhysicsFS where it may write files.

   625  *
   437  * Set a new write dir. This will override the previous setting. If the
   626  * Set a new write dir. This will override the previous setting. If the
   438  *  directory or a parent directory doesn't exist in the physical filesystem,
   627  *  directory or a parent directory doesn't exist in the physical filesystem,
   439  *  PhysicsFS will attempt to create them as needed.
   628  *  PhysicsFS will attempt to create them as needed.
   440  *
   629  *
   441  * This call will fail (and fail to change the write dir) if the current
   630  * This call will fail (and fail to change the write dir) if the current
   442  *  write dir still has files open in it.
   631  *  write dir still has files open in it.
   443  *
   632  *
   444  *   @param newDir The new directory to be the root of the write dir,
   633  *   \param newDir The new directory to be the root of the write dir,
   445  *                   specified in platform-dependent notation. Setting to NULL
   634  *                   specified in platform-dependent notation. Setting to NULL
   446  *                   disables the write dir, so no files can be opened for
   635  *                   disables the write dir, so no files can be opened for
   447  *                   writing via PhysicsFS.
   636  *                   writing via PhysicsFS.
   448  *  @return non-zero on success, zero on failure. All attempts to open a file
   637  *  \return non-zero on success, zero on failure. All attempts to open a file
   449  *           for writing via PhysicsFS will fail until this call succeeds.
   638  *           for writing via PhysicsFS will fail until this call succeeds.
   450  *           Specifics of the error can be gleaned from PHYSFS_getLastError().
   639  *           Specifics of the error can be gleaned from PHYSFS_getLastError().
   451  *
   640  *

   641  * \sa PHYSFS_getWriteDir
   452  */
   642  */
   453 __EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
   643 __EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
   454
   644
   455
   645
   456 /**
   646 /**
   457  * Add a directory or archive to the search path. If this is a duplicate, the
   647  * \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
   458  *  entry is not added again, even though the function succeeds.
   648  * \brief Add an archive or directory to the search path.
   459  *
   649  *
   460  *   @param newDir directory or archive to add to the path, in
   650  * If this is a duplicate, the entry is not added again, even though the

   651  *  function succeeds.

   652  *

   653  *   \param newDir directory or archive to add to the path, in
   461  *                   platform-dependent notation.
   654  *                   platform-dependent notation.
   462  *   @param appendToPath nonzero to append to search path, zero to prepend.
   655  *   \param appendToPath nonzero to append to search path, zero to prepend.
   463  *  @return nonzero if added to path, zero on failure (bogus archive, dir
   656  *  \return nonzero if added to path, zero on failure (bogus archive, dir
   464  *                   missing, etc). Specifics of the error can be
   657  *                   missing, etc). Specifics of the error can be
   465  *                   gleaned from PHYSFS_getLastError().
   658  *                   gleaned from PHYSFS_getLastError().

   659  *

   660  * \sa PHYSFS_removeFromSearchPath

   661  * \sa PHYSFS_getSearchPath
   466  */
   662  */
   467 __EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
   663 __EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
   468
   664
   469
   665
   470 /**
   666 /**
   471  * Remove a directory or archive from the search path.
   667  * \fn int PHYSFS_removeFromSearchPath(const char *oldDir)

   668  * \brief Remove a directory or archive from the search path.
   472  *
   669  *
   473  * This must be a (case-sensitive) match to a dir or archive already in the
   670  * This must be a (case-sensitive) match to a dir or archive already in the
   474  *  search path, specified in platform-dependent notation.
   671  *  search path, specified in platform-dependent notation.
   475  *
   672  *
   476  * This call will fail (and fail to remove from the path) if the element still
   673  * This call will fail (and fail to remove from the path) if the element still
   477  *  has files open in it.
   674  *  has files open in it.
   478  *
   675  *
   479  *    @param oldDir dir/archive to remove.
   676  *    \param oldDir dir/archive to remove.
   480  *   @return nonzero on success, zero on failure.
   677  *   \return nonzero on success, zero on failure.
   481  *            Specifics of the error can be gleaned from PHYSFS_getLastError().
   678  *            Specifics of the error can be gleaned from PHYSFS_getLastError().

   679  *

   680  * \sa PHYSFS_addToSearchPath

   681  * \sa PHYSFS_getSearchPath
   482  */
   682  */
   483 __EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
   683 __EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
   484
   684
   485
   685
   486 /**
   686 /**
   487  * Get the current search path. The default search path is an empty list.
   687  * \fn char **PHYSFS_getSearchPath(void)

   688  * \brief Get the current search path.

   689  *

   690  * The default search path is an empty list.
   488  *
   691  *
   489  * The returned value is an array of strings, with a NULL entry to signify the
   692  * The returned value is an array of strings, with a NULL entry to signify the
   490  *  end of the list:
   693  *  end of the list:
   491  *
   694  *

   695  * \code
   492  * char **i;
   696  * char **i;
   493  *
   697  *
   494  * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
   698  * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
   495  *     printf("[%s] is in the search path.\n", *i);
   699  *     printf("[%s] is in the search path.\n", *i);

   700  * \endcode
   496  *
   701  *
   497  * When you are done with the returned information, you may dispose of the
   702  * When you are done with the returned information, you may dispose of the
   498  *  resources by calling PHYSFS_freeList() with the returned pointer.
   703  *  resources by calling PHYSFS_freeList() with the returned pointer.
   499  *
   704  *
   500  *   @return Null-terminated array of null-terminated strings. NULL if there
   705  *   \return Null-terminated array of null-terminated strings. NULL if there
   501  *            was a problem (read: OUT OF MEMORY).
   706  *            was a problem (read: OUT OF MEMORY).

   707  *

   708  * \sa PHYSFS_addToSearchPath

   709  * \sa PHYSFS_removeFromSearchPath
   502  */
   710  */
   503 __EXPORT__ char **PHYSFS_getSearchPath(void);
   711 __EXPORT__ char **PHYSFS_getSearchPath(void);
   504
   712
   505
   713
   506 /**
   714 /**

   715  * \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)

   716  * \brief Set up sane, default paths.

   717  *
   507  * Helper function.
   718  * Helper function.
   508  *
   719  *
   509  * Set up sane, default paths. The write dir will be set to
   720  * The write dir will be set to "userdir/.organization/appName", which is
   510  *  "userdir/.organization/appName", which is created if it doesn't exist.
   721  *  created if it doesn't exist.
   511  *
   722  *
   512  * The above is sufficient to make sure your program's configuration directory
   723  * The above is sufficient to make sure your program's configuration directory
   513  *  is separated from other clutter, and platform-independent. The period
   724  *  is separated from other clutter, and platform-independent. The period
   514  *  before "mygame" even hides the directory on Unix systems.
   725  *  before "mygame" even hides the directory on Unix systems.
   515  *
   726  *
   527  *  order, regardless of which directories they were found in.
   738  *  order, regardless of which directories they were found in.
   528  *
   739  *
   529  * All of this can be accomplished from the application, but this just does it
   740  * All of this can be accomplished from the application, but this just does it
   530  *  all for you. Feel free to add more to the search path manually, too.
   741  *  all for you. Feel free to add more to the search path manually, too.
   531  *
   742  *
   532  *    @param organization Name of your company/group/etc to be used as a
   743  *    \param organization Name of your company/group/etc to be used as a
   533  *                         dirname, so keep it small, and no-frills.
   744  *                         dirname, so keep it small, and no-frills.
   534  *
   745  *
   535  *    @param appName Program-specific name of your program, to separate it
   746  *    \param appName Program-specific name of your program, to separate it
   536  *                   from other programs using PhysicsFS.
   747  *                   from other programs using PhysicsFS.
   537  *
   748  *
   538  *    @param archiveExt File extention used by your program to specify an
   749  *    \param archiveExt File extention used by your program to specify an
   539  *                      archive. For example, Quake 3 uses "pk3", even though
   750  *                      archive. For example, Quake 3 uses "pk3", even though
   540  *                      they are just zipfiles. Specify NULL to not dig out
   751  *                      they are just zipfiles. Specify NULL to not dig out
   541  *                      archives automatically. Do not specify the '.' char;
   752  *                      archives automatically. Do not specify the '.' char;
   542  *                      If you want to look for ZIP files, specify "ZIP" and
   753  *                      If you want to look for ZIP files, specify "ZIP" and
   543  *                      not ".ZIP" ... the archive search is case-insensitive.
   754  *                      not ".ZIP" ... the archive search is case-insensitive.
   544  *
   755  *
   545  *    @param includeCdRoms Non-zero to include CD-ROMs in the search path, and
   756  *    \param includeCdRoms Non-zero to include CD-ROMs in the search path, and
   546  *                         (if (archiveExt) != NULL) search them for archives.
   757  *                         (if (archiveExt) != NULL) search them for archives.
   547  *                         This may cause a significant amount of blocking
   758  *                         This may cause a significant amount of blocking
   548  *                         while discs are accessed, and if there are no discs
   759  *                         while discs are accessed, and if there are no discs
   549  *                         in the drive (or even not mounted on Unix systems),
   760  *                         in the drive (or even not mounted on Unix systems),
   550  *                         then they may not be made available anyhow. You may
   761  *                         then they may not be made available anyhow. You may
   551  *                         want to specify zero and handle the disc setup
   762  *                         want to specify zero and handle the disc setup
   552  *                         yourself.
   763  *                         yourself.
   553  *
   764  *
   554  *    @param archivesFirst Non-zero to prepend the archives to the search path.
   765  *    \param archivesFirst Non-zero to prepend the archives to the search path.
   555  *                          Zero to append them. Ignored if !(archiveExt).
   766  *                          Zero to append them. Ignored if !(archiveExt).
   556  *
   767  *
   557  *  @return nonzero on success, zero on error. Specifics of the error can be
   768  *  \return nonzero on success, zero on error. Specifics of the error can be
   558  *          gleaned from PHYSFS_getLastError().
   769  *          gleaned from PHYSFS_getLastError().
   559  */
   770  */
   560 __EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
   771 __EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
   561                                     const char *appName,
   772                                     const char *appName,
   562                                     const char *archiveExt,
   773                                     const char *archiveExt,
   563                                     int includeCdRoms,
   774                                     int includeCdRoms,
   564                                     int archivesFirst);
   775                                     int archivesFirst);
   565
   776
   566
   777
   567 /**
   778 /**
   568  * Create a directory. This is specified in platform-independent notation in
   779  * \fn int PHYSFS_mkdir(const char *dirName)
   569  *  relation to the write dir. All missing parent directories are also
   780  * \brief Create a directory.
   570  *  created if they don't exist.
   781  *

   782  * This is specified in platform-independent notation in relation to the

   783  *  write dir. All missing parent directories are also created if they

   784  *  don't exist.
   571  *
   785  *
   572  * So if you've got the write dir set to "C:\mygame\writedir" and call
   786  * So if you've got the write dir set to "C:\mygame\writedir" and call
   573  *  PHYSFS_mkdir("downloads/maps") then the directories
   787  *  PHYSFS_mkdir("downloads/maps") then the directories
   574  *  "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
   788  *  "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
   575  *  will be created if possible. If the creation of "maps" fails after we
   789  *  will be created if possible. If the creation of "maps" fails after we
   576  *  have successfully created "downloads", then the function leaves the
   790  *  have successfully created "downloads", then the function leaves the
   577  *  created directory behind and reports failure.
   791  *  created directory behind and reports failure.
   578  *
   792  *
   579  *   @param dirname New dir to create.
   793  *   \param dirName New dir to create.
   580  *  @return nonzero on success, zero on error. Specifics of the error can be
   794  *  \return nonzero on success, zero on error. Specifics of the error can be
   581  *          gleaned from PHYSFS_getLastError().
   795  *          gleaned from PHYSFS_getLastError().

   796  *

   797  * \sa PHYSFS_delete
   582  */
   798  */
   583 __EXPORT__ int PHYSFS_mkdir(const char *dirName);
   799 __EXPORT__ int PHYSFS_mkdir(const char *dirName);
   584
   800
   585
   801
   586 /**
   802 /**
   587  * Delete a file or directory. This is specified in platform-independent
   803  * \fn int PHYSFS_delete(const char *filename)
   588  *  notation in relation to the write dir.
   804  * \brief Delete a file or directory.

   805  *

   806  * (filename) is specified in platform-independent notation in relation to the

   807  *  write dir.
   589  *
   808  *
   590  * A directory must be empty before this call can delete it.
   809  * A directory must be empty before this call can delete it.
   591  *
   810  *
   592  * Deleting a symlink will remove the link, not what it points to, regardless
   811  * Deleting a symlink will remove the link, not what it points to, regardless
   593  *  of whether you "permitSymLinks" or not.
   812  *  of whether you "permitSymLinks" or not.
   604  *
   823  *
   605  * Chances are, the bits that make up the file still exist, they are just
   824  * Chances are, the bits that make up the file still exist, they are just
   606  *  made available to be written over at a later point. Don't consider this
   825  *  made available to be written over at a later point. Don't consider this
   607  *  a security method or anything.  :)
   826  *  a security method or anything.  :)
   608  *
   827  *
   609  *   @param filename Filename to delete.
   828  *   \param filename Filename to delete.
   610  *  @return nonzero on success, zero on error. Specifics of the error can be
   829  *  \return nonzero on success, zero on error. Specifics of the error can be
   611  *          gleaned from PHYSFS_getLastError().
   830  *          gleaned from PHYSFS_getLastError().
   612  */
   831  */
   613 __EXPORT__ int PHYSFS_delete(const char *filename);
   832 __EXPORT__ int PHYSFS_delete(const char *filename);
   614
   833
   615
   834
   616 /**
   835 /**
   617  * Figure out where in the search path a file resides. The file is specified
   836  * \fn const char *PHYSFS_getRealDir(const char *filename)
   618  *  in platform-independent notation. The returned filename will be the
   837  * \brief Figure out where in the search path a file resides.
   619  *  element of the search path where the file was found, which may be a
   838  *
   620  *  directory, or an archive. Even if there are multiple matches in different
   839  * The file is specified in platform-independent notation. The returned
   621  *  parts of the search path, only the first one found is used, just like
   840  *  filename will be the element of the search path where the file was found,
   622  *  when opening a file.
   841  *  which may be a directory, or an archive. Even if there are multiple

   842  *  matches in different parts of the search path, only the first one found

   843  *  is used, just like when opening a file.
   623  *
   844  *
   624  * So, if you look for "maps/level1.map", and C:\mygame is in your search
   845  * So, if you look for "maps/level1.map", and C:\mygame is in your search
   625  *  path and C:\mygame\maps\level1.map exists, then "C:\mygame" is returned.
   846  *  path and C:\mygame\maps\level1.map exists, then "C:\mygame" is returned.
   626  *
   847  *
   627  * If a any part of a match is a symbolic link, and you've not explicitly
   848  * If a any part of a match is a symbolic link, and you've not explicitly
   628  *  permitted symlinks, then it will be ignored, and the search for a match
   849  *  permitted symlinks, then it will be ignored, and the search for a match
   629  *  will continue.
   850  *  will continue.
   630  *
   851  *
   631  *     @param filename file to look for.
   852  *     \param filename file to look for.
   632  *    @return READ ONLY string of element of search path containing the
   853  *    \return READ ONLY string of element of search path containing the
   633  *             the file in question. NULL if not found.
   854  *             the file in question. NULL if not found.
   634  */
   855  */
   635 __EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
   856 __EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
   636
   857
   637
   858
   638
   859
   639 /**
   860 /**
   640  * Get a file listing of a search path's directory. Matching directories are
   861  * \fn char **PHYSFS_enumerateFiles(const char *dir)
   641  *  interpolated. That is, if "C:\mydir" is in the search path and contains a
   862  * \brief Get a file listing of a search path's directory.
   642  *  directory "savegames" that contains "x.sav", "y.sav", and "z.sav", and
   863  *
   643  *  there is also a "C:\userdir" in the search path that has a "savegames"
   864  * Matching directories are interpolated. That is, if "C:\mydir" is in the
   644  *  subdirectory with "w.sav", then the following code:
   865  *  search path and contains a directory "savegames" that contains "x.sav",
   645  *
   866  *  "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path
   646  * ------------------------------------------------
   867  *  that has a "savegames" subdirectory with "w.sav", then the following code:

   868  *

   869  * \code
   647  * char **rc = PHYSFS_enumerateFiles("savegames");
   870  * char **rc = PHYSFS_enumerateFiles("savegames");
   648  * char **i;
   871  * char **i;
   649  *
   872  *
   650  * for (i = rc; *i != NULL; i++)
   873  * for (i = rc; *i != NULL; i++)
   651  *     printf("We've got [%s].\n", *i);
   874  *     printf(" * We've got [%s].\n", *i);
   652  *
   875  *
   653  * PHYSFS_freeList(rc);
   876  * PHYSFS_freeList(rc);
   654  * ------------------------------------------------
   877  * \endcode
   655  *
   878  *
   656  *  ...will print:
   879  *  ...will print:
   657  *
   880  *
   658  * ------------------------------------------------
   881  * \verbatim
   659  * We've got [x.sav].
   882  * We've got [x.sav].
   660  * We've got [y.sav].
   883  * We've got [y.sav].
   661  * We've got [z.sav].
   884  * We've got [z.sav].
   662  * We've got [w.sav].
   885  * We've got [w.sav].\endverbatim
   663  * ------------------------------------------------

   664  *
   886  *
   665  * Feel free to sort the list however you like. We only promise there will
   887  * Feel free to sort the list however you like. We only promise there will
   666  *  be no duplicates, but not what order the final list will come back in.
   888  *  be no duplicates, but not what order the final list will come back in.
   667  *
   889  *
   668  * Don't forget to call PHYSFS_freeList() with the return value from this
   890  * Don't forget to call PHYSFS_freeList() with the return value from this
   669  *  function when you are done with it.
   891  *  function when you are done with it.
   670  *
   892  *
   671  *    @param dir directory in platform-independent notation to enumerate.
   893  *    \param dir directory in platform-independent notation to enumerate.
   672  *   @return Null-terminated array of null-terminated strings.
   894  *   \return Null-terminated array of null-terminated strings.
   673  */
   895  */
   674 __EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
   896 __EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
   675
   897
   676
   898
   677 /**
   899 /**
   678  * Determine if there is an entry anywhere in the search path by the
   900  * \fn int PHYSFS_exists(const char *fname)

   901  * \brief Determine if a file exists in the search path.

   902  *

   903  * Reports true if there is an entry anywhere in the search path by the
   679  *  name of (fname).
   904  *  name of (fname).
   680  *
   905  *
   681  * Note that entries that are symlinks are ignored if
   906  * Note that entries that are symlinks are ignored if
   682  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
   907  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
   683  *  might end up further down in the search path than expected.
   908  *  might end up further down in the search path than expected.
   684  *
   909  *
   685  *    @param fname filename in platform-independent notation.
   910  *    \param fname filename in platform-independent notation.
   686  *   @return non-zero if filename exists. zero otherwise.
   911  *   \return non-zero if filename exists. zero otherwise.

   912  *

   913  * \sa PHYSFS_isDirectory

   914  * \sa PHYSFS_isSymbolicLink
   687  */
   915  */
   688 __EXPORT__ int PHYSFS_exists(const char *fname);
   916 __EXPORT__ int PHYSFS_exists(const char *fname);
   689
   917
   690
   918
   691 /**
   919 /**

   920  * \fn int PHYSFS_isDirectory(const char *fname)

   921  * \brief Determine if a file in the search path is really a directory.

   922  *
   692  * Determine if the first occurence of (fname) in the search path is
   923  * Determine if the first occurence of (fname) in the search path is
   693  *  really a directory entry.
   924  *  really a directory entry.
   694  *
   925  *
   695  * Note that entries that are symlinks are ignored if
   926  * Note that entries that are symlinks are ignored if
   696  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
   927  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
   697  *  might end up further down in the search path than expected.
   928  *  might end up further down in the search path than expected.
   698  *
   929  *
   699  *    @param fname filename in platform-independent notation.
   930  *    \param fname filename in platform-independent notation.
   700  *   @return non-zero if filename exists and is a directory.  zero otherwise.
   931  *   \return non-zero if filename exists and is a directory.  zero otherwise.

   932  *

   933  * \sa PHYSFS_exists

   934  * \sa PHYSFS_isSymbolicLink
   701  */
   935  */
   702 __EXPORT__ int PHYSFS_isDirectory(const char *fname);
   936 __EXPORT__ int PHYSFS_isDirectory(const char *fname);
   703
   937
   704
   938
   705 /**
   939 /**

   940  * \fn int PHYSFS_isSymbolicLink(const char *fname)

   941  * \brief Determine if a file in the search path is really a symbolic link.

   942  *
   706  * Determine if the first occurence of (fname) in the search path is
   943  * Determine if the first occurence of (fname) in the search path is
   707  *  really a symbolic link.
   944  *  really a symbolic link.
   708  *
   945  *
   709  * Note that entries that are symlinks are ignored if
   946  * Note that entries that are symlinks are ignored if
   710  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
   947  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
   711  *  this function will always return 0 in that case.
   948  *  this function will always return 0 in that case.
   712  *
   949  *
   713  *    @param fname filename in platform-independent notation.
   950  *    \param fname filename in platform-independent notation.
   714  *   @return non-zero if filename exists and is a symlink.  zero otherwise.
   951  *   \return non-zero if filename exists and is a symlink.  zero otherwise.

   952  *

   953  * \sa PHYSFS_exists

   954  * \sa PHYSFS_isDirectory
   715  */
   955  */
   716 __EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
   956 __EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
   717
   957
   718
   958
   719 /**
   959 /**

   960  * \fn PHYSFS_file *PHYSFS_openWrite(const char *filename)

   961  * \brief Open a file for writing.

   962  *
   720  * Open a file for writing, in platform-independent notation and in relation
   963  * Open a file for writing, in platform-independent notation and in relation
   721  *  to the write dir as the root of the writable filesystem. The specified
   964  *  to the write dir as the root of the writable filesystem. The specified
   722  *  file is created if it doesn't exist. If it does exist, it is truncated to
   965  *  file is created if it doesn't exist. If it does exist, it is truncated to
   723  *  zero bytes, and the writing offset is set to the start.
   966  *  zero bytes, and the writing offset is set to the start.
   724  *
   967  *
   725  * Note that entries that are symlinks are ignored if
   968  * Note that entries that are symlinks are ignored if
   726  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
   969  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
   727  *  symlink with this function will fail in such a case.
   970  *  symlink with this function will fail in such a case.
   728  *
   971  *
   729  *   @param filename File to open.
   972  *   \param filename File to open.
   730  *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
   973  *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
   731  *           of the error can be gleaned from PHYSFS_getLastError().
   974  *           of the error can be gleaned from PHYSFS_getLastError().

   975  *

   976  * \sa PHYSFS_openRead

   977  * \sa PHYSFS_openAppend

   978  * \sa PHYSFS_write

   979  * \sa PHYSFS_close
   732  */
   980  */
   733 __EXPORT__ PHYSFS_file *PHYSFS_openWrite(const char *filename);
   981 __EXPORT__ PHYSFS_file *PHYSFS_openWrite(const char *filename);
   734
   982
   735
   983
   736 /**
   984 /**

   985  * \fn PHYSFS_file *PHYSFS_openAppend(const char *filename)

   986  * \brief Open a file for appending.

   987  *
   737  * Open a file for writing, in platform-independent notation and in relation
   988  * Open a file for writing, in platform-independent notation and in relation
   738  *  to the write dir as the root of the writable filesystem. The specified
   989  *  to the write dir as the root of the writable filesystem. The specified
   739  *  file is created if it doesn't exist. If it does exist, the writing offset
   990  *  file is created if it doesn't exist. If it does exist, the writing offset
   740  *  is set to the end of the file, so the first write will be the byte after
   991  *  is set to the end of the file, so the first write will be the byte after
   741  *  the end.
   992  *  the end.
   742  *
   993  *
   743  * Note that entries that are symlinks are ignored if
   994  * Note that entries that are symlinks are ignored if
   744  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
   995  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
   745  *  symlink with this function will fail in such a case.
   996  *  symlink with this function will fail in such a case.
   746  *
   997  *
   747  *   @param filename File to open.
   998  *   \param filename File to open.
   748  *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
   999  *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
   749  *           of the error can be gleaned from PHYSFS_getLastError().
  1000  *           of the error can be gleaned from PHYSFS_getLastError().

  1001  *

  1002  * \sa PHYSFS_openRead

  1003  * \sa PHYSFS_openWrite

  1004  * \sa PHYSFS_write

  1005  * \sa PHYSFS_close
   750  */
  1006  */
   751 __EXPORT__ PHYSFS_file *PHYSFS_openAppend(const char *filename);
  1007 __EXPORT__ PHYSFS_file *PHYSFS_openAppend(const char *filename);
   752
  1008
   753
  1009
   754 /**
  1010 /**

  1011  * \fn PHYSFS_file *PHYSFS_openRead(const char *filename)

  1012  * \brief Open a file for reading.

  1013  *
   755  * Open a file for reading, in platform-independent notation. The search path
  1014  * Open a file for reading, in platform-independent notation. The search path
   756  *  is checked one at a time until a matching file is found, in which case an
  1015  *  is checked one at a time until a matching file is found, in which case an
   757  *  abstract filehandle is associated with it, and reading may be done.
  1016  *  abstract filehandle is associated with it, and reading may be done.
   758  *  The reading offset is set to the first byte of the file.
  1017  *  The reading offset is set to the first byte of the file.
   759  *
  1018  *
   760  * Note that entries that are symlinks are ignored if
  1019  * Note that entries that are symlinks are ignored if
   761  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
  1020  *  PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
   762  *  symlink with this function will fail in such a case.
  1021  *  symlink with this function will fail in such a case.
   763  *
  1022  *
   764  *   @param filename File to open.
  1023  *   \param filename File to open.
   765  *  @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
  1024  *  \return A valid PhysicsFS filehandle on success, NULL on error. Specifics
   766  *           of the error can be gleaned from PHYSFS_getLastError().
  1025  *           of the error can be gleaned from PHYSFS_getLastError().

  1026  *

  1027  * \sa PHYSFS_openWrite

  1028  * \sa PHYSFS_openAppend

  1029  * \sa PHYSFS_read

  1030  * \sa PHYSFS_close
   767  */
  1031  */
   768 __EXPORT__ PHYSFS_file *PHYSFS_openRead(const char *filename);
  1032 __EXPORT__ PHYSFS_file *PHYSFS_openRead(const char *filename);
   769
  1033
   770
  1034
   771 /**
  1035 /**
   772  * Close a PhysicsFS filehandle. This call is capable of failing if the
  1036  * \fn int PHYSFS_close(PHYSFS_file *handle)
   773  *  operating system was buffering writes to this file, and (now forced to
  1037  * \brief Close a PhysicsFS filehandle.
   774  *  write those changes to physical media) can not store the data for any
  1038  *
   775  *  reason. In such a case, the filehandle stays open. A well-written program
  1039  * This call is capable of failing if the operating system was buffering
   776  *  should ALWAYS check the return value from the close call in addition to
  1040  *  writes to the physical media, and, now forced to write those changes to
   777  *  every writing call!
  1041  *  physical media, can not store the data for some reason. In such a case,
   778  *
  1042  *  the filehandle stays open. A well-written program should ALWAYS check the
   779  *   @param handle handle returned from PHYSFS_open*().
  1043  *  return value from the close call in addition to every writing call!
   780  *  @return nonzero on success, zero on error. Specifics of the error can be
  1044  *

  1045  *   \param handle handle returned from PHYSFS_open*().

  1046  *  \return nonzero on success, zero on error. Specifics of the error can be
   781  *          gleaned from PHYSFS_getLastError().
  1047  *          gleaned from PHYSFS_getLastError().

  1048  *

  1049  * \sa PHYSFS_openRead

  1050  * \sa PHYSFS_openWrite

  1051  * \sa PHYSFS_openAppend
   782  */
  1052  */
   783 __EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
  1053 __EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
   784
  1054
   785
  1055
   786 /**
  1056 /**
   787  * Get the last modification time of a file. This is returned as a
  1057  * \fn PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename)
   788  *  number of seconds since the epoch (Jan 1, 1970). The exact derivation
  1058  * \brief Get the last modification time of a file.
   789  *  and accuracy of this time depends on the particular archiver. If there
  1059  *
   790  *  is no reasonable way to obtain this information for a particular archiver,
  1060  * The modtime is returned as a number of seconds since the epoch
   791  *  or there was some sort of error, this function returns (-1).
  1061  *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
   792  *
  1062  *  the particular archiver. If there is no reasonable way to obtain this
   793  *   @param filename filename to check.
  1063  *  information for a particular archiver, or there was some sort of error,
   794  *  @return last modified time of the file. -1 if it can't be determined.
  1064  *  this function returns (-1).

  1065  *

  1066  *   \param filename filename to check, in platform-independent notation.

  1067  *  \return last modified time of the file. -1 if it can't be determined.
   795  */
  1068  */
   796 __EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
  1069 __EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
   797
  1070
   798
  1071
   799 /**
  1072 /**
   800  * Read data from a PhysicsFS filehandle. The file must be opened for reading.
  1073  * \fn PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
   801  *
  1074  * \brief Read data from a PhysicsFS filehandle
   802  *   @param handle handle returned from PHYSFS_openRead().
  1075  *
   803  *   @param buffer buffer to store read data into.
  1076  * The file must be opened for reading.
   804  *   @param objSize size in bytes of objects being read from (handle).
  1077  *
   805  *   @param objCount number of (objSize) objects to read from (handle).
  1078  *   \param handle handle returned from PHYSFS_openRead().
   806  *  @return number of objects read. PHYSFS_getLastError() can shed light on
  1079  *   \param buffer buffer to store read data into.

  1080  *   \param objSize size in bytes of objects being read from (handle).

  1081  *   \param objCount number of (objSize) objects to read from (handle).

  1082  *  \return number of objects read. PHYSFS_getLastError() can shed light on
   807  *           the reason this might be < (objCount), as can PHYSFS_eof().
  1083  *           the reason this might be < (objCount), as can PHYSFS_eof().
   808  *            -1 if complete failure.
  1084  *            -1 if complete failure.

  1085  *

  1086  * \sa PHYSFS_eof
   809  */
  1087  */
   810 __EXPORT__ PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle,
  1088 __EXPORT__ PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle,
   811                                      void *buffer,
  1089                                      void *buffer,
   812                                      PHYSFS_uint32 objSize,
  1090                                      PHYSFS_uint32 objSize,
   813                                      PHYSFS_uint32 objCount);
  1091                                      PHYSFS_uint32 objCount);
   814
  1092
   815 /**
  1093 /**
   816  * Write data to a PhysicsFS filehandle. The file must be opened for writing.
  1094  * \fn PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle, const void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)
   817  *
  1095  * \brief Write data to a PhysicsFS filehandle
   818  *   @param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
  1096  *
   819  *   @param buffer buffer to store read data into.
  1097  * The file must be opened for writing.
   820  *   @param objSize size in bytes of objects being read from (handle).
  1098  *
   821  *   @param objCount number of (objSize) objects to read from (handle).
  1099  *   \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
   822  *  @return number of objects written. PHYSFS_getLastError() can shed light on
  1100  *   \param buffer buffer to store read data into.

  1101  *   \param objSize size in bytes of objects being read from (handle).

  1102  *   \param objCount number of (objSize) objects to read from (handle).

  1103  *  \return number of objects written. PHYSFS_getLastError() can shed light on
   823  *           the reason this might be < (objCount). -1 if complete failure.
  1104  *           the reason this might be < (objCount). -1 if complete failure.
   824  */
  1105  */
   825 __EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
  1106 __EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
   826                                       const void *buffer,
  1107                                       const void *buffer,
   827                                       PHYSFS_uint32 objSize,
  1108                                       PHYSFS_uint32 objSize,
   828                                       PHYSFS_uint32 objCount);
  1109                                       PHYSFS_uint32 objCount);
   829
  1110
   830 /**
  1111 /**

  1112  * \fn int PHYSFS_eof(PHYSFS_file *handle)

  1113  * \brief Check for end-of-file state on a PhysicsFS filehandle.

  1114  *
   831  * Determine if the end of file has been reached in a PhysicsFS filehandle.
  1115  * Determine if the end of file has been reached in a PhysicsFS filehandle.
   832  *
  1116  *
   833  *   @param handle handle returned from PHYSFS_openRead().
  1117  *   \param handle handle returned from PHYSFS_openRead().
   834  *  @return nonzero if EOF, zero if not.
  1118  *  \return nonzero if EOF, zero if not.

  1119  *

  1120  * \sa PHYSFS_read

  1121  * \sa PHYSFS_tell
   835  */
  1122  */
   836 __EXPORT__ int PHYSFS_eof(PHYSFS_file *handle);
  1123 __EXPORT__ int PHYSFS_eof(PHYSFS_file *handle);
   837
  1124
   838
  1125
   839 /**
  1126 /**
   840  * Determine current position within a PhysicsFS filehandle.
  1127  * \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle)
   841  *
  1128  * \brief Determine current position within a PhysicsFS filehandle.
   842  *   @param handle handle returned from PHYSFS_open*().
  1129  *
   843  *  @return offset in bytes from start of file. -1 if error occurred.
  1130  *   \param handle handle returned from PHYSFS_open*().

  1131  *  \return offset in bytes from start of file. -1 if error occurred.
   844  *           Specifics of the error can be gleaned from PHYSFS_getLastError().
  1132  *           Specifics of the error can be gleaned from PHYSFS_getLastError().

  1133  *

  1134  * \sa PHYSFS_seek
   845  */
  1135  */
   846 __EXPORT__ PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle);
  1136 __EXPORT__ PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle);
   847
  1137
   848
  1138
   849 /**
  1139 /**
   850  * Seek to a new position within a PhysicsFS filehandle. The next read or write
  1140  * \fn int PHYSFS_seek(PHYSFS_file *handle, PHYSFS_uint64 pos)
   851  *  will occur at that place. Seeking past the beginning or end of the file is
  1141  * \brief Seek to a new position within a PhysicsFS filehandle.
   852  *  not allowed.
  1142  *
   853  *
  1143  * The next read or write will occur at that place. Seeking past the
   854  *   @param handle handle returned from PHYSFS_open*().
  1144  *  beginning or end of the file is not allowed, and causes an error.
   855  *   @param pos number of bytes from start of file to seek to.
  1145  *
   856  *  @return nonzero on success, zero on error. Specifics of the error can be
  1146  *   \param handle handle returned from PHYSFS_open*().

  1147  *   \param pos number of bytes from start of file to seek to.

  1148  *  \return nonzero on success, zero on error. Specifics of the error can be
   857  *          gleaned from PHYSFS_getLastError().
  1149  *          gleaned from PHYSFS_getLastError().

  1150  *

  1151  * \sa PHYSFS_tell
   858  */
  1152  */
   859 __EXPORT__ int PHYSFS_seek(PHYSFS_file *handle, PHYSFS_uint64 pos);
  1153 __EXPORT__ int PHYSFS_seek(PHYSFS_file *handle, PHYSFS_uint64 pos);
   860
  1154
   861
  1155
   862 /**
  1156 /**
   863  * Get total length of a file in bytes. Note that if the file size can't
  1157  * \fn PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle)
   864  *  be determined (since the archive is "streamed" or whatnot) than this
  1158  * \brief Get total length of a file in bytes.
   865  *  will report (-1). Also note that if another process/thread is writing
  1159  *
   866  *  to this file at the same time, then the information this function
  1160  * Note that if the file size can't be determined (since the archive is
   867  *  supplies could be incorrect before you get it. Use with caution, or
  1161  *  "streamed" or whatnot) than this will report (-1). Also note that if
   868  *  better yet, don't use at all.
  1162  *  another process/thread is writing to this file at the same time, then
   869  *
  1163  *  the information this function supplies could be incorrect before you
   870  *   @param handle handle returned from PHYSFS_open*().
  1164  *  get it. Use with caution, or better yet, don't use at all.
   871  *  @return size in bytes of the file. -1 if can't be determined.
  1165  *

  1166  *   \param handle handle returned from PHYSFS_open*().

  1167  *  \return size in bytes of the file. -1 if can't be determined.

  1168  *

  1169  * \sa PHYSFS_tell

  1170  * \sa PHYSFS_seek
   872  */
  1171  */
   873 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
  1172 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
   874
  1173
   875
  1174
   876 /* Byteorder stuff... */
  1175 /* Byteorder stuff... */
   877
  1176
   878 /**
  1177 /**

  1178  * \fn PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val)

  1179  * \brief Swap littleendian signed 16 to platform's native byte order.

  1180  *
   879  * Take a 16-bit signed value in littleendian format and convert it to
  1181  * Take a 16-bit signed value in littleendian format and convert it to
   880  *  the platform's native byte order.
  1182  *  the platform's native byte order.
   881  *
  1183  *
   882  *    @param val value to convert
  1184  *    \param val value to convert
   883  *   @return converted value.
  1185  *   \return converted value.
   884  */
  1186  */
   885 __EXPORT__ PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val);
  1187 __EXPORT__ PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val);
   886
  1188
   887
  1189
   888 /**
  1190 /**

  1191  * \fn PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val)

  1192  * \brief Swap littleendian unsigned 16 to platform's native byte order.

  1193  *
   889  * Take a 16-bit unsigned value in littleendian format and convert it to
  1194  * Take a 16-bit unsigned value in littleendian format and convert it to
   890  *  the platform's native byte order.
  1195  *  the platform's native byte order.
   891  *
  1196  *
   892  *    @param val value to convert
  1197  *    \param val value to convert
   893  *   @return converted value.
  1198  *   \return converted value.
   894  */
  1199  */
   895 __EXPORT__ PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val);
  1200 __EXPORT__ PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val);
   896
  1201
   897 /**
  1202 /**

  1203  * \fn PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val)

  1204  * \brief Swap littleendian signed 32 to platform's native byte order.

  1205  *
   898  * Take a 32-bit signed value in littleendian format and convert it to
  1206  * Take a 32-bit signed value in littleendian format and convert it to
   899  *  the platform's native byte order.
  1207  *  the platform's native byte order.
   900  *
  1208  *
   901  *    @param val value to convert
  1209  *    \param val value to convert
   902  *   @return converted value.
  1210  *   \return converted value.
   903  */
  1211  */
   904 __EXPORT__ PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val);
  1212 __EXPORT__ PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val);
   905
  1213
   906
  1214
   907 /**
  1215 /**

  1216  * \fn PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val)

  1217  * \brief Swap littleendian unsigned 32 to platform's native byte order.

  1218  *
   908  * Take a 32-bit unsigned value in littleendian format and convert it to
  1219  * Take a 32-bit unsigned value in littleendian format and convert it to
   909  *  the platform's native byte order.
  1220  *  the platform's native byte order.
   910  *
  1221  *
   911  *    @param val value to convert
  1222  *    \param val value to convert
   912  *   @return converted value.
  1223  *   \return converted value.
   913  */
  1224  */
   914 __EXPORT__ PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val);
  1225 __EXPORT__ PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val);
   915
  1226
   916 /**
  1227 /**

  1228  * \fn PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val)

  1229  * \brief Swap littleendian signed 64 to platform's native byte order.

  1230  *
   917  * Take a 64-bit signed value in littleendian format and convert it to
  1231  * Take a 64-bit signed value in littleendian format and convert it to
   918  *  the platform's native byte order.
  1232  *  the platform's native byte order.
   919  *
  1233  *
   920  *    @param val value to convert
  1234  *    \param val value to convert
   921  *   @return converted value.
  1235  *   \return converted value.

  1236  *

  1237  * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without

  1238  *          any sort of 64-bit support.
   922  */
  1239  */
   923 __EXPORT__ PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val);
  1240 __EXPORT__ PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val);
   924
  1241
   925
  1242
   926 /**
  1243 /**

  1244  * \fn PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val)

  1245  * \brief Swap littleendian unsigned 64 to platform's native byte order.

  1246  *
   927  * Take a 64-bit unsigned value in littleendian format and convert it to
  1247  * Take a 64-bit unsigned value in littleendian format and convert it to
   928  *  the platform's native byte order.
  1248  *  the platform's native byte order.
   929  *
  1249  *
   930  *    @param val value to convert
  1250  *    \param val value to convert
   931  *   @return converted value.
  1251  *   \return converted value.

  1252  *

  1253  * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without

  1254  *          any sort of 64-bit support.
   932  */
  1255  */
   933 __EXPORT__ PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val);
  1256 __EXPORT__ PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val);
   934
  1257
   935
  1258
   936 /**
  1259 /**

  1260  * \fn PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val)

  1261  * \brief Swap bigendian signed 16 to platform's native byte order.

  1262  *
   937  * Take a 16-bit signed value in bigendian format and convert it to
  1263  * Take a 16-bit signed value in bigendian format and convert it to
   938  *  the platform's native byte order.
  1264  *  the platform's native byte order.
   939  *
  1265  *
   940  *    @param val value to convert
  1266  *    \param val value to convert
   941  *   @return converted value.
  1267  *   \return converted value.
   942  */
  1268  */
   943 __EXPORT__ PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val);
  1269 __EXPORT__ PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val);
   944
  1270
   945
  1271
   946 /**
  1272 /**

  1273  * \fn PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val)

  1274  * \brief Swap bigendian unsigned 16 to platform's native byte order.

  1275  *
   947  * Take a 16-bit unsigned value in bigendian format and convert it to
  1276  * Take a 16-bit unsigned value in bigendian format and convert it to
   948  *  the platform's native byte order.
  1277  *  the platform's native byte order.
   949  *
  1278  *
   950  *    @param val value to convert
  1279  *    \param val value to convert
   951  *   @return converted value.
  1280  *   \return converted value.
   952  */
  1281  */
   953 __EXPORT__ PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val);
  1282 __EXPORT__ PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val);
   954
  1283
   955 /**
  1284 /**

  1285  * \fn PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val)

  1286  * \brief Swap bigendian signed 32 to platform's native byte order.

  1287  *
   956  * Take a 32-bit signed value in bigendian format and convert it to
  1288  * Take a 32-bit signed value in bigendian format and convert it to
   957  *  the platform's native byte order.
  1289  *  the platform's native byte order.
   958  *
  1290  *
   959  *    @param val value to convert
  1291  *    \param val value to convert
   960  *   @return converted value.
  1292  *   \return converted value.
   961  */
  1293  */
   962 __EXPORT__ PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val);
  1294 __EXPORT__ PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val);
   963
  1295
   964
  1296
   965 /**
  1297 /**

  1298  * \fn PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val)

  1299  * \brief Swap bigendian unsigned 32 to platform's native byte order.

  1300  *
   966  * Take a 32-bit unsigned value in bigendian format and convert it to
  1301  * Take a 32-bit unsigned value in bigendian format and convert it to
   967  *  the platform's native byte order.
  1302  *  the platform's native byte order.
   968  *
  1303  *
   969  *    @param val value to convert
  1304  *    \param val value to convert
   970  *   @return converted value.
  1305  *   \return converted value.
   971  */
  1306  */
   972 __EXPORT__ PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val);
  1307 __EXPORT__ PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val);
   973
  1308
   974
  1309
   975 /**
  1310 /**

  1311  * \fn PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val)

  1312  * \brief Swap bigendian signed 64 to platform's native byte order.

  1313  *
   976  * Take a 64-bit signed value in bigendian format and convert it to
  1314  * Take a 64-bit signed value in bigendian format and convert it to
   977  *  the platform's native byte order.
  1315  *  the platform's native byte order.
   978  *
  1316  *
   979  *    @param val value to convert
  1317  *    \param val value to convert
   980  *   @return converted value.
  1318  *   \return converted value.

  1319  *

  1320  * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without

  1321  *          any sort of 64-bit support.
   981  */
  1322  */
   982 __EXPORT__ PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val);
  1323 __EXPORT__ PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val);
   983
  1324
   984
  1325
   985 /**
  1326 /**

  1327  * \fn PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val)

  1328  * \brief Swap bigendian unsigned 64 to platform's native byte order.

  1329  *
   986  * Take a 64-bit unsigned value in bigendian format and convert it to
  1330  * Take a 64-bit unsigned value in bigendian format and convert it to
   987  *  the platform's native byte order.
  1331  *  the platform's native byte order.
   988  *
  1332  *
   989  *    @param val value to convert
  1333  *    \param val value to convert
   990  *   @return converted value.
  1334  *   \return converted value.

  1335  *

  1336  * \warning Remember, PHYSFS_uint64 is only 32 bits on platforms without

  1337  *          any sort of 64-bit support.
   991  */
  1338  */
   992 __EXPORT__ PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val);
  1339 __EXPORT__ PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val);
   993
  1340
   994 #ifdef __cplusplus
  1341 #ifdef __cplusplus
   995 }
  1342 }