List directory entries

[cceckman]

As far as I can tell (maybe I'm missing it-- sorry!) there's no way to go from a handle to a directory and list its contents.

As the motivating example here: if I wanted to make a basic "serve files to Web" server, I want to start at the "files from this directory" root, and generate an index page of all the files / subdirectories. pathrs would be a great way to do all this safely, without exposing myself to .. paths.

But it seems like I still have to drop back to std::fs to list the entries? (Again, if I'm just missing this in the API surface, sorry!)

---

It seems like this can be done more-or-less safely:

• getdents syscall to get directory entries
• Construct a Handle based on the parent directory's FD for each name returned

The race "may be deleted after the Handle is constructed" applies; but if I understand correctly, that's true of any Handle.

[cyphar]

I did want to add something like that, but for the most part it would just be shorthand for stuff callers could do with an open_subpath(O_DIRECTORY) handle.

There are two issues:

1. For the Rust API, it seems that returning an iterator of directory entries without cloning the file descriptor requires some HKT features not yet present in Rust (IIRC it requires GAT?). If you look at what rustix does in their directory iterator implementation, they implicitly clone the file descriptor. I explain a bit more about the issue in root/handle: readdir wrappers? #110 (which this issue is kind of a duplicate of), and I really didn't want to enshrine a suboptimal API.
2. More generally, it's unclear to me what the right C API would be for this.

• For the directory name listing we could reimplement getdirents semantics, but those a) suck; and b) are already implemented for generic file descriptor objects in most languages (such as (*os.File).Getdirnames in Go), making us writing our own wrapper kinda needless work.
• For the fd-based iterator there is a more obvious justification, but that one is even harder to figure out a same API for. We could fill an array with fds but that runs the risk of exhausting RLIMIT_NOFILE and file descriptor leaks become very easy to do by accident. You could do a cookie-based pull iterator but that would require more annoying leaking of structures and would be quite inefficient when doing FFI.

In short, I've wanted to add something like this for a while but it's unclear to me what a reasonable API would look like for it.

At the moment, the best thing you can do is open_subpath(O_DIRECTORY) then iterate over directory entries. I have example code for this in src/utils/dir.rs (see the remove_all implementation) though it uses raw fds -- you could use Root and Handle but it'll be less efficient for basically no extra security.