Functions
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 callAtomicFile.finish
to atomica…Directly access the
.file
field, and then callAtomicFile.finish
to atomically replacedest_path
with contents. Always callAtomicFile.deinit
to clean up, regardless of whetherAtomicFile.finish
succeeded.dest_path
must remain valid untilAtomicFile.deinit
is called.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, seedeleteTree
. Asserts that the path parameter has no null bytes.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 oneIterator
active at a time to minimize th…Like
deleteTree
, but only keeps oneIterator
active at a time to minimize the function’s stack size. This is slower thandeleteTree
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, seemakeDirAbsolute
.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, seemakeDirAbsoluteW
.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, seemakeDirAbsoluteZ
.fn makeOpenPathIterable(self: Dir, sub_path: []const u8, open_dir_options: OpenDirOptions) !IterableDir
This function performs
makePath
, followed byopenIterableDir
. If supported …This function performs
makePath
, followed byopenIterableDir
. 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 directoryfn 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
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
. CallFile.close
to release the resource. Asserts that the path parameter has no null bytes.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 matchesbuffer.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
, returnserror.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
, returnserror.FileTooBig
. Ifsize_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 index0
. Asserts that the path parameter has no null bytes.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 thepathname
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 thisDir
. Ifpathname
is absolute, ignores thisDir
handle and returns the canonicalized absolute pathname ofpathname
argument. This function is not universally supported by all platforms. Currently supported hosts are: Linux, macOS, and Windows. See alsoDir.realpathZ
,Dir.realpathW
, andDir.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 alsoDir.realpath
.fn realpathW(self: Dir, pathname: []const u16, out_buffer: []u8) ![]u8
Windows-only. Same as
Dir.realpath
exceptpathname
is WTF16 encoded. See al…Windows-only. Same as
Dir.realpath
exceptpathname
is WTF16 encoded. See alsoDir.realpath
,realpathW
.fn realpathZ(self: Dir, pathname: [*:0]const u8, out_buffer: []u8) ![]u8
Same as
Dir.realpath
exceptpathname
is null-terminated. See also `Dir.real…Same as
Dir.realpath
exceptpathname
is null-terminated. See alsoDir.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
orerror.NotDir
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 WASIfn 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 caseself
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 stringtarget_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. Ifsym_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
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
anddest_path
. If they a…Check the file size, mtime, and mode of
source_path
anddest_path
. If they are equal, does nothing. Otherwise, atomically copiessource_path
todest_path
. The destination file gains the mtime, atime, and mode of the source file so that the next call toupdateFile
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.
Values
AccessError | type | |
CopyFileError | type | |
DeleteFileError | type | |
DeleteTreeError | type | |
MetadataError | type | |
OpenError | type | |
RenameError | type | |
SetPermissionsError | type | |
StatError | type | |
StatFileError | type | |
chmod | undefined | |
chown | undefined | |
iterate | undefined | |
walk | undefined |