Fields

fd: os.fd_t,

Functions

fn access(self: Dir, sub_path: []const u8, flags: File.OpenFlags) AccessError!void

Test accessing path. path is UTF-8-encoded. Be careful of Time-Of-Check-Ti…

Test accessing path. path is UTF-8-encoded. Be careful of Time-Of-Check-Time-Of-Use race conditions when using this function. For example, instead of testing if a file exists and then opening it, just open it and handle the error for file not found.

fn accessW(self: Dir, sub_path_w: [*:0]const u16, flags: File.OpenFlags) AccessError!void

Same as access except asserts the target OS is Windows and the path parameter …

Same as access except asserts the target OS is Windows and the path parameter is

  • WTF-16 encoded
  • null-terminated
  • NtDll prefixed TODO currently this ignores flags.
fn accessZ(self: Dir, sub_path: [*:0]const u8, flags: File.OpenFlags) AccessError!void

Same as access except the path parameter is null-terminated.

fn atomicFile(self: Dir, dest_path: []const u8, options: AtomicFileOptions) !AtomicFile

Directly access the .file field, and then call AtomicFile.finish to atomica…

Directly access the .file field, and then call AtomicFile.finish to atomically replace dest_path with contents. Always call AtomicFile.deinit to clean up, regardless of whether AtomicFile.finish succeeded. dest_path must remain valid until AtomicFile.deinit is called.

fn close(self: *Dir) void

No documentation provided.

fn copyFile(source_dir: Dir, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, options: CopyFileOptions) CopyFileError!void

Guaranteed to be atomic. On Linux, until https://patchwork.kernel.org/patch/963…

Guaranteed to be atomic. On Linux, until https://patchwork.kernel.org/patch/9636735/ is merged and readily available, there is a possibility of power loss or application termination leaving temporary files present in the same directory as dest_path.

fn createFile(self: Dir, sub_path: []const u8, flags: File.CreateFlags) File.OpenError!File

Creates, opens, or overwrites a file with write access. Call File.close on th…

Creates, opens, or overwrites a file with write access. Call File.close on the result when done. Asserts that the path parameter has no null bytes.

fn createFileW(self: Dir, sub_path_w: []const u16, flags: File.CreateFlags) File.OpenError!File

