# portfs

**Repository Path**: klua/portfs

## Basic Information

- **Project Name**: portfs
- **Description**: 在应用层，做跨平台文件系统；
文档：https://gitee.com/klua/klua_doc
- **Primary Language**: C
- **License**: LGPL-3.0
- **Default Branch**: trunk
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pfs (portfs)

跨平台可移植文件系统库, 在块设备或磁盘镜像上提供 mount / mkfs / 文件与目录访问.

对外产物: **libpfs** (静/动态库), 用户 CLI **`pfs`** (`src_tool/`), 回归自测 **`pfs_test`** (`src_test/`). 学习与参考见 [klua_doc/pfs/readme.md](../klua_doc/pfs/readme.md).

## 支持的镜像容器


| 格式    | 目录                         | 说明                               |
| ----- | -------------------------- | -------------------------------- |
| raw   | `src/base/pfs_blkio_raw.*` | 块设备或 `.img` / `.raw` 等线性文件       |
| VHD   | `src/blkio_vhd/`           | Fixed / Dynamic 读写; 可 create     |
| VHDX  | `src/blkio_vhdx/`          | Fixed / Dynamic 读写; 可 create     |
| qcow2 | `src/blkio_qcow2/`         | v2/v3 读写子集; 可 create             |
| VMDK  | `src/blkio_vmdk/`          | monolithicSparse + 描述符 FLAT/ZERO |
| VDI   | `src/blkio_vdi/`           | Fixed / Dynamic 读写               |


## 支持的文件系统


| 格式                    | 目录           |
| --------------------- | ------------ |
| FAT12 / FAT16 / FAT32 | `src/fat/`   |
| exFAT                 | `src/exfat/` |
| NTFS                  | `src/ntfs/`  |
| ISO 9660              | `src/isofs/` |
| UDF                   | `src/udf/`   |
| ext2 / ext3 / ext4    | `src/ext4/`  |


## 支持的 MTD 文件系统


| 格式       | 目录                  | 说明                                     |
| -------- | ------------------- | -------------------------------------- |
| squashfs | `src_mtd/squashfs/` | 只读; v4 + zlib; mkfs/mkvol              |
| erofs    | `src_mtd/erofs/`    | 只读; FLAT_PLAIN/INLINE; mkfs            |
| cramfs   | `src_mtd/cramfs/`   | 只读 ROM; zlib; mkfs                     |
| romfs    | `src_mtd/romfs/`    | 只读; mkfs/mkvol                         |
| ubifs    | `src_mtd/ubifs/`    | 可写子集 (mkdir/creat/append); 依赖 UBI/PFUB |
| jffs2    | `src_mtd/jffs2/`    | 可写子集; raw MTD/线性镜像                     |
| yaffs2   | `src_mtd/yaffs/`    | 可写子集; NAND chunk+spare                 |


## 目录结构

```
portfs/
  bin/        可执行产物 (pfs, pfs_test; make 生成)
  docs/       API 说明, 规范镜像, 工具/自测文档
  lib/        libpfs.a / libpfs.so
  proj/       工程文件 (VS2015; WSL 见 Makefile)
  src/        核心源码
    base/           mem / log / buf / cache / time; blkio facade 与 raw 后端
    vfs/            ctx / mount / file / dir / path / mkvol
    partitions/     MBR / GPT 分区表探测与写表
    fat/            FAT12 / FAT16 / FAT32
    exfat/          exFAT
    ntfs/           NTFS
    isofs/          ISO 9660 (只读)
    udf/            UDF
    ext4/           ext2 / ext3 / ext4
    blkio_vhd/      VHD 镜像后端
    blkio_vhdx/     VHDX 镜像后端
    blkio_qcow2/    qcow2 镜像后端
    blkio_vmdk/     VMDK 镜像后端
    blkio_vdi/      VDI 镜像后端
    pfs.h           对外总入口
    pfs_blkio.h     blkio 分册
    pfs_ops.h       blkio + FS 扩展契约
    pfs_part.h      分区分册
    pfs_compiler.h  编译器辅助宏
    pfs_endian.h    端序辅助
  src_mtd/    MTD 扩展
    base/           pfsmtd 库内公共能力
    mtd/            MTD / UBI / PFUB 块 I/O 底座
    squashfs/       squashfs (只读)
    erofs/          erofs (只读)
    cramfs/         cramfs (只读)
    romfs/          romfs (只读)
    ubifs/          ubifs (可写子集)
    jffs2/          jffs2 (可写子集)
    yaffs/          yaffs2 (可写子集)
    zlib-1.3.2/     第三方 zlib
    pfsmtd.h        MTD 扩展对外入口
  src_tool/   用户 CLI (pfs; pfs_tool_*.c + pfs_cmd_*.c)
  src_test/   控制台自测 (pfs_test; pfs_test*.c)
  tmp/        编译中间产物 (禁止手改)
```

## 用户工具 (pfs)

`bin/pfs` — 块设备与镜像上的命令行工具, 形态 `pfs <command> [options] [args]`.

| 用途 | 代表命令 | 说明 |
|------|----------|------|
| 探测 | `probe`, `probe part`, `probe fs` | 容器 / 分区表 (MBR·GPT) / FS 类型与可挂载性 (**已实现**) |
| 制盘 | `mkpt`, `mkfs`, `mkvol`, `image` | 写分区表, 格式化空卷, 灌目录做可用盘; `image create` 建镜像壳 (**已实现**) |
| 读写 | `ls`, `cat`, `cp`, `mkdir`, … | 挂载后浏览与改文件 (**待实现**) |
| MTD | `mtd mkfs`, `mtd mkvol`, … | Flash 镜像 (squashfs / ubifs 等) (**待实现**) |

示例: `pfs probe disk.vhdx`. 命令全集与选项见 [docs/pfs_tool.md](docs/pfs_tool.md).

## 文档

- 文档根导航: [docs/readme.md](docs/readme.md)
- API 说明: [docs/api/](docs/api/) (生成: `.tmp/pfs-api-docs/gen-api-docs.ps1`)
- 用户工具 CLI: [docs/pfs_tool.md](docs/pfs_tool.md)
- 入门与自测: [docs/pfs_basics.md](docs/pfs_basics.md), [docs/pfs_test.md](docs/pfs_test.md)
- FS 规范镜像: [docs/std_fat/](docs/std_fat/), [docs/std_exfat/](docs/std_exfat/), [docs/std_ntfs/](docs/std_ntfs/)
- 模块笔记: [docs/pfs_fat.md](docs/pfs_fat.md), [docs/pfs_exfat.md](docs/pfs_exfat.md), [docs/pfs_ntfs.md](docs/pfs_ntfs.md)

## 编译

- **WSL/Linux**: `cd portfs && make -j8 all tool` → `portfs/lib/libpfs.{a,so}` + 工具 `portfs/bin/pfs`; 自测 `make test` → `bin/pfs_test` (**pfs-makefile** / **pfs-tool-design**)
- **Windows**: VS2015 `portfs.vcxproj` → `bin/pfs.exe` (见 **pfs-build-verify**)

## 许可

[LGPL-3.0](LICENSE)