physfs.h
changeset 265 6187d310b2c0
parent 240 052041af9001
child 322 597af607e7d3
equal deleted 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 }