From d41c242619d37ce14bd4d03819dc531196db0e24 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Thu, 7 Jun 2001 05:48:42 +0000 Subject: [PATCH] Fixed typos, expanded documentation, added init and deinit functions, and some more !!! todos. --- physfs.h | 97 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 25 deletions(-) diff --git a/physfs.h b/physfs.h index 3bae017e..c8f03404 100644 --- a/physfs.h +++ b/physfs.h @@ -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. @@ -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 @@ -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 @@ -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. @@ -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. */ @@ -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. @@ -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. @@ -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 @@ -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. @@ -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); @@ -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(). @@ -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(). @@ -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. @@ -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. @@ -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