Subversion Repositories Games.Descent

/**

 * \file physfs.h

 *

 * Main header file for PhysicsFS.

 */

/**

 * \mainpage PhysicsFS

 *

 * The latest version of PhysicsFS can be found at:

 *     https://icculus.org/physfs/

 *

 * PhysicsFS; a portable, flexible file i/o abstraction.

 *

 * This API gives you access to a system file system in ways superior to the

 *  stdio or system i/o calls. The brief benefits:

 *

 *   - It's portable.

 *   - It's safe. No file access is permitted outside the specified dirs.

 *   - It's flexible. Archives (.ZIP files) can be used transparently as

 *      directory structures.

 *

 * With PhysicsFS, you have a single writing directory and multiple

 *  directories (the "search path") 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. This prevents an application's internal scripting

 *  language from piddling over c:\\config.sys, for example. If you'd rather

 *  give PHYSFS full access to the system's REAL file system, set the writing

 *  dir to "C:\", but that's generally A Bad Thing for several reasons.

 *

 * Drive letters are hidden in PhysicsFS once you set up your initial paths.

 *  The search path creates a single, hierarchical directory structure.

 *  Not only does this lend itself well to general abstraction with archives,

 *  it also gives better support to operating systems like MacOS and Unix.

 *  Generally speaking, you shouldn't ever hardcode a drive letter; not only

 *  does this hurt portability to non-Microsoft OSes, but it limits your win32

 *  users to a single drive, too. Use the PhysicsFS abstraction functions and

 *  allow user-defined configuration options, too. When opening a file, you

 *  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 dir to

 *  "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an

 *  abstraction across all platforms. Specifying a file in this way is termed

 *  "platform-independent notation" in this documentation. Specifying a

 *  a filename in a form such 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 directory and search path; after that, all file

 *  access into those directories are done with platform-independent notation.

 *

 * All files opened for writing are opened in relation to the write directory,

 *  which is the root of the writable filesystem. When opening a file for

 *  reading, PhysicsFS goes through the search path. This is NOT the

 *  same thing as the PATH environment variable. An application using

 *  PhysicsFS specifies directories to be searched which may be actual

 *  directories, or archive files that contain files and subdirectories of

 *  their own. See the end of these docs for currently supported archive

 *  formats.

 *

 * Once the search path is defined, you may open files for reading. If you've

 *  got the following search path defined (to use a win32 example again):

 *

 *  - C:\\mygame

 *  - C:\\mygame\\myuserfiles

 *  - D:\\mygamescdromdatafiles

 *  - C:\\mygame\\installeddatafiles.zip

 *

 * Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory

 *  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, so you should be careful to specify

 *  it correctly.

 *

 * Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir

 *  elements. Not only are these meaningless on MacOS Classic and/or Unix,

 *  they are a security hole. Also, symbolic links (which can be found in

 *  some archive types and directly in the filesystem on Unix platforms) are

 *  NOT followed until you call PHYSFS_permitSymbolicLinks(). That's left to

 *  your own discretion, as following a symlink can allow for access outside

 *  the write dir and search paths. For portability, there is no mechanism for

 *  creating new symlinks in PhysicsFS.

 *

 * The write dir is not included in the search path unless you specifically

 *  add it. While you CAN change the write dir as many times as you like,

 *  you should probably set it once and stick to it. Remember that your

 *  program will not have permission to write in every directory on Unix and

 *  NT systems.

 *

 * All files are opened in binary mode; there is no endline conversion for

 *  textfiles. Other than that, PhysicsFS has some convenience functions for

 *  platform-independence. There is a function to tell you the current

 *  platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),

 *  which is needed only to set up your search/write paths. There is a

 *  function to tell you what CD-ROM drives contain accessible discs, and a

 *  function to recommend a good search path, etc.

 *

 * A recommended order for the search path is the write dir, then the base dir,

 *  then the cdrom dir, then any archives discovered. Quake 3 does something

 *  like this, but moves the archives to the start of the search path. Build

 *  Engine games, like Duke Nukem 3D and Blood, place the archives last, and

 *  use the base dir for both searching and writing. There is a helper

 *  function (PHYSFS_setSaneConfig()) that puts together a basic configuration

 *  for you, based on a few parameters. Also see the comments on

 *  PHYSFS_getBaseDir(), and PHYSFS_getPrefDir() for info on what those

 *  are and how they can help you determine an optimal search path.

 *

 * PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points

 *  in the search path. If a zipfile contains "maps/level.map" and you mount

 *  that archive at "mods/mymod", then you would have to open

 *  "mods/mymod/maps/level.map" to access the file, even though "mods/mymod"

 *  isn't actually specified in the .zip file. Unlike the Unix mentality of

 *  mounting a filesystem, "mods/mymod" doesn't actually have to exist when

 *  mounting the zipfile. It's a "virtual" directory. The mounting mechanism

 *  allows the developer to seperate archives in the tree and avoid trampling

 *  over files when added new archives, such as including mod support in a

 *  game...keeping external content on a tight leash in this manner can be of

 *  utmost importance to some applications.

 *

 * PhysicsFS is mostly thread safe. The errors returned by

 *  PHYSFS_getLastErrorCode() are unique by thread, and library-state-setting

 *  functions are mutex'd. For efficiency, individual file accesses are

 *  not locked, so you can not safely read/write/seek/close/etc the same

 *  file from two threads at the same time. Other race conditions are bugs

 *  that should be reported/patched.

 *

 * While you CAN use stdio/syscall file access in a program that has PHYSFS_*

 *  calls, doing so is not recommended, and you can not directly use system

 *  filehandles with PhysicsFS and vice versa (but as of PhysicsFS 2.1, you

 *  can wrap them in a PHYSFS_Io interface yourself if you wanted to).

 *

 * Note that archives need not be named as such: if you have a ZIP file and

 *  rename it with a .PKG extension, the file will still be recognized as a

 *  ZIP archive by PhysicsFS; the file's contents are used to determine its

 *  type where possible.

 *

 * Currently supported archive types:

 *   - .ZIP (pkZip/WinZip/Info-ZIP compatible)

 *   - .7Z  (7zip archives)

 *   - .ISO (ISO9660 files, CD-ROM images)

 *   - .GRP (Build Engine groupfile archives)

 *   - .PAK (Quake I/II archive format)

 *   - .HOG (Descent I/II HOG file archives)

 *   - .MVL (Descent II movielib archives)

 *   - .WAD (DOOM engine archives)

 *   - .VDF (Gothic I/II engine archives)

 *   - .SLB (Independence War archives)

 *

 * String policy for PhysicsFS 2.0 and later:

 *

 * PhysicsFS 1.0 could only deal with null-terminated ASCII strings. All high

 *  ASCII chars resulted in undefined behaviour, and there was no Unicode

 *  support at all. PhysicsFS 2.0 supports Unicode without breaking binary

 *  compatibility with the 1.0 API by using UTF-8 encoding of all strings

 *  passed in and out of the library.

 *

 * All strings passed through PhysicsFS are in null-terminated UTF-8 format.

 *  This means that if all you care about is English (ASCII characters <= 127)

 *  then you just use regular C strings. If you care about Unicode (and you

 *  should!) then you need to figure out what your platform wants, needs, and

 *  offers. If you are on Windows before Win2000 and build with Unicode

 *  support, your TCHAR strings are two bytes per character (this is called

 *  "UCS-2 encoding"). Any modern Windows uses UTF-16, which is two bytes

 *  per character for most characters, but some characters are four. You

 *  should convert them to UTF-8 before handing them to PhysicsFS with

 *  PHYSFS_utf8FromUtf16(), which handles both UTF-16 and UCS-2. If you're

 *  using Unix or Mac OS X, your wchar_t strings are four bytes per character

 *  ("UCS-4 encoding", sometimes called "UTF-32"). Use PHYSFS_utf8FromUcs4().

 *  Mac OS X can give you UTF-8 directly from a CFString or NSString, and many

 *  Unixes generally give you C strings in UTF-8 format everywhere. If you

 *  have a single-byte high ASCII charset, like so-many European "codepages"

 *  you may be out of luck. We'll convert from "Latin1" to UTF-8 only, and

 *  never back to Latin1. If you're above ASCII 127, all bets are off: move

 *  to Unicode or use your platform's facilities. Passing a C string with

 *  high-ASCII data that isn't UTF-8 encoded will NOT do what you expect!

 *

 * Naturally, there's also PHYSFS_utf8ToUcs2(), PHYSFS_utf8ToUtf16(), and

 *  PHYSFS_utf8ToUcs4() to get data back into a format you like. Behind the

 *  scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on

 *  Windows will be converted and used with the multibyte Windows APIs, for

 *  example.

 *

 * PhysicsFS offers basic encoding conversion support, but not a whole string

 *  library. Get your stuff into whatever format you can work with.

 *

 * Most platforms supported by PhysicsFS 2.1 and later fully support Unicode.

 *  Some older platforms have been dropped (Windows 95, Mac OS 9). Some, like

 *  OS/2, might be able to convert to a local codepage or will just fail to

 *  open/create the file. Modern OSes (macOS, Linux, Windows, etc) should all

 *  be fine.

 *

 * Many game-specific archivers are seriously unprepared for Unicode (the

 *  Descent HOG/MVL and Build Engine GRP archivers, for example, only offer a

 *  DOS 8.3 filename, for example). Nothing can be done for these, but they

 *  tend to be legacy formats for existing content that was all ASCII (and

 *  thus, valid UTF-8) anyhow. Other formats, like .ZIP, don't explicitly

 *  offer Unicode support, but unofficially expect filenames to be UTF-8

 *  encoded, and thus Just Work. Most everything does the right thing without

 *  bothering you, but it's good to be aware of these nuances in case they

 *  don't.

 *

 *

 * Other stuff:

 *

 * Please see the file LICENSE.txt in the source's root directory for

 *  licensing and redistribution rights.

 *

 * Please see the file CREDITS.txt in the source's "docs" directory for

 *  a more or less complete list of who's responsible for this.

 *

 *  \author Ryan C. Gordon.

 */

