# File system: best practices

**URL:** <https://ziggit.dev/t/file-system-best-practices/4854>\
**Category:** Explain\
**Tags:** standard-library\
**Created:** [June 24, 2024, 1:05pm UTC](https://ziggit.dev/t/file-system-best-practices/4854 "2024-06-24T13:05:41Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![Durobot](https://ziggit.dev/user_avatar/ziggit.dev/durobot/32/447_2.png) [@Durobot](https://ziggit.dev/u/Durobot)\
**Post date:** [June 24, 2024, 1:05pm UTC](https://ziggit.dev/t/file-system-best-practices/4854/1 "2024-06-24T13:05:42Z")

</div>

I was wondering if there’s a write-up on working with the file system.  
How does one work with directories, files - how are we supposed to do standard operations with them, what are the best practices, etc.

For example, it’s not quite clear to me ATM, how best to pass a directory path to a function which would enumerate and load certain files from it.

If I simply pass it as a string, how do I handle separators if I want my code to be cross-platform? Should I use Path (from std/Build/Cache/Path.zig) instead of a string? Maybe something from std/fs/path.zig ?

The examples I’ve seen don’t give much explanation, they’re just that - short examples. For instance paths in them are just strings, and they don’t include any separators.  
I would love to see something more substantial.

---

<div class="post-metadata">

**Author:** ![dimdin](https://ziggit.dev/user_avatar/ziggit.dev/dimdin/32/1457_2.png) [@dimdin](https://ziggit.dev/u/dimdin)\
**Post date:** [June 24, 2024, 1:51pm UTC](https://ziggit.dev/t/file-system-best-practices/4854/2 "2024-06-24T13:51:33Z")

</div>

> [@Durobot](#):
>
> If I simply pass it as a string, how do I handle separators if I want my code to be cross-platform?

[std.fs.path.delimiter](https://ziglang.org/documentation/master/std/#std.fs.path.delimiter) is the target platform path separator.  
[std.fs.path.join](https://ziglang.org/documentation/master/std/#std.fs.path.join) combines path segments with the separator.

> [@Durobot](#):
>
> Should I use Path (from std/Build/Cache/Path.zig) instead of a string?

No, this path is only for the builder.

* * *

The relative packages are:

- [std.fs.path](https://ziglang.org/documentation/master/std/#std.fs.path) handles paths as strings, without filesystem calls
- [std.fs.Dir](https://ziglang.org/documentation/master/std/#std.fs.Dir) all file and directory operations (mkdir, delete, rename), [walk](https://ziglang.org/documentation/master/std/#std.fs.Dir.walk) that returns a directory [Entry](https://ziglang.org/documentation/master/std/#std.fs.Dir.Walker.Entry) iterator, [createFile](https://ziglang.org/documentation/master/std/#std.fs.Dir.createFile) and [openFile](https://ziglang.org/documentation/master/std/#std.fs.Dir.openFile) that return a file handle.
- [std.fs.File](https://ziglang.org/documentation/master/std/#std.fs.File) read/write operations on file handles

---

<div class="post-metadata">

**Author:** ![Durobot](https://ziggit.dev/user_avatar/ziggit.dev/durobot/32/447_2.png) [@Durobot](https://ziggit.dev/u/Durobot)\
**Post date:** [June 24, 2024, 2:07pm UTC](https://ziggit.dev/t/file-system-best-practices/4854/3 "2024-06-24T14:07:26Z")

</div>

Thank you.

However, if a general post / article / in-depth explanation exists, I would still love to read it, because have other questions too.

For example (and this is just one example), `Dir` is an essential struct if you want to work with files (create, open, etc.).  
In order to create a `Dir` you always start with `std.fs.cwd()`, at least that’s what all the examples show.

But what if I want to use absolute paths and don’t care about current directory? `std.fs.Dir.openDir()` expects an existing `Dir` (`self`), so in order to use it I must have a valid `Dir` first, and `std.fs.cwd()` seems to be the only function that doesn’t need a `Dir` to open a `Dir`.

Which means you MUST always start with `std.fs.cwd()`. Seems strange to me.

I feel that I could benefit greatly if I understood the line of thinking behind the design of this API.

---

<div class="post-metadata">

**Author:** ![ktz\_alias](https://ziggit.dev/user_avatar/ziggit.dev/ktz_alias/32/1202_2.png) [@ktz\_alias](https://ziggit.dev/u/ktz_alias)\
**Post date:** [June 24, 2024, 3:24pm UTC](https://ziggit.dev/t/file-system-best-practices/4854/4 "2024-06-24T15:24:29Z")

</div>

> [@Durobot](#):
>
> But what if I want to use absolute paths and don’t care about current directory? `std.fs.Dir.openDir()` expects an existing `Dir` (`self`), so in order to use it I must have a valid `Dir` first, and `std.fs.cwd()` seems to be the only function that doesn’t need a `Dir` to open a `Dir`.

Even if you want to specify the absolute path, `std.fs.cwd().openXXX` (XXX is Dir or File) is accepted this path, and will return appropriate `std.fs.Dir`.

Consider the following case:  
It calls `ls` with an absolute path from the arbitrary directory.  
File lists of specified absolute path will be list.

I seems to be same result calling `std.fs.cwd().openXXX` by the absolute path.  
I’ve checked this case on MacOS platform.  
Another platform may be different result.

---

<div class="post-metadata">

**Author:** ![squeek502](https://ziggit.dev/user_avatar/ziggit.dev/squeek502/32/409_2.png) [@squeek502](https://ziggit.dev/u/squeek502)\
**Post date:** [June 24, 2024, 4:31pm UTC](https://ziggit.dev/t/file-system-best-practices/4854/5 "2024-06-24T16:31:19Z")

</div>

One random point of clarification since I’ve seen it trip people up:

The APIs in `std.fs.Dir` can handle both relative _and_ absolute paths

> [@Durobot](#):
>
> how do I handle separators if I want my code to be cross-platform

`/` works on every platform if you’re using the `std.fs` APIs (the lower level Windows-specific APIs may need `\`, but the higher level cross-platform APIs will take care of transforming them for you under-the-hood).

> [@Durobot](#):
>
> Which means you MUST always start with `std.fs.cwd()`. Seems strange to me.

By leaning into using `std.fs.Dir`, you get:

- better protection against Time Of Check, Time Of Use bugs
- your code will likely just work when targeting WASI without any extra effort

See [the “Why Dir-based for everything” section of this (closed) proposal](https://github.com/ziglang/zig/issues/16736)

---

<div class="post-metadata">

**Author:** ![Durobot](https://ziggit.dev/user_avatar/ziggit.dev/durobot/32/447_2.png) [@Durobot](https://ziggit.dev/u/Durobot)\
**Post date:** [June 25, 2024, 9:25am UTC](https://ziggit.dev/t/file-system-best-practices/4854/6 "2024-06-25T09:25:12Z")

</div>

> [@squeek502](#):
>
> `/` works on every platform if you’re using the `std.fs` APIs

Is this guaranteed on all platforms, now and in the future, including `WASM` and whatnot? I haven’t seen any discussion of this point, this is why I was asking for a write-up on `fs`.

> [@squeek502](#):
>
> By leaning into using `std.fs.Dir`, you get:

I’m not against using `Dir`, quite the opposite. I just don’t get the reasoning that makes `cwd()` the mandatory part of `Dir` initialization.

What if I want to start with some arbitrary absolute path, why make a reference to the current working directory? Once again, I would love to read about the “why”, not just “how to”.

---

<div class="post-metadata">

**Author:** ![squeek502](https://ziggit.dev/user_avatar/ziggit.dev/squeek502/32/409_2.png) [@squeek502](https://ziggit.dev/u/squeek502)\
**Post date:** [June 25, 2024, 10:09am UTC](https://ziggit.dev/t/file-system-best-practices/4854/7 "2024-06-25T10:09:33Z")

</div>

> [@Durobot](#):
>
> Is this guaranteed on all platforms, now and in the future, including `WASM` and whatnot? I haven’t seen any discussion of this point, this is why I was asking for a write-up on `fs`.

The one platform it likely won’t work on is UEFI but I’m not sure that the `std.fs` API works with UEFI anyway. Every other platform that I’m aware of supports `/` as the path separator, and any cross-platform `std.fs` API not properly handling `/` as a path separator should be treated as a bug IMO.

Note also that `fs/test.zig` actually tests that both `/` and `\` work on Windows as of [this commit](https://github.com/ziglang/zig/commit/f1dd1ee5ed43732a7a671fb438810462136b83eb) (on Windows, all tests that use `testWithAllSupportedPathTypes` are run once with `/` as the separator and again with `\` as the separator).

> [@Durobot](#):
>
> What if I want to start with some arbitrary absolute path, why make a reference to the current working directory? Once again, I would love to read about the “why”, not just “how to”.

If you’d like to avoid going through `cwd`, then you can use one of the `std.fs.<something>Absolute` functions. This point, that users may have reason to avoid `cwd`, is [the reason that those functions exist](https://github.com/ziglang/zig/pull/16743#discussion_r1328058924), but it’s also worth noting that many of the `Absolute` suffixed functions are currently nothing but wrappers around the `Dir` function, so in practical terms you might not actually always avoid the `cwd()` call:

> <https://github.com/ziglang/zig/blob/3e9ab6aa7b2d90c25cb906d425a148abf9da3dcb/lib/std/fs.zig#L280>

Another thing worth noting is that currently, on every platform (including WASI), [`std.fs.cwd()` doesn’t actually make any syscalls by default](https://github.com/ziglang/zig/blob/3e9ab6aa7b2d90c25cb906d425a148abf9da3dcb/lib/std/fs.zig#L255-L263):

- On Windows, a handle to the current directory can be retrieved from the [Process Environment Block](https://en.wikipedia.org/wiki/Process_Environment_Block)
- On POSIX systems, it returns a `Dir` with an `fd` containing a special constant `AT_FDCWD`. The fact that this is not a real fd [can cause problems](https://github.com/ziglang/zig/issues/9688) (and there are bugs if you try to use the return of `cwd()` with certain APIs. How best to handle this is still up in the air)
- On WASI, there is no actual CWD, so by default Zig just returns the fd of the first preopen. If this is not what you want, you can customize the behavior of `cwd()` for WASI via [a root `std_options` decl](https://github.com/ziglang/zig/blob/3e9ab6aa7b2d90c25cb906d425a148abf9da3dcb/lib/std/std.zig#L105-L106) and providing [a `wasiCwd` function](https://github.com/ziglang/zig/blob/3e9ab6aa7b2d90c25cb906d425a148abf9da3dcb/lib/std/std.zig#L111-L112).

This means that a `cwd()` call is effectively free, which makes it a nice common-denominator starting point for the `Dir` APIs, even if the `cwd` doesn’t end up being used (i.e. you’re using an absolute path). If `cwd()` wasn’t a cheap call (or could fail), then it seems pretty likely that `cwd()` calls wouldn’t be so ubiquitous.

---

<div class="post-metadata">

**Author:** ![matklad](https://ziggit.dev/user_avatar/ziggit.dev/matklad/32/2462_2.png) [@matklad](https://ziggit.dev/u/matklad)\
**Post date:** [June 25, 2024, 11:16am UTC](https://ziggit.dev/t/file-system-best-practices/4854/8 "2024-06-25T11:16:41Z")

</div>

One useful part of mental model here is that absolute paths are relative to a particular file system. In the simplest case, `/etc/passwd` on my machine is not the same as `/etc/passwd` on _your_ machine.

I had to model this situation in rust-analyzer. While it doesn’t do this currently, I architectured the thing such that it can function in “remote-server” mode, where a powerful machine provides code analysis for source code stored on the client machines. So this created a need to model abosolute paths not globally, but rather as “an abosolute path on this particular machine/file system”. The _obvious_ way to do this is to represent a path as a `(FileSystem, String)` pair, but threading filesystem parameter everywhere didn’t seem like a good idea for a “wishful thinking” future needs. The key realisation there was that, if you want to use an absolute path, you get that path from some other file, and you can use that existing file. So paths are modeled as `FileDescriptor, String`, and the difference with `FileSystem` approach is that you always have FileDescriptor already.

Which is to say: you can think of a Dir file descriptor which gives you a capability of:

- reaching any subfile, using relative path
- or, reaching any file _in the same universe that this Dir comes from_, using an absolute path.

This gets rid of ambient authority of absolute paths.
