src/physfs.h
changeset 1070 822d91dde8e8
parent 1069 2f0de4ad18a5
child 1075 abbb759c1398
equal deleted inserted replaced
1069:2f0de4ad18a5 1070:822d91dde8e8
     1 /** \file physfs.h */
     1 /**
       
     2  * \file physfs.h
       
     3  *
       
     4  * Main header file for PhysicsFS.
       
     5  */
     2 
     6 
     3 /**
     7 /**
     4  * \mainpage PhysicsFS
     8  * \mainpage PhysicsFS
     5  *
     9  *
     6  * The latest version of PhysicsFS can be found at:
    10  * The latest version of PhysicsFS can be found at:
  1013  *     printf(" * We've got [%s].\n", *i);
  1017  *     printf(" * We've got [%s].\n", *i);
  1014  *
  1018  *
  1015  * PHYSFS_freeList(rc);
  1019  * PHYSFS_freeList(rc);
  1016  * \endcode
  1020  * \endcode
  1017  *
  1021  *
  1018  *  ...will print:
  1022  *  \...will print:
  1019  *
  1023  *
  1020  * \verbatim
  1024  * \verbatim
  1021  * We've got [x.sav].
  1025  * We've got [x.sav].
  1022  * We've got [y.sav].
  1026  * We've got [y.sav].
  1023  * We've got [z.sav].
  1027  * We've got [z.sav].
  1103  *
  1107  *
  1104  * The modtime is returned as a number of seconds since the epoch
  1108  * The modtime is returned as a number of seconds since the epoch
  1105  *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
  1109  *  (Jan 1, 1970). The exact derivation and accuracy of this time depends on
  1106  *  the particular archiver. If there is no reasonable way to obtain this
  1110  *  the particular archiver. If there is no reasonable way to obtain this
  1107  *  information for a particular archiver, or there was some sort of error,
  1111  *  information for a particular archiver, or there was some sort of error,
  1108  *  this function returns (-1).
  1112  *  this function returns (\-1).
  1109  *
  1113  *
  1110  *   \param filename filename to check, in platform-independent notation.
  1114  *   \param filename filename to check, in platform-independent notation.
  1111  *  \return last modified time of the file. -1 if it can't be determined.
  1115  *  \return last modified time of the file. \-1 if it can't be determined.
  1112  */
  1116  */
  1113 PHYSFS_DECL PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
  1117 PHYSFS_DECL PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
  1114 
  1118 
  1115 
  1119 
  1116 /* i/o stuff... */
  1120 /* i/o stuff... */
  1222  *   \param buffer buffer to store read data into.
  1226  *   \param buffer buffer to store read data into.
  1223  *   \param objSize size in bytes of objects being read from (handle).
  1227  *   \param objSize size in bytes of objects being read from (handle).
  1224  *   \param objCount number of (objSize) objects to read from (handle).
  1228  *   \param objCount number of (objSize) objects to read from (handle).
  1225  *  \return number of objects read. PHYSFS_getLastError() can shed light on
  1229  *  \return number of objects read. PHYSFS_getLastError() can shed light on
  1226  *           the reason this might be < (objCount), as can PHYSFS_eof().
  1230  *           the reason this might be < (objCount), as can PHYSFS_eof().
  1227  *            -1 if complete failure.
  1231  *            \-1 if complete failure.
  1228  *
  1232  *
  1229  * \sa PHYSFS_eof
  1233  * \sa PHYSFS_eof
  1230  */
  1234  */
  1231 PHYSFS_DECL PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle,
  1235 PHYSFS_DECL PHYSFS_sint64 PHYSFS_read(PHYSFS_File *handle,
  1232                                       void *buffer,
  1236                                       void *buffer,
  1242  *   \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
  1246  *   \param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
  1243  *   \param buffer buffer to store read data into.
  1247  *   \param buffer buffer to store read data into.
  1244  *   \param objSize size in bytes of objects being read from (handle).
  1248  *   \param objSize size in bytes of objects being read from (handle).
  1245  *   \param objCount number of (objSize) objects to read from (handle).
  1249  *   \param objCount number of (objSize) objects to read from (handle).
  1246  *  \return number of objects written. PHYSFS_getLastError() can shed light on
  1250  *  \return number of objects written. PHYSFS_getLastError() can shed light on
  1247  *           the reason this might be < (objCount). -1 if complete failure.
  1251  *           the reason this might be < (objCount). \-1 if complete failure.
  1248  */
  1252  */
  1249 PHYSFS_DECL PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle,
  1253 PHYSFS_DECL PHYSFS_sint64 PHYSFS_write(PHYSFS_File *handle,
  1250                                        const void *buffer,
  1254                                        const void *buffer,
  1251                                        PHYSFS_uint32 objSize,
  1255                                        PHYSFS_uint32 objSize,
  1252                                        PHYSFS_uint32 objCount);
  1256                                        PHYSFS_uint32 objCount);
  1272 /**
  1276 /**
  1273  * \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle)
  1277  * \fn PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle)
  1274  * \brief Determine current position within a PhysicsFS filehandle.
  1278  * \brief Determine current position within a PhysicsFS filehandle.
  1275  *
  1279  *
  1276  *   \param handle handle returned from PHYSFS_open*().
  1280  *   \param handle handle returned from PHYSFS_open*().
  1277  *  \return offset in bytes from start of file. -1 if error occurred.
  1281  *  \return offset in bytes from start of file. \-1 if error occurred.
  1278  *           Specifics of the error can be gleaned from PHYSFS_getLastError().
  1282  *           Specifics of the error can be gleaned from PHYSFS_getLastError().
  1279  *
  1283  *
  1280  * \sa PHYSFS_seek
  1284  * \sa PHYSFS_seek
  1281  */
  1285  */
  1282 PHYSFS_DECL PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle);
  1286 PHYSFS_DECL PHYSFS_sint64 PHYSFS_tell(PHYSFS_File *handle);
  1302 /**
  1306 /**
  1303  * \fn PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle)
  1307  * \fn PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle)
  1304  * \brief Get total length of a file in bytes.
  1308  * \brief Get total length of a file in bytes.
  1305  *
  1309  *
  1306  * Note that if the file size can't be determined (since the archive is
  1310  * Note that if the file size can't be determined (since the archive is
  1307  *  "streamed" or whatnot) than this will report (-1). Also note that if
  1311  *  "streamed" or whatnot) than this will report (\-1). Also note that if
  1308  *  another process/thread is writing to this file at the same time, then
  1312  *  another process/thread is writing to this file at the same time, then
  1309  *  the information this function supplies could be incorrect before you
  1313  *  the information this function supplies could be incorrect before you
  1310  *  get it. Use with caution, or better yet, don't use at all.
  1314  *  get it. Use with caution, or better yet, don't use at all.
  1311  *
  1315  *
  1312  *   \param handle handle returned from PHYSFS_open*().
  1316  *   \param handle handle returned from PHYSFS_open*().
  1313  *  \return size in bytes of the file. -1 if can't be determined.
  1317  *  \return size in bytes of the file. \-1 if can't be determined.
  1314  *
  1318  *
  1315  * \sa PHYSFS_tell
  1319  * \sa PHYSFS_tell
  1316  * \sa PHYSFS_seek
  1320  * \sa PHYSFS_seek
  1317  */
  1321  */
  1318 PHYSFS_DECL PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle);
  1322 PHYSFS_DECL PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_File *handle);
  2431  * \brief Discover the current allocator.
  2435  * \brief Discover the current allocator.
  2432  *
  2436  *
  2433  * (This is for limited, hardcore use. If you don't immediately see a need
  2437  * (This is for limited, hardcore use. If you don't immediately see a need
  2434  *  for it, you can probably ignore this forever.)
  2438  *  for it, you can probably ignore this forever.)
  2435  *
  2439  *
  2436  * This function exposes the function pointers that make up the currently-used
  2440  * This function exposes the function pointers that make up the currently used
  2437  *  allocator. This can be useful for apps that want to access PhysicsFS's
  2441  *  allocator. This can be useful for apps that want to access PhysicsFS's
  2438  *  internal, default allocation routines, as well as for external code that
  2442  *  internal, default allocation routines, as well as for external code that
  2439  *  wants to share the same allocator, even if the application specified their
  2443  *  wants to share the same allocator, even if the application specified their
  2440  *  own.
  2444  *  own.
  2441  *
  2445  *
  2450  *
  2454  *
  2451  * If you aren't immediately sure what to do with this function, you can
  2455  * If you aren't immediately sure what to do with this function, you can
  2452  *  safely ignore it altogether.
  2456  *  safely ignore it altogether.
  2453  *
  2457  *
  2454  *  \return Current allocator, as set by PHYSFS_setAllocator(), or PhysicsFS's
  2458  *  \return Current allocator, as set by PHYSFS_setAllocator(), or PhysicsFS's
  2455  *          internal, default allocator if no application-defined allocator
  2459  *          internal, default allocator if no application defined allocator
  2456  *          is currently set. Will return NULL if the library is not
  2460  *          is currently set. Will return NULL if the library is not
  2457  *          initialized.
  2461  *          initialized.
  2458  *
  2462  *
  2459  * \sa PHYSFS_Allocator
  2463  * \sa PHYSFS_Allocator
  2460  * \sa PHYSFS_setAllocator
  2464  * \sa PHYSFS_setAllocator
  2483  * \struct PHYSFS_Stat
  2487  * \struct PHYSFS_Stat
  2484  * \brief Meta data for a file or directory
  2488  * \brief Meta data for a file or directory
  2485  *
  2489  *
  2486  * Container for various meta data about a file in the virtual file system.
  2490  * Container for various meta data about a file in the virtual file system.
  2487  * PHYSFS_stat() uses this structure for returning the information. The time
  2491  * PHYSFS_stat() uses this structure for returning the information. The time
  2488  * data will be either a real timestamp or -1 if there is none. So every value
  2492  * data will be either a real timestamp or \-1 if there is none. So every value
  2489  * is at least epoch. The FileSize is only valid for real files. And the
  2493  * is at least epoch. The FileSize is only valid for real files. And the
  2490  * readonly tells you whether when you open a file for writing you are writing
  2494  * readonly tells you whether when you open a file for writing you are writing
  2491  * to the same file as if you were opening it, given you have enough
  2495  * to the same file as if you were opening it, given you have enough
  2492  * filesystem rights to do that.
  2496  * filesystem rights to do that.
  2493  *
  2497  *
  2494  * \sa PHYSFS_stat
  2498  * \sa PHYSFS_stat
  2495  * \sa PHYSFS_FileType
  2499  * \sa PHYSFS_FileType
  2496  */
  2500  */
  2497 typedef struct PHYSFS_Stat
  2501 typedef struct PHYSFS_Stat
  2498 {
  2502 {
  2499 	PHYSFS_sint64 filesize; /**< size in bytes, -1 for non-files and unknown */
  2503 	PHYSFS_sint64 filesize; /**< size in bytes, \-1 for non-files and unknown */
  2500 	PHYSFS_sint64 modtime;  /**< same value as PHYSFS_getLastModTime() */
  2504 	PHYSFS_sint64 modtime;  /**< same value as PHYSFS_getLastModTime() */
  2501 	PHYSFS_sint64 createtime; /**< like modtime, but for file creation time */
  2505 	PHYSFS_sint64 createtime; /**< like modtime, but for file creation time */
  2502 	PHYSFS_sint64 accesstime; /**< like modtime, but for file access time */
  2506 	PHYSFS_sint64 accesstime; /**< like modtime, but for file access time */
  2503 	PHYSFS_FileType filetype; /**< File? Directory? Symlink? */
  2507 	PHYSFS_FileType filetype; /**< File? Directory? Symlink? */
  2504 	int readonly; /**< non-zero if read only, zero if writable. */
  2508 	int readonly; /**< non-zero if read only, zero if writable. */