#ifndef _INCLUDE_PHYSFS_H_

#define _INCLUDE_PHYSFS_H_

#ifdef __cplusplus

extern "C" {

#endif

#if defined(PHYSFS_DECL)

/* do nothing. */

#elif defined(_MSC_VER)

#define PHYSFS_DECL __declspec(dllexport)

#elif defined(__SUNPRO_C)

#define PHYSFS_DECL __global

#elif ((__GNUC__ >= 3) && (!defined(__EMX__)) && (!defined(sun)))

#define PHYSFS_DECL __attribute__((visibility("default")))

#else

#define PHYSFS_DECL

#endif

#if defined(PHYSFS_DEPRECATED)

/* do nothing. */

#elif (__GNUC__ >= 4)  /* technically, this arrived in gcc 3.1, but oh well. */

#define PHYSFS_DEPRECATED __attribute__((deprecated))

#else

#define PHYSFS_DEPRECATED

#endif

#if 0  /* !!! FIXME: look into this later. */

#if defined(PHYSFS_CALL)

/* do nothing. */

#elif defined(__WIN32__) && !defined(__GNUC__)

#define PHYSFS_CALL __cdecl

#elif defined(__OS2__) || defined(OS2) /* should work across all compilers. */

#define PHYSFS_CALL _System

#else

#define PHYSFS_CALL

#endif

#endif

/**

 * \typedef PHYSFS_uint8

 * \brief An unsigned, 8-bit integer type.

 */

typedef unsigned char         PHYSFS_uint8;

/**

 * \typedef PHYSFS_sint8

 * \brief A signed, 8-bit integer type.

 */

typedef signed char           PHYSFS_sint8;

/**

 * \typedef PHYSFS_uint16

 * \brief An unsigned, 16-bit integer type.

 */

typedef unsigned short        PHYSFS_uint16;

/**

 * \typedef PHYSFS_sint16

 * \brief A signed, 16-bit integer type.

 */

typedef signed short          PHYSFS_sint16;

/**

 * \typedef PHYSFS_uint32

 * \brief An unsigned, 32-bit integer type.

 */

typedef unsigned int          PHYSFS_uint32;

/**

 * \typedef PHYSFS_sint32

 * \brief A signed, 32-bit integer type.

 */

typedef signed int            PHYSFS_sint32;

/**

 * \typedef PHYSFS_uint64

 * \brief An unsigned, 64-bit integer type.

 * \warning on platforms without any sort of 64-bit datatype, this is

 *           equivalent to PHYSFS_uint32!

 */

/**

 * \typedef PHYSFS_sint64

 * \brief A signed, 64-bit integer type.

 * \warning on platforms without any sort of 64-bit datatype, this is

 *           equivalent to PHYSFS_sint32!

 */

#if (defined PHYSFS_NO_64BIT_SUPPORT)  /* oh well. */

typedef PHYSFS_uint32         PHYSFS_uint64;

typedef PHYSFS_sint32         PHYSFS_sint64;

#elif (defined _MSC_VER)

typedef signed __int64        PHYSFS_sint64;

typedef unsigned __int64      PHYSFS_uint64;

#else

typedef unsigned long long    PHYSFS_uint64;

typedef signed long long      PHYSFS_sint64;

#endif

#ifndef DOXYGEN_SHOULD_IGNORE_THIS

/* Make sure the types really have the right sizes */

#define PHYSFS_COMPILE_TIME_ASSERT(name, x) \

       typedef int PHYSFS_compile_time_assert_##name[(x) * 2 - 1]

PHYSFS_COMPILE_TIME_ASSERT(uint8IsOneByte, sizeof(PHYSFS_uint8) == 1);

PHYSFS_COMPILE_TIME_ASSERT(sint8IsOneByte, sizeof(PHYSFS_sint8) == 1);

PHYSFS_COMPILE_TIME_ASSERT(uint16IsTwoBytes, sizeof(PHYSFS_uint16) == 2);

PHYSFS_COMPILE_TIME_ASSERT(sint16IsTwoBytes, sizeof(PHYSFS_sint16) == 2);

PHYSFS_COMPILE_TIME_ASSERT(uint32IsFourBytes, sizeof(PHYSFS_uint32) == 4);

PHYSFS_COMPILE_TIME_ASSERT(sint32IsFourBytes, sizeof(PHYSFS_sint32) == 4);

#ifndef PHYSFS_NO_64BIT_SUPPORT

PHYSFS_COMPILE_TIME_ASSERT(uint64IsEightBytes, sizeof(PHYSFS_uint64) == 8);

PHYSFS_COMPILE_TIME_ASSERT(sint64IsEightBytes, sizeof(PHYSFS_sint64) == 8);

#endif

#undef PHYSFS_COMPILE_TIME_ASSERT

#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */

/**

 * \struct PHYSFS_File

 * \brief A PhysicsFS file handle.

 *

 * You get a pointer to one of these when you open a file for reading,

 *  writing, or appending via PhysicsFS.

 *

 * As you can see from the lack of meaningful fields, you should treat this

 *  as opaque data. Don't try to manipulate the file handle, just pass the

 *  pointer you got, unmolested, to various PhysicsFS APIs.

 *

 * \sa PHYSFS_openRead

 * \sa PHYSFS_openWrite

 * \sa PHYSFS_openAppend

 * \sa PHYSFS_close

 * \sa PHYSFS_read

 * \sa PHYSFS_write

 * \sa PHYSFS_seek

 * \sa PHYSFS_tell

 * \sa PHYSFS_eof

 * \sa PHYSFS_setBuffer

 * \sa PHYSFS_flush

 */

typedef struct PHYSFS_File

{

    void *opaque;  /**< That's all you get. Don't touch. */

} PHYSFS_File;

/**

 * \def PHYSFS_file

 * \brief 1.0 API compatibility define.

 *

 * PHYSFS_file is identical to PHYSFS_File. This #define is here for backwards

 *  compatibility with the 1.0 API, which had an inconsistent capitalization

 *  convention in this case. New code should use PHYSFS_File, as this #define

 *  may go away someday.

 *

 * \sa PHYSFS_File

 */

#define PHYSFS_file PHYSFS_File

/**

 * \struct PHYSFS_ArchiveInfo

 * \brief Information on various PhysicsFS-supported archives.

 *

 * This structure gives you details on what sort of archives are supported

 *  by this implementation of PhysicsFS. Archives tend to be things like

 *  ZIP files and such.

 *

 * \warning Not all binaries are created equal! PhysicsFS can be built with

 *          or without support for various archives. You can check with

 *          PHYSFS_supportedArchiveTypes() to see if your archive type is

 *          supported.

 *

 * \sa PHYSFS_supportedArchiveTypes

 * \sa PHYSFS_registerArchiver

 * \sa PHYSFS_deregisterArchiver

 */

typedef struct PHYSFS_ArchiveInfo

{

    const char *extension;   /**< Archive file extension: "ZIP", for example. */

    const char *description; /**< Human-readable archive description. */

    const char *author;      /**< Person who did support for this archive. */

    const char *url;         /**< URL related to this archive */

    int supportsSymlinks;    /**< non-zero if archive offers symbolic links. */

} PHYSFS_ArchiveInfo;

/**

 * \struct PHYSFS_Version

 * \brief Information the version of PhysicsFS in use.

 *

 * Represents the library's version as three levels: major revision

 *  (increments with massive changes, additions, and enhancements),

 *  minor revision (increments with backwards-compatible changes to the

 *  major revision), and patchlevel (increments with fixes to the minor

 *  revision).

 *

 * \sa PHYSFS_VERSION

 * \sa PHYSFS_getLinkedVersion

 */

typedef struct PHYSFS_Version

{

    PHYSFS_uint8 major; /**< major revision */

    PHYSFS_uint8 minor; /**< minor revision */

    PHYSFS_uint8 patch; /**< patchlevel */

} PHYSFS_Version;

#ifndef DOXYGEN_SHOULD_IGNORE_THIS

#define PHYSFS_VER_MAJOR 3

#define PHYSFS_VER_MINOR 0

#define PHYSFS_VER_PATCH 2

#endif  /* DOXYGEN_SHOULD_IGNORE_THIS */

/* PhysicsFS state stuff ... */

/**

 * \def PHYSFS_VERSION(x)

 * \brief Macro to determine PhysicsFS version program was compiled against.

 *

 * This macro fills in a PHYSFS_Version structure with the version of the

 *  library you compiled against. This is determined by what header the

 *  compiler uses. Note that if you dynamically linked the library, you might

 *  have a slightly newer or older version at runtime. That version can be

 *  determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,

 *  is not a macro.

 *

 * \param x A pointer to a PHYSFS_Version struct to initialize.

 *

 * \sa PHYSFS_Version

 * \sa PHYSFS_getLinkedVersion

 */

#define PHYSFS_VERSION(x) \

{ \

    (x)->major = PHYSFS_VER_MAJOR; \

    (x)->minor = PHYSFS_VER_MINOR; \

    (x)->patch = PHYSFS_VER_PATCH; \

}

/**

 * \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)

 * \brief Get the version of PhysicsFS that is linked against your program.

 *

 * If you are using a shared library (DLL) version of PhysFS, then it is

 *  possible that it will be different than the version you compiled against.

 *

 * This is a real function; the macro PHYSFS_VERSION tells you what version

 *  of PhysFS you compiled against:

 *

 * \code

 * PHYSFS_Version compiled;

 * PHYSFS_Version linked;

 *

 * PHYSFS_VERSION(&compiled);

 * PHYSFS_getLinkedVersion(&linked);

 * printf("We compiled against PhysFS version %d.%d.%d ...\n",

 *           compiled.major, compiled.minor, compiled.patch);

 * printf("But we linked against PhysFS version %d.%d.%d.\n",

 *           linked.major, linked.minor, linked.patch);

 * \endcode

 *

 * This function may be called safely at any time, even before PHYSFS_init().

 *

 * \sa PHYSFS_VERSION

 */

PHYSFS_DECL void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);

