Zephyr OS Directory Enumeration: Check the Entry Name Before Treating Zero as Another File

A zero return from fs_readdir() does not always mean that another directory entry was produced. Zephyr OS uses the same successful return for a valid entry and for the end of the directory. The entry name distinguishes those outcomes.

That small contract difference can break a device file browser, removable-media importer or log exporter ported from a different filesystem API. The following review targets Zephyr v4.4.0 and separates a completed listing from a listing interrupted by an error. It does not report a hardware test.

Use both outputs of the operation

The tagged filesystem interface specifies zero for both success and end-of-directory. At the end, entry.name[0] is zero. Negative values identify failures. The directory object must be initialized before opening and closed after use.

The decision order should therefore be: handle a negative result, then stop normally if the name is empty, and otherwise process the entry. A loop that runs while the result equals zero without inspecting the name can continue past normal completion. A loop that expects a positive entry count can stop before displaying any file.

For a hypothetical export screen, these bugs have different symptoms. One can repeatedly append an empty row; the other can show an empty list despite files being present. Neither symptom proves that the storage medium was erased or that its filesystem is corrupt.

Do not reuse entry fields after an error or end marker

Treat the entry structure as usable only after the result and name checks have accepted it. The type and size belong to that accepted entry, not to a separate durable listing record. Copy the fields the application needs before the next iteration overwrites the structure.

Avoid showing a previous filename as if it were a fresh result after a failed read. For an importer, a stale name could also cause duplicate processing. Keep progress information distinct from the directory-entry output so the UI can say that some entries were found before the listing failed.

This is especially important when building a list incrementally. A partial list may be useful, but it should not silently become a complete inventory. The product needs a deliberate policy for retrying or discarding that partial view.

Account for the abstraction layer

The versioned filesystem core skips the special directory entries dot and dot-dot when they are returned by a mounted backend. Applications should not depend on receiving those entries to implement parent-directory navigation.

The virtual root has its own enumeration path over mounted filesystems. It returns an empty name when there is no next entry. If the mount-list entry being tracked has disappeared before a later call, the implementation can return -ENOENT. That is different from an ordinary end marker.

For a removable-media browser, coordinate mount changes with listing operations and preserve the distinction in the interface. If media disappears mid-list, display an interrupted or unavailable state rather than a convincing but incomplete snapshot of the directory.

Exercise the loop with revealing cases

Use an empty directory, a directory with one ordinary file and a directory with several entries. Check that the empty case exits once, the one-file case processes exactly one accepted name, and the multi-entry case terminates when the name becomes empty.

Then exercise a controlled listing failure, including the virtual-root mount-change case if the product permits dynamic mounting. Confirm that cleanup occurs for a successfully opened directory and that a failure is not reported as a normal complete listing.

Finally, keep ordering assumptions out of the reader loop unless the selected backend explicitly guarantees them. Sorting and stable pagination are application concerns. First obtain valid entries using the actual return contract; only then build the view the user sees.