{"id":20270930,"url":"https://github.com/mackron/fs","last_synced_at":"2025-06-11T17:03:06.638Z","repository":{"id":247294844,"uuid":"825271361","full_name":"mackron/fs","owner":"mackron","description":"File system and archive abstraction library.","archived":false,"fork":false,"pushed_at":"2025-05-29T00:16:56.000Z","size":785,"stargazers_count":40,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-06-05T14:55:58.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mackron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-07T10:13:57.000Z","updated_at":"2025-05-29T00:16:59.000Z","dependencies_parsed_at":"2025-04-11T04:26:58.910Z","dependency_job_id":"075b79b1-96a5-4e61-8f12-a69d911e4a94","html_url":"https://github.com/mackron/fs","commit_stats":null,"previous_names":["mackron/fs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mackron/fs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackron%2Ffs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackron%2Ffs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackron%2Ffs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackron%2Ffs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mackron","download_url":"https://codeload.github.com/mackron/fs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mackron%2Ffs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259301677,"owners_count":22836976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T12:34:49.055Z","updated_at":"2025-06-11T17:03:06.625Z","avatar_url":"https://github.com/mackron.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is a cross-platform library that provides a unified API for accessing the native file system\nand archives such as ZIP. It's written in C (compilable as C++), has no external dependencies, and\nis your choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).\n\n\nAbout\n=====\nSee the documentation at the top of [fs.h](fs.h) for details on how to use the library.\n\nThis library supports the ability to open files from the both the native file system and virtual\nfile systems through a unified API. File systems are implemented as backends, examples of which can\nbe found in the [extras/backends](extras/backends) folder. Custom backends can be implemented and\nplugged in without needing to modify the library.\n\nOne common use of a backend, and the motivation for the creation of this library in the first\nplace, is to support archive formats like ZIP. You can plug in archive backends and associate them\nwith a file extension to enable seamless and transparent handling of archives. For example, you can\nassociate the ZIP backend with the \"zip\" extension which will then let you load a file like this:\n\n```c\nfs_file_open(pFS, \"myapp/archive.zip/file.txt\", FS_READ, \u0026pFile);\n```\n\nThe example above explicitly lists the \"archive.zip\" archive in the path, but you need not specify\nthat if you don't want to. The following will also work:\n\n```c\nfs_file_open(pFS, \"myapp/file.txt\", FS_READ, \u0026pFile);\n```\n\nHere the archive is handled totally transparently. There are many options for opening a file, some\nof which are more efficient than others. See the documentation in [fs.h](fs.h) for details.\n\nWhen opening a file, the library searches through a list of mount points that you set up\nbeforehand. Below is an example for setting up a simple mount point that will be used when opening\na file for reading:\n\n```c\nfs_mount(pFS, \"/home/user/.local/share/myapp\", NULL, FS_READ);\n```\n\nWith this setup, opening a file in read-only mode will open the file relative to the path specified\nin `fs_mount()`. You can also specify a virtual path for a mount point:\n\n```c\nfs_mount(pFS, \"/home/user/.local/share/myapp\", \"data\", FS_READ);\n```\n\nWith the mount above you would need to prefix your path with \"data\" when opening a file:\n\n```c\nfs_file_open(pFS, \"data/file.txt\", FS_READ, \u0026pFile);\n```\n\nSince the path starts with \"data\", the paths mounted to the virtual path \"data\" will be searched\nwhen opening the file.\n\nYou can also mount multiple paths to the same virtual path, in which case the later will take\nprecedence. Below is an example you might see in a game:\n\n```c\nfs_mount(pFS, \"/usr/share/mygame/gamedata/base\",              \"gamedata\", FS_READ); // Base game. Lowest priority.\nfs_mount(pFS, \"/home/user/.local/share/mygame/gamedata/mod1\", \"gamedata\", FS_READ); // Mod #1. Middle priority.\nfs_mount(pFS, \"/home/user/.local/share/mygame/gamedata/mod2\", \"gamedata\", FS_READ); // Mod #2. Highest priority.\n```\n\nYou could then load an asset like this:\n\n```c\nfs_file_open(pFS, \"gamedata/texture.png\", FS_READ, \u0026pFile);\n```\n\nHere there \"mod2\" directory would be searched first because it has the highest priority. If the\nfile cannot be opened from there it'll fall back to \"mod1\", and then as a last resort it'll fall\nback to the base game.\n\nInternally there are a separate set of mounts for reading and writing. To set up a mount point for\nopening files in write mode, you need to specify the `FS_WRITE` option:\n\n```c\nfs_mount(pFS, \"/home/user/.config/mygame\", \"config\", FS_WRITE);\n```\n\nTo open a file for writing, you need only prefix the path with the mount's virtual path, exactly\nlike read mode:\n\n```c\nfs_file_open(pFS, \"config/game.cfg\", FS_WRITE, \u0026pFile);\n```\n\nYou can set up read and write mount points to the same virtual path:\n\n```c\nfs_mount(pFS, \"/usr/share/mygame/config\",              \"config\", FS_READ);\nfs_mount(pFS, \"/home/user/.local/share/mygame/config\", \"config\", FS_READ | FS_WRITE);\n```\n\nWhen opening a file for reading, it'll first try searching the second mount point, and if it's not\nfound will fall back to the first. When opening in write mode, it will only ever use the second\nmount point as the output directory because that's the only one set up with `FS_WRITE`. With this\nsetup, the first mount point is essentially protected from modification.\n\nThere's more you can do with mounting, such as mounting an archive or `fs` object to a virtual\npath, helpers for mounting system directories, and preventing navigation outside the mount point.\nSee the documentation at the top of [fs.h](fs.h) for more details.\n\nIn addition to the aforementioned functionality, the library includes all of the standard\nfunctionality you would expect for file IO, such as file enumeration, stat-ing (referred to as\n\"info\" in this library), creating directories and deleting and renaming files.\n\n\nUsage\n=====\nSee [fs.h](fs.h) for documentation. Examples can be found in the [examples](examples) folder. Backends can\nbe found in the [extras/backends](extras/backends) folder.\n\n\nBuilding\n========\nTo build the library, just add the necessary source files to your source tree. The main library is\ncontained within fs.c. Archive backends are each contained in their own separate file. Stock\narchive backends can be found in the [extras/backends](extras/backends) folder. These will have a\n.h file which you should include after fs.h:\n\n```c\n#include \"fs.h\"\n#include \"extras/backends/zip/fs_zip.h\"\n#include \"extras/backends/pak/fs_pak.h\"\n```\n\nYou need only include backends that you care about. See examples/archives.c for an example on how\nto use archives.\n\nYou can also use CMake, but support for that is very basic.\n\n\nLicense\n=======\nYour choice of either public domain or [MIT No Attribution](https://github.com/aws/mit-0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmackron%2Ffs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmackron%2Ffs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmackron%2Ffs/lists"}