/**

 * \fn int PHYSFS_init(const char *argv0)

 * \brief Initialize the PhysicsFS library.

 *

 * This must be called before any other PhysicsFS function.

 *

 * This should be called prior to any attempts to change your process's

 *  current working directory.

 *

 *   \param argv0 the argv[0] string passed to your program's mainline.

 *          This may be NULL on most platforms (such as ones without a

 *          standard main() function), but you should always try to pass

 *          something in here. Unix-like systems such as Linux _need_ to

 *          pass argv[0] from main() in here.

 *  \return nonzero on success, zero on error. Specifics of the error can be

 *          gleaned from PHYSFS_getLastError().

 *

 * \sa PHYSFS_deinit

 * \sa PHYSFS_isInit

 */

PHYSFS_DECL int PHYSFS_init(const char *argv0);

/**

 * \fn int PHYSFS_deinit(void)

 * \brief Deinitialize the PhysicsFS library.

 *

 * This closes any files opened via PhysicsFS, blanks the search/write paths,

 *  frees memory, and invalidates all of your file handles.

 *

 * Note that this call can FAIL if there's a file open for writing that

 *  refuses to close (for example, the underlying operating system was

 *  buffering writes to network filesystem, and the fileserver has crashed,

 *  or a hard drive has failed, etc). It is usually best to close all write

 *  handles yourself before calling this function, so that you can gracefully

 *  handle a specific failure.

 *

 * Once successfully deinitialized, PHYSFS_init() can be called again to

 *  restart the subsystem. All default API states are restored at this

 *  point, with the exception of any custom allocator you might have

 *  specified, which survives between initializations.

 *

 *  \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.

 *

 * \sa PHYSFS_init

 * \sa PHYSFS_isInit

 */

