physfs.h
changeset 147 5e1eda65ceb3
parent 137 66bddb94b6e0
child 160 b17e94892394
equal deleted inserted replaced
146:93dba4d3d0d2 147:5e1eda65ceb3
   100  *  function (PHYSFS_setSaneConfig()) that puts together a basic configuration
   100  *  function (PHYSFS_setSaneConfig()) that puts together a basic configuration
   101  *  for you, based on a few parameters. Also see the comments on
   101  *  for you, based on a few parameters. Also see the comments on
   102  *  PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
   102  *  PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
   103  *  are and how they can help you determine an optimal search path.
   103  *  are and how they can help you determine an optimal search path.
   104  *
   104  *
   105  * PhysicsFS is (sort of) NOT thread safe! The error messages returned by
   105  * PhysicsFS is mostly thread safe. The error messages returned by
   106  *  PHYSFS_getLastError are unique by thread, but that's it. Generally
   106  *  PHYSFS_getLastError are unique by thread, and library-state-setting
   107  *  speaking, we'd have to request a mutex at the start of each function,
   107  *  functions are mutex'd. For efficiency, individual file accesses are 
   108  *  and release it before returning. Not only is this REALLY slow, it requires
   108  *  not locked, so you can not safely read/write/seek/close/etc the same 
   109  *  a thread lock portability layer to be written. All that work is only
   109  *  file from two threads at the same time. Other race conditions are bugs 
   110  *  necessary as a safety if the calling application is poorly written.
   110  *  that should be reported/patched.
   111  *  Generally speaking, it is safe to call most functions that don't set state
       
   112  *  simultaneously; you can read and write and open and close different files
       
   113  *  at the same time in different threads, but trying to set the write path in
       
   114  *  one thread while opening a file for writing in another will, at best,
       
   115  *  cause a polite error, but depending on the race condition results, you may
       
   116  *  get a segfault and crash, too. Use your head, and implement you own thread
       
   117  *  locks where needed. Also, consider if you REALLY need a multithreaded
       
   118  *  solution in the first place.
       
   119  *
   111  *
   120  * While you CAN use stdio/syscall file access in a program that has PHYSFS_*
   112  * While you CAN use stdio/syscall file access in a program that has PHYSFS_*
   121  *  calls, doing so is not recommended, and you can not use system
   113  *  calls, doing so is not recommended, and you can not use system
   122  *  filehandles with PhysicsFS filehandles and vice versa.
   114  *  filehandles with PhysicsFS and vice versa.
   123  *
   115  *
   124  * Note that archives need not be named as such: if you have a ZIP file and
   116  * Note that archives need not be named as such: if you have a ZIP file and
   125  *  rename it with a .PKG extension, the file will still be recognized as a
   117  *  rename it with a .PKG extension, the file will still be recognized as a
   126  *  ZIP archive by PhysicsFS; the file's contents are used to determine its
   118  *  ZIP archive by PhysicsFS; the file's contents are used to determine its
   127  *  type.
   119  *  type.
   864  *   @param handle handle returned from PHYSFS_open*().
   856  *   @param handle handle returned from PHYSFS_open*().
   865  *  @return size in bytes of the file. -1 if can't be determined.
   857  *  @return size in bytes of the file. -1 if can't be determined.
   866  */
   858  */
   867 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
   859 __EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
   868 
   860 
       
   861 #if 0 /* !!! FIXME: add this? */
       
   862 #undef __EXPORT__
       
   863 #endif
       
   864 
   869 #ifdef __cplusplus
   865 #ifdef __cplusplus
   870 }
   866 }
   871 #endif
   867 #endif
   872 
   868 
   873 #endif  /* !defined _INCLUDE_PHYSFS_H_ */
   869 #endif  /* !defined _INCLUDE_PHYSFS_H_ */