Skip to content

Commit

Permalink
Fixed typos, expanded documentation, added init and deinit functions,…
Browse files Browse the repository at this point in the history 
… and

 some more !!! todos.
  • Loading branch information
@icculus
icculus committed Jun 7, 2001
1 parent de901e4 commit d41c242
Showing 1 changed file with 72 additions and 25 deletions.
97 changes: 72 additions & 25 deletions physfs.h
View file
Expand Up @@ -5,17 +5,17 @@
* stdio or system i/o calls. The brief benefits:
*
* - It's portable.
* - It can handle byte ordering on alternative processors.
* - It's safe. No file access is permitted outside the specified dirs.
* - It can handle byte ordering on alternative processors.
* - It's flexible. Archives (.ZIP files) can be used transparently as
* directory structures.
*
* This system is largely inspired by Quake 3's PK3 files and the related
* fs_* cvars. If you've ever tinkered with these, then this API will be very
* fs_* cvars. If you've ever tinkered with these, then this API will be
* familiar to you.
*
* With the PhysicsFS, you have a single writing directory and multiple
* "search paths" for reading. You can think of this as a filesystem within a
* With PhysicsFS, you have a single writing path and multiple "search paths"
* for reading. You can think of this as a filesystem within a
* filesystem. If (on Windows) you were to set the writing directory to
* "C:\MyGame\MyWritingDirectory", then no PHYSFS calls could touch anything
* above this directory, including the "C:\MyGame" and "C:\" directories.
Expand All @@ -35,7 +35,12 @@
* specify it like it was on a Unix filesystem: if you want to write to
* "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write path to
* "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
* abstraction across all platforms.
* abstraction across all platforms. Specifying a file in this way is termed
* "platform-independent notation" in this documentation. Specifying a path
* as "C:\mydir\myfile" or "MacOS hard drive:My Directory:My File" is termed
* "platform-dependent notation". The only time you use platform-dependent
* notation is when setting up your write and search paths; after that, all
* file access into those paths are done with platform-independent notation.
*
* All files opened for writing are opened in relation to the write path,
* which is the root of the writable filesystem. When opening a file for
Expand All @@ -55,12 +60,14 @@
* C:\mygame\installeddatafiles.zip
*
* Then a call to PHYSFS_openread("textfiles/myfile.txt") (note the directory
* separator) will check for C:\mygame\textfiles\myfile.txt, then
* separator, lack of drive letter, and lack of dir separator at the start of
* the string; this is platform-independent notation) will check for
* C:\mygame\textfiles\myfile.txt, then
* C:\mygame\myuserfiles\textfiles\myfile.txt, then
* D:\mygamescdromdatafiles\textfiles\myfile.txt, then, finally, for
* textfiles\myfile.txt inside of C:\mygame\installeddatafiles.zip. Remember
* that most archive types and platform filesystems store their filenames in
* a case-sensitive manner.
* a case-sensitive manner, so you should be careful to specify it correctly.
*
* Files opened through PhysicsFS may NOT contain "." or ".." as path
* elements. Not only are these meaningless on MacOS, they are a security
Expand Down Expand Up @@ -119,11 +126,35 @@ extern "C" {

/* functions... */

/**
* Initialize PhysicsFS. This must be called before any other PhysicsFS
* function (except PHYSFS_getLastError()).
*
* @param argv0 the argv[0] string passed to your program's mainline.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
int PHYSFS_init(const char *argv0);


/**
* Shutdown PhysicsFS. This closes any files opened via PhysicsFS, blanks the
* search/write paths, frees memory, and invalidates all your handles.
*
* Once deinitialized, PHYSFS_init() can be called again to restart the
* subsystem.
*
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
* undefined, and probably badly screwed up.
*/
void PHYSFS_deinit(void);


/**
* Get the last PhysicsFS error message as a null-terminated string.
* This will be NULL if there's been no error since the last call to this
* function. The pointer returned by this call points to a static buffer
* function. The pointer returned by this call points to a static
* internal buffer, and this call is not thread safe.
*
* @return READ ONLY string of last error message.
Expand All @@ -136,8 +167,9 @@ const char *PHYSFS_getLastError(void);
* and ":" on MacOS. It may be more than one character, depending on the
* platform, and your code should take that into account. Note that this is
* only useful for setting up the search/write paths, since access into those
* paths always use '/' to separate directories. This is also handy for
* getting platform-independent access when using stdio calls.
* paths always use '/' (platform-independent notation) to separate
* directories. This is also handy for getting platform-independent access
* when using stdio calls.
*
* @return READ ONLY null-terminated string of platform's path separator.
*/
Expand Down Expand Up @@ -165,7 +197,7 @@ const char *PHYSFS_getPathSeparator(void);
*
* // lock thread here, if needed.
*
* for (i = PHYSFS__getCdRomPaths(); *i != NULL; i++)
* for (i = PHYSFS_getCdRomPaths(); *i != NULL; i++)
* printf("cdrom path [%s] is available.\n", *i);
*
* // unlock thread here, if needed.
Expand Down Expand Up @@ -256,7 +288,7 @@ int PHYSFS_addToSearchPath(const char *newPath, int appendToPath);


/**
* Remove a directory or archive to the search path.
* Remove a directory or archive from the search path.
*
* This must be a (case-sensitive) match to a dir or archive already in the
* search path, specified in platform-dependent notation.
Expand Down Expand Up @@ -307,12 +339,12 @@ const char **PHYSFS_getSearchPath(void);
*
* The search path will be:
*
* - The Write Path
* - The Write Path/appName
* - The Write Path (created if it doesn't exist)
* - The Write Path/appName (created if it doesn't exist)
* - The Base Path (PHYSFS_getBasePath())
* - The Base Path/appName
* - The Base Path/appName (if it exists)
* - All found CD-ROM paths (optionally)
* - All found CD-ROM paths/appName (optionally)
* - All found CD-ROM paths/appName (optionally, and if they exist)
*
* These directories are then searched for files ending with the extension
* (archiveExt), which, if they are valid and supported archives, will also
Expand All @@ -322,7 +354,7 @@ const char **PHYSFS_getSearchPath(void);
* order, regardless of which directories they were found in.
*
* All of this can be accomplished from the application, but this just does it
* all for you.
* all for you. Feel free to add more to the search path manually, too.
*
* @param appName Program-specific name of your program, to separate it
* from other programs using PhysicsFS.
Expand All @@ -333,15 +365,16 @@ const char **PHYSFS_getSearchPath(void);
* archives automatically.
*
* @param includeCdRoms Non-zero to include CD-ROMs in the search path, and
* search them for archives. This may cause a
* significant amount of blocking while discs are
* accessed, and if there are no discs in the drive
* (or even not mounted on Unix systems), then they
* may not be made available anyhow. You may want to
* specify zero and handle the disc setup yourself.
* (if (archiveExt) != NULL) search them for archives.
* This may cause a significant amount of blocking
* while discs are accessed, and if there are no discs
* in the drive (or even not mounted on Unix systems),
* then they may not be made available anyhow. You may
* want to specify zero and handle the disc setup
* yourself.
*
* @param archivesFirst Non-zero to prepend the archives to the search path.
* Zero to append them.
* Zero to append them. Ignored if !(archiveExt).
*/
void PHYSFS_setSanePaths(const char *appName, const char *archiveExt,
int includeCdRoms, int archivesFirst);
Expand Down Expand Up @@ -377,6 +410,10 @@ int PHYSFS_mkdir(const char *dirName);
* physical filesystem, if it exists and the operating system permits the
* deletion.
*
* Note that on Unix systems, deleting a file may be successful, but the
* actual file won't be removed until all processes that have an open
* filehandle to it (including your program) close their handles.
*
* @param filename Filename to delete.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
Expand All @@ -400,6 +437,10 @@ int PHYSFS_delete(const char *filename);
* directories) is removed from the physical filesystem, if it exists and the
* operating system permits the deletion.
*
* Note that on Unix systems, deleting a file may be successful, but the
* actual file won't be removed until all processes that have an open
* filehandle to it (including your program) close their handles.
*
* @param filename root of directory tree to delete.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
Expand Down Expand Up @@ -433,7 +474,8 @@ void PHYSFS_permitSymbolicLinks(int allow);

/**
* Determine if a file exists. Just because it exists does NOT mean that you
* will have access to read or write it.
* will have access to read or write it, or that it will continue to exist
* after this call (as other processes may delete it on multitasking systems).
*
* @param filename a file in platform-independent notation.
* @param inWritePath nonzero to check write path, zero to check search path.
Expand All @@ -454,6 +496,9 @@ int PHYSFS_exists(const char *filename, int inWritePath);
* path and C:\mygame\maps\level1.map exists, then buffer will be filled in
* with "C:\mygame\maps\level1.map" and the function returns nonzero.
*
* If a match is a symbolic link, and you've not explicitly permitted symlinks,
* then it will be ignored, and the search for a match will continue.
*
* @param buffer pointer to buffer to fill with path.
* @param bufsize size of buffer pointed to by (buffer).
* @param filename file to look for.
Expand Down Expand Up @@ -587,6 +632,8 @@ int PHYSFS_writeBE16(void *handle, int buffer);
int PHYSFS_writeBE32(void *handle, int buffer);
*/

/* !!! need way to enumerate the contents of a directory. */

#ifdef __cplusplus
}
#endif
Expand Down

0 comments on commit d41c242

Please sign in to comment.