PHYSFS_DECL int PHYSFS_deinit(void);

/**

 * \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)

 * \brief Get a list of supported archive types.

 *

 * Get a list of archive types supported by this implementation of PhysicFS.

 *  These are the file formats usable for search path entries. This is for

 *  informational purposes only. Note that the extension listed is merely

 *  convention: if we list "ZIP", you can open a PkZip-compatible archive

 *  with an extension of "XYZ", if you like.

 *

 * The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,

 *  with a NULL entry to signify the end of the list:

 *

 * \code

 * PHYSFS_ArchiveInfo **i;

 *

 * for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)

 * {

 *     printf("Supported archive: [%s], which is [%s].\n",

 *              (*i)->extension, (*i)->description);

 * }

 * \endcode

 *

 * The return values are pointers to internal memory, and should

 *  be considered READ ONLY, and never freed. The returned values are

 *  valid until the next call to PHYSFS_deinit(), PHYSFS_registerArchiver(),

 *  or PHYSFS_deregisterArchiver().

 *

 *   \return READ ONLY Null-terminated array of READ ONLY structures.

 *

 * \sa PHYSFS_registerArchiver

 * \sa PHYSFS_deregisterArchiver

 */

PHYSFS_DECL const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);

/**

 * \fn void PHYSFS_freeList(void *listVar)

 * \brief Deallocate resources of lists returned by PhysicsFS.

 *

 * Certain PhysicsFS functions return lists of information that are

 *  dynamically allocated. Use this function to free those resources.

 *

 * It is safe to pass a NULL here, but doing so will cause a crash in versions

 *  before PhysicsFS 2.1.0.

 *

 *   \param listVar List of information specified as freeable by this function.

 *                  Passing NULL is safe; it is a valid no-op.

 *

 * \sa PHYSFS_getCdRomDirs

 * \sa PHYSFS_enumerateFiles

 * \sa PHYSFS_getSearchPath

 */

