physfs.h(3)

📦

version 3.2.0 · 4 versions

3.2.0 · arch rolling, fedora 44 (latest)
3.0.2 · epel 9
3.0.2 · epel 10
3.0.2 · fedora 43

✨ `physfs.h(3)` ✨

Library Functions Manual — okay bestie, this is the PhysicsFS header page, and we're going through it together. No cap, it's giving "everything you need to know about physfs.h" and I'm obsessed. 💖

grab your iced coffee, bestie, because this is the synopsis and it's lowkey iconic. 💅

💖 NAME 💖

physfs.h — that's the name, periodt. The header that brings all the PhysicsFS declarations together.

🌸 SYNOPSIS 🌸

Okay so here's the whole vibe check: all the data structures, macros, typedefs, and enumerations that live in this header. Let's break it down, bestie. 🦋

🎀 Data Structures 🎀

struct PHYSFS_File — A PhysicsFS file handle. literally your main character for file operations.
struct PHYSFS_ArchiveInfo — Information on various PhysicsFS-supported archives.
struct PHYSFS_Version — Information the version of PhysicsFS in use. yes, the version info, slay.
struct PHYSFS_Allocator — PhysicsFS allocation function pointers.
struct PHYSFS_Stat — Meta data for a file or directory.
struct PHYSFS_Io — An abstract i/o interface.
struct PHYSFS_Archiver — Abstract interface to provide support for user-defined archives. custom archives? iconic.

🎀 Macros 🎀

#define PHYSFS_file PHYSFS_File — 1.0 API compatibility define. keeping the old name alive, no cap.
#define PHYSFS_VERSION(x) — Macro to determine PhysicsFS version program was compiled against.

🎀 Typedefs 🎀

typedef unsigned char PHYSFS_uint8 — An unsigned, 8-bit integer type.
typedef signed char PHYSFS_sint8 — A signed, 8-bit integer type.
typedef unsigned short PHYSFS_uint16 — An unsigned, 16-bit integer type.
typedef signed short PHYSFS_sint16 — A signed, 16-bit integer type.
typedef unsigned int PHYSFS_uint32 — An unsigned, 32-bit integer type.
typedef signed int PHYSFS_sint32 — A signed, 32-bit integer type.
typedef unsigned long long PHYSFS_uint64 — An unsigned, 64-bit integer type.
typedef signed long long PHYSFS_sint64 — A signed, 64-bit integer type.
typedef struct PHYSFS_File PHYSFS_File
typedef struct PHYSFS_ArchiveInfo PHYSFS_ArchiveInfo
typedef struct PHYSFS_Version PHYSFS_Version
typedef struct PHYSFS_Allocator PHYSFS_Allocator
typedef void(* PHYSFS_StringCallback) (void *data, const char *str) — Function signature for callbacks that report strings.
typedef void(* PHYSFS_EnumFilesCallback) (void *data, const char *origdir, const char *fname) — Function signature for callbacks that enumerate files.
typedef enum PHYSFS_EnumerateCallbackResult PHYSFS_EnumerateCallbackResult
typedef PHYSFS_EnumerateCallbackResult(* PHYSFS_EnumerateCallback) (void *data, const char *origdir, const char *fname) — Possible return values from PHYSFS_EnumerateCallback.
typedef enum PHYSFS_FileType PHYSFS_FileType
typedef struct PHYSFS_Stat PHYSFS_Stat
typedef struct PHYSFS_Io PHYSFS_Io
typedef enum PHYSFS_ErrorCode PHYSFS_ErrorCode
typedef struct PHYSFS_Archiver PHYSFS_Archiver

🎀 Enumerations 🎀

enum PHYSFS_EnumerateCallbackResult { PHYSFS_ENUM_ERROR = -1, PHYSFS_ENUM_STOP = 0, PHYSFS_ENUM_OK = 1 }
enum PHYSFS_FileType { PHYSFS_FILETYPE_REGULAR, PHYSFS_FILETYPE_DIRECTORY, PHYSFS_FILETYPE_SYMLINK, PHYSFS_FILETYPE_OTHER } — Type of a File.
enum PHYSFS_ErrorCode { PHYSFS_ERR_OK, PHYSFS_ERR_OTHER_ERROR, PHYSFS_ERR_OUT_OF_MEMORY, PHYSFS_ERR_NOT_INITIALIZED, PHYSFS_ERR_IS_INITIALIZED, PHYSFS_ERR_ARGV0_IS_NULL, PHYSFS_ERR_UNSUPPORTED, PHYSFS_ERR_PAST_EOF, PHYSFS_ERR_FILES_STILL_OPEN, PHYSFS_ERR_INVALID_ARGUMENT, PHYSFS_ERR_NOT_MOUNTED, PHYSFS_ERR_NOT_FOUND, PHYSFS_ERR_SYMLINK_FORBIDDEN, PHYSFS_ERR_NO_WRITE_DIR, PHYSFS_ERR_OPEN_FOR_READING, PHYSFS_ERR_OPEN_FOR_WRITING, PHYSFS_ERR_NOT_A_FILE, PHYSFS_ERR_READ_ONLY, PHYSFS_ERR_CORRUPT, PHYSFS_ERR_SYMLINK_LOOP, PHYSFS_ERR_IO, PHYSFS_ERR_PERMISSION, PHYSFS_ERR_NO_SPACE, PHYSFS_ERR_BAD_FILENAME, PHYSFS_ERR_BUSY, PHYSFS_ERR_DIR_NOT_EMPTY, PHYSFS_ERR_OS_ERROR, PHYSFS_ERR_DUPLICATE, PHYSFS_ERR_BAD_PASSWORD, PHYSFS_ERR_APP_CALLBACK } — Values that represent specific causes of failure.

✨ FUNCTIONS ✨

okay bestie, this is the main character list — every single function this header gives you, in order, no skips, no cuts. it's giving buffet. grab a plate 🍓

void PHYSFS_getLinkedVersion (PHYSFS_Version *ver) — tells you which version of PhysicsFS is the one actually linked against your program, and dumps it into *ver.
int PHYSFS_init (const char *argv0) — boot up the PhysicsFS library. pass it argv0.
int PHYSFS_deinit (void) — shut the whole library back down. closing time, everybody out 💅
const PHYSFS_ArchiveInfo ** PHYSFS_supportedArchiveTypes (void) — hands you the list of archive types it can deal with.
void PHYSFS_freeList (void *listVar) — frees up the resources for lists that PhysicsFS itself handed you. important: those lists are yours to free, not to free() yourself.
const char * PHYSFS_getLastError (void) — the human-readable tea on what just went wrong.
const char * PHYSFS_getDirSeparator (void) — the directory separator string for whatever platform you're on.
void PHYSFS_permitSymbolicLinks (int allow) — turn following of symbolic links on or off.
char ** PHYSFS_getCdRomDirs (void) — an array of paths pointing at the CD-ROM drives you've got.
const char * PHYSFS_getBaseDir (void) — where your application lives.
const char * PHYSFS_getUserDir (void) — where the user's home directory lives.
const char * PHYSFS_getWriteDir (void) — the path where PhysicsFS will actually let you write stuff.
int PHYSFS_setWriteDir (const char *newDir) — tell PhysicsFS where it's allowed to write files.
int PHYSFS_addToSearchPath (const char *newDir, int appendToPath) — add an archive or a directory onto the search path.
int PHYSFS_removeFromSearchPath (const char *oldDir) — take a directory or archive back off the search path. it's not you, it's the search path 🫶
char ** PHYSFS_getSearchPath (void) — the current search path, right now, as it stands.
int PHYSFS_setSaneConfig (const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst) — sets up sensible default paths for you so you don't have to hand-build the whole thing.
int PHYSFS_mkdir (const char *dirName) — make a directory.
int PHYSFS_delete (const char *filename) — delete a file or a directory.
const char * PHYSFS_getRealDir (const char *filename) — works out whereabouts in the search path a given file is actually sitting.
char ** PHYSFS_enumerateFiles (const char *dir) — get a listing of a directory inside the search path.
int PHYSFS_exists (const char *fname) — does this file exist in the search path? yes or no.
int PHYSFS_isDirectory (const char *fname) — is this thing in the search path genuinely a directory?
int PHYSFS_isSymbolicLink (const char *fname) — is this thing in the search path genuinely a symbolic link?
PHYSFS_sint64 PHYSFS_getLastModTime (const char *filename) — when was this file last modified?
PHYSFS_File * PHYSFS_openWrite (const char *filename) — open a file for writing.
PHYSFS_File * PHYSFS_openAppend (const char *filename) — open a file for appending.
PHYSFS_File * PHYSFS_openRead (const char *filename) — open a file for reading.
int PHYSFS_close (PHYSFS_File *handle) — close a PhysicsFS filehandle.

PHYSFS_sint64 PHYSFS_read (PHYSFS_File *handle, void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount) — read data out of a PhysicsFS filehandle.
PHYSFS_sint64 PHYSFS_write (PHYSFS_File *handle, const void *buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount) — write data into a PhysicsFS filehandle.
int PHYSFS_eof (PHYSFS_File *handle) — check whether a PhysicsFS filehandle has hit end-of-file.
PHYSFS_sint64 PHYSFS_tell (PHYSFS_File *handle) — where are we currently sitting inside this filehandle?
int PHYSFS_seek (PHYSFS_File *handle, PHYSFS_uint64 pos) — jump to a new position inside a PhysicsFS filehandle.
PHYSFS_sint64 PHYSFS_fileLength (PHYSFS_File *handle) — total length of a file, in bytes.
int PHYSFS_setBuffer (PHYSFS_File *handle, PHYSFS_uint64 bufsize) — set up buffering on a PhysicsFS file handle.
int PHYSFS_flush (PHYSFS_File *handle) — flush a buffered PhysicsFS file handle. do not skip this one, bestie, the vibes will not survive it.

byte-swap corner 🌈 all of these take a value in some endianness and hand it back in your platform's native byte order:

PHYSFS_sint16 PHYSFS_swapSLE16 (PHYSFS_sint16 val) — little-endian signed 16 → native.
PHYSFS_uint16 PHYSFS_swapULE16 (PHYSFS_uint16 val) — little-endian unsigned 16 → native.
PHYSFS_sint32 PHYSFS_swapSLE32 (PHYSFS_sint32 val) — little-endian signed 32 → native.
PHYSFS_uint32 PHYSFS_swapULE32 (PHYSFS_uint32 val) — little-endian unsigned 32 → native.
PHYSFS_sint64 PHYSFS_swapSLE64 (PHYSFS_sint64 val) — little-endian signed 64 → native.
PHYSFS_uint64 PHYSFS_swapULE64 (PHYSFS_uint64 val) — little-endian unsigned 64 → native.
PHYSFS_sint16 PHYSFS_swapSBE16 (PHYSFS_sint16 val) — big-endian signed 16 → native.
PHYSFS_uint16 PHYSFS_swapUBE16 (PHYSFS_uint16 val) — big-endian unsigned 16 → native.
PHYSFS_sint32 PHYSFS_swapSBE32 (PHYSFS_sint32 val) — big-endian signed 32 → native.
PHYSFS_uint32 PHYSFS_swapUBE32 (PHYSFS_uint32 val) — big-endian unsigned 32 → native.
PHYSFS_sint64 PHYSFS_swapSBE64 (PHYSFS_sint64 val) — big-endian signed 64 → native.
PHYSFS_uint64 PHYSFS_swapUBE64 (PHYSFS_uint64 val) — big-endian unsigned 64 → native.

and now the read-and-convert girlies, who read straight out of a file and do the endian flip for you 🦋

int PHYSFS_readSLE16 (PHYSFS_File *file, PHYSFS_sint16 *val) — read + convert a signed 16-bit little-endian value.
int PHYSFS_readULE16 (PHYSFS_File *file, PHYSFS_uint16 *val) — read + convert an unsigned 16-bit little-endian value.
int PHYSFS_readSBE16 (PHYSFS_File *file, PHYSFS_sint16 *val) — read + convert a signed 16-bit big-endian value.
int PHYSFS_readUBE16 (PHYSFS_File *file, PHYSFS_uint16 *val) — read + convert an unsigned 16-bit big-endian value.
int PHYSFS_readSLE32 (PHYSFS_File *file, PHYSFS_sint32 *val) — read + convert a signed 32-bit little-endian value.
int PHYSFS_readULE32 (PHYSFS_File *file, PHYSFS_uint32 *val) — read + convert an unsigned 32-bit little-endian value.
int PHYSFS_readSBE32 (PHYSFS_File *file, PHYSFS_sint32 *val) — read + convert a signed 32-bit big-endian value.
int PHYSFS_readUBE32 (PHYSFS_File *file, PHYSFS_uint32 *val) — read + convert an unsigned 32-bit big-endian value.
int PHYSFS_readSLE64 (PHYSFS_File *file, PHYSFS_sint64 *val) — read + convert a signed 64-bit little-endian value.
int PHYSFS_readULE64 (PHYSFS_File *file, PHYSFS_uint64 *val) — read + convert an unsigned 64-bit little-endian value.
int PHYSFS_readSBE64 (PHYSFS_File *file, PHYSFS_sint64 *val) — read + convert a signed 64-bit big-endian value.
int PHYSFS_readUBE64 (PHYSFS_File *file, PHYSFS_uint64 *val) — read + convert an unsigned 64-bit big-endian value.

their mirror-image cousins, the convert-and-write squad ✨

