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 e2b3e27f7caeb4def036343d39119f2e59e77672
Author: tengshuangshuang <[email protected]>
AuthorDate: Wed Nov 18 11:00:24 2026 +0800

    fs/zipfs: Add the function headers.
    
    Add the function headers that the NuttX coding standard asks for to the
    functions of zip_vfs.c and wzip_vfs.c: Name, Description, Input Parameters 
and
    Returned Value, and Assumptions/Limitations where there is something to 
know.
    Some of the functions had no header, and the others had only some sections.
    
    Only comments change.
    
    Assisted-by: Claude Code:claude-sonnet-5.5
    Signed-off-by: tengshuangshuang <[email protected]>
---
 fs/zipfs/wzip_vfs.c | 271 ++++++++++++++++++++++++++++++----
 fs/zipfs/zip_vfs.c  | 411 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 657 insertions(+), 25 deletions(-)

diff --git a/fs/zipfs/wzip_vfs.c b/fs/zipfs/wzip_vfs.c
index 4f80cb5f617..1597423807f 100644
--- a/fs/zipfs/wzip_vfs.c
+++ b/fs/zipfs/wzip_vfs.c
@@ -134,6 +134,23 @@ const struct mountpt_operations g_wzipfs_operations =
  * Private Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: wzipfs_convert_result
