openDir

Opens a directory at the given path. The directory is a system resource that remains open until close is called on the result. The directory cannot be iterated unless the iterate option is set to true.

On Windows, sub_path should be encoded as WTF-8. On WASI, sub_path should be encoded as valid UTF-8. On other platforms, sub_path is an opaque sequence of bytes with no particular encoding. Asserts that the path parameter has no null bytes.

Function parameters

Parameters

self:Dir
sub_path:[]const u8
args:OpenOptions

Type definitions in this namespace

Types

Entry
Walker
MakePathStatus
OpenOptions
SymLinkFlags: Use with `Dir.symLink`, `Dir.atomicSymLink`, and `symLinkAbsolute` to
WriteFileOptions
CopyFileOptions
PrevStatus
AtomicFileOptions
Stat

Functions in this namespace

Functions

iterate
iterateAssumeFirstIteration: Like `iterate`, but will not reset the directory cursor before the first
walk: Recursively iterates over a directory.
close
openFile: Opens a file for reading or writing, without attempting to create a new file.
openFileZ: Same as `openFile` but the path parameter is null-terminated.
openFileW: Same as `openFile` but Windows-only and the path parameter is
createFile: Creates, opens, or overwrites a file with write access.
createFileZ: Same as `createFile` but the path parameter is null-terminated.
createFileW: Same as `createFile` but Windows-only and the path parameter is
makeDir: Creates a single directory with a relative or absolute path.
makeDirZ: Same as `makeDir`, but `sub_path` is null-terminated.
makeDirW: Creates a single directory with a relative or absolute null-terminated WTF-16 LE-encoded path.
makePath: Calls makeDir iteratively to make an entire path
makePathStatus: Same as `makePath` except returns whether the path already existed or was successfully created.
makeOpenPath: This function performs `makePath`, followed by `openDir`.
realpath: This function returns the canonicalized absolute pathname of
realpathZ: Same as `Dir.realpath` except `pathname` is null-terminated.
realpathW: Windows-only.
realpathAlloc: Same as `Dir.realpath` except caller must free the returned memory.
setAsCwd: Changes the current working directory to the open directory handle.
openDir: Opens a directory at the given path.
openDirZ: Same as `openDir` except the parameter is null-terminated.
openDirW: Same as `openDir` except the path parameter is WTF-16 LE encoded, NT-prefixed.
deleteFile: Delete a file name and possibly the file it refers to, based on an open directory handle.
deleteFileZ: Same as `deleteFile` except the parameter is null-terminated.
deleteFileW: Same as `deleteFile` except the parameter is WTF-16 LE encoded.
deleteDir: Returns `error.DirNotEmpty` if the directory is not empty.
deleteDirZ: Same as `deleteDir` except the parameter is null-terminated.
deleteDirW: Same as `deleteDir` except the parameter is WTF16LE, NT prefixed.
rename: Change the name or location of a file or directory.
renameZ: Same as `rename` except the parameters are null-terminated.
renameW: Same as `rename` except the parameters are WTF16LE, NT prefixed.
symLink: Creates a symbolic link named `sym_link_path` which contains the string `target_path`.
symLinkWasi: WASI-only.
symLinkZ: Same as `symLink`, except the pathname parameters are null-terminated.
symLinkW: Windows-only.
atomicSymLink: Same as `symLink`, except tries to create the symbolic link until it
readLink: Read value of a symbolic link.
readLinkWasi: WASI-only.
readLinkZ: Same as `readLink`, except the `sub_path_c` parameter is null-terminated.
readLinkW: Windows-only.
readFile: Read all of file contents using a preallocated buffer.
readFileAlloc: On success, caller owns returned buffer.
readFileAllocOptions: On success, caller owns returned buffer.
deleteTree: Whether `sub_path` describes a symlink, file, or directory, this function
deleteTreeMinStackSize: Like `deleteTree`, but only keeps one `Iterator` active at a time to minimize the function's stack size.
writeFile: Writes content to the file system, using the file creation flags provided.
access: Test accessing `sub_path`.
accessZ: Same as `access` except the path parameter is null-terminated.
accessW: Same as `access` except asserts the target OS is Windows and the path parameter is
updateFile: Check the file size, mtime, and mode of `source_path` and `dest_path`.
copyFile: Atomically creates a new file at `dest_path` within `dest_dir` with the
atomicFile: Directly access the `.file` field, and then call `AtomicFile.finish` to
stat
statFile: Returns metadata for a file inside the directory.
chmod: Changes the mode of the directory.
chown: Changes the owner and group of the directory.
setPermissions: Sets permissions according to the provided `Permissions` struct.

Error sets in this namespace

Error Sets

OpenError
MakeError
RealPathError
RealPathAllocError
DeleteFileError
DeleteDirError
RenameError
ReadLinkError
DeleteTreeError
WriteFileError
AccessError
CopyFileError
StatError
StatFileError
ChmodError
ChownError
SetPermissionsError

= posix.fd_t

Values

Handle: = posix.fd_t
default_mode: = 0o755

Source

Implementation

pub fn openDir(self: Dir, sub_path: []const u8, args: OpenOptions) OpenError!Dir {
    switch (native_os) {
        .windows => {
            const sub_path_w = try windows.sliceToPrefixedFileW(self.fd, sub_path);
            return self.openDirW(sub_path_w.span().ptr, args);
        },
        .wasi => if (!builtin.link_libc) {
            var base: std.os.wasi.rights_t = .{
                .FD_FILESTAT_GET = true,
                .FD_FDSTAT_SET_FLAGS = true,
                .FD_FILESTAT_SET_TIMES = true,
            };
            if (args.access_sub_paths) {
                base.FD_READDIR = true;
                base.PATH_CREATE_DIRECTORY = true;
                base.PATH_CREATE_FILE = true;
                base.PATH_LINK_SOURCE = true;
                base.PATH_LINK_TARGET = true;
                base.PATH_OPEN = true;
                base.PATH_READLINK = true;
                base.PATH_RENAME_SOURCE = true;
                base.PATH_RENAME_TARGET = true;
                base.PATH_FILESTAT_GET = true;
                base.PATH_FILESTAT_SET_SIZE = true;
                base.PATH_FILESTAT_SET_TIMES = true;
                base.PATH_SYMLINK = true;
                base.PATH_REMOVE_DIRECTORY = true;
                base.PATH_UNLINK_FILE = true;
            }

            const result = posix.openatWasi(
                self.fd,
                sub_path,
                .{ .SYMLINK_FOLLOW = !args.no_follow },
                .{ .DIRECTORY = true },
                .{},
                base,
                base,
            );
            const fd = result catch |err| switch (err) {
                error.FileTooBig => unreachable, // can't happen for directories
                error.IsDir => unreachable, // we're setting DIRECTORY
                error.NoSpaceLeft => unreachable, // not setting CREAT
                error.PathAlreadyExists => unreachable, // not setting CREAT
                error.FileLocksNotSupported => unreachable, // locking folders is not supported
                error.WouldBlock => unreachable, // can't happen for directories
                error.FileBusy => unreachable, // can't happen for directories
                else => |e| return e,
            };
            return .{ .fd = fd };
        },
        else => {},
    }
    const sub_path_c = try posix.toPosixPath(sub_path);
    return self.openDirZ(&sub_path_c, args);
}