int PHYSFS_writeSLE16 (PHYSFS_File *file, PHYSFS_sint16 val) — convert + write a signed 16-bit little-endian value.
int PHYSFS_writeULE16 (PHYSFS_File *file, PHYSFS_uint16 val) — convert + write an unsigned 16-bit little-endian value.
int PHYSFS_writeSBE16 (PHYSFS_File *file, PHYSFS_sint16 val) — convert + write a signed 16-bit big-endian value.
int PHYSFS_writeUBE16 (PHYSFS_File *file, PHYSFS_uint16 val) — convert + write an unsigned 16-bit big-endian value.
int PHYSFS_writeSLE32 (PHYSFS_File *file, PHYSFS_sint32 val) — convert + write a signed 32-bit little-endian value.
int PHYSFS_writeULE32 (PHYSFS_File *file, PHYSFS_uint32 val) — convert + write an unsigned 32-bit little-endian value.
int PHYSFS_writeSBE32 (PHYSFS_File *file, PHYSFS_sint32 val) — convert + write a signed 32-bit big-endian value.
int PHYSFS_writeUBE32 (PHYSFS_File *file, PHYSFS_uint32 val) — convert + write an unsigned 32-bit big-endian value.
int PHYSFS_writeSLE64 (PHYSFS_File *file, PHYSFS_sint64 val) — convert + write a signed 64-bit little-endian value.
int PHYSFS_writeULE64 (PHYSFS_File *file, PHYSFS_uint64 val) — convert + write an unsigned 64-bit little-endian value.
int PHYSFS_writeSBE64 (PHYSFS_File *file, PHYSFS_sint64 val) — convert + write a signed 64-bit bigending value. (yes bestie, the page really does spell it "bigending" right there — we are preserving the lore, not fixing it 💀)
int PHYSFS_writeUBE64 (PHYSFS_File *file, PHYSFS_uint64 val) — convert + write an unsigned 64-bit big-endian value.