Same as createFile but Windows-only and the path parameter is [WTF-16](https:…

Same as createFile but Windows-only and the path parameter is WTF-16 encoded.

fn createFileWasi(self: Dir, sub_path: []const u8, flags: File.CreateFlags) File.OpenError!File

Same as createFile but WASI only.

fn createFileZ(self: Dir, sub_path_c: [*:0]const u8, flags: File.CreateFlags) File.OpenError!File

Same as createFile but the path parameter is null-terminated.

fn deleteDir(self: Dir, sub_path: []const u8) DeleteDirError!void

Returns error.DirNotEmpty if the directory is not empty. To delete a director…

Returns error.DirNotEmpty if the directory is not empty. To delete a directory recursively, see deleteTree. Asserts that the path parameter has no null bytes.

fn deleteDirW(self: Dir, sub_path_w: []const u16) DeleteDirError!void

Same as deleteDir except the parameter is UTF16LE, NT prefixed. This function…

Same as deleteDir except the parameter is UTF16LE, NT prefixed. This function is Windows-only.

fn deleteDirZ(self: Dir, sub_path_c: [*:0]const u8) DeleteDirError!void

Same as deleteDir except the parameter is null-terminated.

fn deleteFile(self: Dir, sub_path: []const u8) DeleteFileError!void

Delete a file name and possibly the file it refers to, based on an open director…

Delete a file name and possibly the file it refers to, based on an open directory handle. Asserts that the path parameter has no null bytes.

fn deleteFileW(self: Dir, sub_path_w: []const u16) DeleteFileError!void

Same as deleteFile except the parameter is WTF-16 encoded.

fn deleteFileZ(self: Dir, sub_path_c: [*:0]const u8) DeleteFileError!void

Same as deleteFile except the parameter is null-terminated.

fn deleteTree(self: Dir, sub_path: []const u8) DeleteTreeError!void

Whether full_path describes a symlink, file, or directory, this function remo…

Whether full_path describes a symlink, file, or directory, this function removes it. If it cannot be removed because it is a non-empty directory, this function recursively removes its entries and then tries again. This operation is not atomic on most file systems.

fn deleteTreeMinStackSize(self: Dir, sub_path: []const u8) DeleteTreeError!void

Like deleteTree, but only keeps one Iterator active at a time to minimize th…

Like deleteTree, but only keeps one Iterator active at a time to minimize the function’s stack size. This is slower than deleteTree but uses less stack space.

fn makeDir(self: Dir, sub_path: []const u8) !void

Creates a single directory with a relative or absolute path. To create multiple…

Creates a single directory with a relative or absolute path. To create multiple directories to make an entire path, see makePath. To operate on only absolute paths, see makeDirAbsolute.

fn makeDirW(self: Dir, sub_path: [*:0]const u16) !void

Creates a single directory with a relative or absolute null-terminated WTF-16-en…

Creates a single directory with a relative or absolute null-terminated WTF-16-encoded path. To create multiple directories to make an entire path, see makePath. To operate on only absolute paths, see makeDirAbsoluteW.

fn makeDirZ(self: Dir, sub_path: [*:0]const u8) !void

Creates a single directory with a relative or absolute null-terminated UTF-8-enc…

Creates a single directory with a relative or absolute null-terminated UTF-8-encoded path. To create multiple directories to make an entire path, see makePath. To operate on only absolute paths, see makeDirAbsoluteZ.

fn makeOpenPath(self: Dir, sub_path: []const u8, open_dir_options: OpenDirOptions) !Dir

This function performs makePath, followed by openDir. If supported by the O…

This function performs makePath, followed by openDir. If supported by the OS, this operation is atomic. It is not atomic on all operating systems.

fn makeOpenPathIterable(self: Dir, sub_path: []const u8, open_dir_options: OpenDirOptions) !IterableDir

This function performs makePath, followed by openIterableDir. If supported …

This function performs makePath, followed by openIterableDir. If supported by the OS, this operation is atomic. It is not atomic on all operating systems.

fn makePath(self: Dir, sub_path: []const u8) !void

Calls makeDir recursively to make an entire path. Returns success if the path a…

Calls makeDir recursively to make an entire path. Returns success if the path already exists and is a directory. This function is not atomic, and if it returns an error, the file system may have been modified regardless.

fn metadata(self: Dir) MetadataError!Metadata

Returns a Metadata struct, representing the permissions on the directory

fn openDir(self: Dir, sub_path: []const u8, args: OpenDirOptions) OpenError!Dir

Opens a directory at the given path. The directory is a system resource that rem…

Opens a directory at the given path. The directory is a system resource that remains open until close is called on the result.

Asserts that the path parameter has no null bytes.

fn openDirW(self: Dir, sub_path_w: [*:0]const u16, args: OpenDirOptions, iterable: bool) OpenError!Dir

Same as openDir except the path parameter is WTF-16 encoded, NT-prefixed. Thi…

Same as openDir except the path parameter is WTF-16 encoded, NT-prefixed. This function asserts the target OS is Windows.

fn openDirWasi(self: Dir, sub_path: []const u8, args: OpenDirOptions) OpenError!Dir

Same as openDir except only WASI.

fn openDirZ(self: Dir, sub_path_c: [*:0]const u8, args: OpenDirOptions, iterable: bool) OpenError!Dir

Same as openDir except the parameter is null-terminated.

fn openFile(self: Dir, sub_path: []const u8, flags: File.OpenFlags) File.OpenError!File

Opens a file for reading or writing, without attempting to create a new file. T…

Opens a file for reading or writing, without attempting to create a new file. To create a new file, see createFile. Call File.close to release the resource. Asserts that the path parameter has no null bytes.

fn openFileW(self: Dir, sub_path_w: []const u16, flags: File.OpenFlags) File.OpenError!File

Same as openFile but Windows-only and the path parameter is [WTF-16](https://…

Same as openFile but Windows-only and the path parameter is WTF-16 encoded.

fn openFileWasi(self: Dir, sub_path: []const u8, flags: File.OpenFlags) File.OpenError!File

Same as openFile but WASI only.

fn openFileZ(self: Dir, sub_path: [*:0]const u8, flags: File.OpenFlags) File.OpenError!File

Same as openFile but the path parameter is null-terminated.

fn openIterableDir(self: Dir, sub_path: []const u8, args: OpenDirOptions) OpenError!IterableDir

Opens an iterable directory at the given path. The directory is a system resourc…

Opens an iterable directory at the given path. The directory is a system resource that remains open until close is called on the result.

Asserts that the path parameter has no null bytes.

fn readFile(self: Dir, file_path: []const u8, buffer: []u8) ![]u8

Read all of file contents using a preallocated buffer. The returned slice has t…

Read all of file contents using a preallocated buffer. The returned slice has the same pointer as buffer. If the length matches buffer.len the situation is ambiguous. It could either mean that the entire file was read, and it exactly fits the buffer, or it could mean the buffer was not big enough for the entire file.

fn readFileAlloc(self: Dir, allocator: mem.Allocator, file_path: []const u8, max_bytes: usize) ![]u8

On success, caller owns returned buffer. If the file is larger than max_bytes

On success, caller owns returned buffer. If the file is larger than max_bytes, returns error.FileTooBig.

fn readFileAllocOptions(self: Dir, allocator: mem.Allocator, file_path: []const u8, max_bytes: usize, size_hint: ?usize, comptime alignment: u29, comptime optional_sentinel: ?u8) !if (optional_sentinel) |s| [:s]align(alignment) u8 else []align(alignment) u8

On success, caller owns returned buffer. If the file is larger than max_bytes

On success, caller owns returned buffer. If the file is larger than max_bytes, returns error.FileTooBig. If size_hint is specified the initial buffer size is calculated using that value, otherwise the effective file size is used instead. Allows specifying alignment and a sentinel value.

fn readLink(self: Dir, sub_path: []const u8, buffer: []u8) ![]u8

Read value of a symbolic link. The return value is a slice of buffer, from in…

Read value of a symbolic link. The return value is a slice of buffer, from index 0. Asserts that the path parameter has no null bytes.

fn readLinkW(self: Dir, sub_path_w: []const u16, buffer: []u8) ![]u8

Windows-only. Same as readLink except the pathname parameter is null-terminat…

Windows-only. Same as readLink except the pathname parameter is null-terminated, WTF16 encoded.

fn readLinkWasi(self: Dir, sub_path: []const u8, buffer: []u8) ![]u8

WASI-only. Same as readLink except targeting WASI.

fn readLinkZ(self: Dir, sub_path_c: [*:0]const u8, buffer: []u8) ![]u8

Same as readLink, except the pathname parameter is null-terminated.

fn realpath(self: Dir, pathname: []const u8, out_buffer: []u8) ![]u8

This function returns the canonicalized absolute pathname of pathname relativ…

This function returns the canonicalized absolute pathname of pathname relative to this Dir. If pathname is absolute, ignores this Dir handle and returns the canonicalized absolute pathname of pathname argument. This function is not universally supported by all platforms. Currently supported hosts are: Linux, macOS, and Windows. See also Dir.realpathZ, Dir.realpathW, and Dir.realpathAlloc.

fn realpathAlloc(self: Dir, allocator: Allocator, pathname: []const u8) ![]u8

Same as Dir.realpath except caller must free the returned memory. See also `D…

Same as Dir.realpath except caller must free the returned memory. See also Dir.realpath.

fn realpathW(self: Dir, pathname: []const u16, out_buffer: []u8) ![]u8

Windows-only. Same as Dir.realpath except pathname is WTF16 encoded. See al…

Windows-only. Same as Dir.realpath except pathname is WTF16 encoded. See also Dir.realpath, realpathW.

fn realpathZ(self: Dir, pathname: [*:0]const u8, out_buffer: []u8) ![]u8

Same as Dir.realpath except pathname is null-terminated. See also `Dir.real…

Same as Dir.realpath except pathname is null-terminated. See also Dir.realpath, realpathZ.

fn rename(self: Dir, old_sub_path: []const u8, new_sub_path: []const u8) RenameError!void

Change the name or location of a file or directory. If new_sub_path already exi…

Change the name or location of a file or directory. If new_sub_path already exists, it will be replaced. Renaming a file over an existing directory or a directory over an existing file will fail with error.IsDir or error.NotDir

fn renameW(self: Dir, old_sub_path_w: []const u16, new_sub_path_w: []const u16) RenameError!void

Same as rename except the parameters are UTF16LE, NT prefixed. This function …

Same as rename except the parameters are UTF16LE, NT prefixed. This function is Windows-only.

fn renameZ(self: Dir, old_sub_path_z: [*:0]const u8, new_sub_path_z: [*:0]const u8) RenameError!void

Same as rename except the parameters are null-terminated.

fn setAsCwd(self: Dir) !void

Changes the current working directory to the open directory handle. This modifi…

Changes the current working directory to the open directory handle. This modifies global state and can have surprising effects in multi- threaded applications. Most applications and especially libraries should not call this function as a general rule, however it can have use cases in, for example, implementing a shell, or child process execution. Not all targets support this. For example, WASI does not have the concept of a current working directory.

fn setPermissions(self: Dir, permissions: Permissions) SetPermissionsError!void

Sets permissions according to the provided Permissions struct. This method is…

Sets permissions according to the provided Permissions struct. This method is NOT available on WASI

fn stat(self: Dir) StatError!Stat

No documentation provided.

fn statFile(self: Dir, sub_path: []const u8) StatFileError!Stat

Returns metadata for a file inside the directory.

Returns metadata for a file inside the directory.

On Windows, this requires three syscalls. On other operating systems, it only takes one.

Symlinks are followed.

sub_path may be absolute, in which case self is ignored.

fn symLink(self: Dir, target_path: []const u8, sym_link_path: []const u8, flags: SymLinkFlags) !void

Creates a symbolic link named sym_link_path which contains the string `target_…

Creates a symbolic link named sym_link_path which contains the string target_path. A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link. If sym_link_path exists, it will not be overwritten.

fn symLinkW(self: Dir, target_path_w: []const u16, sym_link_path_w: []const u16, flags: SymLinkFlags) !void

Windows-only. Same as symLink except the pathname parameters are null-termina…

Windows-only. Same as symLink except the pathname parameters are null-terminated, WTF16 encoded.

fn symLinkWasi(self: Dir, target_path: []const u8, sym_link_path: []const u8, _: SymLinkFlags) !void

WASI-only. Same as symLink except targeting WASI.

fn symLinkZ(self: Dir, target_path_c: [*:0]const u8, sym_link_path_c: [*:0]const u8, flags: SymLinkFlags) !void

Same as symLink, except the pathname parameters are null-terminated.

fn updateFile(source_dir: Dir, source_path: []const u8, dest_dir: Dir, dest_path: []const u8, options: CopyFileOptions) !PrevStatus

Check the file size, mtime, and mode of source_path and dest_path. If they a…

Check the file size, mtime, and mode of source_path and dest_path. If they are equal, does nothing. Otherwise, atomically copies source_path to dest_path. The destination file gains the mtime, atime, and mode of the source file so that the next call to updateFile will not need a copy. Returns the previous status of the file before updating. If any of the directories do not exist for dest_path, they are created.

fn writeFile(self: Dir, sub_path: []const u8, data: []const u8) !void

Writes content to the file system, creating a new file if it does not exist, tru…

Writes content to the file system, creating a new file if it does not exist, truncating if it already exists.

Error Sets