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

Reply via email to