int PHYSFS_isInit (void) — is the PhysicsFS library initialized, or is it not?
int PHYSFS_symbolicLinksPermitted (void) — are symbolic links permitted around here?
int PHYSFS_setAllocator (const PHYSFS_Allocator *allocator) — hook your own allocation routines into PhysicsFS. bring your own memory management, queen 👑
int PHYSFS_mount (const char *newDir, const char *mountPoint, int appendToPath) — add an archive or directory onto the search path.
const char * PHYSFS_getMountPoint (const char *dir) — find out what mountpoint a mounted archive is using.
void PHYSFS_getCdRomDirsCallback (PHYSFS_StringCallback c, void *d) — list the CD-ROM directories, but through a callback you define yourself.
void PHYSFS_getSearchPathCallback (PHYSFS_StringCallback c, void *d) — walk the search path, again via your own application-defined callback.
void PHYSFS_enumerateFilesCallback (const char *dir, PHYSFS_EnumFilesCallback c, void *d) — get a directory listing from the search path, using an application-defined callback.
void PHYSFS_utf8FromUcs4 (const PHYSFS_uint32 *src, char *dst, PHYSFS_uint64 len) — convert a UCS-4 string over to UTF-8.
void PHYSFS_utf8ToUcs4 (const char *src, PHYSFS_uint32 *dst, PHYSFS_uint64 len) — convert a UTF-8 string over to UCS-4.
void PHYSFS_utf8FromUcs2 (const PHYSFS_uint16 *src, char *dst, PHYSFS_uint64 len) — convert a UCS-2 string over to UTF-8.
void PHYSFS_utf8ToUcs2 (const char *src, PHYSFS_uint16 *dst, PHYSFS_uint64 len) — convert a UTF-8 string over to UCS-2.
void PHYSFS_utf8FromLatin1 (const char *src, char *dst, PHYSFS_uint64 len) — converts a UTF-8 string over to Latin1. (and yes, that is exactly how the page describes PHYSFS_utf8FromLatin1 — we're reporting it, not judging it 🙈)
int PHYSFS_caseFold (const PHYSFS_uint32 from, PHYSFS_uint32 *to) — fold a Unicode codepoint down to its lowercase equivalent. (the raw text in the page comes through a little squished — Fold"aUnicodecodepointtoalowercaseequivalent. — but that's the gist, bestie.)
int PHYSFS_utf8stricmp (const char *str1, const char *str2) — case-insensitive compare of two UTF-8 strings.
int PHYSFS_utf16stricmp (const PHYSFS_uint16 *str1, const PHYSFS_uint16 *str2) — case-insensitive compare of two UTF-16 strings.
int PHYSFS_ucs4stricmp (const PHYSFS_uint32 *str1, const PHYSFS_uint32 *str2) — case-insensitive compare of two UCS-4 strings.
int PHYSFS_enumerate (const char *dir, PHYSFS_EnumerateCallback c, void *d) — a directory listing from the search path using an application-defined callback, except this one actually reports its errors back to you. the glow-up version, fr fr
int PHYSFS_unmount (const char *oldDir) — remove a directory or archive from the search path.
const PHYSFS_Allocator * PHYSFS_getAllocator (void) — find out which allocator is currently in play.
int PHYSFS_stat (const char *fname, PHYSFS_Stat *stat) — pull all sorts of info about a directory or a file. 🔍

okay bestie we're still in the function list, don't worry, it's almost over, but every single one of these deserves its moment 💅✨

void PHYSFS_utf8FromUtf16(const PHYSFS_uint16 *src, char *dst, PHYSFS_uint64 len) — glow-up a UTF-16 string into a UTF-8 string 🌈
void PHYSFS_utf8ToUtf16(const char *src, PHYSFS_uint16 *dst, PHYSFS_uint64 len) — and the other direction: UTF-8 string becomes a UTF-16 string 💫
PHYSFS_sint64 PHYSFS_readBytes(PHYSFS_File *handle, void *buffer, PHYSFS_uint64 len) — read bytes out of a PhysicsFS filehandle 📖
PHYSFS_sint64 PHYSFS_writeBytes(PHYSFS_File *handle, const void *buffer, PHYSFS_uint64 len) — write data into a PhysicsFS filehandle ✍️
int PHYSFS_mountIo(PHYSFS_Io *io, const char *newDir, const char *mountPoint, int appendToPath) — add an archive built on a PHYSFS_Io to the search path 🧚
int PHYSFS_mountMemory(const void *buf, PHYSFS_uint64 len, void (*del)(void *), const char *newDir, const char *mountPoint, int appendToPath) — add an archive that's just vibing inside a memory buffer to the search path 🍓
int PHYSFS_mountHandle(PHYSFS_File *file, const char *newDir, const char *mountPoint, int appendToPath) — add an archive contained in a PHYSFS_File handle to the search path 🎀
PHYSFS_ErrorCode PHYSFS_getLastErrorCode(void) — get machine-readable error info, iykyk 💀
const char * PHYSFS_getErrorByCode(PHYSFS_ErrorCode code) — get the human-readable description string for a given error code 🫶
void PHYSFS_setErrorCode(PHYSFS_ErrorCode code) — set the current thread's error code, main character energy 🔥
const char * PHYSFS_getPrefDir(const char *org, const char *app) — get the user-and-app-specific path where files can be written 📁
int PHYSFS_registerArchiver(const PHYSFS_Archiver *archiver) — add a new archiver to the system, we love a new hire ✨
int PHYSFS_deregisterArchiver(const char *ext) — remove an archiver from the system, okay bye 👋
int PHYSFS_setRoot(const char *archive, const char *subdir) — make a subdirectory of an archive act as its root directory 👑

💖 DETAILED DESCRIPTION 💖

Main header file for PhysicsFS. that's literally it, that's the whole description. it's THE header. the moment. the icon 🌟

🌸 MACRO DEFINITION DOCUMENTATION 🌸

`#define PHYSFS_file PHYSFS_File`

bestie this is a 1.0 API compatibility define. PHYSFS_file is identical to PHYSFS_File, no cap.

It's here for backwards compatibility with the 1.0 API, which had an inconsistent capitalization convention in this case 🙈. New code should use PHYSFS_File, because this #define may go away someday. don't get attached, it's giving temporary 💔

See also

PHYSFS_File

`#define PHYSFS_VERSION( x)`

Value:

{ \
    (x)->major = PHYSFS_VER_MAJOR; \
    (x)->minor = PHYSFS_VER_MINOR; \
    (x)->patch = PHYSFS_VER_PATCH; \
}

Macro to determine the PhysicsFS version your program was compiled against 🕰️.

This macro fills in a PHYSFS_Version structure with the version of the library you compiled against. That's determined by what header the compiler uses. Lowkey important caveat tho: if you dynamically linked the library, you might have a slightly newer or older version at runtime 👀. That runtime version can be determined with PHYSFS_getLinkedVersion(), which — unlike PHYSFS_VERSION — is not a macro. one of them is compile-time, one is runtime, they are not the same bestie, don't confuse them 💅

Parameters

x — A pointer to a PHYSFS_Version struct to initialize.

See also

PHYSFS_Version
PHYSFS_getLinkedVersion

🦋 TYPEDEF DOCUMENTATION 🦋

`typedef PHYSFS_EnumerateCallbackResult(* PHYSFS_EnumerateCallback) (void data, const char origdir, const char *fname)`

Possible return values from PHYSFS_EnumerateCallback. Function signature for callbacks that enumerate and return results 🎯.

These values dictate if an enumeration callback should continue to fire, or stop — and why it's stopping. yes bestie, your callback gets an opinion now, we love agency ✨

See also

PHYSFS_EnumerateCallback
PHYSFS_enumerate

This is the same thing as PHYSFS_EnumFilesCallback from PhysicsFS 2.0, except it can return a result from the callback. namely: if you're looking for something specific, once you find it, you can tell PhysicsFS to stop enumerating further 🔥. This is used with PHYSFS_enumerate(), which we hopefully got right this time. :)

Parameters

data — User-defined data pointer, passed through from the API that eventually called the callback.
origdir — A string containing the full path, in platform-independent notation, of the directory containing this file. In most cases, this is the directory on which you requested enumeration, passed in the callback for your convenience.
fname — The filename that is being enumerated. It may not be in alphabetical order compared to other callbacks that have fired, and it will not contain the full path. You can recreate the fullpath with $origdir/$fname ... The file can be a subdirectory, a file, a symlink, etc.

Returns

A value from PHYSFS_EnumerateCallbackResult. All other values are (currently) undefined; don't use them 🚫.

See also

PHYSFS_enumerate
PHYSFS_EnumerateCallbackResult

`typedef void(* PHYSFS_EnumFilesCallback) (void data, const char origdir, const char *fname)`

Function signature for callbacks that enumerate files 📂.

Warning — As of PhysicsFS 2.1, use PHYSFS_EnumerateCallback with PHYSFS_enumerate() instead; it gives you more control over the process. this one is so 2.0, we've moved on bestie 💅

These are used to report a list of directory entries to an original caller, one file/dir/symlink per callback. All strings are UTF-8 encoded 🌈. Functions should not try to modify or free any string's memory. hands off the strings, they are not yours 🙅

These callbacks are used, starting in PhysicsFS 1.1, as an alternative to functions that would return lists that need to be cleaned up with PHYSFS_freeList(). The callback means that the library doesn't need to allocate an entire list and all the strings up front — efficiency era 🧚

Be aware that promised data ordering in the list versions are not necessarily so in the callback versions. Check the documentation on specific APIs, but strings may not be sorted as you expect and you might get duplicate strings 👀. (yes, duplicates. the chaos is real.)

Parameters

data — User-defined data pointer, passed through from the API that eventually called the callback.
origdir — A string containing the full path, in platform-independent notation, of the directory containing this file. In most cases, this is the directory on which you requested enumeration, passed in the callback for your convenience.
fname — The filename that is being enumerated. It may not be in alphabetical order compared to other callbacks that have fired, and it will not contain the full path. You can recreate the fullpath with $origdir/$fname ... The file can be a subdirectory, a file, a symlink, etc.

See also

PHYSFS_enumerateFilesCallback

`typedef signed long long PHYSFS_sint64`

A signed, 64-bit integer type 🔢.

Warning — on platforms without any sort of 64-bit datatype, this is equivalent to PHYSFS_sint32! so on those platforms, surprise, you got 32 bits and nobody told you 😭

`typedef void(* PHYSFS_StringCallback) (void data, const char str)`

Function signature for callbacks that report strings 🎀. These are used to report a list of strings to an original caller, one string per callback. All strings are UTF-8 encoded 🌸. Functions should not try to modify or free the string's memory. again: hands off 🙈

Be aware that promises data ordering in the list versions are not necessarily so in the callback versions. Check the documentation on specific APIs, but strings may not be sorted as you expect. (note: this one doesn't promise duplicates, unlike its friend above. read carefully bestie 💜)

Parameters

data — User-defined data pointer, passed through from the API that eventually called the callback.
str — The string data about which the callback is meant to inform.

See also

PHYSFS_getCdRomDirsCallback
PHYSFS_getSearchPathCallback

`typedef unsigned long long PHYSFS_uint64`

An unsigned, 64-bit integer type 🔢✨

Warning — on platforms without any sort of 64-bit datatype, this is equivalent to PHYSFS_uint32! same deal as its signed sibling, but with no minus signs allowed 💀

✨ Enumeration Type Documentation ✨

`enum PHYSFS_EnumerateCallbackResult`

🌸 Enumerator 🌸

PHYSFS_ENUM_ERROR — stop the whole enumeration and report an error back to the app 💀
PHYSFS_ENUM_STOP — stop enumerating, but report success to the app ✋
PHYSFS_ENUM_OK — keep it going bestie, no problems here 💅

`enum PHYSFS_ErrorCode`

okay so these are the values that represent specific causes of failure. most of the time you should only care whether an operation failed or not, but sometimes you're planning to handle one specific failure case all graceful-like, so they hand you the specific error codes 🎀

ngl most of these errors are a little vague, and most aren't things you can actually fix... if there's a permission error, for example, all you can really do is pass that info on to the user and let them figure out how to handle it. in most of these cases, your program should only care that it failed to accomplish its goals, and not care specifically why 🙈

See also

PHYSFS_getLastErrorCode
PHYSFS_getErrorByCode

⭐ Enumerator ⭐

PHYSFS_ERR_OK — success; no error ✨
PHYSFS_ERR_OTHER_ERROR — error not otherwise covered here 🤷
PHYSFS_ERR_OUT_OF_MEMORY — memory allocation failed 😭
PHYSFS_ERR_NOT_INITIALIZED — PhysicsFS is not initialized
PHYSFS_ERR_IS_INITIALIZED — PhysicsFS is already initialized
PHYSFS_ERR_ARGV0_IS_NULL — needed argv[0], but it is NULL
PHYSFS_ERR_UNSUPPORTED — operation or feature unsupported
PHYSFS_ERR_PAST_EOF — attempted to access past end of file
PHYSFS_ERR_FILES_STILL_OPEN — files still open
PHYSFS_ERR_INVALID_ARGUMENT — bad parameter passed to an function
PHYSFS_ERR_NOT_MOUNTED — requested archive/dir not mounted
PHYSFS_ERR_NOT_FOUND — file (or whatever) not found
PHYSFS_ERR_SYMLINK_FORBIDDEN — symlink seen when not permitted
PHYSFS_ERR_NO_WRITE_DIR — no write dir has been specified
PHYSFS_ERR_OPEN_FOR_READING — wrote to a file opened for reading
PHYSFS_ERR_OPEN_FOR_WRITING — read from a file opened for writing
PHYSFS_ERR_NOT_A_FILE — needed a file, got a directory (etc)
PHYSFS_ERR_READ_ONLY — wrote to a read-only filesystem
PHYSFS_ERR_CORRUPT — corrupted data encountered
PHYSFS_ERR_SYMLINK_LOOP — infinite symbolic link loop 🌀
PHYSFS_ERR_IO — i/o error (hardware failure, etc)
PHYSFS_ERR_PERMISSION — permission denied 🚫
PHYSFS_ERR_NO_SPACE — no space (disk full, over quota, etc)
PHYSFS_ERR_BAD_FILENAME — filename is bogus/insecure
PHYSFS_ERR_BUSY — tried to modify a file the OS needs
PHYSFS_ERR_DIR_NOT_EMPTY — tried to delete dir with files in it
PHYSFS_ERR_OS_ERROR — unspecified OS-level error
PHYSFS_ERR_DUPLICATE — duplicate entry
PHYSFS_ERR_BAD_PASSWORD — bad password 🔐
PHYSFS_ERR_APP_CALLBACK — application callback reported error

`enum PHYSFS_FileType`

the type of a File. possible types of a file 🦋

See also

PHYSFS_stat

💜 Enumerator 💜

PHYSFS_FILETYPE_REGULAR — a normal file
PHYSFS_FILETYPE_DIRECTORY — a directory
PHYSFS_FILETYPE_SYMLINK — a symlink
PHYSFS_FILETYPE_OTHER — something completely different like a device

🔥 Function Documentation 🔥

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

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:

PHYSFS_mount(newDir, NULL, appendToPath);

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).

See also

PHYSFS_mount
PHYSFS_removeFromSearchPath
PHYSFS_getSearchPath

`int PHYSFS_caseFold (const PHYSFS_uint32 from, PHYSFS_uint32 * to)`

"fold" a Unicode codepoint to a lowercase equivalent. (this is for limited, hardcore use. if you don't immediately see a need for it, you can probably ignore this forever 💀)

this will convert a Unicode codepoint into its lowercase equivalent. bogus codepoints and codepoints without a lowercase equivalent will be returned unconverted.

note that you might get multiple codepoints in return! the German Eszett, for example, will fold down to two lowercase latin 's' codepoints. the theory is that if you fold two strings, one with an Eszett and one with "SS" down, they will match 👑

Warning — anyone that is a student of Unicode knows about the "Turkish I" problem. this API does not handle it. assume this one letter in all of Unicode will definitely fold sort of incorrectly. if you don't know what this is about, you can probably ignore this problem for most of the planet, but perfection is impossible 😭

Parameters

from — the codepoint to fold.
to — buffer to store the folded codepoint values into. this should point to space for at least 3 PHYSFS_uint32 slots.

Returns

the number of codepoints the folding produced. between 1 and 3.

`int PHYSFS_close (PHYSFS_File * handle)`

close a PhysicsFS filehandle 🎀

this call is capable of failing if the operating system was buffering writes to the physical media, and, now forced to write those changes to physical media, can not store the data for some reason. in such a case, the filehandle stays open. a well-written program should ALWAYS check the return value from the close call in addition to every writing call! no cap.

Parameters

handle — handle returned from PHYSFS_open*().

Returns

nonzero on success, zero on error. use PHYSFS_getLastErrorCode() to obtain the specific error.

See also

PHYSFS_openRead
PHYSFS_openWrite
PHYSFS_openAppend

`int PHYSFS_deinit (void )`

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 🌈

Returns

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 💀

See also

PHYSFS_init
PHYSFS_isInit

`int PHYSFS_delete (const char * filename)`

delete a file or directory 🗑️

(filename) is specified in platform-independent notation in relation to the write dir.

a directory must be empty before this call can delete it.

deleting a symlink will remove the link, not what it points to, regardless of whether you "permitSymLinks" or not.

so if you've got the write dir set to C:\mygame\writedir and call PHYSFS_delete("downloads/maps/level1.map") then the file C:\mygame\writedir\downloads\maps\level1.map 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.

chances are, the bits that make up the file still exist, they are just made available to be written over at a later point. don't consider this a security method or anything. :)

Parameters

filename — filename to delete.

Returns

nonzero on success, zero on error. use PHYSFS_getLastErrorCode() to obtain the specific error.

`int PHYSFS_deregisterArchiver (const char * ext)`

remove an archiver from the system 🧚

if for some reason, you only need your previously-registered archiver to live for a portion of your app's lifetime, you can remove it from the system once you're done with it through this function.

this fails if there are any archives still open that use this archiver.

this function can also remove internally-supplied archivers, like .zip support or whatnot. this could be useful in some situations, like disabling support for them outright or overriding them with your own implementation. once an internal archiver is disabled like this, PhysicsFS provides no mechanism to recover them, short of calling PHYSFS_deinit() and PHYSFS_init() again ⚠️

PHYSFS_deinit() will automatically deregister all archivers, so you don't need to explicitly deregister yours if you otherwise shut down cleanly ✨

Parameters

ext — filename extension that the archiver handles.

Returns

zero on error, non-zero on success.

See also

PHYSFS_Archiver
PHYSFS_registerArchiver

`int PHYSFS_enumerate (const char * dir, PHYSFS_EnumerateCallback c, void * d)`

get a file listing of a search path's directory, using an application-defined callback, with errors reported 🌸

internally, PHYSFS_enumerateFiles() just calls this function and then builds a list before returning to the application, so functionality is identical except for how the information is represented to the application.

unlike PHYSFS_enumerateFiles(), this function does not return an array. rather, it calls a function specified by the application once per element of the search path:

static PHYSFS_EnumerateCallbackResult printDir(void *data, const char *origdir, const char *fname)
{
    printf(" * We've got [%s] in [%s].\n", fname, origdir);
    return PHYSFS_ENUM_OK;  // give me more data, please.
}

// ...
PHYSFS_enumerate("/some/path", printDir, NULL);

items sent to the callback are not guaranteed to be in any order whatsoever. there is no sorting done at this level, and if you need that, you should probably use PHYSFS_enumerateFiles() instead, which guarantees alphabetical sorting. this form reports whatever is discovered in each archive before moving on to the next. even within one archive, we can't guarantee what order it will discover data. any sorting you find in these callbacks is just pure luck. do not rely on it 🙈 as this walks the entire list of archives, you may receive duplicate filenames.

okay so bestie, this API and the callbacks themselves are literally capable of reporting errors. Before this API, callbacks had to accept every enumerated item, even if they were only looking for one specific thing and wanted to stop after that, or had a serious error and couldn't alert anyone. And if PhysicsFS itself had a problem (disk error or whatnot), it couldn't report it to the calling app — it would just have to skip items or stop enumerating outright, and the caller wouldn't know it lost data along the way. 💀

Now the caller can be sure it got a complete data set, and its callback has control if it wants enumeration to stop early. See the documentation for PHYSFS_EnumerateCallback for details on how your callback should behave. ✨

Parameters 💖

dir — Directory, in platform-independent notation, to enumerate.
c — Callback function to notify about search path elements.
d — Application-defined data passed to callback. Can be NULL.

Returns ✨

non-zero on success, zero on failure. Use PHYSFS_getLastErrorCode() to obtain the specific error. If the callback returns PHYSFS_ENUM_STOP to stop early, this will be considered success. Callbacks returning PHYSFS_ENUM_ERROR will make this function return zero and set the error code to PHYSFS_ERR_APP_CALLBACK.

`char ** PHYSFS_enumerateFiles (const char * dir)`

Get a file listing of a search path's directory. It's giving inventory energy. 📂

Warning 🚨 In PhysicsFS versions prior to 2.1, this function would return as many items as it could in the face of a failure condition (out of memory, disk i/o error, etc). Since this meant apps couldn't distinguish between complete success and partial failure, and since the function could always return NULL to report catastrophic failures anyway, in PhysicsFS 2.1 this function's policy changed: it will either return a list of complete results or it will return NULL for any failure of any kind, so we can guarantee that the enumeration ran to completion and has no gaps in its results.

Matching directories are interpolated. That is, if "C:\mydir" is in the search path and contains a directory "savegames" that contains "x.sav", "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path that has a "savegames" subdirectory with "w.sav", then the following code:

char **rc = PHYSFS_enumerateFiles("savegames");
char **i;

for (i = rc; *i != NULL; i++)
    printf(" * We've got [%s].\n", *i);

PHYSFS_freeList(rc);

 * We've got [x.sav].
 * We've got [y.sav].
 * We've got [z.sav].
 * We've got [w.sav]..fi

Feel free to sort the list however you like. However, the returned data will always contain no duplicates, and will be always sorted in alphabetic (rather: case-sensitive Unicode) order for you. No cap. 🦋

Don't forget to call PHYSFS_freeList() with the return value from this function when you are done with it. Like, actually don't forget, bestie. 💅

Parameters 🌸

dir — directory in platform-independent notation to enumerate.

Returns ✨

Null-terminated array of null-terminated strings, or NULL for failure cases.

`void PHYSFS_enumerateFilesCallback (const char * dir, PHYSFS_EnumFilesCallback c, void * d)`

Get a file listing of a search path's directory, using an application-defined callback. Old school vibes. 📼

Deprecated 🚫 As of PhysicsFS 2.1, use PHYSFS_enumerate() instead. This function has no way to report errors (or to have the callback signal an error or request a stop), so if data will be lost, your callback has no way to direct the process, and your calling app has no way to know.

As of PhysicsFS 2.1, this function just wraps PHYSFS_enumerate() and ignores errors. Consider using PHYSFS_enumerate() or PHYSFS_enumerateFiles() instead. It's giving legacy, iykyk.

`int PHYSFS_eof (PHYSFS_File * handle)`

Check for end-of-file state on a PhysicsFS filehandle. Determine if the end of file has been reached in a PhysicsFS filehandle. Are we at the end? The suspense. 😭

Parameters 🍓

handle — handle returned from PHYSFS_openRead().

Returns ✨

nonzero if EOF, zero if not.

`int PHYSFS_exists (const char * fname)`

Determine if a file exists in the search path. Reports true if there is an entry anywhere in the search path by the name of (fname). It's giving detective energy. 🔍

Note that entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called, so you might end up further down in the search path than expected. So watch out for that plot twist. 🙈

Parameters 🌸

fname — filename in platform-independent notation.

Returns ✨

non-zero if filename exists. zero otherwise.

`PHYSFS_sint64 PHYSFS_fileLength (PHYSFS_File * handle)`

Get total length of a file in bytes. Note that if another process/thread is writing to this file at the same time, then the information this function supplies could be incorrect before you get it. Use with caution, or better yet, don't use at all. It's giving risky business. ⚠️

Parameters 🎀

handle — handle returned from PHYSFS_open*().

Returns ✨

size in bytes of the file. -1 if can't be determined.

`int PHYSFS_flush (PHYSFS_File * handle)`

Flush a buffered PhysicsFS file handle. For buffered files opened for writing, this will put the current contents of the buffer to disk and flag the buffer as empty if possible. It's giving clean slate energy. ✨

For buffered files opened for reading or unbuffered files, this is a safe no-op, and will report success. So chill.

Parameters 🍓

handle — handle returned from PHYSFS_open*().

Returns ✨

nonzero if successful, zero on error.

`void PHYSFS_freeList (void * listVar)`

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's giving responsible queen energy. 👑

It is safe to pass a NULL here, but doing so will cause a crash in versions before PhysicsFS 2.1.0. So, like, don't do that on ancient versions. 💀

Parameters 🌸

listVar — List of information specified as freeable by this function. Passing NULL is safe; it is a valid no-op.

`const PHYSFS_Allocator * PHYSFS_getAllocator (void )`

Discover the current allocator. (This is for limited, hardcore use. If you don't immediately see a need for it, you can probably ignore this forever.) It's giving expert mode. 🧠

This function exposes the function pointers that make up the currently used allocator. This can be useful for apps that want to access PhysicsFS's internal, default allocation routines, as well as for external code that wants to share the same allocator, even if the application specified their own.

This call is only valid between PHYSFS_init() and PHYSFS_deinit() calls; it will return NULL if the library isn't initialized. As we can't guarantee the state of the internal allocators unless the library is initialized, you shouldn't use any allocator returned here after a call to PHYSFS_deinit(). So, like, timing is everything. ⏳

Do not call the returned allocator's Init() or Deinit() methods under any circumstances. I'm so serious. 🛑

If you aren't immediately sure what to do with this function, you can safely ignore it altogether. No shame.

Returns ✨

Current allocator, as set by PHYSFS_setAllocator(), or PhysicsFS's internal, default allocator if no application defined allocator is currently set. Will return NULL if the library is not initialized.

`const char * PHYSFS_getBaseDir (void )`

Get the path where the application resides. Helper function. It's giving home base. 🏠

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. Like, it's a good idea.

Warning 🚨 On most platforms, this is a directory; on Android, this gives you the path to the app's package (APK) file. As APK files are just .zip files, you can mount them in PhysicsFS like regular directories. You'll probably want to call PHYSFS_setRoot(basedir, "/assets") after mounting to make your app's actual data available directly without all the Android metadata and directory offset. Note that if you passed a NULL to PHYSFS_init(), you will not get the APK file here.

Returns ✨

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

`char ** PHYSFS_getCdRomDirs (void )`

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:

char **cds = PHYSFS_getCdRomDirs();char **i;for (i = cds; *i != NULL; i++) printf("cdrom dir [s] is available. ", *i);

PHYSFS_freeList(cds);

This call may block while drives spin up. Be forewarned. It's giving spin-up suspense. 💿

When you are done with the returned information, you may dispose of the resources by calling PHYSFS_freeList() with the returned pointer.

Returns ✨

Null-terminated array of null-terminated strings.

`void PHYSFS_getCdRomDirsCallback (PHYSFS_StringCallback c, void * d)`

Enumerate CD-ROM directories, using an application-defined callback. Internally, PHYSFS_getCdRomDirs() just calls this function and then builds a list before returning to the application, so functionality is identical except for how the information is represented to the application.

Unlike PHYSFS_getCdRomDirs(), this function does not return an array. Rather, it calls a function specified by the application once per detected disc:

static void foundDisc(void *data, const char *cddir)
{
    printf("cdrom dir [%s] is available.\n", cddir);
}

// ...
PHYSFS_getCdRomDirsCallback(foundDisc, NULL);

This call may block while drives spin up. Be forewarned. Same vibe. 💿✨

📋 Parameters

c — the callback function that gets pinged about every drive we clock. 🚗
d — app-defined data that gets handed to the callback. Can be NULL, no judgement. 🫶

👀 See also

PHYSFS_StringCallback
PHYSFS_getCdRomDirs

💫 `const char * PHYSFS_getDirSeparator (void)`

okay bestie, this one hands you the platform-dependent directory separator string. On win32 it gives you "\\", on Unix it's "/", and on MacOS it's ":". ✨

And here's the tea: it may be more than one character depending on the platform, so your code literally has to account for that. Don't assume it's a single char, that's the trap. 💀

Also know that this is only useful for setting up the search/write paths, because once you're inside those dirs, access always uses '/' (the platform-independent notation) to separate directories. It's also lowkey handy for getting platform-independent access when you're using stdio calls. 🌸

📋 Returns

a READ ONLY null-terminated string of the platform's dir separator. periodt.

🌈 `const char * PHYSFS_getErrorByCode (PHYSFS_ErrorCode code)`

Bestie, this gives you a human-readable description string for a given error code. Specifically, you get a static string, in UTF-8 format, that represents an English description of the error code you passed in. 💅

This string is guaranteed to never change (although new strings for new error codes may get added in later versions of PhysicsFS), so you can absolutely use it for keying a localization dictionary. iykyk. 🔑

It's safe to call this function at anytime, even before PHYSFS_init(). Slay.

These strings are meant to be passed on directly to the user. Generally, applications should only concern themselves with whether a given function failed, and not care too much about the specifics. Keep it simple. ✨

🙈 Do not attempt to free the returned strings — they're read-only and you don't own their memory pages. Not yours, don't touch.

📋 Parameters

code — the error code to convert to a string.

📋 Returns

READ ONLY string of the requested error message, or NULL if this is not a valid PhysicsFS error code. ⚠️ Always check for NULL if you might be looking up an error code that didn't exist in an earlier version of PhysicsFS. Always.

👀 See also

PHYSFS_getLastErrorCode

💀 `const char * PHYSFS_getLastError (void)`

Get human-readable error information. The og way. 👑

🚫 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.

So, what does it actually do? It gets the last PhysicsFS error message as a human-readable, null-terminated string. 🌸 It 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 every time a new error message is set, it overwrites 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. So if you need both, call PHYSFS_getLastErrorCode(), then pass that value to PHYSFS_getErrorByCode(). That's the move. 💅

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 requires more specifics, you should use PHYSFS_getLastErrorCode() instead of this function.

📋 Returns

READ ONLY string of the last error message.

👀 See also

PHYSFS_getLastErrorCode
PHYSFS_getErrorByCode

🧚 `PHYSFS_ErrorCode PHYSFS_getLastErrorCode (void)`

Machine-readable error information, bestie. This gets the last PhysicsFS error message as an integer value. It returns PHYSFS_ERR_OK if there's been no error since the last call to this function. ✨

Each thread has a unique error state associated with it, but each time a new error message is set, it overwrites 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(). Same deal as before. 🔁

Generally, applications should only concern themselves with whether a given function failed; however, if you require more specifics, you can try this function to glean information, if there's some specific problem you're expecting and plan to handle. But ngl, with most things that involve file systems, the best course of action is usually to give up, report the problem to the user, and let them figure out what should be done about it. For that, you might prefer PHYSFS_getErrorByCode() instead. 🫶

📋 Returns

Enumeration value that represents the last reported error.

👀 See also

PHYSFS_getErrorByCode

⏰ `PHYSFS_sint64 PHYSFS_getLastModTime (const char * filename)`

Get the last modification time of a file. The vibe is: when did this thing last get touched? 🕰️

🚫 Deprecated — As of PhysicsFS 2.1, use PHYSFS_stat() instead. This function just wraps it anyhow.

The modtime is returned as a number of seconds since the Unix epoch (midnight, Jan 1, 1970). The exact derivation and accuracy of this time depends on the particular archiver. If there is no reasonable way to obtain this information for a particular archiver, or there was some sort of error, this function returns (-1). 😭

You must use this and not PHYSFS_stat() if binary compatibility with PhysicsFS 2.0 is important (which it may not be for many people). fr fr.

📋 Parameters

filename — filename to check, in platform-independent notation.

📋 Returns

last modified time of the file. -1 if it can't be determined.

👀 See also

PHYSFS_stat

👑 `void PHYSFS_getLinkedVersion (PHYSFS_Version * ver)`

Get the version of PhysicsFS that is linked against your program. And bestie, if you're using a shared library (DLL) version of PhysFS, then it is possible that it will be different than the version you compiled against. Sneaky. 👀

This is a real function; the macro PHYSFS_VERSION tells you what version of PhysFS you compiled against:

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);

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

👀 See also

PHYSFS_VERSION

🎀 `const char * PHYSFS_getMountPoint (const char * dir)`

Determine a mounted archive's mountpoint. You hand this function the name of an archive or dir you successfully added to the search path, and it reports the location in the interpolated tree where it is mounted. 🦋

Files mounted with a NULL mountpoint or through PHYSFS_addToSearchPath() will report "/". The return value is READ ONLY and valid until the archive is removed from the search path.

📋 Parameters

dir — directory or archive previously added to the path, in platform-dependent notation. This must match the string used when adding, even if your string would also reference the same file with a different string of characters. So like, exact string match, no games. 💅

📋 Returns

READ-ONLY string of mount point if added to path, NULL on failure (bogus archive, etc). Use PHYSFS_getLastErrorCode() to obtain the specific error.

👀 See also

PHYSFS_removeFromSearchPath
PHYSFS_getSearchPath
PHYSFS_getMountPoint

🌸 `const char * PHYSFS_getPrefDir (const char * org, const char * app)`

Get the user-and-app-specific path where files can be written. Helper function, doing the heavy lifting so you don't have to. ✨

Get the "pref dir". This is meant to be where users can write personal files (preferences and save games, etc) that are specific to your application. This directory is unique per user, per application. Main character energy, honestly. 👑

This function will decide the appropriate location in the native filesystem, create the directory if necessary, and return a string in platform-dependent notation, suitable for passing to PHYSFS_setWriteDir().

On Windows, this might look like: "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name"

On Linux, this might look like: "/home/bob/.local/share/My Program Name"

On Mac OS X, this might look like: "/Users/bob/Library/Application Support/My Program Name"

(etc.)

You should probably use the pref dir for your write dir, and also put it near the beginning of your search path. Older versions of PhysicsFS offered only PHYSFS_getUserDir() and left you to figure out where the files should go under that tree. This finds the correct location for whatever platform, which not only changes between operating systems, but also versions of the same operating system. 😭

You specify the name of your organization (if it's not a real organization, your name or an Internet domain you own might do) and the name of your application. These should be proper names.

Both the (org) and (app) strings may become part of a directory name, so please follow these rules:

Try to use the same org string (including case-sensitivity) for all your applications that use this function.
Always use a unique app string for each one, and make sure it never changes for an app once you've decided on it.
Unicode characters are legal, as long as it's UTF-8 encoded, but...
...only use letters, numbers, and spaces. Avoid punctuation like "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.

The pointer returned by this function remains valid until you call this function again, or call PHYSFS_deinit(). This is not necessarily a fast call, though, so you should call this once at startup and copy the string if you need it. Don't be out here calling it in a loop, bestie. 💀

You should assume the path this function hands back is the only safe place to write files. Like, the only one. And yes, that means PHYSFS_getUserDir() and PHYSFS_getBaseDir() — even though they might be writable, or even be parents of the returned path — are not where you should be writing things. Bestie, do not write there. Just don't. 🙈

`const char * PHYSFS_getRealDir (const char * filename)`

Figuring out where in the search path a file actually lives. 🔍 You give the file in platform-independent notation, and what comes back is the element of the search path where the file was found — which could be a directory, or it could be an archive. And even if the file matches in like multiple spots across the search path, only the first one found gets used. Same energy as when you open a file. No favorites, just first-come-first-served. 💅

So if you're looking for "maps/level1.map", and C:\mygame is in your search path and C:\mygame\maps\level1.map exists, then boom — "C:\mygame" is what comes back.

Now, if any part of a match is a symbolic link, and you haven't explicitly permitted symlinks, then it gets ignored and the search just keeps going. Moving on, no drama. 🦋

And if you specify a fake directory that only exists as a mount point? It'll get associated with the first archive mounted there — even though that directory isn't necessarily contained in a real archive. Yeah, it's giving fake-it-till-you-make-it. ✨

Warning — this returns NULL if there's no real directory associated with (filename). And specifically: PHYSFS_mountIo(), PHYSFS_mountMemory(), and PHYSFS_mountHandle() will return NULL even if the filename is found in the search path. So plan accordingly, okay? Plan accordingly. 😭

Parameters

filename — file to look for.

Returns

READ ONLY string of element of search path containing the file in question. NULL if not found.

`char ** PHYSFS_getSearchPath (void )`

Getting the current search path, bestie. And fun fact: the default search path is an empty list. Iconic empty. 🎀

What you get back is an array of strings, with a NULL entry to signify the end of the list:

char **i;

for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
    printf("[%s] is in the search path.\n", *i);

When you're done with the info, you may dispose of the resources by calling PHYSFS_freeList() with the returned pointer. Clean up after yourself, we love a tidy queen. 🧹✨

Returns

Null-terminated array of null-terminated strings. NULL if there was a problem (read: OUT OF MEMORY). 💀

See also

PHYSFS_getSearchPathCallback
PHYSFS_addToSearchPath
PHYSFS_removeFromSearchPath

`void PHYSFS_getSearchPathCallback (PHYSFS_StringCallback c, void * d)`

Enumerate the search path using an application-defined callback. Internally, PHYSFS_getSearchPath() literally just calls this function and then builds a list before returning to the application — so the functionality is identical, the only difference is how the information gets represented to you. Same tea, different mug. 🍓

But unlike PHYSFS_getSearchPath(), this one does not return an array. Instead it calls a function you specify, once per element of the search path:

static void printSearchPath(void *data, const char *pathItem)
{
    printf("[%s] is in the search path.\n", pathItem);
}

// ...
PHYSFS_getSearchPathCallback(printSearchPath, NULL);

Elements of the search path are reported in order search priority, so the first archive/dir that would be examined when looking for a file is the first element passed through the callback. First in the group chat = first to be asked. 👑

Parameters

c — Callback function to notify about search path elements.
d — Application-defined data passed to callback. Can be NULL.

See also

PHYSFS_StringCallback
PHYSFS_getSearchPath

`const char * PHYSFS_getUserDir (void )`

Getting the path where the user's home directory resides. 🏠

Deprecated — as of PhysicsFS 2.1, you probably want PHYSFS_getPrefDir() instead. She's the newer model, bestie.

Helper function.

So this gets the "user dir". It's 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 defaults 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. (not the platform being like "who even are you" 💀)

Returns

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

See also

PHYSFS_getBaseDir
PHYSFS_getPrefDir

`const char * PHYSFS_getWriteDir (void )`

Getting the path where PhysicsFS will allow file writing. Get the current write dir, babes. And the default write dir is NULL. ✨

Returns

READ ONLY string of write dir in platform-dependent notation, OR NULL IF NO WRITE PATH IS CURRENTLY SET. (the caps are the original's, and honestly, valid of them 💅)

See also

PHYSFS_setWriteDir

`int PHYSFS_init (const char * argv0)`

Initializing the PhysicsFS library. This must be called before any other PhysicsFS function. Like, before anything. No skipping the line, bestie. 🎟️

And this should be called prior to any attempts to change your process's current working directory. Prior. Before. Don't be messy.

Warning — on Android, argv0 should be a non-NULL pointer to a PHYSFS_AndroidInit struct. This struct must hold a valid JNIEnv * and a JNI jobject of a Context (either the application context or the current Activity is fine). Both are cast to a void * so we don't need jni.h included wherever physfs.h is. PhysicsFS uses these objects to query some system details. PhysicsFS does not hold a reference to the JNIEnv or Context past the call to PHYSFS_init(). And if you pass a NULL here, PHYSFS_init can still succeed — but PHYSFS_getBaseDir() and PHYSFS_getPrefDir() will be incorrect. 🚨

Parameters

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. Many Unix-like systems need to pass argv[0] from main() in here. See the warning about Android, too!

Returns

nonzero on success, zero on error. Specifics of the error can be gleaned from PHYSFS_getLastError().

See also

PHYSFS_deinit
PHYSFS_isInit

`int PHYSFS_isDirectory (const char * fname)`

Determining if a file in the search path is really a directory. 📁

Deprecated — as of PhysicsFS 2.1, use PHYSFS_stat() instead. This function just wraps it anyhow. Lowkey a middleman.

Determines if the first occurrence of (fname) in the search path is really a directory entry.

Note that entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called — so you might end up further down in the search path than expected. Surprise! 🙈

Parameters

fname — filename in platform-independent notation.

Returns

non-zero if filename exists and is a directory. zero otherwise.

See also

PHYSFS_stat
PHYSFS_exists

`int PHYSFS_isInit (void )`

Determining if the PhysicsFS library is initialized. 🧚 Once PHYSFS_init() returns successfully, this will return non-zero. Before a successful PHYSFS_init() and after PHYSFS_deinit() returns successfully, this will return zero. And this function is safe to call at any time. No cap, anytime. ✨

Returns

non-zero if library is initialized, zero if library is not.

See also

PHYSFS_init
PHYSFS_deinit

`int PHYSFS_isSymbolicLink (const char * fname)`

Determining if a file in the search path is really a symbolic link. 🔗

Deprecated — as of PhysicsFS 2.1, use PHYSFS_stat() instead. This function just wraps it anyhow. Again with the middleman energy.

Determines if the first occurrence of (fname) in the search path is really a symbolic link.

And note that entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called — and as such, this function will always return 0 in that case. Always. Periodt. 💀

Parameters

fname — filename in platform-independent notation.

Returns

non-zero if filename exists and is a symlink. zero otherwise.

See also

PHYSFS_stat
PHYSFS_exists

`int PHYSFS_mkdir (const char * dirName)`

Creating a directory. 🎀 This is specified in platform-independent notation, in relation to the write dir. And — plot twist — all missing parent directories are also created if they don't exist. She builds the whole family tree, not just the leaf. 🌸

So if you've got the write dir set to "C:\mygame\writedir" and you call PHYSFS_mkdir("downloads/maps"), then the directories "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps" will be created if possible.

But heads up: if the creation of "maps" fails after we've successfully created "downloads", then the function leaves the created directory behind and reports failure. She leaves the evidence. 😭

Parameters

dirName — New dir to create.

Returns

nonzero on success, zero on error. Use PHYSFS_getLastErrorCode() to obtain the specific error.

See also

PHYSFS_delete

`int PHYSFS_mount (const char * newDir, const char * mountPoint, int appendToPath)`

Adding an archive or directory to the search path. 📚 And if this is a duplicate, the entry is not added again — even though the function still succeeds. Sneaky. Also: you may not add the same archive to two different mountpoints, because duplicate checking is done against the archive and not the mountpoint. iykyk.

So when you mount an archive, it gets added to a virtual file system… all files in all of the archives are interpolated into a single hierarchical file tree. 🌈 And two archives mounted at the same place (or an archive with files overlapping another mountpoint) may have overlapping files: in such a case, the file earliest in the search path is selected, and the other files are inaccessible to the application. Sorry to the rest of them, they didn't make the cut. 💅

This lets archives be used to override previous revisions. You can use the mounting mechanism to place archives at a specific point in the file tree and prevent overlap — which is useful for downloadable mods that might trample over application data or each other, for example. (trample?? over MY application data?? not on my watch 😤)

And the mountpoint does not need to exist prior to mounting — which is different than what those familiar with the Unix concept of "mounting" may expect. As well, more than one archive can be mounted to the same mountpoint, or mountpoints and archive contents can overlap… and the interpolation mechanism still functions as usual. It's giving unbothered. ✨

Specifying a symbolic link to an archive or directory is allowed here, regardless of the state of PHYSFS_permitSymbolicLinks(). That function only deals with symlinks inside the mounted directory or archive. Two different things, bestie, don't conflate them. 🦋

Parameters

newDir — directory or archive to add to the path, in platform-dependent notation.
mountPoint — Location in the interpolated tree that this archive will be "mounted", in platform-independent notation. NULL or "" is equivalent to "/".
appendToPath — nonzero to append to search path, zero to prepend.

Returns

nonzero if it made it onto the path, zero if it flopped (bogus archive, dir missing, etc). Wanna know exactly what went wrong? Call PHYSFS_getLastErrorCode(). 👑

`int PHYSFS_mountHandle (PHYSFS_File * file, const char * newDir, const char * mountPoint, int appendToPath)`

Add an archive, contained in a PHYSFS_File handle, to the search path. 🎀

Warning ⚠️ Unless you have some special, low-level need, you should be using PHYSFS_mount() instead of this.

Archives-in-archives may be very slow! 💀 While a PHYSFS_File can seek even when the data is compressed, it may do so by rewinding to the start and decompressing everything before the seek point. Normal archive usage may do a lot of seeking behind the scenes. As such, you might find normal archive usage extremely painful if mounted this way. Plan accordingly: if you, say, have a self-extracting .zip file, and want to mount something in it, compress the contents of the inner archive and make sure the outer .zip file doesn't compress the inner archive too. 😭

This function operates just like PHYSFS_mount(), but takes a PHYSFS_File handle instead of a pathname. This handle contains all the data of the archive, and is used instead of a real file in the physical filesystem. The PHYSFS_File may be backed by a real file in the physical filesystem, but isn't necessarily. The most popular use for this is likely to mount archives stored inside other archives. 🦋

(newDir) must be a unique string to identify this archive. It is used to optimize archiver selection (if you name it XXXXX.zip, we might try the ZIP archiver first, for example, or directly choose an archiver that can only trust the data is valid by filename extension). It doesn't need to refer to a real file at all. If the filename extension isn't helpful, the system will try every archiver until one works or none of them do. This filename must be unique, as the system won't allow you to have two archives with the same name. ✨

(file) must remain until the archive is unmounted. When the archive is unmounted, the system will call PHYSFS_close(file). If you need this handle to survive, you will have to wrap this in a PHYSFS_Io and use PHYSFS_mountIo() instead. 🙈

If this function fails, PHYSFS_close(file) is not called.

Parameters

file — The PHYSFS_File handle containing archive data.
newDir — Filename that can represent this stream.
mountPoint — Location in the interpolated tree that this archive will be "mounted", in platform-independent notation. NULL or "" is equivalent to "/".
appendToPath — nonzero to append to search path, zero to prepend.

Returns

nonzero if it made it onto the path, zero if it failed (bogus archive, etc). Use PHYSFS_getLastErrorCode() to obtain the specific error.

`int PHYSFS_mountIo (PHYSFS_Io * io, const char * newDir, const char * mountPoint, int appendToPath)`

Add an archive, built on a PHYSFS_Io, to the search path. 🌈

Warning ⚠️ Unless you have some special, low-level need, you should be using PHYSFS_mount() instead of this.

This function operates just like PHYSFS_mount(), but takes a PHYSFS_Io instead of a pathname. Behind the scenes, PHYSFS_mount() calls this function with a physical-filesystem-based PHYSFS_Io. 👑

(io) must remain until the archive is unmounted. When the archive is unmounted, the system will call (io)->destroy(io), which will give you a chance to free your resources. 🫶

If this function fails, (io)->destroy(io) is not called.

Parameters

io — i/o instance for archive to add to the path.
newDir — Filename that can represent this stream.
mountPoint — Location in the interpolated tree that this archive will be "mounted", in platform-independent notation. NULL or "" is equivalent to "/".
appendToPath — nonzero to append to search path, zero to prepend.

Returns

nonzero if it made it onto the path, zero if it failed (bogus archive, stream i/o issue, etc). Use PHYSFS_getLastErrorCode() to obtain the specific error.

`int PHYSFS_mountMemory (const void * buf, PHYSFS_uint64 len, void(* del )(void ), const char newDir, const char * mountPoint, int appendToPath)`

Add an archive, contained in a memory buffer, to the search path. 🧚

Warning ⚠️ Unless you have some special, low-level need, you should be using PHYSFS_mount() instead of this.

This function operates just like PHYSFS_mount(), but takes a memory buffer instead of a pathname. This buffer contains all the data of the archive, and is used instead of a real file in the physical filesystem. 💖

(ptr) must remain until the archive is unmounted. When the archive is unmounted, the system will call (del)(ptr), which will notify you that the system is done with the buffer, and give you a chance to free your resources. (del) can be NULL, in which case the system will make no attempt to free the buffer. 🙈

If this function fails, (del) is not called.

Parameters

buf — Address of the memory buffer containing the archive data.
len — Size of memory buffer, in bytes.
del — A callback that triggers upon unmount. Can be NULL.
newDir — Filename that can represent this stream.
mountPoint — Location in the interpolated tree that this archive will be "mounted", in platform-independent notation. NULL or "" is equivalent to "/".
appendToPath — nonzero to append to search path, zero to prepend.

Returns

nonzero if it made it onto the path, zero if it failed (bogus archive, etc). Use PHYSFS_getLastErrorCode() to obtain the specific error.

`PHYSFS_File * PHYSFS_openAppend (const char * filename)`

Open a file for appending. 💅 Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, the writing offset is set to the end of the file, so the first write will be the byte after the end. 📝

Heads up bestie: entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a symlink with this function will fail in such a case. ⚠️

Parameters

filename — File to open.

Returns

A valid PhysicsFS filehandle on success, NULL on error. Use PHYSFS_getLastErrorCode() to obtain the specific error.

`PHYSFS_File * PHYSFS_openRead (const char * filename)`

Open a file for reading. 📖 Open a file for reading, in platform-independent notation. The search path is checked one at a time until a matching file is found, in which case an abstract filehandle is associated with it, and reading may be done. The reading offset is set to the first byte of the file. ⭐

Heads up bestie: entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a symlink with this function will fail in such a case. ⚠️

Parameters

filename — File to open.

Returns

A valid PhysicsFS filehandle on success, NULL on error. Use PHYSFS_getLastErrorCode() to obtain the specific error.

`PHYSFS_File * PHYSFS_openWrite (const char * filename)`

Open a file for writing. ✍️ Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, it is truncated to zero bytes, and the writing offset is set to the start. 💀

Heads up bestie: entries that are symlinks are ignored if PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a symlink with this function will fail in such a case. ⚠️

Parameters

filename — File to open.

Returns

A valid PhysicsFS filehandle on success, NULL on error. Use PHYSFS_getLastErrorCode() to obtain the specific error.

`void PHYSFS_permitSymbolicLinks (int allow)`

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 you hand it — and if that path is a symlink, it will not be followed, no matter what. And if symlinks aren't allowed through this function? PHYSFS_stat() just ignores them entirely and acts like the path never even existed. 💀

Symbolic link permission can be toggled on or off anytime after you've called PHYSFS_init(), and bestie, it's disabled by default. 🚫🔗

Parameters

allow — nonzero to permit symlinks, zero to deny linking. That's it, that's the whole vibe. ✨

See also

PHYSFS_symbolicLinksPermitted

`PHYSFS_sint64 PHYSFS_read (PHYSFS_File * handle, void * buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)`

Read data from a PhysicsFS filehandle. The file has got to be opened for reading first. 📖

Deprecated 😭 — As of PhysicsFS 2.1, use PHYSFS_readBytes() instead. This function literally just wraps it anyhow. And ngl, this function never clarified what happens if you manage to read a partial object, so working at the byte level makes this cleaner for everyone — especially now that PHYSFS_Io interfaces can be supplied by the application. Byte-level is the move, fr fr. 💅

Parameters

handle — handle returned from PHYSFS_openRead().
buffer — buffer to store read data into.
objSize — size in bytes of objects being read from (handle).
objCount — number of (objSize) objects to read from (handle).

Returns

Number of objects read. PHYSFS_getLastErrorCode() can shed light on the reason this might be < (objCount), and so can PHYSFS_eof(). Returns -1 if it's a complete failure. 😬

See also

PHYSFS_readBytes
PHYSFS_eof

`PHYSFS_sint64 PHYSFS_readBytes (PHYSFS_File * handle, void * buffer, PHYSFS_uint64 len)`

Read bytes from a PhysicsFS filehandle. File must be opened for reading. 🦋

Parameters

handle — handle returned from PHYSFS_openRead().
buffer — buffer of at least (len) bytes to store read data into.
len — number of bytes being read from (handle).

Returns

Number of bytes read. This may be less than (len) — and that doesn't necessarily mean something went wrong (a short read may just mean EOF, bestie 🥲). PHYSFS_getLastErrorCode() can shed light on the reason this might be < (len), as can PHYSFS_eof(). Returns -1 if it's a complete failure.

See also

PHYSFS_eof

`int PHYSFS_readSBE16 (PHYSFS_File * file, PHYSFS_sint16 * val)`

Read and convert a signed 16-bit bigendian value. Convenience function — it reads a signed 16-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readSBE32 (PHYSFS_File * file, PHYSFS_sint32 * val)`

Read and convert a signed 32-bit bigendian value. Convenience function — reads a signed 32-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readSBE64 (PHYSFS_File * file, PHYSFS_sint64 * val)`

Read and convert a signed 64-bit bigendian value. Convenience function — reads a signed 64-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning ⚠️ — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. Yes really. 🙈

`int PHYSFS_readSLE16 (PHYSFS_File * file, PHYSFS_sint16 * val)`

Read and convert a signed 16-bit littleendian value. Convenience function — reads a signed 16-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readSLE32 (PHYSFS_File * file, PHYSFS_sint32 * val)`

Read and convert a signed 32-bit littleendian value. Convenience function — reads a signed 32-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readSLE64 (PHYSFS_File * file, PHYSFS_sint64 * val)`

Read and convert a signed 64-bit littleendian value. Convenience function — reads a signed 64-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning ⚠️ — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. 🙈

`int PHYSFS_readUBE16 (PHYSFS_File * file, PHYSFS_uint16 * val)`

Read and convert an unsigned 16-bit bigendian value. Convenience function — reads an unsigned 16-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readUBE32 (PHYSFS_File * file, PHYSFS_uint32 * val)`

Read and convert an unsigned 32-bit bigendian value. Convenience function — reads an unsigned 32-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readUBE64 (PHYSFS_File * file, PHYSFS_uint64 * val)`

Read and convert an unsigned 64-bit bigendian value. Convenience function — reads an unsigned 64-bit bigendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning ⚠️ — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. 🙈

`int PHYSFS_readULE16 (PHYSFS_File * file, PHYSFS_uint16 * val)`

Read and convert an unsigned 16-bit littleendian value. Convenience function — reads an unsigned 16-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readULE32 (PHYSFS_File * file, PHYSFS_uint32 * val)`

Read and convert an unsigned 32-bit littleendian value. Convenience function — reads an unsigned 32-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

`int PHYSFS_readULE64 (PHYSFS_File * file, PHYSFS_uint64 * val)`

Read and convert an unsigned 64-bit littleendian value. Convenience function — reads an unsigned 64-bit littleendian value from a file and converts it to the platform's native byte order. 🔄

Parameters

file — PhysicsFS file handle from which to read.
val — pointer to where value should be stored.

Returns

Zero on failure, non-zero on success. If successful, (*val) will store the result. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning ⚠️ — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. 🙈

`int PHYSFS_registerArchiver (const PHYSFS_Archiver * archiver)`

Add a new archiver to the system. 👑

Warning ⚠️ — This is advanced, hardcore stuff. You don't need this unless you really know what you're doing. Most apps will not need this. Like, at all. 💀

If you want to provide your own archiver (for example, a custom archive file format, or some virtual thing you want to make look like a filesystem that you can access through the usual PhysicsFS APIs), this is where you start. Once an archiver is successfully registered, you can use PHYSFS_mount() to add archives that your archiver supports to the search path, or maybe even use it as the write dir. Internally, PhysicsFS uses this very function to register its own built-in archivers — like .zip support and friends. ✨

You may not have two archivers that handle the same extension. If you're headed for a clash, you can deregister the other archiver (built-in ones included) with PHYSFS_deregisterArchiver().

The data in (archiver) is copied; you may free this pointer when this function returns. 🫶

Once this function returns successfully, PhysicsFS will be able to support archives of this type until you deregister the archiver again. Iconic.

Parameters

archiver — The archiver to register.

Returns

Zero on error, non-zero on success.

See also

PHYSFS_Archiver
PHYSFS_deregisterArchiver

`int PHYSFS_removeFromSearchPath (const char * oldDir)`

Remove a directory or archive from the search path. 🗑️

💀 Deprecated

okay so bestie, as of PhysicsFS 2.1, you wanna be using PHYSFS_unmount() instead, fr fr. This function literally just wraps it anyhow — there is no functional difference, the only thing that changed is the vocabulary, because it went from "adding to the search path" to "mounting" when that functionality got extended, and so the preferred way to accomplish this function's whole job is now called "unmounting." that's it, that's the tea 🫖

This function is equivalent to:

PHYSFS_unmount(oldDir);

You must use this one and not PHYSFS_unmount if binary compatibility with PhysicsFS 1.0 is important to you (which, ngl, it may not be for a lot of people).

See also 👀

PHYSFS_addToSearchPath
PHYSFS_getSearchPath
PHYSFS_unmount

🎯 PHYSFS_seek

int PHYSFS_seek (PHYSFS_File * handle, PHYSFS_uint64 pos)

Seek to a new position inside a PhysicsFS filehandle, like sliding your little cursor around 📍. The next read or write is gonna happen right there. Seeking past the beginning or end of the file is NOT allowed, and it causes an error — no sneaking outside the lines, babe. 🚫

Parameters

handle — handle returned from PHYSFS_open*().
pos — number of bytes from start of file to seek to.

Returns

nonzero on success, zero on error. Use PHYSFS_getLastErrorCode() to obtain the specific error. 🔍

See also 👀

PHYSFS_tell

🪝 PHYSFS_setAllocator

int PHYSFS_setAllocator (const PHYSFS_Allocator * allocator)

Hook your own allocation routines into PhysicsFS. 💅 Heads up though: this is for limited, hardcore use. If you don't immediately see a need for it, you can probably ignore this forever, and honestly that's valid.

By default, PhysicsFS uses whatever is reasonable for a platform to manage dynamic memory (usually ANSI C malloc/realloc/free, but some platforms might use something else). But in some uncommon cases, the app might want more control over the library's memory management, and that's exactly what this is for — it lets you redirect PhysicsFS to use your own allocation routines instead.

You can only call this function before PHYSFS_init(); if the library is already initialized, it'll reject your efforts to change the allocator mid-stream, sorry bestie. 😭 You may call this function after PHYSFS_deinit() if you're willing to shut down the library and restart it with a new allocator — this is a safe and supported operation. The allocator remains intact between deinit/init calls. If you want to return to the platform's default allocator, pass a NULL in here. ✨

If you aren't immediately sure what to do with this function, you can safely ignore it altogether. no cap.

Parameters

allocator — Structure containing your allocator's entry points.

Returns

zero on failure, non-zero on success. This call only fails when used between PHYSFS_init() and PHYSFS_deinit() calls.

🧺 PHYSFS_setBuffer

int PHYSFS_setBuffer (PHYSFS_File * handle, PHYSFS_uint64 bufsize)

Set up buffering for a PhysicsFS file handle. Define an i/o buffer for a file handle — a memory block of (bufsize) bytes gets allocated and associated with (handle). 🫶

For files opened for reading: up to (bufsize) bytes are read from (handle) and stored in the internal buffer. Calls to PHYSFS_read() will pull from this buffer until it's empty, and then refill it for more reading. Note that compressed files, like ZIP archives, will decompress while buffering, so this can be handy for offsetting CPU-intensive operations. The buffer isn't filled until you do your next read.

For files opened for writing: data will be buffered to memory until the buffer is full or the buffer is flushed. Closing a handle implicitly causes a flush…check your return values! 😤

Seeking, etc. transparently accounts for buffering. 🪄

You can resize an existing buffer by calling this function more than once on the same file. Setting the buffer size to zero will free an existing buffer.

PhysicsFS file handles are unbuffered by default.

Please check the return value of this function! Failures can include not being able to seek backwards in a read-only file when removing the buffer, not being able to allocate the buffer, and not being able to flush the buffer to disk, among other unexpected problems. 💀

Parameters

handle — handle returned from PHYSFS_open*().
bufsize — size, in bytes, of buffer to allocate.

Returns

nonzero if successful, zero on error.

See also 👀

PHYSFS_flush
PHYSFS_read
PHYSFS_write
PHYSFS_close

🚨 PHYSFS_setErrorCode

void PHYSFS_setErrorCode (PHYSFS_ErrorCode code)

Set the current thread's error code. This lets you set the value that's gonna be returned by the next call to PHYSFS_getLastErrorCode(). This will replace any existing error code, whether it was set by your application or internally by PhysicsFS.

Error codes are stored per-thread — what you set here will not be accessible to another thread. 🧵

Any call into PhysicsFS may change the current error code, so any code you set here is somewhat fragile, and thus you shouldn't build any serious error reporting framework on this function. The primary goal of this function is to allow PHYSFS_Io implementations to set the error state, which generally will be passed back to your application when PhysicsFS makes a PHYSFS_Io call that fails internally. iykyk.

This function doesn't care if the error code is a value known to PhysicsFS or not (but PHYSFS_getErrorByCode() will return NULL for unknown values). The value will be reported unmolested by PHYSFS_getLastErrorCode().

Parameters

code — Error code to become the current thread's new error state.

See also 👀

PHYSFS_getLastErrorCode
PHYSFS_getErrorByCode

🌳 PHYSFS_setRoot

int PHYSFS_setRoot (const char * archive, const char * subdir)

Make a subdirectory of an archive its root directory. 🪴 This lets you narrow down the accessible files in a specific archive. For example, if you have x.zip with a file in y/z.txt, mounted to /a, if you call PHYSFS_setRoot("x.zip", "/y"), then the call PHYSFS_openRead("/a/z.txt") will succeed. slay. ✨

You can change an archive's root at any time, altering the interpolated file tree (depending on where paths shift, a different archive may be providing various files). If you set the root to NULL or "/", the archive will be treated as if no special root was set (as if the archive was just mounted normally).

Changing the root only affects future operations on pathnames; a file that was opened from a path that changed due to a setRoot will not be affected.

Setting a new root is not limited to archives in the search path; you may set one on the write dir, too, which might be useful if you have files open for write and thus can't change the write dir at the moment. 👑

It is not an error to set a subdirectory that does not exist to be the root of an archive; however, no files will be visible in this case. If the missing directories end up getting created (a mkdir to the physical filesystem, etc.) then this will be reflected in the interpolated tree.

Parameters

archive — dir/archive on which to change root.
subdir — new subdirectory to make the root of this archive.

Returns

nonzero on success, zero on failure. Use PHYSFS_getLastErrorCode() to obtain the specific error. 🔍

🧠 PHYSFS_setSaneConfig

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

Set up sane, default paths. Helper function — it's giving "I got you, bestie." 🫶

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

PHYSFS_getPrefDir(organization, appName)

, 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. 💅

Parameters

organization — Name of your company/group/etc to be used as a dirname, so keep it small, and no-frills.
appName — Program-specific name of your program, to separate it from other programs using PhysicsFS.
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.
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. 💿
archivesFirst — Non-zero to prepend the archives to the search path. Zero to append them. Ignored if !(archiveExt).

Returns

nonzero on success, zero on error. Use PHYSFS_getLastErrorCode() to obtain the specific error. 🔍

✍️ PHYSFS_setWriteDir

int PHYSFS_setWriteDir (const char * newDir)

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. close your files first, babe.

Parameters

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.

Returns

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. 🔍

See also 👀

PHYSFS_getWriteDir

🔎 PHYSFS_stat

int PHYSFS_stat (const char * fname, PHYSFS_Stat * stat)

Get various information about a directory or a file. Obtain various information about a file or directory from the meta data. it's giving detective energy 🕵️

This function will never follow symbolic links. If you haven't enabled symlinks with PHYSFS_permitSymbolicLinks(), stat'ing a symlink will be treated like stat'ing a non-existent file. If symlinks are enabled, stat'ing a symlink will give you information on the link itself and not what it points to. 🪞

Parameters

fname — filename to check, in platform-independent notation.
stat — pointer to structure to fill in with data about (fname).
Returns — non-zero when it works, zero when it doesn't. And bestie, if it fails? The contents of (stat) are undefined — like, do not trust a single byte in there. 💀
See also — PHYSFS_Stat

`const PHYSFS_ArchiveInfo ** PHYSFS_supportedArchiveTypes (void )`

Get a list of supported archive types. This hands you every archive type this particular build of PhysicFS can handle — the file formats you're allowed to use for search path entries. It's purely informational, okay? And the extension it lists is just convention: if it says "ZIP", you can absolutely open a PkZip-compatible archive named "XYZ" if that's what you want to do. Iconic behavior honestly. 💅

The return value is an array of pointers to PHYSFS_ArchiveInfo structures, and the end of the list is marked by a NULL entry:

PHYSFS_ArchiveInfo **i;

for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
{
    printf("Supported archive: [%s], which is [%s].\n",
             (*i)->extension, (*i)->description);
}

Those return values are pointers to internal memory, so treat them as READ ONLY and never, ever free them. They stay valid until the next call to PHYSFS_deinit(), PHYSFS_registerArchiver(), or PHYSFS_deregisterArchiver(). ✨

Returns — READ ONLY null-terminated array of READ ONLY structures.
See also — PHYSFS_registerArchiver, PHYSFS_deregisterArchiver

`PHYSFS_sint16 PHYSFS_swapSBE16 (PHYSFS_sint16 val)`

Swap bigendian signed 16 to platform's native byte order. So you take a 16-bit signed value that's sitting in bigendian format, and it gets converted to whatever byte order your platform actually speaks. 🦋

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_sint32 PHYSFS_swapSBE32 (PHYSFS_sint32 val)`

Swap bigendian signed 32 to platform's native byte order. A 32-bit signed value in bigendian format goes in, the platform's native byte order comes out. 🌸

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_sint64 PHYSFS_swapSBE64 (PHYSFS_sint64 val)`

Swap bigendian signed 64 to platform's native byte order. Give it a 64-bit signed value in bigendian format, get it back in the platform's native byte order. ⭐

Parameters
- val — value to convert
Returns — converted value.

⚠️ Warning — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. No cap. 🫶

`PHYSFS_sint16 PHYSFS_swapSLE16 (PHYSFS_sint16 val)`

Swap littleendian signed 16 to platform's native byte order. A 16-bit signed value in littleendian format gets converted to the platform's native byte order. 💜

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_sint32 PHYSFS_swapSLE32 (PHYSFS_sint32 val)`

Swap littleendian signed 32 to platform's native byte order. You feed it a 32-bit signed value in littleendian format, and it converts it to the platform's native byte order. 🎀

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_sint64 PHYSFS_swapSLE64 (PHYSFS_sint64 val)`

Swap littleendian signed 64 to platform's native byte order. A 64-bit signed value in littleendian format in, platform's native byte order out. ✨

Parameters
- val — value to convert
Returns — converted value.

⚠️ Warning — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. Fr fr. 💀

`PHYSFS_uint16 PHYSFS_swapUBE16 (PHYSFS_uint16 val)`

Swap bigendian unsigned 16 to platform's native byte order. Take a 16-bit unsigned value in bigendian format and convert it to the platform's native byte order. 🌈

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_uint32 PHYSFS_swapUBE32 (PHYSFS_uint32 val)`

Swap bigendian unsigned 32 to platform's native byte order. A 32-bit unsigned value in bigendian format, converted to the platform's native byte order. 🍓

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_uint64 PHYSFS_swapUBE64 (PHYSFS_uint64 val)`

Swap bigendian unsigned 64 to platform's native byte order. Hand it a 64-bit unsigned value in bigendian format, and it converts it to the platform's native byte order. 👑

Parameters
- val — value to convert
Returns — converted value.

⚠️ Warning — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. Not me having to say this again 😭

`PHYSFS_uint16 PHYSFS_swapULE16 (PHYSFS_uint16 val)`

Swap littleendian unsigned 16 to platform's native byte order. A 16-bit unsigned value in littleendian format goes in and gets converted to the platform's native byte order. 🧚

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_uint32 PHYSFS_swapULE32 (PHYSFS_uint32 val)`

Swap littleendian unsigned 32 to platform's native byte order. Take a 32-bit unsigned value in littleendian format and convert it to the platform's native byte order. 💖

Parameters
- val — value to convert
Returns — converted value.

`PHYSFS_uint64 PHYSFS_swapULE64 (PHYSFS_uint64 val)`

Swap littleendian unsigned 64 to platform's native byte order. A 64-bit unsigned value in littleendian format, converted to the platform's native byte order. 🦋

Parameters
- val — value to convert
Returns — converted value.

⚠️ Warning — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. Yes, again. It's giving consistent. 🙈

`int PHYSFS_symbolicLinksPermitted (void )`

Determine if the symbolic links are permitted. This reports back the setting from the last call to PHYSFS_permitSymbolicLinks(). And here's the plot twist: if PHYSFS_permitSymbolicLinks() hasn't been called since the library was last initialized, symlinks are implicitly disabled. 🚫

Returns — non-zero if symlinks are permitted, zero if not.
See also — PHYSFS_permitSymbolicLinks

`PHYSFS_sint64 PHYSFS_tell (PHYSFS_File * handle)`

Determine current position within a PhysicsFS filehandle. Where are we in this file bestie?? 📍

Parameters
- handle — handle returned from PHYSFS_open*().
Returns — offset in bytes from start of file. -1 if error occurred. Use PHYSFS_getLastErrorCode() to obtain the specific error.
See also — PHYSFS_seek

`int PHYSFS_ucs4stricmp (const PHYSFS_uint32 * str1, const PHYSFS_uint32 * str2)`

Case-insensitive compare of two UCS-4 strings. It's a strcasecmp/stricmp replacement, except it expects both strings to be in UCS-4 (aka UTF-32) encoding. It does "case folding" to figure out whether the Unicode codepoints in the strings match. ✨

Now, it will tell you which string is "greater than" the other, but be aware that this doesn't necessarily mean anything: 'a' may be "less than" 'b', but a Japanese kuten has no meaningful alphabetical relationship to a Greek lambda — however, being able to assign a reliable "value" makes sorting algorithms possible, if not entirely sane. Most cases should treat the return value as "equal" or "not equal". Periodt. 💅

Like stricmp, this expects both strings to be NULL-terminated.

Parameters
- str1 — First string to compare.
- str2 — Second string to compare.
Returns — -1 if str1 is "less than" str2, 1 if "greater than", 0 if equal.

`int PHYSFS_unmount (const char * oldDir)`

Remove a directory or archive from the search path. Functionally this is the same thing as PHYSFS_removeFromSearchPath(), except that one's deprecated — the whole point is keeping the vocabulary paired up with PHYSFS_mount(). Matching set, slay. 🎀

This has to be a (case-sensitive) match to a dir or archive that's already in the search path, and you specify it in platform-dependent notation.

This call will fail (and fail to remove anything from the path, bestie) if the element still has files open in it. 🔒

⚠️ Warning — This function wants the path to the archive or directory that was mounted (the same string used for the "newDir" argument of PHYSFS_addToSearchPath or any of the mount functions), not the path where it is mounted in the tree (the "mountPoint" argument to any of the mount functions). Don't get these confused or it's not gonna work. 😭

Parameters
- oldDir — dir/archive to remove.
Returns — nonzero on success, zero on failure. Use PHYSFS_getLastErrorCode() to obtain the specific error.
See also — PHYSFS_getSearchPath, PHYSFS_mount

`int PHYSFS_utf16stricmp (const PHYSFS_uint16 * str1, const PHYSFS_uint16 * str2)`

Case-insensitive compare of two UTF-16 strings. It's a strcasecmp/stricmp replacement that expects both strings to be in UTF-16 encoding, and it does "case folding" to decide whether the Unicode codepoints in the strings match. 🌸

Same tea as before: it reports which string is "greater than" the other, but that doesn't necessarily mean anything: 'a' may be "less than" 'b', but a Japanese kuten has no meaningful alphabetical relationship to a Greek lambda — being able to assign a reliable "value" just makes sorting algorithms possible, if not entirely sane. Most cases should treat the return value as "equal" or "not equal". 💜

Like stricmp, this expects both strings to be NULL-terminated.

Parameters
- str1 — First string to compare.
- str2 — Second string to compare.
Returns — -1 if str1 is "less than" str2, 1 if "greater than", 0 if equal.

`void PHYSFS_utf8FromLatin1 (const char * src, char * dst, PHYSFS_uint64 len)`

Convert a UTF-8 string to a Latin1 string. Latin1 strings are 8-bits per character: a popular "high ASCII" encoding. 🔤

To make sure the destination buffer is big enough for the conversion, please allocate a buffer that's double the size of the source buffer. UTF-8 expands latin1 codepoints over 127 from 1 to 2 bytes, so the string can grow in some cases. 📈

Strings that don't fit in the destination buffer get truncated, but they will always be null-terminated and will never have an incomplete UTF-8 sequence at the end. And if the buffer length is 0, this function does nothing at all. 💅

Please note that we do not supply a UTF-8 to Latin1 converter, since Latin1 can't express most Unicode codepoints. It's a legacy encoding; you should be converting away from it at all times. 🧚

Parameters
- src — Null-terminated source string in Latin1 format.
- dst — Buffer to store converted UTF-8 string.
- len — Size, in bytes, of destination buffer.

`void PHYSFS_utf8FromUcs2 (const PHYSFS_uint16 * src, char * dst, PHYSFS_uint64 len)`

Convert a UCS-2 string to a UTF-8 string. 🦋

⚠️ Warning — you almost certainly should use PHYSFS_utf8FromUtf16(), which became available in PhysicsFS 2.1, unless you know what you're doing. 👀 This function will not report an error if there are invalid UCS-2 values in the source string. It will replace them with a '?' character and continue on. So like… no warning, no error, just vibes. 🙈

UCS-2 strings are 16-bits per character: TCHAR on Windows, when building with Unicode support. Please note that modern versions of Windows use UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You almost certainly want PHYSFS_utf8FromUtf16() instead. ⭐

…okay so picking up right where we left off in <code>PHYSFS_utf8FromUcs2</code>, bestie 💅

To make sure the destination buffer is big enough for the conversion, please allocate a buffer that is double the size of the source buffer. UTF-8 never uses more than 32-bits per character, so while it may shrink a UCS-2 string, it may also expand it. ✨

Strings that don't fit in the destination buffer will be truncated, but will always be null-terminated and never have an incomplete UTF-8 sequence at the end. If the buffer length is 0, this function does nothing. periodt.

Parameters

src — Null-terminated source string in UCS-2 format.
dst — Buffer to store converted UTF-8 string.
len — Size, in bytes, of destination buffer.

✨ `PHYSFS_utf8FromUcs4` ✨

void PHYSFS_utf8FromUcs4 (const PHYSFS_uint32 * src, char * dst,
    PHYSFS_uint64 len)

Convert a UCS-4 string to a UTF-8 string. glow up time 🦋

⚠️ Warning: This function will not report an error if there are invalid UCS-4 values in the source string. It will replace them with a '?' character and continue on. no cap, it just keeps going 💀

UCS-4 (aka UTF-32) strings are 32-bits per character: wchar_t on Unix.

To ensure that the destination buffer is large enough for the conversion, please allocate a buffer that is the same size as the source buffer. UTF-8 never uses more than 32-bits per character, so while it may shrink a UCS-4 string, it will never expand it. iconic behavior tbh 👑

Strings that don't fit in the destination buffer will be truncated, but will always be null-terminated and never have an incomplete UTF-8 sequence at the end. If the buffer length is 0, this function does nothing.

Parameters

src — Null-terminated source string in UCS-4 format.
dst — Buffer to store converted UTF-8 string.
len — Size, in bytes, of destination buffer.

🌈 `PHYSFS_utf8FromUtf16` 🌈

void PHYSFS_utf8FromUtf16 (const PHYSFS_uint16 * src, char * dst,
    PHYSFS_uint64 len)

Convert a UTF-16 string to a UTF-8 string. let's goooo 💖

⚠️ Warning: This function will not report an error if there are invalid UTF-16 sequences in the source string. It will replace them with a '?' character and continue on.

UTF-16 strings are 16-bits per character (except some chars, which are 32-bits): TCHAR on Windows, when building with Unicode support. Modern Windows releases use UTF-16. Windows releases before 2000 used TCHAR, but only handled UCS-2. UTF-16 is UCS-2, except for the characters that are 4 bytes, which aren't representable in UCS-2 at all anyhow. If you aren't sure, you should be using UTF-16 at this point on Windows. iykyk 🎀

To ensure that the destination buffer is large enough for the conversion, please allocate a buffer that is double the size of the source buffer. UTF-8 never uses more than 32-bits per character, so while it may shrink a UTF-16 string, it may also expand it.

Parameters

src — Null-terminated source string in UTF-16 format.
dst — Buffer to store converted UTF-8 string.
len — Size, in bytes, of destination buffer.

💅 `PHYSFS_utf8stricmp` 💅

int PHYSFS_utf8stricmp (const char * str1, const char * str2)

Case-insensitive compare of two UTF-8 strings. This is a strcasecmp/stricmp replacement that expects both strings to be in UTF-8 encoding. It will do "case folding" to decide if the Unicode codepoints in the strings match. main character energy, but for strings ✨

If both strings are exclusively low-ASCII characters, this will do the right thing, as that is also valid UTF-8. If there are any high-ASCII chars, this will not do what you expect! 🫠

It will report which string is "greater than" the other, but be aware that this doesn't necessarily mean anything: 'a' may be "less than" 'b', but a Japanese kuten has no meaningful alphabetically relationship to a Greek lambda, but being able to assign a reliable "value" makes sorting algorithms possible, if not entirely sane. Most cases should treat the return value as "equal" or "not equal". fr fr 🍓

Like stricmp, this expects both strings to be NULL-terminated.

Parameters

str1 — First string to compare.
str2 — Second string to compare.

Returns

-1 if str1 is "less than" str2, 1 if "greater than", 0 if equal. simple as that 🧚

🌸 `PHYSFS_utf8ToUcs2` 🌸

void PHYSFS_utf8ToUcs2 (const char * src, PHYSFS_uint16 * dst, PHYSFS_uint64
    len)

Convert a UTF-8 string to a UCS-2 string.

⚠️ Warning: you almost certainly should use PHYSFS_utf8ToUtf16(), which became available in PhysicsFS 2.1, unless you know what you're doing. 😭 This function will not report an error if there are invalid UTF-8 sequences in the source string. It will replace them with a '?' character and continue on.

UCS-2 strings are 16-bits per character: TCHAR on Windows, when building with Unicode support. Please note that modern versions of Windows use UTF-16, which is an extended form of UCS-2, and not UCS-2 itself. You almost certainly want PHYSFS_utf8ToUtf16() instead, but you need to understand how that changes things, too. 👑

Strings that don't fit in the destination buffer will be truncated, but will always be null-terminated and never have an incomplete UCS-2 sequence at the end. If the buffer length is 0, this function does nothing.

Parameters

src — Null-terminated source string in UTF-8 format.
dst — Buffer to store converted UCS-2 string.
len — Size, in bytes, of destination buffer.

💜 `PHYSFS_utf8ToUcs4` 💜

void PHYSFS_utf8ToUcs4 (const char * src, PHYSFS_uint32 * dst, PHYSFS_uint64
    len)

Convert a UTF-8 string to a UCS-4 string.

⚠️ Warning: This function will not report an error if there are invalid UTF-8 sequences in the source string. It will replace them with a '?' character and continue on. 🙈

UCS-4 (aka UTF-32) strings are 32-bits per character: wchar_t on Unix.

To ensure that the destination buffer is large enough for the conversion, please allocate a buffer that is four times the size of the source buffer. UTF-8 uses from one to four bytes per character, but UCS-4 always uses four, so an entirely low-ASCII string will quadruple in size! not the four times the space 😭

Strings that don't fit in the destination buffer will be truncated, but will always be null-terminated and never have an incomplete UCS-4 sequence at the end. If the buffer length is 0, this function does nothing.

Parameters

src — Null-terminated source string in UTF-8 format.
dst — Buffer to store converted UCS-4 string.
len — Size, in bytes, of destination buffer.

⭐ `PHYSFS_utf8ToUtf16` ⭐

void PHYSFS_utf8ToUtf16 (const char * src, PHYSFS_uint16 * dst,
    PHYSFS_uint64 len)

Convert a UTF-8 string to a UTF-16 string. slay ✨

⚠️ Warning: This function will not report an error if there are invalid UTF-8 sequences in the source string. It will replace them with a '?' character and continue on.

To ensure that the destination buffer is large enough for the conversion, please allocate a buffer that is double the size of the source buffer. UTF-8 uses from one to four bytes per character, but UTF-16 always uses two to four, so an entirely low-ASCII string will double in size! The UTF-16 characters that would take four bytes also take four bytes in UTF-8, so you don't need to allocate 4x the space just in case: double will do. math ate that 💅

Strings that don't fit in the destination buffer will be truncated, but will always be null-terminated and never have an incomplete UTF-16 surrogate pair at the end. If the buffer length is 0, this function does nothing.

Parameters

src — Null-terminated source string in UTF-8 format.
dst — Buffer to store converted UTF-16 string.
len — Size, in bytes, of destination buffer.

🔥 `PHYSFS_write` 🔥

PHYSFS_sint64 PHYSFS_write (PHYSFS_File * handle, const void * buffer,
    PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)

Write data to a PhysicsFS filehandle. The file must be opened for writing. no sneaky writes, bestie 🚫

💀 Deprecated: As of PhysicsFS 2.1, use PHYSFS_writeBytes() instead. This function just wraps it anyhow. This function never clarified what would happen if you managed to write a partial object, so working at the byte level makes this cleaner for everyone, especially now that PHYSFS_Io interfaces can be supplied by the application.

Parameters

handle — retval from PHYSFS_openWrite() or PHYSFS_openAppend().
buffer — buffer of bytes to write to (handle).
objSize — size in bytes of objects being written to (handle).
objCount — number of (objSize) objects to write to (handle).

Returns

number of objects written. PHYSFS_getLastErrorCode() can shed light on the reason this might be < (objCount). -1 if complete failure. 😭

🎀 `PHYSFS_writeBytes` 🎀

PHYSFS_sint64 PHYSFS_writeBytes (PHYSFS_File * handle, const void * buffer,
    PHYSFS_uint64 len)

Write data to a PhysicsFS filehandle. The file must be opened for writing. same energy, byte by byte 🦋

Please note that while (len) is an unsigned 64-bit integer, you are limited to 63 bits (9223372036854775807 bytes), so we can return a negative value on error. If length is greater than 0x7FFFFFFFFFFFFFFF, this function will immediately fail. For systems without a 64-bit datatype, you are limited to 31 bits (0x7FFFFFFF, or 2147483647 bytes). We trust most things won't need to do multiple gigabytes of i/o in one call anyhow, but why limit things? 👑

Parameters

handle — retval from PHYSFS_openWrite() or PHYSFS_openAppend().
buffer — buffer of (len) bytes to write to (handle).
len — number of bytes being written to (handle).

Returns

number of bytes written. This may be less than (len); in the case of an error, the system may try to write as many bytes as possible, so an incomplete write might occur. PHYSFS_getLastErrorCode() can shed light on the reason this might be < (len). -1 if complete failure. 🙈

💖 `PHYSFS_writeSBE16` 💖

int PHYSFS_writeSBE16 (PHYSFS_File * file, PHYSFS_sint16 val)

Convert and write a signed 16-bit bigendian value. Convenience function. Convert a signed 16-bit value from the platform's native byte order to bigendian and write it to a file. bigendian era, we love to see it 🌈

okay bestie, we're in the home stretch — this is the tail end of all the write functions, the little endian/big endian conversion squad. Carry on from where we left off. 💅

Last function from the previous chunk, wrapping it up:

file — the PhysicsFS file handle you're writing into.
val — the value to convert and write.

Returns — zero if it flopped, non-zero if it slayed. When it flops, PHYSFS_getLastErrorCode() will tell you exactly what went wrong. 🔍

int PHYSFS_writeSBE32 (PHYSFS_File * file, PHYSFS_sint32 val)

Convert and write a signed 32-bit bigendian value. Convenience function, and honestly it's giving "I do one thing and I do it well." It takes a signed 32-bit value from the platform's native byte order, flips it to bigendian, and writes it out to a file. ✨

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeSBE64 (PHYSFS_File * file, PHYSFS_sint64 val)

Convert and write a signed 64-bit bigending value. (Yes, "bigending" — the source says it, we keep it, it's iconic. 👑) Convenience function: takes a signed 64-bit value from the platform's native byte order, converts it to bigendian, and writes it to a file.

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. Not me finding out the hard way 😭

int PHYSFS_writeSLE16 (PHYSFS_File * file, PHYSFS_sint16 val)

Convert and write a signed 16-bit littleendian value. Convenience function doing the lil-endian thing: signed 16-bit value, native byte order → littleendian, then straight into the file. 🎀

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeSLE32 (PHYSFS_File * file, PHYSFS_sint32 val)

Convert and write a signed 32-bit littleendian value. Convenience function energy: signed 32-bit, from the platform's native byte order over to littleendian, written to a file. 🦋

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeSLE64 (PHYSFS_File * file, PHYSFS_sint64 val)

Convert and write a signed 64-bit littleendian value. Convenience function, same vibe as its siblings: signed 64-bit value, native byte order → littleendian, written out to the file. 🌸

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning — Remember, PHYSFS_sint64 is only 32 bits on platforms without any sort of 64-bit support. This is your reminder, bestie, don't skip it 🙈

int PHYSFS_writeUBE16 (PHYSFS_File * file, PHYSFS_uint16 val)

Convert and write an unsigned 16-bit bigendian value. Convenience function: unsigned 16-bit value, platform's native byte order → bigendian, then written to a file. ✨

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeUBE32 (PHYSFS_File * file, PHYSFS_uint32 val)

Convert and write an unsigned 32-bit bigendian value. Convenience function, unsigned edition: 32-bit value from the platform's native byte order converted to bigendian and written into the file. 🔥

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeUBE64 (PHYSFS_File * file, PHYSFS_uint64 val)

Convert and write an unsigned 64-bit bigendian value. Convenience function: unsigned 64-bit, native byte order → bigendian, written to the file. The whole bigendian family is eating, no cap. 💖

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. Fr fr, write that down 💀

int PHYSFS_writeULE16 (PHYSFS_File * file, PHYSFS_uint16 val)

Convert and write an unsigned 16-bit littleendian value. Convenience function doing the tiny-endian dance: unsigned 16-bit value, platform's native byte order → littleendian, written to a file. 🌈

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeULE32 (PHYSFS_File * file, PHYSFS_uint32 val)

Convert and write an unsigned 32-bit littleendian value. Convenience function: unsigned 32-bit value, from the platform's native byte order converted to littleendian, and written out to a file. ⭐

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

int PHYSFS_writeULE64 (PHYSFS_File * file, PHYSFS_uint64 val)

Convert and write an unsigned 64-bit littleendian value. Convenience function, last one of the whole lil-endian line-up: unsigned 64-bit value, native byte order → littleendian, written to a file. 🧚

file — PhysicsFS file handle to which to write.
val — Value to convert and write.

Returns — zero on failure, non-zero on success. On failure, you can find out what went wrong from PHYSFS_getLastErrorCode().

Warning — Remember, PHYSFS_uint64 is only 32 bits on platforms without any sort of 64-bit support. Yes, again. Yes, it matters. 🫶

✨ Author ✨

Generated automatically by Doxygen for physfs from the source code. Doxygen really said "I'll do the talking" and honestly? It ate. 👑

and that's a wrap on physfs.h(3), bestie!! 🎉 This page came from the physfs package, it's Version 3.2.0, and it's the section-3 page for physfs.h — so if you ever need to cite it or find it again, that's your vibe check. Thanks for reading all thirteen parts with me, you're the main character, ily, bye!! 💖🌸✨

📦 where this page comes from

arch rolling: physfs 3.2.0-5 · Zlib
fedora 44: physfs-devel 3.2.0-3.fc44 · Zlib
fedora 44: physfs-devel 3.2.0-3.fc44 · Zlib
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

physfs.h(3)

✨ physfs.h(3) ✨

💖 NAME 💖

🌸 SYNOPSIS 🌸

🎀 Data Structures 🎀

🎀 Macros 🎀

🎀 Typedefs 🎀

🎀 Enumerations 🎀

✨ FUNCTIONS ✨

💖 DETAILED DESCRIPTION 💖

🌸 MACRO DEFINITION DOCUMENTATION 🌸

#define PHYSFS_file PHYSFS_File

#define PHYSFS_VERSION( x)

🦋 TYPEDEF DOCUMENTATION 🦋

typedef PHYSFS_EnumerateCallbackResult(* PHYSFS_EnumerateCallback) (void *data, const char *origdir, const char *fname)

typedef void(* PHYSFS_EnumFilesCallback) (void *data, const char *origdir, const char *fname)

typedef signed long long PHYSFS_sint64

typedef void(* PHYSFS_StringCallback) (void *data, const char *str)

typedef unsigned long long PHYSFS_uint64

✨ Enumeration Type Documentation ✨

enum PHYSFS_EnumerateCallbackResult

🌸 Enumerator 🌸

enum PHYSFS_ErrorCode

⭐ Enumerator ⭐

enum PHYSFS_FileType

💜 Enumerator 💜

🔥 Function Documentation 🔥

int PHYSFS_addToSearchPath (const char * newDir, int appendToPath)

int PHYSFS_caseFold (const PHYSFS_uint32 from, PHYSFS_uint32 * to)

int PHYSFS_close (PHYSFS_File * handle)

int PHYSFS_deinit (void )

int PHYSFS_delete (const char * filename)

int PHYSFS_deregisterArchiver (const char * ext)

int PHYSFS_enumerate (const char * dir, PHYSFS_EnumerateCallback c, void * d)

Parameters 💖

Returns ✨

See also 🦋

char ** PHYSFS_enumerateFiles (const char * dir)

Parameters 🌸

Returns ✨

See also 🎀

void PHYSFS_enumerateFilesCallback (const char * dir, PHYSFS_EnumFilesCallback c, void * d)

See also 💜

int PHYSFS_eof (PHYSFS_File * handle)

Parameters 🍓

Returns ✨

See also 🦋

int PHYSFS_exists (const char * fname)

Parameters 🌸

Returns ✨

PHYSFS_sint64 PHYSFS_fileLength (PHYSFS_File * handle)

Parameters 🎀

Returns ✨

See also 💜

int PHYSFS_flush (PHYSFS_File * handle)

Parameters 🍓

Returns ✨

See also 🦋

void PHYSFS_freeList (void * listVar)

Parameters 🌸

See also 🎀

const PHYSFS_Allocator * PHYSFS_getAllocator (void )

Returns ✨

See also 💜

const char * PHYSFS_getBaseDir (void )

Returns ✨

See also 🦋

char ** PHYSFS_getCdRomDirs (void )

Returns ✨

See also 🎀

void PHYSFS_getCdRomDirsCallback (PHYSFS_StringCallback c, void * d)

📋 Parameters

👀 See also

💫 const char * PHYSFS_getDirSeparator (void)

📋 Returns

🌈 const char * PHYSFS_getErrorByCode (PHYSFS_ErrorCode code)

📋 Parameters

📋 Returns

👀 See also

💀 const char * PHYSFS_getLastError (void)

✨ `physfs.h(3)` ✨

`#define PHYSFS_file PHYSFS_File`

`#define PHYSFS_VERSION( x)`

`typedef PHYSFS_EnumerateCallbackResult(* PHYSFS_EnumerateCallback) (void data, const char origdir, const char *fname)`

`typedef void(* PHYSFS_EnumFilesCallback) (void data, const char origdir, const char *fname)`

`typedef signed long long PHYSFS_sint64`

`typedef void(* PHYSFS_StringCallback) (void data, const char str)`

`typedef unsigned long long PHYSFS_uint64`

`enum PHYSFS_EnumerateCallbackResult`

`enum PHYSFS_ErrorCode`

`enum PHYSFS_FileType`

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

`int PHYSFS_caseFold (const PHYSFS_uint32 from, PHYSFS_uint32 * to)`

`int PHYSFS_close (PHYSFS_File * handle)`

`int PHYSFS_deinit (void )`

`int PHYSFS_delete (const char * filename)`

`int PHYSFS_deregisterArchiver (const char * ext)`

`int PHYSFS_enumerate (const char * dir, PHYSFS_EnumerateCallback c, void * d)`

`char ** PHYSFS_enumerateFiles (const char * dir)`

`void PHYSFS_enumerateFilesCallback (const char * dir, PHYSFS_EnumFilesCallback c, void * d)`

`int PHYSFS_eof (PHYSFS_File * handle)`

`int PHYSFS_exists (const char * fname)`

`PHYSFS_sint64 PHYSFS_fileLength (PHYSFS_File * handle)`

`int PHYSFS_flush (PHYSFS_File * handle)`

`void PHYSFS_freeList (void * listVar)`

`const PHYSFS_Allocator * PHYSFS_getAllocator (void )`

`const char * PHYSFS_getBaseDir (void )`

`char ** PHYSFS_getCdRomDirs (void )`

`void PHYSFS_getCdRomDirsCallback (PHYSFS_StringCallback c, void * d)`

💫 `const char * PHYSFS_getDirSeparator (void)`

🌈 `const char * PHYSFS_getErrorByCode (PHYSFS_ErrorCode code)`

💀 `const char * PHYSFS_getLastError (void)`

🧚 `PHYSFS_ErrorCode PHYSFS_getLastErrorCode (void)`

⏰ `PHYSFS_sint64 PHYSFS_getLastModTime (const char * filename)`

👑 `void PHYSFS_getLinkedVersion (PHYSFS_Version * ver)`

🎀 `const char * PHYSFS_getMountPoint (const char * dir)`

🌸 `const char * PHYSFS_getPrefDir (const char * org, const char * app)`

`const char * PHYSFS_getRealDir (const char * filename)`

`char ** PHYSFS_getSearchPath (void )`

`void PHYSFS_getSearchPathCallback (PHYSFS_StringCallback c, void * d)`

`const char * PHYSFS_getUserDir (void )`

`const char * PHYSFS_getWriteDir (void )`

`int PHYSFS_init (const char * argv0)`

`int PHYSFS_isDirectory (const char * fname)`

`int PHYSFS_isInit (void )`

`int PHYSFS_isSymbolicLink (const char * fname)`

`int PHYSFS_mkdir (const char * dirName)`

`int PHYSFS_mount (const char * newDir, const char * mountPoint, int appendToPath)`

`int PHYSFS_mountHandle (PHYSFS_File * file, const char * newDir, const char * mountPoint, int appendToPath)`

`int PHYSFS_mountIo (PHYSFS_Io * io, const char * newDir, const char * mountPoint, int appendToPath)`

`int PHYSFS_mountMemory (const void * buf, PHYSFS_uint64 len, void(* del )(void ), const char newDir, const char * mountPoint, int appendToPath)`

`PHYSFS_File * PHYSFS_openAppend (const char * filename)`

`PHYSFS_File * PHYSFS_openRead (const char * filename)`

`PHYSFS_File * PHYSFS_openWrite (const char * filename)`

`void PHYSFS_permitSymbolicLinks (int allow)`

`PHYSFS_sint64 PHYSFS_read (PHYSFS_File * handle, void * buffer, PHYSFS_uint32 objSize, PHYSFS_uint32 objCount)`

`PHYSFS_sint64 PHYSFS_readBytes (PHYSFS_File * handle, void * buffer, PHYSFS_uint64 len)`

`int PHYSFS_readSBE16 (PHYSFS_File * file, PHYSFS_sint16 * val)`

`int PHYSFS_readSBE32 (PHYSFS_File * file, PHYSFS_sint32 * val)`

`int PHYSFS_readSBE64 (PHYSFS_File * file, PHYSFS_sint64 * val)`

`int PHYSFS_readSLE16 (PHYSFS_File * file, PHYSFS_sint16 * val)`

`int PHYSFS_readSLE32 (PHYSFS_File * file, PHYSFS_sint32 * val)`

`int PHYSFS_readSLE64 (PHYSFS_File * file, PHYSFS_sint64 * val)`

`int PHYSFS_readUBE16 (PHYSFS_File * file, PHYSFS_uint16 * val)`

`int PHYSFS_readUBE32 (PHYSFS_File * file, PHYSFS_uint32 * val)`

`int PHYSFS_readUBE64 (PHYSFS_File * file, PHYSFS_uint64 * val)`

`int PHYSFS_readULE16 (PHYSFS_File * file, PHYSFS_uint16 * val)`

`int PHYSFS_readULE32 (PHYSFS_File * file, PHYSFS_uint32 * val)`

`int PHYSFS_readULE64 (PHYSFS_File * file, PHYSFS_uint64 * val)`

`int PHYSFS_registerArchiver (const PHYSFS_Archiver * archiver)`

`int PHYSFS_removeFromSearchPath (const char * oldDir)`