PHYSFS_DECL void PHYSFS_freeList(void *listVar);

/**

 * \fn const char *PHYSFS_getLastError(void)

 * \brief Get human-readable error information.

 *

 * \deprecated Use PHYSFS_getLastErrorCode() and PHYSFS_getErrorByCode() instead.

 *

 * \warning As of PhysicsFS 2.1, this function has been nerfed.

 *          Before PhysicsFS 2.1, this function was the only way to get

 *          error details beyond a given function's basic return value.

 *          This was meant to be a human-readable string in one of several

 *          languages, and was not useful for application parsing. This was

 *          a problem, because the developer and not the user chose the

 *          language at compile time, and the PhysicsFS maintainers had

 *          to (poorly) maintain a significant amount of localization work.

 *          The app couldn't parse the strings, even if they counted on a

 *          specific language, since some were dynamically generated.

 *          In 2.1 and later, this always returns a static string in

 *          English; you may use it as a key string for your own

 *          localizations if you like, as we'll promise not to change

 *          existing error strings. Also, if your application wants to

 *          look at specific errors, we now offer a better option:

 *          use PHYSFS_getLastErrorCode() instead.

 *

 * Get the last PhysicsFS error message as a human-readable, null-terminated

 *  string. This will return NULL if there's been no error since the last call

 *  to this function. The pointer returned by this call points to an internal

 *  buffer. Each thread has a unique error state associated with it, but each

 *  time a new error message is set, it will overwrite the previous one

 *  associated with that thread. It is safe to call this function at anytime,

 *  even before PHYSFS_init().

 *

 * PHYSFS_getLastError() and PHYSFS_getLastErrorCode() both reset the same

 *  thread-specific error state. Calling one will wipe out the other's

 *  data. If you need both, call PHYSFS_getLastErrorCode(), then pass that

 *  value to PHYSFS_getErrorByCode().

 *

 * As of PhysicsFS 2.1, this function only presents text in the English

 *  language, but the strings are static, so you can use them as keys into

 *  your own localization dictionary. These strings are meant to be passed on

 *  directly to the user.

 *

 * Generally, applications should only concern themselves with whether a

 *  given function failed; however, if your code require more specifics, you

 *  should use PHYSFS_getLastErrorCode() instead of this function.

 *

 *   \return READ ONLY string of last error message.

 *

 * \sa PHYSFS_getLastErrorCode

 * \sa PHYSFS_getErrorByCode

 */

