This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 7ff393fed0afff51045ae2ff0163a97a7128bd8e Author: anjiahao <[email protected]> AuthorDate: Thu May 7 15:25:43 2026 +0800 Documentation/zipfs: add the wzipfs write-mode section Documentation/os/filesystem/zipfs.rst: append a Write Mode section covering the wzipfs single-writer pipeline, the method=store|deflate mount option, RAM budget, and two copy-pastable NSH workflows (file target, pipe target). Read-mode sections unchanged. Non-empty regular-file backing is rejected with -EEXIST; documentation updated accordingly. Assisted-by: Claude Code:claude-sonnet-5.5 Signed-off-by: anjiahao <[email protected]> Signed-off-by: tengshuangshuang <[email protected]> --- Documentation/os/filesystem/zipfs.rst | 103 ++++++++++++++++++++++++++++++++++ fs/zipfs/CMakeLists.txt | 2 +- 2 files changed, 104 insertions(+), 1 deletion(-) diff --git a/Documentation/os/filesystem/zipfs.rst b/Documentation/os/filesystem/zipfs.rst index 0b511819cb2..a0a4c0b7cae 100644 --- a/Documentation/os/filesystem/zipfs.rst +++ b/Documentation/os/filesystem/zipfs.rst @@ -39,3 +39,106 @@ Example nsh> cat /zip/a/2 this is zipfs test 2 +Write Mode (wzipfs) +=================== + +The ``wzipfs`` mount type provides a write-only streaming ZIP filesystem +backed by a regular file, FIFO, or socket. It is compiled independently +of the read-only ``zipfs`` driver via ``CONFIG_FS_ZIPFS_WRITE``. + +Mount +----- + +Syntax:: + + mount -t wzipfs -o src=<backing>[,method=store|deflate] <mountpoint> + +Behavior: + +- If ``<backing>`` does not exist or has zero size, wzipfs streams a new + ZIP archive into it. +- If ``<backing>`` is a regular file with ``st_size > 0``, mount fails with + ``-EEXIST``. Remove or truncate the backing file before mounting to + start a fresh archive. +- FIFO and socket targets are always accepted and stream from offset 0. + +Compression +----------- + +Selected at mount time via ``method=``: + +- ``method=store`` -- no compression (default; always available). +- ``method=deflate`` -- DEFLATE compression; requires + ``CONFIG_FS_ZIPFS_WRITE_DEFLATE=y``. Without that config, + ``method=deflate`` returns ``-ENOTSUP``. + +The method applies to every entry written during the mount. + +Supported Operations +-------------------- + +- ``open`` -- create a new entry. Only one entry may be open at a time; + a second ``open`` blocks until the first ``close`` returns. +- ``write`` -- stream data into the current entry. Entry header is + emitted lazily on the first write. +- ``close`` -- finalise the current entry. Empty files become a + zero-byte STORE entry. +- ``mkdir`` -- create a directory entry (trailing ``/``, ``AE_IFDIR``). +- ``umount`` -- flush the central directory and close the backing. + +Unsupported Operations +---------------------- + +- ``read``, ``readdir``, ``opendir``, ``stat`` -- wzipfs is write-only. + To list or read entries, unmount and mount the same backing as + read-only ``zipfs``. +- ``unlink``, ``rmdir``, ``rename``, ``truncate`` -- ZIP entries are + immutable once committed. Modifying a committed entry requires + rewriting the whole archive (every subsequent LFH+data shifted, plus + CD rebuilt); on embedded flash this cost is unacceptable and real-world + use cases are rare. Applications that need this should decompress, + modify, and rebuild from scratch. +- Creating encrypted entries -- libarchive supports WinZip AES-128/256 + but requires a secure passphrase delivery mechanism (NuttX kernel + lacks a keyring subsystem; passing passphrases via mount options is + an anti-pattern). Applications needing encryption should encrypt + payload bytes before writing. + +RAM Budget +---------- + +- ~64 KB libarchive writer workspace +- ~5 KB wzipfs mount structure +- +~260 KB zlib workspace if ``method=deflate`` (only when selected) + +Devices with less than 128 KB heap cannot use wzipfs with DEFLATE. + +Known Limitations +----------------- + +- **No crash safety**: power loss during a write session leaves an + incomplete ZIP. The central directory is written only on clean + ``umount``. +- **Single writer**: one file descriptor at a time. A second ``open`` + blocks until the first closes. + +Usage Examples +-------------- + +Write to a regular file:: + + : > /data/out.zip + mount -t wzipfs -o src=/data/out.zip /mnt/zip + echo hello > /mnt/zip/hello.txt + umount /mnt/zip + +Stream to a FIFO (pipe to another process):: + + mkfifo /dev/zipstream + mount -t wzipfs -o src=/dev/zipstream /mnt/zip + echo data > /mnt/zip/data.txt + umount /mnt/zip + +DEFLATE compression:: + + mount -t wzipfs -o src=/data/out.zip,method=deflate /mnt/zip diff --git a/fs/zipfs/CMakeLists.txt b/fs/zipfs/CMakeLists.txt index 6afe79f73b7..bb4375454c5 100644 --- a/fs/zipfs/CMakeLists.txt +++ b/fs/zipfs/CMakeLists.txt @@ -14,7 +14,7 @@ # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations under # the License. #
