字段
Filebuiltinnative_osis_windowsstdIoassertDirFlagsHandleReaderWriterAtomicMemoryMapMultiReaderINodeNLinkUidGidBlockSizeKindStatstdoutstderrstdinStatErrorstatLockOpenErrorclosecloseManySyncErrorsyncisTtyEnableAnsiEscapeCodesErrorenableAnsiEscapeCodessupportsAnsiEscapeCodesSetLengthErrorsetLengthLengthErrorlengthSetPermissionsErrorsetPermissionsSetOwnerErrorsetOwnerPermissionsSetTimestampsErrorSetTimestampsOptionsSetTimestampsetTimestampssetTimestampsNowReadStreamingErrorreadStreamingReadPositionalErrorreadPositionalWritePositionalErrorwritePositionalwritePositionalAllSeekErrorWriteFilePositionalErrorreaderreadPositionalAllreaderStreamingwriterwriterStreamingwriteStreamingwriteStreamingAllLockErrorlockunlocktryLockDowngradeLockErrordowngradeLockRealPathErrorrealPathHardLinkOptionsHardLinkErrorhardLinkcreateMemoryMap
std.Io.File.assert
别名
别名目标 std.debug.assert
std.Io.File.Atomic
别名
别名目标 std.Io.File.Atomic
std.Io.File.BlockSize
类型
std.Io.File.builtin
常量
std.Io.File.close
函数
pub fn close(file: File, io: Io) void
参数
std.Io.File.closeMany
函数
pub fn closeMany(io: Io, files: []const File) void
参数
std.Io.File.createMemoryMap
函数
pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap
参数
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput ReadPositionalError
- IsDir ReadPositionalError
尝试将目录文件描述符当作普通文件读取。
- LockViolation ReadPositionalError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- LockedMemoryLimitExceeded
- NotOpenForReading ReadPositionalError
打开文件时未授予读取能力。
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- SystemResources ReadPositionalError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable ReadPositionalError
此文件不支持按位置读取。
- WouldBlock ReadPositionalError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.Dir
别名
别名目标 std.Io.Dir
std.Io.File.downgradeLock
函数
假定文件已处于独占锁定模式。 以原子方式将锁改为共享模式,而不释放锁。
pub fn downgradeLock(file: File, io: Io) LockError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.DowngradeLockError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.enableAnsiEscapeCodes
函数
pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- NotTerminalDevice
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.EnableAnsiEscapeCodesError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- NotTerminalDevice
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.File
别名
别名目标 std.Io.File
std.Io.File.Flags
容器
字段
nonblocking: bool- true:
- windows:以 MODE.IO.ASYNCHRONOUS 打开
- POSIX:已设置 O_NONBLOCK
- false:
- windows:以 SYNCHRONOUS_ALERT 或 SYNCHRONOUS_NONALERT 打开, 或不是文件。
- POSIX:未设置 O_NONBLOCK
std.Io.File.Gid
别名
别名目标 std.posix.gid_t
std.Io.File.Handle
别名
别名目标 std.posix.fd_t
std.Io.File.hardLink
函数
pub fn hardLink( file: File, io: Io, new_dir: Dir, new_sub_path: []const u8, options: HardLinkOptions, ) HardLinkError!void
参数
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DiskQuota
- FileNotFound
- HardwareFailure
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft
- NotDir
- OperationUnsupported
操作系统或文件系统不支持硬链接。
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.HardLinkError
错误集合
错误
- AccessDenied
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- CrossDevice
- DiskQuota
- FileNotFound
- HardwareFailure
- LinkQuotaExceeded
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NoSpaceLeft
- NotDir
- OperationUnsupported
操作系统或文件系统不支持硬链接。
- PathAlreadyExists
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.HardLinkOptions
容器
字段
follow_symlinks: bool = false
std.Io.File.INode
别名
别名目标 std.posix.ino_t
std.Io.File.Io
别名
别名目标 std.Io
std.Io.File.is_windows
常量
std.Io.File.isTty
函数
pub fn isTty(file: File, io: Io) Io.Cancelable!bool
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.File.Kind
容器
字段
block_device
character_device
directory
named_pipe
sym_link
file
unix_domain_socket
whiteout
door
event_port
unknown
std.Io.File.length
函数
获取文件末尾的字节索引。
若只需长度,有时比 stat 开销更低。
pub fn length(file: File, io: Io) LengthError!u64
参数
错误
- AccessDenied StatError
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied StatError
- Streaming StatError
尝试对非文件流调用 stat。
- SystemResources StatError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.LengthError
别名
std.Io.File.lock
函数
其他进程持有不兼容的锁时阻塞。一个进程对某文件 只能持有一种锁,共享锁或独占锁。进程 以任何方式终止时,锁都会释放。
假定文件未锁定。
pub fn lock(file: File, io: Io, l: Lock) LockError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Lock
容器
字段
none
shared
exclusive
std.Io.File.LockError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.MemoryMap
别名
预期与文件内容保持一致的内存。
std.Io.File.MultiReader
别名
并发读取多个文件流,消除 死锁风险。
std.Io.File.native_os
常量
std.Io.File.NLink
别名
别名目标 std.posix.nlink_t
std.Io.File.OpenError
错误集合
错误
- AccessDenied
在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- BadPathName PathNameError
文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
以下三种情况之一:
- pathname 指向正在执行的可执行映像, 且请求写访问。
- pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
- pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
- FileLocksUnsupported
- FileNotFound
以下任一情况:
- 某个路径分量不存在。
- 使用了当前工作目录,但该目录已被删除。
- 已打开目录句柄所关联的路径已被删除。
- macOS 上,多个进程或线程将
O.EXCL设为false,并发争相创建同一文件。
- FileTooBig
文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
- IsDir
以下任一情况:
- 路径指向目录,但请求了写权限。
- 路径指向目录,但
allow_directory被设为 false。
- NameTooLong PathNameError
提供的缓冲区过小, 无法容纳路径名时返回。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
设备没有空间容纳新文件,无法创建新路径。 仅在提供
CREAT标志时才可能出现此错误。- NotDir
路径中用作目录的某个部分实际上不是目录, 或者指定了
DIRECTORY,但路径不是目录。- PathAlreadyExists
路径已存在,且提供了
CREAT和EXCL标志。- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
路径超过
max_path_bytes字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已请求非阻塞模式,但该操作无法立即返回。
std.Io.File.Permissions
常量
文件权限的跨平台表示。
POSIX 系统中对应“mode”,Windows 中对应“attributes”。
std.Io.File.Permissions.default_dir
常量
@This()
std.Io.File.Permissions.default_dir
常量
@This()
std.Io.File.Permissions.executable_file
常量
@This()
std.Io.File.Permissions.executable_file
常量
@This()
std.Io.File.Permissions.executable_file
常量
@This()
std.Io.File.Permissions.fromMode
函数
pub fn fromMode(mode: std.posix.mode_t) @This()
参数
std.Io.File.Permissions.has_executable_bit
原始类型
std.Io.File.Permissions.has_executable_bit
常量
std.Io.File.Permissions.has_executable_bit
原始类型
std.Io.File.Permissions.readOnly
函数
pub fn readOnly(self: @This()) bool
参数
self: @This()
std.Io.File.Permissions.readOnly
函数
当且仅当所有权限类别均无写权限时返回 true。
pub fn readOnly(self: @This()) bool
参数
self: @This()
std.Io.File.Permissions.setReadOnly
函数
pub fn setReadOnly(self: @This(), read_only: bool) @This()
参数
self: @This()
read_only: bool
std.Io.File.Permissions.setReadOnly
函数
为所有用户类别启用写权限。
pub fn setReadOnly(self: @This(), read_only: bool) @This()
参数
self: @This()
read_only: bool
std.Io.File.Permissions.toAttributes
函数
pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE
参数
self: @This()
std.Io.File.Permissions.toMode
函数
pub fn toMode(self: @This()) std.posix.mode_t
参数
self: @This()
std.Io.File.Permissions.windows
别名
别名目标 std.os.windows
std.Io.File.reader
函数
pub fn reader(file: File, io: Io, buffer: []u8) Reader
参数
std.Io.File.Reader
别名
别名目标 std.Io.File.Reader
std.Io.File.readerStreaming
函数
pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader
参数
std.Io.File.readPositional
函数
pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.readPositionalAll
函数
pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.ReadPositionalError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.readStreaming
函数
pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize
参数
错误
- AccessDenied UnendingError
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- EndOfStream
- InputOutput UnendingError
- IsDir UnendingError
尝试将目录文件描述符当作普通文件读取。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- SocketUnconnected UnendingError
- SystemResources UnendingError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock UnendingError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.ReadStreamingError
错误集合
错误
- AccessDenied UnendingError
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionResetByPeer UnendingError
- EndOfStream
- InputOutput UnendingError
- IsDir UnendingError
尝试将目录文件描述符当作普通文件读取。
- LockViolation UnendingError
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading UnendingError
打开文件时未授予读取能力。
- SocketUnconnected UnendingError
- SystemResources UnendingError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock UnendingError
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.realPath
函数
获取与打开的文件句柄对应的规范化绝对路径名。
此函数的平台支持有限,使用它可能导致 不必要的失败和竞态条件。通常建议 完全避免使用此函数。
pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize
参数
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.File.RealPathError
错误集合
错误
- AccessDenied
- AntivirusInterference
Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- FileBusy
- FileNotFound
- FileSystem
- FileTooBig
- InputOutput
- IsDir
- NameTooLong
完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。
- NetworkNotFound
在 Windows 上,未找到
\\server或\\server\share。- NoDevice
- NoSpaceLeft
- NotDir
- OperationUnsupported
此操作系统、文件系统或
Io实现 不支持 realpath 操作。- PathAlreadyExists
- PermissionDenied
- PipeBusy
- ProcessFdQuotaExceeded
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnrecognizedVolume
在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。
std.Io.File.SeekError
错误集合
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.File.setLength
函数
截短或扩展文件,新增数据填零。
调用后文件偏移量保持不变。
此函数操作已打开的文件句柄。Dir 中没有
按路径操作的等效函数,因为这种
功能通常会引入检查时间与使用时间之间的竞态,即 TOCTOU。
在确实需要此语义的少数情况下,可以
使用截短标志打开文件。
pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileTooBig
- InputOutput
- NonResizable
- PermissionDenied
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetLengthError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileTooBig
- InputOutput
- NonResizable
- PermissionDenied
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.setOwner
函数
也称为“chown”。
进程必须具备相应权限才能成功执行此操作。
文件所有者可将所属组改为自己所属的任意组。
若所有者或所属组指定为
null,则不更改对应标识。
pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetOwnerError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.setPermissions
函数
又称“chmod”。
进程必须具有适当权限,或者有效用户 ID 必须与文件所有者匹配, 才能成功执行。
pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetPermissionsError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetTimestamp
容器
字段
std.Io.File.SetTimestamp.init
函数
便于与 Stat 交互,其中 null 表示 unchanged。
pub fn init(optional: ?Io.Timestamp) SetTimestamp
参数
std.Io.File.setTimestamps
函数
最终存储的时间粒度取决于操作系统 与文件系统的组合。若提供的值超出此范围, 则将其限制为最大值。
pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void
参数
错误
- AccessDenied
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetTimestampsError
错误集合
错误
- AccessDenied
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.setTimestampsNow
函数
将 file 的访问时间戳和修改时间戳设置为当前
挂钟时间。
最终存储的时间粒度由操作系统与 文件系统的组合决定。
pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void
参数
错误
- AccessDenied
times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
- 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
- 文件被标记为不可变,参见 chattr(1)。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
- 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
- 文件被标记为仅追加或不可变,参见 chattr(1)。
- ReadOnlyFileSystem
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SetTimestampsOptions
容器
字段
access_timestamp: SetTimestamp = .unchanged
modify_timestamp: SetTimestamp = .unchanged
std.Io.File.stat
函数
pub fn stat(file: File, io: Io) StatError!Stat
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Stat
容器
字段
inode: INode系统用于指向文件元数据的数字。 不保证此数字在时间维度上唯一,因为某些文件 系统会在文件删除后复用其 inode。某些 系统也可能随时间改变文件的 inode。
在 Linux 上,inode 是保存元数据的结构体, 此处看到的是 inode 的编号,即 inode 的索引号。
Windows 上的 FileIndex 类似。它是文件的编号, 在每个文件系统内唯一。
nlink: NLink
size: u64
permissions: Permissions
kind: Kind
atime: ?Io.Timestamp相对于 UTC 1970-01-01 的最后访问时间,单位为纳秒。
文件系统通常难以持续更新此值,因为
这会把只读的文件系统访问变成文件系统修改。
某些系统报告过时的值,某些系统则明确拒绝
报告此值。后一种情况使用 null 表示。
mtime: Io.Timestamp最后修改时间,相对于 UTC 1970-01-01,以纳秒表示。
ctime: Io.Timestamp相对于 UTC 1970-01-01 的最后状态/元数据修改时间,单位为纳秒。
block_size: BlockSize适合最优 I/O 的最小块长度,以字节计。
对不支持此概念的操作系统或文件系统,
该值设为 1。不一定是二的幂。
std.Io.File.StatError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- Streaming
尝试对非文件流调用 stat。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.std
别名
别名目标 std
std.Io.File.stderr
函数
pub fn stderr() File
std.Io.File.stdin
函数
pub fn stdin() File
std.Io.File.stdout
函数
pub fn stdout() File
std.Io.File.supportsAnsiEscapeCodes
函数
测试 ANSI 转义码是否会被当作转义码处理, 但不尝试启用 ANSI 转义码支持。
pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.File.sync
函数
阻塞,直到此文件所有待处理的内容和元数据修改 均与底层文件系统同步。
不保证包含该文件的目录的元数据 也已经写入磁盘。
pub fn sync(file: File, io: Io) SyncError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- InputOutput
- NoSpaceLeft
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.SyncError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- DiskQuota
- InputOutput
- NoSpaceLeft
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.tryLock
函数
尝试获取锁。获得锁时返回 true,若已有其他不兼容的锁被持有,则返回 false。
进程只能对同一文件持有一种锁,共享锁或排他锁。进程以任意方式结束时,锁都会释放。
假定文件当前未锁定。
pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.Uid
别名
别名目标 std.posix.uid_t
std.Io.File.unlock
函数
假定文件已加锁。
pub fn unlock(file: File, io: Io) void
参数
std.Io.File.WriteFilePositionalError
错误集合
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- CorruptedData WriteFileError
在 FreeBSD 上使用 copy_file_range 时可能发生。
- DeviceBusy Error
- DiskQuota Error
- EndOfStream WriteFileError
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- ReadFailed WriteFileError
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unimplemented WriteFileError
描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。
- Unseekable
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.File.writePositional
函数
另请参见:
pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize
参数
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.File.writePositionalAll
函数
等同于创建位置写入器、写入 bytes,然后刷新。
pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void
参数
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.File.WritePositionalError
错误集合
错误
- AccessDenied
文件描述符没有写入所需的权限。
- BrokenPipe
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft
- NotOpenForWriting
文件打开时没有写入能力。
- PermissionDenied
- SystemResources
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
无法对该文件按指定位置写入。
- WouldBlock
已启用非阻塞模式,而此操作将阻塞。
std.Io.File.writer
函数
默认采用定位读取;不可用时退回流式读取。
定位读取不影响全局查找位置, 因此更便于线程安全使用。
pub fn writer(file: File, io: Io, buffer: []u8) Writer
参数
std.Io.File.Writer
别名
别名目标 std.Io.File.Writer
std.Io.File.writerStreaming
函数
定位读取不影响全局查找位置,因此更便于线程安全使用。 但若相应系统调用不可用,则预先初始化为 流式模式可省去一次失败的系统调用。
pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer
参数
std.Io.File.writeStreaming
函数
这是直接调用 Io 接口函数的底层 API。
更高层 API 参见 writerStreaming。
pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize
参数
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
std.Io.File.writeStreamingAll
函数
等同于创建流式写入器、写入 bytes,然后刷新。
pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void
参数
错误
- AccessDenied Error
文件描述符没有写入所需的权限。
- BrokenPipe Error
文件为未连接的套接字,或其读取端已关闭。
- Canceled Cancelable
调用方请求停止异步操作。
- DeviceBusy Error
- DiskQuota Error
- FileBusy Error
- FileTooBig Error
- InputOutput Error
- LockViolation Error
进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。
- NoDevice Error
写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
- NoSpaceLeft Error
- NotOpenForWriting Error
- PermissionDenied Error
- SystemResources Error
内核内存不足,无法从 in_fd 读取。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock Error
已启用非阻塞模式,而此操作将阻塞。
源码
std/Io/File.zig
const File = @This();
const builtin = @import("builtin");
const native_os = builtin.os.tag;
const is_windows = native_os == .windows;
const std = @import("../std.zig");
const Io = std.Io;
const assert = std.debug.assert;
const Dir = std.Io.Dir;
handle: Handle,
flags: Flags,
pub const Flags = struct {
/// * true:
/// - windows:以 MODE.IO.ASYNCHRONOUS 打开
/// - POSIX:已设置 O_NONBLOCK
/// * false:
/// - windows:以 SYNCHRONOUS_ALERT 或 SYNCHRONOUS_NONALERT 打开,
/// 或不是文件。
/// - POSIX:未设置 O_NONBLOCK
nonblocking: bool,
};
pub const Handle = std.posix.fd_t;
pub const Reader = @import("File/Reader.zig");
pub const Writer = @import("File/Writer.zig");
pub const Atomic = @import("File/Atomic.zig");
/// 预期与文件内容保持一致的内存。
pub const MemoryMap = @import("File/MemoryMap.zig");
/// 并发读取多个文件流,消除
/// 死锁风险。
pub const MultiReader = @import("File/MultiReader.zig");
pub const INode = std.posix.ino_t;
pub const NLink = std.posix.nlink_t;
pub const Uid = std.posix.uid_t;
pub const Gid = std.posix.gid_t;
pub const BlockSize = u32;
pub const Kind = enum {
block_device,
character_device,
directory,
named_pipe,
sym_link,
file,
unix_domain_socket,
whiteout,
door,
event_port,
unknown,
};
pub const Stat = struct {
/// 系统用于指向文件元数据的数字。
/// 不保证此数字在时间维度上唯一,因为某些文件
/// 系统会在文件删除后复用其 inode。某些
/// 系统也可能随时间改变文件的 inode。
///
/// 在 Linux 上,inode 是保存元数据的结构体,
/// 此处看到的是 inode 的编号,即
/// inode 的索引号。
///
/// Windows 上的 FileIndex 类似。它是文件的编号,
/// 在每个文件系统内唯一。
inode: INode,
nlink: NLink,
size: u64,
permissions: Permissions,
kind: Kind,
/// 相对于 UTC 1970-01-01 的最后访问时间,单位为纳秒。
///
/// 文件系统通常难以持续更新此值,因为
/// 这会把只读的文件系统访问变成文件系统修改。
/// 某些系统报告过时的值,某些系统则明确拒绝
/// 报告此值。后一种情况使用 `null` 表示。
atime: ?Io.Timestamp,
/// 最后修改时间,相对于 UTC 1970-01-01,以纳秒表示。
mtime: Io.Timestamp,
/// 相对于 UTC 1970-01-01 的最后状态/元数据修改时间,单位为纳秒。
ctime: Io.Timestamp,
/// 适合最优 I/O 的最小块长度,以字节计。
/// 对不支持此概念的操作系统或文件系统,
/// 该值设为 `1`。不一定是二的幂。
block_size: BlockSize,
};
pub fn stdout() File {
return switch (native_os) {
.windows => .{
.handle = std.os.windows.peb().ProcessParameters.hStdOutput,
.flags = .{ .nonblocking = false },
},
else => .{
.handle = std.posix.STDOUT_FILENO,
.flags = .{ .nonblocking = false },
},
};
}
pub fn stderr() File {
return switch (native_os) {
.windows => .{
.handle = std.os.windows.peb().ProcessParameters.hStdError,
.flags = .{ .nonblocking = false },
},
else => .{
.handle = std.posix.STDERR_FILENO,
.flags = .{ .nonblocking = false },
},
};
}
pub fn stdin() File {
return switch (native_os) {
.windows => .{
.handle = std.os.windows.peb().ProcessParameters.hStdInput,
.flags = .{ .nonblocking = false },
},
else => .{
.handle = std.posix.STDIN_FILENO,
.flags = .{ .nonblocking = false },
},
};
}
pub const StatError = error{
SystemResources,
/// 在 WASI 中,当文件描述符不具备获取自身 filestat
/// 信息所需的权限时,可能发生此错误。
AccessDenied,
PermissionDenied,
/// 尝试对非文件流调用 stat。
Streaming,
} || Io.Cancelable || Io.UnexpectedError;
/// 返回包含 `File` 基本信息的 `Stat`。
pub fn stat(file: File, io: Io) StatError!Stat {
return io.vtable.fileStat(io.userdata, file);
}
pub const Lock = enum {
none,
shared,
exclusive,
};
pub const OpenError = error{
PipeBusy,
NoDevice,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
/// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
/// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
///
///
///
AntivirusInterference,
/// 在 WASI 中,若文件描述符不具有相对于它
/// 打开新资源所需的权限,可能发生此错误。
AccessDenied,
PermissionDenied,
SymLinkLoop,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
/// 以下任一情况:
/// * 某个路径分量不存在。
/// * 使用了当前工作目录,但该目录已被删除。
/// * 已打开目录句柄所关联的路径已被删除。
/// * macOS 上,多个进程或线程将 `O.EXCL` 设为 `false`,并发争相创建同一文件。
///
FileNotFound,
/// 路径超过 `max_path_bytes` 字节。
/// 可用内核内存不足;或者
/// 指定文件为 FIFO,且达到每用户
/// 管道内存分配的硬限制。
SystemResources,
/// 文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。
///
FileTooBig,
/// 以下任一情况:
/// * 路径指向目录,但请求了写权限。
/// * 路径指向目录,但 `allow_directory` 被设为 false。
IsDir,
/// 设备没有空间容纳新文件,无法创建新路径。
/// 仅在提供 `CREAT` 标志时才可能出现此错误。
NoSpaceLeft,
/// 路径中用作目录的某个部分实际上不是目录,
/// 或者指定了 `DIRECTORY`,但路径不是目录。
NotDir,
/// 路径已存在,且提供了 `CREAT` 和 `EXCL` 标志。
PathAlreadyExists,
ReadOnlyFileSystem,
DeviceBusy,
FileLocksUnsupported,
/// 以下三种情况之一:
/// * pathname 指向正在执行的可执行映像,
/// 且请求写访问。
/// * pathname 指向当前用作交换
/// 文件的文件,且指定了 O_TRUNC 标志。
/// * pathname 指向内核正在读取的文件,
/// 例如用于加载模块或固件,且请求
/// 写访问。
FileBusy,
/// 已请求非阻塞模式,但该操作无法立即返回。
WouldBlock,
} || Dir.PathNameError || Io.Cancelable || Io.UnexpectedError;
pub fn close(file: File, io: Io) void {
return io.vtable.fileClose(io.userdata, (&file)[0..1]);
}
pub fn closeMany(io: Io, files: []const File) void {
return io.vtable.fileClose(io.userdata, files);
}
pub const SyncError = error{
InputOutput,
NoSpaceLeft,
DiskQuota,
AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;
/// 阻塞,直到此文件所有待处理的内容和元数据修改
/// 均与底层文件系统同步。
///
/// 不保证包含该文件的目录的元数据
/// 也已经写入磁盘。
pub fn sync(file: File, io: Io) SyncError!void {
return io.vtable.fileSync(io.userdata, file);
}
/// 测试文件是否指向终端(类似于 libc 的 "isatty")。
///
/// 另见:
/// * `enableAnsiEscapeCodes`
/// * `supportsAnsiEscapeCodes`。
pub fn isTty(file: File, io: Io) Io.Cancelable!bool {
return io.vtable.fileIsTty(io.userdata, file);
}
pub const EnableAnsiEscapeCodesError = error{
NotTerminalDevice,
} || Io.Cancelable || Io.UnexpectedError;
pub fn enableAnsiEscapeCodes(file: File, io: Io) EnableAnsiEscapeCodesError!void {
return io.vtable.fileEnableAnsiEscapeCodes(io.userdata, file);
}
/// 测试 ANSI 转义码是否会被当作转义码处理,
/// 但不尝试启用 ANSI 转义码支持。
pub fn supportsAnsiEscapeCodes(file: File, io: Io) Io.Cancelable!bool {
return io.vtable.fileSupportsAnsiEscapeCodes(io.userdata, file);
}
pub const SetLengthError = error{
FileTooBig,
InputOutput,
FileBusy,
AccessDenied,
PermissionDenied,
NonResizable,
} || Io.Cancelable || Io.UnexpectedError;
/// 截短或扩展文件,新增数据填零。
///
/// 调用后文件偏移量保持不变。
///
/// 此函数操作已打开的文件句柄。`Dir` 中没有
/// 按路径操作的等效函数,因为这种
/// 功能通常会引入检查时间与使用时间之间的竞态,即 TOCTOU。
/// 在确实需要此语义的少数情况下,可以
/// 使用截短标志打开文件。
pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void {
return io.vtable.fileSetLength(io.userdata, file, new_length);
}
pub const LengthError = StatError;
/// 获取文件末尾的字节索引。
///
/// 若只需长度,有时比 `stat` 开销更低。
pub fn length(file: File, io: Io) LengthError!u64 {
return io.vtable.fileLength(io.userdata, file);
}
pub const SetPermissionsError = error{
AccessDenied,
PermissionDenied,
InputOutput,
SymLinkLoop,
FileNotFound,
SystemResources,
ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;
/// 又称“chmod”。
///
/// 进程必须具有适当权限,或者有效用户 ID
/// 必须与文件所有者匹配,
/// 才能成功执行。
pub fn setPermissions(file: File, io: Io, new_permissions: Permissions) SetPermissionsError!void {
return io.vtable.fileSetPermissions(io.userdata, file, new_permissions);
}
pub const SetOwnerError = error{
AccessDenied,
PermissionDenied,
InputOutput,
SymLinkLoop,
FileNotFound,
SystemResources,
ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;
/// 也称为“chown”。
///
/// 进程必须具备相应权限才能成功执行此操作。
/// 文件所有者可将所属组改为自己所属的任意组。
/// 若所有者或所属组指定为
/// `null`,则不更改对应标识。
pub fn setOwner(file: File, io: Io, owner: ?Uid, group: ?Gid) SetOwnerError!void {
return io.vtable.fileSetOwner(io.userdata, file, owner, group);
}
/// 文件权限的跨平台表示。
///
/// POSIX 系统中对应“mode”,Windows 中对应“attributes”。
pub const Permissions = std.Options.FilePermissions orelse if (is_windows) enum(std.os.windows.DWORD) {
default_file = 0,
_,
pub const default_dir: @This() = .default_file;
pub const executable_file: @This() = .default_file;
pub const has_executable_bit = false;
const windows = std.os.windows;
pub fn toAttributes(self: @This()) windows.FILE.ATTRIBUTE {
return @bitCast(@backingInt(self));
}
pub fn readOnly(self: @This()) bool {
const attributes = toAttributes(self);
return attributes & windows.FILE_ATTRIBUTE_READONLY != 0;
}
pub fn setReadOnly(self: @This(), read_only: bool) @This() {
const attributes = toAttributes(self);
return @fromBackingInt(@intCast(if (read_only)
attributes | windows.FILE_ATTRIBUTE_READONLY
else
attributes & ~@as(windows.DWORD, windows.FILE_ATTRIBUTE_READONLY)));
}
} else if (std.posix.mode_t != u0) enum(std.posix.mode_t) {
/// 这是在 POSIX 操作系统上创建
/// 文件时使用的默认模式。`0o666` 表示 "-rw-rw-rw-",乍看违反直觉,
/// 因为多数人会期望 "-rw-r--r--",例如使用
/// `touch` 命令时,该权限对应 `0o644`。但 POSIX
/// libc 实现将 `0o666` 用于 `fopen`,再依赖
/// 进程级的 "umask" 设置调整创建文件时的权限值。
default_file = 0o666,
/// 这是在 POSIX 操作系统上创建目录时传递的
/// 默认权限模式。`0o777` 为“-rwxrwxrwx”,初看可能不合直觉,
/// 因为多数人期望的是“-rwxr-xr-x”,例如使用
/// `touch` 命令时,对应 `0o755`。
default_dir = 0o777,
_,
pub const has_executable_bit = native_os != .wasi;
pub const executable_file: @This() = .default_dir;
pub fn toMode(self: @This()) std.posix.mode_t {
return @backingInt(self);
}
pub fn fromMode(mode: std.posix.mode_t) @This() {
return @fromBackingInt(@intCast(mode));
}
/// 当且仅当所有权限类别均无写权限时返回 `true`。
pub fn readOnly(self: @This()) bool {
const mode = toMode(self);
return mode & 0o222 == 0;
}
/// 为所有用户类别启用写权限。
pub fn setReadOnly(self: @This(), read_only: bool) @This() {
const mode = toMode(self);
const o222 = @as(std.posix.mode_t, 0o222);
return @fromBackingInt(@intCast(if (read_only) mode & ~o222 else mode | o222));
}
} else enum(u0) {
default_file = 0,
pub const default_dir: @This() = .default_file;
pub const executable_file: @This() = .default_file;
pub const has_executable_bit = false;
};
pub const SetTimestampsError = error{
/// times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:
/// * 调用方的有效用户标识符与文件
/// 所有者不匹配,调用方不具有该文件的
/// 写入权限,且调用方不具有特权;Linux 上即不具备
/// CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力;
/// 或者,
/// * 文件被标记为不可变,参见 chattr(1)。
AccessDenied,
/// 调用方尝试将一个或两个时间戳设置为当前时间
/// 以外的值,或将一个时间戳
/// 设为当前时间而保持另一个不变,
/// 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW,
/// 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:
/// * 调用方的有效用户 ID 不等于文件
/// 所有者,且调用方无特权;Linux 上
/// 指不具备 CAP_FOWNER 能力。
/// * 文件被标记为仅追加或不可变,参见 chattr(1)。
PermissionDenied,
ReadOnlyFileSystem,
} || Io.Cancelable || Io.UnexpectedError;
pub const SetTimestampsOptions = struct {
access_timestamp: SetTimestamp = .unchanged,
modify_timestamp: SetTimestamp = .unchanged,
};
pub const SetTimestamp = union(enum) {
/// 保持现有时间戳不变。
unchanged,
/// 使用 `Io.Clock.real` 设置为当前时间。
now,
/// 使用 `Io.Clock.real` 设置为提供的时间戳。
new: Io.Timestamp,
/// 便于与 `Stat` 交互,其中 `null` 表示 `unchanged`。
pub fn init(optional: ?Io.Timestamp) SetTimestamp {
return if (optional) |t| .{ .new = t } else .unchanged;
}
};
/// 最终存储的时间粒度取决于操作系统
/// 与文件系统的组合。若提供的值超出此范围,
/// 则将其限制为最大值。
pub fn setTimestamps(file: File, io: Io, options: SetTimestampsOptions) SetTimestampsError!void {
return io.vtable.fileSetTimestamps(io.userdata, file, options);
}
/// 将 `file` 的访问时间戳和修改时间戳设置为当前
/// 挂钟时间。
///
/// 最终存储的时间粒度由操作系统与
/// 文件系统的组合决定。
pub fn setTimestampsNow(file: File, io: Io) SetTimestampsError!void {
return io.vtable.fileSetTimestamps(io.userdata, file, .{
.access_timestamp = .now,
.modify_timestamp = .now,
});
}
pub const ReadStreamingError = error{EndOfStream} || Reader.Error;
/// 返回字节数可能少于缓冲区可用空间,包括 0。
/// 流结束以 `error.EndOfStream` 表示。
///
/// 另请参见:
/// * `reader`
pub fn readStreaming(file: File, io: Io, buffer: []const []u8) ReadStreamingError!usize {
return (try io.operate(.{ .file_read_streaming = .{
.file = file,
.data = buffer,
} })).file_read_streaming;
}
pub const ReadPositionalError = error{
InputOutput,
SystemResources,
/// 尝试将目录文件描述符当作普通文件读取。
IsDir,
/// 已启用非阻塞模式,且从该文件描述符读取会阻塞。
///
WouldBlock,
/// 在 WASI 中,当文件描述符不具有读取
/// 所需的权限时发生此错误。
AccessDenied,
/// 由于锁定而无法读取文件。根据 `Io` 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。
///
///
LockViolation,
/// 此文件不支持按位置读取。
Unseekable,
/// 打开文件时未授予读取能力。
NotOpenForReading,
} || Io.Cancelable || Io.UnexpectedError;
/// 流结束或 `buffer` 没有可用空间时返回 0。
///
/// 另请参见:
/// * `reader`
pub fn readPositional(file: File, io: Io, buffer: []const []u8, offset: u64) ReadPositionalError!usize {
return io.vtable.fileReadPositional(io.userdata, file, buffer, offset);
}
pub const WritePositionalError = error{
DiskQuota,
FileTooBig,
InputOutput,
NoSpaceLeft,
DeviceBusy,
/// 文件描述符没有写入所需的权限。
AccessDenied,
PermissionDenied,
/// 文件为未连接的套接字,或其读取端已关闭。
BrokenPipe,
/// 内核内存不足,无法从 in_fd 读取。
SystemResources,
/// 进程无法访问文件,因为另一进程已锁定
/// 文件的一部分。仅限 Windows。
LockViolation,
/// 已启用非阻塞模式,而此操作将阻塞。
WouldBlock,
/// 写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
///
NoDevice,
FileBusy,
/// 无法对该文件按指定位置写入。
Unseekable,
/// 文件打开时没有写入能力。
NotOpenForWriting,
} || Io.Cancelable || Io.UnexpectedError;
/// 另请参见:
/// * `writer`
pub fn writePositional(file: File, io: Io, buffer: []const []const u8, offset: u64) WritePositionalError!usize {
return io.vtable.fileWritePositional(io.userdata, file, &.{}, buffer, 1, offset);
}
/// 等同于创建位置写入器、写入 `bytes`,然后刷新。
pub fn writePositionalAll(file: File, io: Io, bytes: []const u8, offset: u64) WritePositionalError!void {
var index: usize = 0;
while (index < bytes.len)
index += try io.vtable.fileWritePositional(io.userdata, file, &.{}, &.{bytes[index..]}, 1, offset + index);
}
pub const SeekError = error{
Unseekable,
/// 文件描述符不具备执行定位所需的权限。
AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;
pub const WriteFilePositionalError = Writer.WriteFileError || error{Unseekable};
/// 默认使用定位读取,失败时回退到流式读取。
///
/// 定位读取不影响全局查找位置,因此线程安全性
/// 更高。
///
/// 另见:
/// * `readerStreaming`
pub fn reader(file: File, io: Io, buffer: []u8) Reader {
return .init(file, io, buffer);
}
/// 等价于创建定位读取器并多次读取,以填满 `buffer`。
///
/// 返回读入 `buffer` 的字节数。若小于 `buffer.len`,表示到达文件末尾。
///
/// 另见:
/// * `reader`
pub fn readPositionalAll(file: File, io: Io, buffer: []u8, offset: u64) ReadPositionalError!usize {
var index: usize = 0;
while (index != buffer.len) {
const amt = try file.readPositional(io, &.{buffer[index..]}, offset + index);
if (amt == 0) break;
index += amt;
}
return index;
}
/// 定位读取不会影响全局查找位置,因此更便于线程安全使用。
/// 但若相应系统调用不可用,则预先初始化为
/// 流式模式可以省去一次失败的系统调用。
///
/// 另见:
/// * `reader`
pub fn readerStreaming(file: File, io: Io, buffer: []u8) Reader {
return .initStreaming(file, io, buffer);
}
/// 默认采用定位读取;不可用时退回流式读取。
///
/// 定位读取不影响全局查找位置,
/// 因此更便于线程安全使用。
pub fn writer(file: File, io: Io, buffer: []u8) Writer {
return .init(file, io, buffer);
}
/// 定位读取不影响全局查找位置,因此更便于线程安全使用。
/// 但若相应系统调用不可用,则预先初始化为
/// 流式模式可省去一次失败的系统调用。
pub fn writerStreaming(file: File, io: Io, buffer: []u8) Writer {
return .initStreaming(file, io, buffer);
}
/// 这是直接调用 `Io` 接口函数的底层 API。
/// 更高层 API 参见 `writerStreaming`。
pub fn writeStreaming(file: File, io: Io, header: []const u8, data: []const []const u8, splat: usize) Writer.Error!usize {
return (try io.operate(.{ .file_write_streaming = .{
.file = file,
.header = header,
.data = data,
.splat = splat,
} })).file_write_streaming;
}
/// 等同于创建流式写入器、写入 `bytes`,然后刷新。
pub fn writeStreamingAll(file: File, io: Io, bytes: []const u8) Writer.Error!void {
var index: usize = 0;
while (index < bytes.len) {
index += try writeStreaming(file, io, &.{}, &.{bytes[index..]}, 1);
}
}
pub const LockError = error{
SystemResources,
FileLocksUnsupported,
} || Io.Cancelable || Io.UnexpectedError;
/// 其他进程持有不兼容的锁时阻塞。一个进程对某文件
/// 只能持有一种锁,共享锁或独占锁。进程
/// 以任何方式终止时,锁都会释放。
///
/// 假定文件未锁定。
pub fn lock(file: File, io: Io, l: Lock) LockError!void {
return io.vtable.fileLock(io.userdata, file, l);
}
/// 假定文件已加锁。
pub fn unlock(file: File, io: Io) void {
return io.vtable.fileUnlock(io.userdata, file);
}
/// 尝试获取锁。获得锁时返回 `true`,若已有其他不兼容的锁被持有,则返回 `false`。
/// 进程只能对同一文件持有一种锁,共享锁或排他锁。进程以任意方式结束时,锁都会释放。
///
/// 假定文件当前未锁定。
///
///
pub fn tryLock(file: File, io: Io, l: Lock) LockError!bool {
return io.vtable.fileTryLock(io.userdata, file, l);
}
pub const DowngradeLockError = Io.Cancelable || Io.UnexpectedError;
/// 假定文件已处于独占锁定模式。
/// 以原子方式将锁改为共享模式,而不释放锁。
pub fn downgradeLock(file: File, io: Io) LockError!void {
return io.vtable.fileDowngradeLock(io.userdata, file);
}
pub const RealPathError = error{
/// 此操作系统、文件系统或 `Io` 实现
/// 不支持 realpath 操作。
OperationUnsupported,
/// 完整文件系统路径无法放入所提供的缓冲区,或
/// 由于路径过长,无论提供多大的缓冲区,
/// 均无法通过 realpath 函数获取。
NameTooLong,
FileNotFound,
AccessDenied,
PermissionDenied,
NotDir,
SymLinkLoop,
InputOutput,
FileTooBig,
IsDir,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
NoDevice,
SystemResources,
NoSpaceLeft,
FileSystem,
DeviceBusy,
FileBusy,
PipeBusy,
/// 在 Windows 上,未找到 `\\server` 或 `\\server\share`。
NetworkNotFound,
PathAlreadyExists,
/// Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。
/// 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。
///
///
///
AntivirusInterference,
/// 在 Windows 上,卷不包含可识别的文件系统。文件
/// 系统驱动可能未加载,或卷可能已损坏。
UnrecognizedVolume,
} || Io.Cancelable || Io.UnexpectedError;
/// 获取与打开的文件句柄对应的规范化绝对路径名。
///
/// 此函数的平台支持有限,使用它可能导致
/// 不必要的失败和竞态条件。通常建议
/// 完全避免使用此函数。
///
pub fn realPath(file: File, io: Io, out_buffer: []u8) RealPathError!usize {
return io.vtable.fileRealPath(io.userdata, file, out_buffer);
}
pub const HardLinkOptions = struct {
follow_symlinks: bool = false,
};
pub const HardLinkError = error{
AccessDenied,
PermissionDenied,
DiskQuota,
PathAlreadyExists,
HardwareFailure,
/// 操作系统或文件系统不支持硬链接。
OperationUnsupported,
SymLinkLoop,
LinkQuotaExceeded,
FileNotFound,
SystemResources,
NoSpaceLeft,
ReadOnlyFileSystem,
CrossDevice,
NotDir,
} || Io.Cancelable || Dir.PathNameError || Io.UnexpectedError;
pub fn hardLink(
file: File,
io: Io,
new_dir: Dir,
new_sub_path: []const u8,
options: HardLinkOptions,
) HardLinkError!void {
return io.vtable.fileHardLink(io.userdata, file, new_dir, new_sub_path, options);
}
pub fn createMemoryMap(file: File, io: Io, options: MemoryMap.CreateOptions) MemoryMap.CreateError!MemoryMap {
return .create(io, file, options);
}
test {
_ = Reader;
_ = Writer;
_ = Atomic;
_ = MemoryMap;
}