PHYSFS_DECL const char *PHYSFS_getLastError(void) PHYSFS_DEPRECATED;

/**

 * \fn const char *PHYSFS_getDirSeparator(void)

 * \brief Get platform-dependent dir separator string.

 *

 * This returns "\\" on win32, "/" on Unix, 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 dirs 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 dir separator.

 */

PHYSFS_DECL const char *PHYSFS_getDirSeparator(void);

/**

 * \fn void PHYSFS_permitSymbolicLinks(int allow)

 * \brief Enable or disable following of symbolic links.

 *

 * Some physical filesystems and archives contain files that are just pointers

 *  to other files. On the physical filesystem, opening such a link will

 *  (transparently) open the file that is pointed to.

 *

 * By default, PhysicsFS will check if a file is really a symlink during open

 *  calls and fail if it is. Otherwise, the link could take you outside the

 *  write and search paths, and compromise security.

 *

 * If you want to take that risk, call this function with a non-zero parameter.

 *  Note that this is more for sandboxing a program's scripting language, in

 *  case untrusted scripts try to compromise the system. Generally speaking,

 *  a user could very well have a legitimate reason to set up a symlink, so

 *  unless you feel there's a specific danger in allowing them, you should

 *  permit them.

 *

 * Symlinks are only explicitly checked when dealing with filenames

 *  in platform-independent notation. That is, when setting up your

 *  search and write paths, etc, symlinks are never checked for.

 *

 * Please note that PHYSFS_stat() will always check the path specified; if

 *  that path is a symlink, it will not be followed in any case. If symlinks

 *  aren't permitted through this function, PHYSFS_stat() ignores them, and

 *  would treat the query as if the path didn't exist at all.

 *

 * Symbolic link permission can be enabled or disabled at any time after

 *  you've called PHYSFS_init(), and is disabled by default.

 *

 *   \param allow nonzero to permit symlinks, zero to deny linking.

 *

 * \sa PHYSFS_symbolicLinksPermitted

 */

