DoxigAlpha

stat

Returns Stat containing basic information about the File. TODO: integrate with async I/O

Function parameters

Parameters

#

Type definitions in this namespace

Types

#
Permissions
Cross-platform representation of permissions on a file.
Reader
Memoizes key information about a file handle such as:

Functions in this namespace

Functions

#
close
Upon success, the stream is in an uninitialized state.
sync
Blocks until all pending file contents and metadata modifications
isTty
Test whether the file refers to a terminal.
getOrEnableAnsiEscapeSupport
Returns whether or not ANSI escape codes will be treated as such,
supportsAnsiEscapeCodes
Test whether ANSI escape codes will be treated as such without
setEndPos
Shrinks or expands the file.
seekBy
Repositions read/write file offset relative to the current offset.
seekFromEnd
Repositions read/write file offset relative to the end.
seekTo
Repositions read/write file offset relative to the beginning.
getPos
TODO: integrate with async I/O
getEndPos
TODO: integrate with async I/O
mode
TODO: integrate with async I/O
stat
Returns `Stat` containing basic information about the `File`.
chmod
Changes the mode of the file.
chown
Changes the owner and group of the file.
setPermissions
Sets permissions according to the provided `Permissions` struct.
updateTimes
The underlying file system may have a different granularity than nanoseconds,
readToEndAlloc
Deprecated in favor of `Reader`.
readToEndAllocOptions
Deprecated in favor of `Reader`.
readAll
Deprecated in favor of `Reader`.
pread
On Windows, this function currently does alter the file pointer.
preadAll
Deprecated in favor of `Reader`.
readv
See https://github.com/ziglang/zig/issues/7699
readvAll
Deprecated in favor of `Reader`.
preadv
See https://github.com/ziglang/zig/issues/7699
preadvAll
Deprecated in favor of `Reader`.
writeAll
Deprecated in favor of `Writer`.
pwrite
On Windows, this function currently does alter the file pointer.
pwriteAll
Deprecated in favor of `Writer`.
writev
See https://github.com/ziglang/zig/issues/7699
writevAll
Deprecated in favor of `Writer`.
pwritev
See https://github.com/ziglang/zig/issues/7699
pwritevAll
Deprecated in favor of `Writer`.
copyRange
Deprecated in favor of `Writer`.
copyRangeAll
Deprecated in favor of `Writer`.
deprecatedReader
Deprecated in favor of `Reader`.
deprecatedWriter
Deprecated in favor of `Writer`.
reader
Defaults to positional reading; falls back to streaming.
readerStreaming
Positional is more threadsafe, since the global seek position is not
writer
Defaults to positional reading; falls back to streaming.
writerStreaming
Positional is more threadsafe, since the global seek position is not
lock
Blocks when an incompatible lock is held by another process.
unlock
Assumes the file is locked.
tryLock
Attempts to obtain a lock, returning `true` if the lock is
downgradeLock
Assumes the file is already locked in exclusive mode.

Error sets in this namespace

Error Sets

#

= posix.fd_t

Values

#
Handle
= posix.fd_t
Mode
= posix.mode_t
INode
= posix.ino_t
Uid
= posix.uid_t
Gid
= posix.gid_t
default_mode
This is the default mode given to POSIX operating systems for creating

Source

Implementation

#
pub fn stat(self: File) StatError!Stat {
    if (builtin.os.tag == .windows) {
        var io_status_block: windows.IO_STATUS_BLOCK = undefined;
        var info: windows.FILE_ALL_INFORMATION = undefined;
        const rc = windows.ntdll.NtQueryInformationFile(self.handle, &io_status_block, &info, @sizeOf(windows.FILE_ALL_INFORMATION), .FileAllInformation);
        switch (rc) {
            .SUCCESS => {},
            // Buffer overflow here indicates that there is more information available than was able to be stored in the buffer
            // size provided. This is treated as success because the type of variable-length information that this would be relevant for
            // (name, volume name, etc) we don't care about.
            .BUFFER_OVERFLOW => {},
            .INVALID_PARAMETER => unreachable,
            .ACCESS_DENIED => return error.AccessDenied,
            else => return windows.unexpectedStatus(rc),
        }
        return .{
            .inode = info.InternalInformation.IndexNumber,
            .size = @as(u64, @bitCast(info.StandardInformation.EndOfFile)),
            .mode = 0,
            .kind = if (info.BasicInformation.FileAttributes & windows.FILE_ATTRIBUTE_REPARSE_POINT != 0) reparse_point: {
                var tag_info: windows.FILE_ATTRIBUTE_TAG_INFO = undefined;
                const tag_rc = windows.ntdll.NtQueryInformationFile(self.handle, &io_status_block, &tag_info, @sizeOf(windows.FILE_ATTRIBUTE_TAG_INFO), .FileAttributeTagInformation);
                switch (tag_rc) {
                    .SUCCESS => {},
                    // INFO_LENGTH_MISMATCH and ACCESS_DENIED are the only documented possible errors
                    // https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/d295752f-ce89-4b98-8553-266d37c84f0e
                    .INFO_LENGTH_MISMATCH => unreachable,
                    .ACCESS_DENIED => return error.AccessDenied,
                    else => return windows.unexpectedStatus(rc),
                }
                if (tag_info.ReparseTag & windows.reparse_tag_name_surrogate_bit != 0) {
                    break :reparse_point .sym_link;
                }
                // Unknown reparse point
                break :reparse_point .unknown;
            } else if (info.BasicInformation.FileAttributes & windows.FILE_ATTRIBUTE_DIRECTORY != 0)
                .directory
            else
                .file,
            .atime = windows.fromSysTime(info.BasicInformation.LastAccessTime),
            .mtime = windows.fromSysTime(info.BasicInformation.LastWriteTime),
            .ctime = windows.fromSysTime(info.BasicInformation.ChangeTime),
        };
    }

    if (builtin.os.tag == .wasi and !builtin.link_libc) {
        const st = try std.os.fstat_wasi(self.handle);
        return Stat.fromWasi(st);
    }

    if (builtin.os.tag == .linux) {
        var stx = std.mem.zeroes(linux.Statx);

        const rc = linux.statx(
            self.handle,
            "",
            linux.AT.EMPTY_PATH,
            linux.STATX_TYPE | linux.STATX_MODE | linux.STATX_ATIME | linux.STATX_MTIME | linux.STATX_CTIME,
            &stx,
        );

        return switch (linux.E.init(rc)) {
            .SUCCESS => Stat.fromLinux(stx),
            .ACCES => unreachable,
            .BADF => unreachable,
            .FAULT => unreachable,
            .INVAL => unreachable,
            .LOOP => unreachable,
            .NAMETOOLONG => unreachable,
            .NOENT => unreachable,
            .NOMEM => error.SystemResources,
            .NOTDIR => unreachable,
            else => |err| posix.unexpectedErrno(err),
        };
    }

    const st = try posix.fstat(self.handle);
    return Stat.fromPosix(st);
}