+ *
+ * Description:
+ *   Convert a libarchive return code to a negated errno value. ARCHIVE_RETRY
+ *   becomes -EAGAIN, ARCHIVE_WARN becomes -ENOEXEC, ARCHIVE_FAILED becomes
+ *   -EINVAL and ARCHIVE_FATAL becomes -EPERM. Any other value, such as
+ *   ARCHIVE_OK, ARCHIVE_EOF or a byte count, is returned unchanged.
+ *
+ * Input Parameters:
+ *   ret - The value that a libarchive function returned.
+ *
+ * Returned Value:
+ *   The negated errno value for a libarchive error, otherwise ret.
+ *
+ ****************************************************************************/
+
 static int wzipfs_convert_result(int ret)
 {
   switch (ret)
@@ -156,12 +173,27 @@ static int wzipfs_convert_result(int ret)
  * Name: wzipfs_parse_options
  *
  * Description:
- *   Parse a NuttX mount "-o" options string.
- *   Accepted keys: src=<path>, fd=<N>, method=store|deflate.
- *   Legacy positional path (no '=' and no ',') is accepted as src.
- *   src= and fd= are mutually exclusive.
+ *   Parse the mount option string. The accepted options are src=<path>,
+ *   fd=<N> and method=store|deflate, separated by commas. A string without =
+ *   and , is accepted as the path of the backing target, as src=. One of
+ *   src= and fd= is required, and they exclude each other.
+ *
+ * Input Parameters:
+ *   data    - The mount option string.
+ *   src     - Buffer to return the path of the backing target. It is empty
+ *             when fd= is used.
+ *   len     - Size of the buffer src.
+ *   fd      - Location to return the file descriptor number of fd=, or -1.
+ *   deflate - Location to return true for method=deflate, otherwise false.
+ *
+ * Returned Value:
+ *   Zero on success. -ENODEV if data is NULL or empty, or if neither src=
+ *   nor fd= is given. -ENAMETOOLONG if a path without src= does not fit in
+ *   src. -EINVAL if src= does not fit in src, the value of fd= is not valid,
+ *   the method or the option is unknown, or both src= and fd= are given.
+ *   -ENOTSUP for method=deflate when CONFIG_FS_ZIPFS_WRITE_DEFLATE is not
+ *   set.
  *
- * Returns 0 on success, negative errno on failure.
  ****************************************************************************/
 
 static int wzipfs_parse_options(FAR const void *data,
@@ -269,6 +301,23 @@ static int wzipfs_parse_options(FAR const void *data,
   return 0;
 }
 
+/****************************************************************************
+ * Name: wzipfs_write_cb
+ *
+ * Description:
+ *   libarchive write callback. Write the data to the backing file.
+ *
+ * Input Parameters:
+ *   a           - The libarchive handle. Not used.
+ *   client_data - The struct wzipfs_priv_s of the mount.
+ *   buff        - The data to write.
+ *   len         - Number of bytes to write.
+ *
+ * Returned Value:
+ *   The number of bytes written, or the negated errno value of file_write().
+ *
+ ****************************************************************************/
+
 static la_ssize_t wzipfs_write_cb(FAR struct archive *a,
                                   FAR void *client_data,
                                   FAR const void *buff,
@@ -282,10 +331,23 @@ static la_ssize_t wzipfs_write_cb(FAR struct archive *a,
 /****************************************************************************
  * Name: wzipfs_init_entry
  *
- * Prepare the reusable archive_entry in priv->entry for a header write.
- * Size is intentionally left unset: for regular files this triggers the
- * streaming (data descriptor) write path; for directories the ZIP writer
- * forces size to 0 internally.
+ * Description:
+ *   Prepare the reusable archive_entry in priv->entry for a header write:
+ *   set the name, the mode, the modification time (now) and the file type,
+ *   which is a directory if mode is a directory and a regular file
+ *   otherwise. The size is left unset on purpose: for a regular file this
+ *   selects the streaming (data descriptor) write of libarchive, and for a
+ *   directory the ZIP writer sets the size to 0.
+ *
+ * Input Parameters:
+ *   priv - The state of the mount.
+ *   path - Name of the entry. The name of a directory ends with /.
+ *   mode - File type and permission bits, S_IFREG or S_IFDIR with the
+ *          permissions.
+ *
+ * Returned Value:
+ *   None.
+ *
  ****************************************************************************/
 
 static void wzipfs_init_entry(FAR struct wzipfs_priv_s *priv,
@@ -302,16 +364,24 @@ static void wzipfs_init_entry(FAR struct wzipfs_priv_s 
*priv,
 /****************************************************************************
  * Name: wzipfs_create_backing
  *
- * Open the backing target.  Accepted cases:
- *   - backing does not exist (ENOENT)    -- create new regular file
- *   - backing is a FIFO or socket        -- stream unconditionally
- *   - backing is a regular file of zero size -- create fresh archive
+ * Description:
+ *   Open the backing target for writing, and create it if it does not exist.
+ *   A regular file must be empty: one with a size greater than zero is
+ *   rejected. Any other target, such as a FIFO or a socket, is used without
+ *   a check. On failure the backing file is closed.
  *
- * Rejected cases:
- *   - regular file with st_size > 0      -- returns -EEXIST
+ * Input Parameters:
+ *   priv - The state of the mount. priv->backing is opened.
+ *   src  - Path of the backing target.
+ *
+ * Returned Value:
+ *   Zero on success, -EEXIST for a regular file that is not empty, or the
+ *   negated errno value of file_open() or file_fstat().
+ *
+ * Assumptions/Limitations:
+ *   To replace an existing archive, remove or truncate the backing file
+ *   before mounting.
  *
- * Callers that want to replace an existing archive should unlink/truncate
- * the backing file before mounting.
  ****************************************************************************/
 
 static int wzipfs_create_backing(FAR struct wzipfs_priv_s *priv,
@@ -348,8 +418,24 @@ static int wzipfs_create_backing(FAR struct wzipfs_priv_s 
*priv,
 /****************************************************************************
  * Name: wzipfs_create_archive
  *
- * Allocate the libarchive writer + reusable entry, set mount-time
- * compression method, and open the write stream onto priv->backing.
+ * Description:
+ *   Create the libarchive writer and the reusable archive_entry, select the
+ *   zip format with UTF-8 names, select the compression of the whole mount,
+ *   and open the write stream on priv->backing. libarchive uses DEFLATE when
+ *   it is not told otherwise and zlib is built in, so STORE is selected
+ *   explicitly.
+ *
+ * Input Parameters:
+ *   priv    - The state of the mount. priv->a and priv->entry are set.
+ *   deflate - True to compress with DEFLATE, false to store. DEFLATE needs
+ *             CONFIG_FS_ZIPFS_WRITE_DEFLATE.
+ *
+ * Returned Value:
+ *   Zero on success, -ENOMEM if memory runs out, -ENOTSUP for DEFLATE
+ *   without CONFIG_FS_ZIPFS_WRITE_DEFLATE, or the negated errno value
+ *   converted from a libarchive error. On failure the writer and the entry
+ *   are freed and priv->a and priv->entry are NULL.
+ *
  ****************************************************************************/
 
 static int wzipfs_create_archive(FAR struct wzipfs_priv_s *priv,
@@ -446,6 +532,26 @@ err:
 
 /****************************************************************************
  * Name: wzipfs_open
+ *
+ * Description:
+ *   Start a new entry of the archive. Only one file can be open for writing
+ *   at a time: this function waits until the previous file is closed. The
+ *   header of the entry is written with archive_write_header(). The file
+ *   must be opened for writing with O_CREAT.
+ *
+ * Input Parameters:
+ *   filep   - The file structure. The state of the mount is in the i_private
+ *             field of its inode.
+ *   relpath - Name of the entry, relative to the mount point.
+ *   oflags  - Open flags.
+ *   mode    - Permission bits of the entry.
+ *
+ * Returned Value:
+ *   Zero on success. -EACCES if the file is opened read only, -ENOSYS if
+ *   O_CREAT is not set, -EINVAL if relpath is empty, or the negated errno
+ *   value of the wait or of writing the header. If writing the header fails,
+ *   the lock is released before the function returns.
+ *
  ****************************************************************************/
 
 static int wzipfs_open(FAR struct file *filep, FAR const char *relpath,
@@ -491,6 +597,18 @@ static int wzipfs_open(FAR struct file *filep, FAR const 
char *relpath,
 
 /****************************************************************************
  * Name: wzipfs_close
+ *
+ * Description:
+ *   Finish the current entry with archive_write_finish_entry() and release
+ *   the lock that wzipfs_open() took, so that the next file can be opened.
+ *
+ * Input Parameters:
+ *   filep - The file structure.
+ *
+ * Returned Value:
+ *   Zero on success, otherwise the negated errno value converted from a
+ *   libarchive error. The lock is released in both cases.
+ *
  ****************************************************************************/
 
 static int wzipfs_close(FAR struct file *filep)
@@ -510,6 +628,22 @@ static int wzipfs_close(FAR struct file *filep)
 
 /****************************************************************************
  * Name: wzipfs_write
+ *
+ * Description:
+ *   Append data to the current entry with archive_write_data(). libarchive
+ *   collects what the zip writer produces in blocks (10240 bytes by default)
+ *   and calls wzipfs_write_cb() for each full block, so the data reaches the
+ *   backing target block by block. The rest is written when the archive is
+ *   closed at unmount.
+ *
+ * Input Parameters:
+ *   filep  - The file structure.
+ *   buffer - The data to write.
+ *   buflen - Number of bytes to write.
+ *
+ * Returned Value:
+ *   The number of bytes written, or a negated errno value.
+ *
  ****************************************************************************/
 
 static ssize_t wzipfs_write(FAR struct file *filep,
@@ -531,10 +665,18 @@ static ssize_t wzipfs_write(FAR struct file *filep,
 /****************************************************************************
  * Name: wzipfs_sync
  *
- * Flush the backing file.  Only the bytes already emitted by libarchive
- * (through the write callback) are guaranteed to be persisted; libarchive
- * retains its own block buffer internally with no public flush hook, so
- * data descriptors for an in-progress entry may still be pending in RAM.
+ * Description:
+ *   Flush the backing file with file_fsync(). Only the bytes that libarchive
+ *   already passed to the write callback are persisted. libarchive keeps its
+ *   own block buffer and has no public way to flush it, so the data
+ *   descriptors of an entry that is being written can still be in memory.
+ *
+ * Input Parameters:
+ *   filep - The file structure.
+ *
+ * Returned Value:
+ *   Zero on success, otherwise the negated errno value of file_fsync().
+ *
  ****************************************************************************/
 
 static int wzipfs_sync(FAR struct file *filep)
@@ -546,6 +688,29 @@ static int wzipfs_sync(FAR struct file *filep)
 
 /****************************************************************************
  * Name: wzipfs_bind
+ *
+ * Description:
+ *   Mount: parse the options, allocate the state of the mount, and open the
+ *   backing target. With fd=, the file descriptor is duplicated into the
+ *   state of the mount, and with src= the path is opened with
+ *   wzipfs_create_backing(). Then the libarchive writer is created with
+ *   wzipfs_create_archive(). No block driver is used.
+ *
+ * Input Parameters:
+ *   driver - Not used.
+ *   data   - The mount option string, see wzipfs_parse_options().
+ *   handle - Location to return the state of the mount.
+ *
+ * Returned Value:
+ *   Zero on success, otherwise a negated errno value: an error of
+ *   wzipfs_parse_options(), -ENOMEM, an error of file_get() or file_dup2()
+ *   for fd=, or an error of wzipfs_create_backing() or
+ *   wzipfs_create_archive(). On failure the state of the mount is freed.
+ *
+ * Assumptions/Limitations:
+ *   With fd=, the caller keeps its own file descriptor and has to keep it
+ *   open until the file system is unmounted.
+ *
  ****************************************************************************/
 
 static int wzipfs_bind(FAR struct inode *driver, FAR const void *data,
@@ -607,6 +772,21 @@ err:
 
 /****************************************************************************
  * Name: wzipfs_unbind
+ *
+ * Description:
+ *   Unmount: close the archive with archive_write_close(), which writes the
+ *   central directory, free the writer and the entry, close the backing
+ *   file, and free the state of the mount.
+ *
+ * Input Parameters:
+ *   handle - The state of the mount that wzipfs_bind() returned.
+ *   driver - Not used.
+ *   flags  - Not used.
+ *
+ * Returned Value:
+ *   Zero on success, or the negated errno value converted from the error of
+ *   archive_write_close(). The resources are released in both cases.
+ *
  ****************************************************************************/
 
 static int wzipfs_unbind(FAR void *handle, FAR struct inode **driver,
@@ -643,6 +823,18 @@ static int wzipfs_unbind(FAR void *handle, FAR struct 
inode **driver,
 
 /****************************************************************************
  * Name: wzipfs_statfs
+ *
+ * Description:
+ *   Return information about the file system: the structure is cleared,
+ *   f_type is set to ZIPFS_MAGIC and f_namelen to NAME_MAX.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. Not used.
+ *   buf     - Location to return the information.
+ *
+ * Returned Value:
+ *   Zero always.
+ *
  ****************************************************************************/
 
 static int wzipfs_statfs(FAR struct inode *mountpt,
@@ -656,6 +848,25 @@ static int wzipfs_statfs(FAR struct inode *mountpt,
 
 /****************************************************************************
  * Name: wzipfs_mkdir
+ *
+ * Description:
+ *   Add a directory entry to the archive. The name is relpath followed by /,
+ *   and its header is written and finished at once.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. The state of the mount is in its
+ *             i_private field.
+ *   relpath - Name of the directory, relative to the mount point.
+ *   mode    - Permission bits of the directory.
+ *
+ * Returned Value:
+ *   Zero on success, -EINVAL if relpath is empty or too long, otherwise the
+ *   negated errno value converted from a libarchive error.
+ *
+ * Assumptions/Limitations:
+ *   It does not take the lock that wzipfs_open() takes. Call it only when no
+ *   file of the mount is open for writing.
+ *
  ****************************************************************************/
 
 static int wzipfs_mkdir(FAR struct inode *mountpt,
@@ -700,8 +911,18 @@ static int wzipfs_mkdir(FAR struct inode *mountpt,
  * Name: wzipfs_stat
  *
  * Description:
- *   Minimal stat for wzipfs. Always reports path as a writable directory
- *   so that rpmsgfs can verify the mount root without blocking.
+ *   Minimal stat of wzipfs: whatever the path is, report a directory with
+ *   mode 0755, so that rpmsgfs can verify the root of the mount without
+ *   blocking. wzipfs does not keep information about the entries that were
+ *   written.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. Not used.
+ *   relpath - Not used.
+ *   buf     - Location to return the stat. It is cleared first.
+ *
+ * Returned Value:
+ *   Zero always.
  *
  ****************************************************************************/
 
diff --git a/fs/zipfs/zip_vfs.c b/fs/zipfs/zip_vfs.c
index 96c1ff002cb..17ae2a4ce5f 100644
--- a/fs/zipfs/zip_vfs.c
+++ b/fs/zipfs/zip_vfs.c
@@ -153,6 +153,23 @@ const struct mountpt_operations g_zipfs_operations =
  * Private Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: zipfs_convert_result
+ *
+ * Description:
+ *   Convert a libarchive return code to a negated errno value. ARCHIVE_RETRY
+ *   becomes -EAGAIN, ARCHIVE_WARN becomes -ENOEXEC, ARCHIVE_FAILED becomes
+ *   -EINVAL and ARCHIVE_FATAL becomes -EPERM. Any other value, such as
+ *   ARCHIVE_OK, ARCHIVE_EOF or a byte count, is returned unchanged.
+ *
+ * Input Parameters:
+ *   ret - The value that a libarchive function returned.
+ *
+ * Returned Value:
+ *   The negated errno value for a libarchive error, otherwise ret.
+ *
+ ****************************************************************************/
+
 static int zipfs_convert_result(int ret)
 {
   switch (ret)
@@ -171,6 +188,21 @@ static int zipfs_convert_result(int ret)
     }
 }
 
+/****************************************************************************
+ * Name: zipfs_close_cb
+ *
+ * Description:
+ *   libarchive close callback. Close the zip file that the reader reads.
+ *
+ * Input Parameters:
+ *   a           - The libarchive handle. Not used.
+ *   client_data - The struct zipfs_priv_s of the reader.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, otherwise the negated errno value of file_close().
+ *
+ ****************************************************************************/
+
 static int zipfs_close_cb(FAR struct archive *a, FAR void *client_data)
 {
   FAR struct zipfs_priv_s *priv = client_data;
@@ -178,6 +210,25 @@ static int zipfs_close_cb(FAR struct archive *a, FAR void 
*client_data)
   return file_close(&priv->file);
 }
 
+/****************************************************************************
+ * Name: zipfs_read_cb
+ *
+ * Description:
+ *   libarchive read callback. Read the next block of the zip file, at most
+ *   CONFIG_FS_ZIPFS_BUFFER_SIZE bytes, into the buffer of the reader.
+ *
+ * Input Parameters:
+ *   a           - The libarchive handle. Not used.
+ *   client_data - The struct zipfs_priv_s of the reader.
+ *   buff        - Location to return a pointer to the data that was read. It
+ *                 is set only when data was read.
+ *
+ * Returned Value:
+ *   The number of bytes read, zero at the end of the zip file, or the
+ *   negated errno value of file_read().
+ *
+ ****************************************************************************/
+
 static la_ssize_t zipfs_read_cb(FAR struct archive *a,
                                 FAR void *client_data,
                                 FAR const void **buff)
@@ -196,6 +247,24 @@ static la_ssize_t zipfs_read_cb(FAR struct archive *a,
   return ret;
 }
 
+/****************************************************************************
+ * Name: zipfs_seek_cb
+ *
+ * Description:
+ *   libarchive seek callback. Set the position in the zip file.
+ *
+ * Input Parameters:
+ *   a           - The libarchive handle. Not used.
+ *   client_data - The struct zipfs_priv_s of the reader.
+ *   offset      - The new position, relative to whence.
+ *   whence      - SEEK_SET, SEEK_CUR or SEEK_END.
+ *
+ * Returned Value:
+ *   The new position in the zip file, or the negated errno value of
+ *   file_seek().
+ *
+ ****************************************************************************/
+
 static la_int64_t zipfs_seek_cb(FAR struct archive *a,
                                 FAR void *client_data,
                                 la_int64_t offset, int whence)
@@ -205,6 +274,27 @@ static la_int64_t zipfs_seek_cb(FAR struct archive *a,
   return file_seek(&priv->file, offset, whence);
 }
 
+/****************************************************************************
+ * Name: zipfs_skip
+ *
+ * Description:
+ *   Skip data of the current entry by reading and discarding it. The data is
+ *   read in blocks of CONFIG_FS_ZIPFS_BUFFER_SIZE bytes into a buffer that
+ *   is allocated on the first call and freed by zipfs_free().
+ *
+ * Input Parameters:
+ *   priv   - The reader, positioned in the data of an entry.
+ *   amount - The number of bytes to skip.
+ *
+ * Returned Value:
+ *   The number of bytes skipped. It is less than amount when the data ends
+ *   or a read fails after some bytes were skipped. If no byte was skipped,
+ *   the value is zero at the end of the data, -ENOMEM if the buffer cannot
+ *   be allocated, or the negated errno value converted from a libarchive
+ *   error.
+ *
+ ****************************************************************************/
+
 static off_t zipfs_skip(FAR struct zipfs_priv_s *priv, off_t amount)
 {
   off_t next = 0;
@@ -240,6 +330,34 @@ static off_t zipfs_skip(FAR struct zipfs_priv_s *priv, 
off_t amount)
   return next;
 }
 
+/****************************************************************************
+ * Name: zipfs_new
+ *
+ * Description:
+ *   Open the zip file with libarchive and create a reader for it. The
+ *   archive formats that are selected with CONFIG_FS_ZIPFS_FORMAT_* are
+ *   enabled. If relpath is NULL, the reader is returned before the first
+ *   entry, which is how a directory is read. Otherwise the entries are read
+ *   until one has the name relpath, and the reader is returned positioned in
+ *   the data of that entry.
+ *
+ * Input Parameters:
+ *   abspath - Path of the zip file.
+ *   relpath - Name of the entry to find, as it is stored in the archive, or
+ *             NULL.
+ *   priv    - Location to return the reader.
+ *
+ * Returned Value:
+ *   Zero (OK) on success. -ENOMEM if memory runs out, -ENOENT if no entry
+ *   has the name relpath (also when reading the archive fails during the
+ *   search), or the negated errno value of file_open() or of a libarchive
+ *   function.
+ *
+ * Assumptions/Limitations:
+ *   The caller releases the reader with zipfs_free().
+ *
+ ****************************************************************************/
+
 int zipfs_new(FAR const char *abspath, FAR const char *relpath,
               FAR struct zipfs_priv_s **priv)
 {
@@ -474,6 +592,21 @@ err_with_priv:
   return ret;
 }
 
+/****************************************************************************
+ * Name: zipfs_free
+ *
+ * Description:
+ *   Release a reader: the skip buffer, the current entry, the libarchive
+ *   handle (which closes the zip file), the mutex and the structure itself.
+ *
+ * Input Parameters:
+ *   priv - The reader that zipfs_new() returned.
+ *
+ * Returned Value:
+ *   None.
+ *
+ ****************************************************************************/
+
 static void zipfs_free(FAR struct zipfs_priv_s *priv)
 {
   if (priv->seekbuf != NULL)
@@ -488,6 +621,21 @@ static void zipfs_free(FAR struct zipfs_priv_s *priv)
   fs_heap_free(priv);
 }
 
+/****************************************************************************
+ * Name: zipfs_stats_common
+ *
+ * Description:
+ *   Copy the stat of the current entry of the reader.
+ *
+ * Input Parameters:
+ *   priv - The reader, positioned on an entry.
+ *   buf  - Location to return the stat.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -EINVAL if libarchive has no stat for the entry.
+ *
+ ****************************************************************************/
+
 static int zipfs_stats_common(FAR struct zipfs_priv_s *priv,
                               FAR struct stat *buf)
 {
@@ -506,6 +654,26 @@ static int zipfs_stats_common(FAR struct zipfs_priv_s 
*priv,
  * Zipfs methods
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: zipfs_open
+ *
+ * Description:
+ *   Open a file of the archive. A new reader is created with zipfs_new() and
+ *   is kept in the f_priv field of the file structure.
+ *
+ * Input Parameters:
+ *   filep   - The file structure. The path of the zip file is in the
+ *             i_private field of its inode.
+ *   relpath - Name of the entry, relative to the mount point.
+ *   oflags  - Not used.
+ *   mode    - Not used.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, otherwise the negated errno value of zipfs_new(),
+ *   for example -ENOENT if the archive has no entry with that name.
+ *
+ ****************************************************************************/
+
 static int zipfs_open(FAR struct file *filep, FAR const char *relpath,
                       int oflags, mode_t mode)
 {
@@ -523,6 +691,20 @@ static int zipfs_open(FAR struct file *filep, FAR const 
char *relpath,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_close
+ *
+ * Description:
+ *   Close a file: release its reader with zipfs_free().
+ *
+ * Input Parameters:
+ *   filep - The file structure.
+ *
+ * Returned Value:
+ *   Zero (OK) always.
+ *
+ ****************************************************************************/
+
 static int zipfs_close(FAR struct file *filep)
 {
   FAR struct zipfs_priv_s *priv = filep->f_priv;
@@ -531,6 +713,25 @@ static int zipfs_close(FAR struct file *filep)
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_read
+ *
+ * Description:
+ *   Read data of an open file. Up to buflen bytes of the current entry are
+ *   read with archive_read_data(), and the file position is advanced by the
+ *   number of bytes read. The reader is locked.
+ *
+ * Input Parameters:
+ *   filep  - The file structure.
+ *   buffer - Location to return the data.
+ *   buflen - Maximum number of bytes to read.
+ *
+ * Returned Value:
+ *   The number of bytes read, zero at the end of the entry, or a negated
+ *   errno value.
+ *
+ ****************************************************************************/
+
 static ssize_t zipfs_read(FAR struct file *filep, FAR char *buffer,
                           size_t buflen)
 {
@@ -548,6 +749,27 @@ static ssize_t zipfs_read(FAR struct file *filep, FAR char 
*buffer,
   return ret;
 }
 
+/****************************************************************************
+ * Name: zipfs_seek
+ *
+ * Description:
+ *   Set the position of an open file. A libarchive reader only moves
+ *   forward, so a forward seek reads and discards data with zipfs_skip(),
+ *   and a backward seek creates a new reader for the same entry and skips
+ *   from its beginning. SEEK_END is relative to the size of the entry.
+ *
+ * Input Parameters:
+ *   filep  - The file structure.
+ *   offset - The new position, relative to whence.
+ *   whence - SEEK_SET, SEEK_CUR or SEEK_END.
+ *
+ * Returned Value:
+ *   The new file position, or a negated errno value: -EINVAL for another
+ *   value of whence, or an error of zipfs_new() or zipfs_skip(). If a new
+ *   reader cannot be created, the old one is kept.
+ *
+ ****************************************************************************/
+
 static off_t zipfs_seek(FAR struct file *filep, off_t offset,
                         int whence)
 {
@@ -606,6 +828,23 @@ err_with_lock:
   return ret < 0 ? ret : filep->f_pos;
 }
 
+/****************************************************************************
+ * Name: zipfs_dup
+ *
+ * Description:
+ *   Duplicate an open file. The entry of oldp is opened again with
+ *   zipfs_open(), so newp has its own reader that starts at the beginning of
+ *   the entry.
+ *
+ * Input Parameters:
+ *   oldp - The file structure to duplicate.
+ *   newp - The new file structure.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, otherwise the negated errno value of zipfs_open().
+ *
+ ****************************************************************************/
+
 static int zipfs_dup(FAR const struct file *oldp, FAR struct file *newp)
 {
   FAR struct zipfs_priv_s *priv = oldp->f_priv;
@@ -614,6 +853,21 @@ static int zipfs_dup(FAR const struct file *oldp, FAR 
struct file *newp)
   return zipfs_open(newp, relpath, oldp->f_oflags, 0);
 }
 
+/****************************************************************************
+ * Name: zipfs_fstat
+ *
+ * Description:
+ *   Return information about an open file: the stat of its entry.
+ *
+ * Input Parameters:
+ *   filep - The file structure.
+ *   buf   - Location to return the stat.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -EINVAL if libarchive has no stat for the entry.
+ *
+ ****************************************************************************/
+
 static int zipfs_fstat(FAR const struct file *filep,
                        FAR struct stat *buf)
 {
@@ -622,6 +876,30 @@ static int zipfs_fstat(FAR const struct file *filep,
   return zipfs_stats_common(priv, buf);
 }
 
+/****************************************************************************
+ * Name: zipfs_opendir
+ *
+ * Description:
+ *   Open a directory. A reader positioned before the first entry of the
+ *   archive is created with zipfs_new() and is kept in a new directory
+ *   structure.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. The path of the zip file is in its
+ *             i_private field.
+ *   relpath - Not used.
+ *   dir     - Location to return the directory structure.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -ENOMEM if memory runs out, or the negated errno
+ *   value of zipfs_new().
+ *
+ * Assumptions/Limitations:
+ *   relpath is not used: every directory lists all the entries of the
+ *   archive, with their full names, whichever directory is opened.
+ *
+ ****************************************************************************/
+
 static int zipfs_opendir(FAR struct inode *mountpt,
                          FAR const char *relpath,
                          FAR struct fs_dirent_s **dir)
@@ -647,6 +925,21 @@ static int zipfs_opendir(FAR struct inode *mountpt,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_closedir
+ *
+ * Description:
+ *   Close a directory: release its reader and the directory structure.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode.
+ *   dir     - The directory structure that zipfs_opendir() returned.
+ *
+ * Returned Value:
+ *   Zero (OK) always.
+ *
+ ****************************************************************************/
+
 static int zipfs_closedir(FAR struct inode *mountpt,
                           FAR struct fs_dirent_s *dir)
 {
@@ -657,6 +950,26 @@ static int zipfs_closedir(FAR struct inode *mountpt,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_readdir
+ *
+ * Description:
+ *   Read the next entry of the archive. The next header is read with
+ *   archive_read_next_header2(), and the full name of the entry is copied to
+ *   the d_name field of entry, truncated if it does not fit. The reader is
+ *   locked.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode.
+ *   dir     - The directory structure that zipfs_opendir() returned.
+ *   entry   - Location to return the directory entry.
+ *
+ * Returned Value:
+ *   Zero (OK) when an entry was returned, EOF (-1) at the end of the
+ *   archive, or a negated errno value when reading the archive fails.
+ *
+ ****************************************************************************/
+
 static int zipfs_readdir(FAR struct inode *mountpt,
                          FAR struct fs_dirent_s *dir,
                          FAR struct dirent *entry)
@@ -686,6 +999,27 @@ err:
   return ret;
 }
 
+/****************************************************************************
+ * Name: zipfs_rewinddir
+ *
+ * Description:
+ *   Replace the current entry of the reader of a directory with a new, empty
+ *   one.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode.
+ *   dir     - The directory structure that zipfs_opendir() returned.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -ENOMEM if the new entry cannot be allocated.
+ *
+ * Assumptions/Limitations:
+ *   The libarchive reader is not moved, because it only moves forward and no
+ *   new reader is created here. The next zipfs_readdir() continues after the
+ *   entries that were already returned.
+ *
+ ****************************************************************************/
+
 static int zipfs_rewinddir(FAR struct inode *mountpt,
                            FAR struct fs_dirent_s *dir)
 {
@@ -705,6 +1039,22 @@ static int zipfs_rewinddir(FAR struct inode *mountpt,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_statfs
+ *
+ * Description:
+ *   Return information about the file system: f_type is set to ZIPFS_MAGIC
+ *   and f_namelen to NAME_MAX. The other fields are not changed.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. Not used.
+ *   buf     - Location to return the information.
+ *
+ * Returned Value:
+ *   Zero (OK) always.
+ *
+ ****************************************************************************/
+
 static int zipfs_statfs(FAR struct inode *mountpt,
                         FAR struct statfs *buf)
 {
@@ -713,6 +1063,31 @@ static int zipfs_statfs(FAR struct inode *mountpt,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_stat
+ *
+ * Description:
+ *   Return information about a path. For the root of the mount point, an
+ *   empty relpath, the result is a directory with mode 0555, and only
+ *   st_mode is set. For any other path the entry is looked up with
+ *   zipfs_new() and its stat is returned.
+ *
+ * Input Parameters:
+ *   mountpt - The mountpoint inode. The path of the zip file is in its
+ *             i_private field.
+ *   relpath - Name of the entry, relative to the mount point.
+ *   buf     - Location to return the stat.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -EINVAL if libarchive has no stat for the entry,
+ *   otherwise the negated errno value of zipfs_new(), for example -ENOENT.
+ *
+ * Assumptions/Limitations:
+ *   relpath must be equal to the name stored in the archive. A directory is
+ *   stored with a trailing /, and it is not found without it.
+ *
+ ****************************************************************************/
+
 static int zipfs_stat(FAR struct inode *mountpt,
                       FAR const char *relpath,
                       FAR struct stat *buf)
@@ -738,6 +1113,26 @@ static int zipfs_stat(FAR struct inode *mountpt,
   return ret;
 }
 
+/****************************************************************************
+ * Name: zipfs_bind
+ *
+ * Description:
+ *   Mount a zip file. The zip file is opened once with zipfs_new() to check
+ *   that it can be read, and its path is copied to a new buffer that becomes
+ *   the mount handle. No block driver is used.
+ *
+ * Input Parameters:
+ *   driver - Not used.
+ *   data   - Path of the zip file.
+ *   handle - Location to return the mount handle, which is the copy of the
+ *            path.
+ *
+ * Returned Value:
+ *   Zero (OK) on success, -ENODEV if data is NULL, -ENOMEM if memory runs
+ *   out, or the negated errno value of zipfs_new().
+ *
+ ****************************************************************************/
+
 static int zipfs_bind(FAR struct inode *driver, FAR const void *data,
                       FAR void **handle)
 {
@@ -770,6 +1165,22 @@ static int zipfs_bind(FAR struct inode *driver, FAR const 
void *data,
   return OK;
 }
 
+/****************************************************************************
+ * Name: zipfs_unbind
+ *
+ * Description:
+ *   Unmount: free the mount handle.
+ *
+ * Input Parameters:
+ *   handle - The mount handle that zipfs_bind() returned.
+ *   driver - Not used.
+ *   flags  - Not used.
+ *
+ * Returned Value:
+ *   Zero (OK) always.
+ *
+ ****************************************************************************/
+
 static int zipfs_unbind(FAR void *handle, FAR struct inode **driver,
                         unsigned int flags)
 {

Reply via email to