PHYSFS_DECL void PHYSFS_permitSymbolicLinks(int allow);

/**

 * \fn char **PHYSFS_getCdRomDirs(void)

 * \brief Get an array of paths to available CD-ROM drives.

 *

 * The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or

 *  whatnot on Unix). Dirs are only returned if there is a disc ready and

 *  accessible in the drive. So if you've got two drives (D: and E:), and only

 *  E: has a disc in it, then that's all you get. If the user inserts a disc

 *  in D: and you call this function again, you get both drives. If, on a

 *  Unix box, the user unmounts a disc and remounts it elsewhere, the next

 *  call to this function will reflect that change.

 *

 * This function refers to "CD-ROM" media, but it really means "inserted disc

 *  media," such as DVD-ROM, HD-DVD, CDRW, and Blu-Ray discs. It looks for

 *  filesystems, and as such won't report an audio CD, unless there's a

 *  mounted filesystem track on it.

 *

 * The returned value is an array of strings, with a NULL entry to signify the

 *  end of the list:

 *

 * \code

 * char **cds = PHYSFS_getCdRomDirs();

 * char **i;

 *

 * for (i = cds; *i != NULL; i++)

 *     printf("cdrom dir [%s] is available.\n", *i);

 *

 * PHYSFS_freeList(cds);

 * \endcode

 *

 * This call may block while drives spin up. Be forewarned.

 *

 * When you are done with the returned information, you may dispose of the

 *  resources by calling PHYSFS_freeList() with the returned pointer.

 *

 *   \return Null-terminated array of null-terminated strings.

 *

 * \sa PHYSFS_getCdRomDirsCallback

 */

PHYSFS_DECL char **PHYSFS_getCdRomDirs(void);

/**

 * \fn const char *PHYSFS_getBaseDir(void)

 * \brief Get the path where the application resides.

 *

 * Helper function.

 *

 * Get the "base dir". This is the directory where the application was run

 *  from, which is probably the installation directory, and may or may not

 *  be the process's current working directory.

 *

 * You should probably use the base dir in your search path.

 *

 *  \return READ ONLY string of base dir in platform-dependent notation.

 *

 * \sa PHYSFS_getPrefDir

 */

PHYSFS_DECL const char *PHYSFS_getBaseDir(void);

/**

 * \fn const char *PHYSFS_getUserDir(void)

 * \brief Get the path where user's home directory resides.

 *

 * \deprecated As of PhysicsFS 2.1, you probably want PHYSFS_getPrefDir().

 *

 * Helper function.

 *

 * Get the "user dir". This is meant to be a suggestion of where a specific

 *  user of the system can store files. On Unix, this is her home directory.

 *  On systems with no concept of multiple home directories (MacOS, win95),

 *  this will default to something like "C:\mybasedir\users\username"

 *  where "username" will either be the login name, or "default" if the

 *  platform doesn't support multiple users, either.

 *

 *  \return READ ONLY string of user dir in platform-dependent notation.

 *

 * \sa PHYSFS_getBaseDir

 * \sa PHYSFS_getPrefDir

 */

PHYSFS_DECL const char *PHYSFS_getUserDir(void) PHYSFS_DEPRECATED;

/**

 * \fn const char *PHYSFS_getWriteDir(void)

 * \brief Get path where PhysicsFS will allow file writing.

 *

 * Get the current write dir. The default write dir is NULL.

 *

 *  \return READ ONLY string of write dir in platform-dependent notation,

 *           OR NULL IF NO WRITE PATH IS CURRENTLY SET.

 *

 * \sa PHYSFS_setWriteDir

 */

PHYSFS_DECL const char *PHYSFS_getWriteDir(void);

/**

 * \fn int PHYSFS_setWriteDir(const char *newDir)

 * \brief Tell PhysicsFS where it may write files.

 *

 * Set a new write dir. This will override the previous setting.

 *

 * This call will fail (and fail to change the write dir) if the current

 *  write dir still has files open in it.

 *

 *   \param newDir The new directory to be the root of the write dir,

 *                   specified in platform-dependent notation. Setting to NULL

 *                   disables the write dir, so no files can be opened for

 *                   writing via PhysicsFS.

 *  \return non-zero on success, zero on failure. All attempts to open a file

 *           for writing via PhysicsFS will fail until this call succeeds.

 *           Use PHYSFS_getLastErrorCode() to obtain the specific error.

 *

 * \sa PHYSFS_getWriteDir

 */

PHYSFS_DECL int PHYSFS_setWriteDir(const char *newDir);

/**

 * \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)

 * \brief Add an archive or directory to the search path.

 *

 * \deprecated As of PhysicsFS 2.0, use PHYSFS_mount() instead. This

 *             function just wraps it anyhow.

 *

 * This function is equivalent to:

 *

 * \code

 *  PHYSFS_mount(newDir, NULL, appendToPath);

 * \endcode

 *

 * You must use this and not PHYSFS_mount if binary compatibility with

 *  PhysicsFS 1.0 is important (which it may not be for many people).

 *

 * \sa PHYSFS_mount

 * \sa PHYSFS_removeFromSearchPath

 * \sa PHYSFS_getSearchPath

 */

PHYSFS_DECL int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)

                                        PHYSFS_DEPRECATED;

/**

 * \fn int PHYSFS_removeFromSearchPath(const char *oldDir)

 * \brief Remove a directory or archive from the search path.

 *

 * \deprecated As of PhysicsFS 2.1, use PHYSFS_unmount() instead. This

 *             function just wraps it anyhow. There's no functional difference

 *             except the vocabulary changed from "adding to the search path"

 *             to "mounting" when that functionality was extended, and thus

 *             the preferred way to accomplish this function's work is now

 *             called "unmounting."

 *

 * This function is equivalent to:

 *

 * \code

 *  PHYSFS_unmount(oldDir);

 * \endcode

 *

 * You must use this and not PHYSFS_unmount if binary compatibility with

 *  PhysicsFS 1.0 is important (which it may not be for many people).

 *

 * \sa PHYSFS_addToSearchPath

 * \sa PHYSFS_getSearchPath

 * \sa PHYSFS_unmount

 */

PHYSFS_DECL int PHYSFS_removeFromSearchPath(const char *oldDir)

                                            PHYSFS_DEPRECATED;

/**

 * \fn char **PHYSFS_getSearchPath(void)

 * \brief Get the current search path.

 *

 * The default search path is an empty list.

 *

 * The returned value is an array of strings, with a NULL entry to signify the

 *  end of the list:

 *

 * \code

 * char **i;

 *

 * for (i = PHYSFS_getSearchPath(); *i != NULL; i++)

 *     printf("[%s] is in the search path.\n", *i);

 * \endcode

 *

 * When you are done with the returned information, you may dispose of the

 *  resources by calling PHYSFS_freeList() with the returned pointer.

 *

 *   \return Null-terminated array of null-terminated strings. NULL if there

 *            was a problem (read: OUT OF MEMORY).

 *

 * \sa PHYSFS_getSearchPathCallback

 * \sa PHYSFS_addToSearchPath

 * \sa PHYSFS_removeFromSearchPath

 */

PHYSFS_DECL char **PHYSFS_getSearchPath(void);

/**

 * \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)

 * \brief Set up sane, default paths.

 *

 * Helper function.

 *

 * The write dir will be set to the pref dir returned by

 *  \code PHYSFS_getPrefDir(organization, appName) \endcode, which is

 *  created if it doesn't exist.

 *

 * The above is sufficient to make sure your program's configuration directory

 *  is separated from other clutter, and platform-independent.

 *

 *  The search path will be:

 *

 *    - The Write Dir (created if it doesn't exist)

 *    - The Base Dir (PHYSFS_getBaseDir())

 *    - All found CD-ROM dirs (optionally)

 *

 * These directories are then searched for files ending with the extension

 *  (archiveExt), which, if they are valid and supported archives, will also

 *  be added to the search path. If you specified "PKG" for (archiveExt), and

 *  there's a file named data.PKG in the base dir, it'll be checked. Archives

 *  can either be appended or prepended to the search path in alphabetical

 *  order, regardless of which directories they were found in. All archives

 *  are mounted in the root of the virtual file system ("/").

 *

 * All of this can be accomplished from the application, but this just does it

 *  all for you. Feel free to add more to the search path manually, too.

 *

 *    \param organization Name of your company/group/etc to be used as a

 *                         dirname, so keep it small, and no-frills.

 *

 *    \param appName Program-specific name of your program, to separate it

 *                   from other programs using PhysicsFS.

 *

 *    \param archiveExt File extension used by your program to specify an

 *                      archive. For example, Quake 3 uses "pk3", even though

 *                      they are just zipfiles. Specify NULL to not dig out

 *                      archives automatically. Do not specify the '.' char;

 *                      If you want to look for ZIP files, specify "ZIP" and

 *                      not ".ZIP" ... the archive search is case-insensitive.

 *

 *    \param includeCdRoms Non-zero to include CD-ROMs in the search path, and

 *                         (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. Ignored if !(archiveExt).

 *

 *  \return nonzero on success, zero on error. Use PHYSFS_getLastErrorCode()

 *          to obtain the specific error.

 */

PHYSFS_DECL int PHYSFS_setSaneConfig(const char *organization,

                                     const char *appName,

                                     const char *archiveExt,

                                     int includeCdRoms,