字段
file: File
offset: u64memory 在 file 内的起始字节索引。按页对齐。
memory: []align(std.heap.page_size_min) u8
section: ?Section表示使用内存映射还是文件操作。在 Windows 上还 包含节句柄。
std.Io.File.MemoryMap.Allocator
别名
别名目标 std.mem.Allocator
std.Io.File.MemoryMap.builtin
常量
std.Io.File.MemoryMap.create
函数
pub fn create(io: Io, file: File, options: CreateOptions) 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.MemoryMap.CreateError
错误集合
错误
- 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.MemoryMap.CreateOptions
容器
字段
len: usize映射大小,以字节为单位。如果超过文件大小,
memory 中超出文件末尾的部分填零;调用 write 后
文件长度会设置为 len 还是保持不变,
没有规定。
此值没有最小对齐要求,但若为
File.Stat.block_size 的整数倍,可能提高效率。
protection: std.process.MemoryProtection = .{ .read = true, .write = true }当 read 设为 false 时,同步前未修改的字节 可能保留原文件内容,也可能被置零。
undefined_contents: bool = false
populate: bool = true预先触发页面缺页处理。若不支持此选项,则静默 忽略。除自定义 Io 实现外,此选项仅在 Linux 和 Windows 上受支持。
offset: u64 = 0断言为页大小的整数倍,
页大小可通过 std.heap.pageSize 获取。
std.Io.File.MemoryMap.destroy
函数
如果未在此函数之前调用 write,则 memory 的更改可能
同步到 file,也可能不同步。
pub fn destroy(mm: *MemoryMap, io: Io) void
参数
std.Io.File.MemoryMap.File
别名
别名目标 std.Io.File
std.Io.File.MemoryMap.Io
别名
别名目标 std.Io
std.Io.File.MemoryMap.is_windows
常量
std.Io.File.MemoryMap.MemoryMap
别名
std.Io.File.MemoryMap.native_os
常量
std.Io.File.MemoryMap.read
函数
将 file 的内容同步到 memory。
pub fn read(mm: *MemoryMap, io: Io) File.ReadPositionalError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.File.MemoryMap.Section
类型
std.Io.File.MemoryMap.setLength
函数
改变映射大小,不同步内容。调用后,
在调用 write 之前,文件大小未指定。
可能改变 memory 的指针地址。
pub fn setLength(mm: *MemoryMap, io: Io, new_len: usize) SetLengthError!void
参数
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.MemoryMap.SetLengthError
错误集合
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.File.MemoryMap.std
别名
别名目标 std
std.Io.File.MemoryMap.write
函数
将 memory 的内容同步到 file。
若 memory.len 大于文件大小,文件末尾以外的
字节可能被丢弃,也可能被写入,
使文件扩展。
pub fn write(mm: *MemoryMap, io: Io) File.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/MemoryMap.zig
const MemoryMap = @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 File = Io.File;
const Allocator = std.mem.Allocator;
file: File,
/// `memory` 在 `file` 内的起始字节索引。按页对齐。
offset: u64,
/// 内存内容可能与文件内容保持一致,也可能不一致。使用 `read`
/// 和 `write` 确保同步点。长度不要求对齐。
///
memory: []align(std.heap.page_size_min) u8,
/// 表示使用内存映射还是文件操作。在 Windows 上还
/// 包含节句柄。
section: ?Section,
pub const Section = if (is_windows) std.os.windows.HANDLE else void;
pub const CreateError = error{
/// 以下任一情况:
/// * `File.Kind` 不是 `file`。
/// * 文件未以读取方式打开,且启用了读取访问保护。
/// * 文件未以写入方式打开,且启用了写入访问保护。
AccessDenied,
/// `prot` 参数请求 `PROT_EXEC`,但映射区域属于
/// 挂载为禁止执行的文件系统中的文件。
PermissionDenied,
LockedMemoryLimitExceeded,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
} || Allocator.Error || File.ReadPositionalError;
pub const CreateOptions = struct {
/// 映射大小,以字节为单位。如果超过文件大小,
/// `memory` 中超出文件末尾的部分填零;调用 `write` 后
/// 文件长度会设置为 `len` 还是保持不变,
/// 没有规定。
///
/// 此值没有最小对齐要求,但若为
/// `File.Stat.block_size` 的整数倍,可能提高效率。
len: usize,
/// 当 read 设为 false 时,同步前未修改的字节
/// 可能保留原文件内容,也可能被置零。
protection: std.process.MemoryProtection = .{ .read = true, .write = true },
/// 若设为 `true`,则允许调用 `read` 之前观察到的字节
/// 为未定义值;也允许将调用 `write` 之前尚未写入的字节
/// 作为未定义内存写入文件。
undefined_contents: bool = false,
/// 预先触发页面缺页处理。若不支持此选项,则静默
/// 忽略。除自定义 Io 实现外,此选项仅在
/// Linux 和 Windows 上受支持。
populate: bool = true,
/// 断言为页大小的整数倍,
/// 页大小可通过 `std.heap.pageSize` 获取。
offset: u64 = 0,
};
/// 要释放返回的 `MemoryMap` 关联的资源,请调用
/// `destroy`。
pub fn create(io: Io, file: File, options: CreateOptions) CreateError!MemoryMap {
return io.vtable.fileMemoryMapCreate(io.userdata, file, options);
}
/// 如果未在此函数之前调用 `write`,则 `memory` 的更改可能
/// 同步到 `file`,也可能不同步。
pub fn destroy(mm: *MemoryMap, io: Io) void {
io.vtable.fileMemoryMapDestroy(io.userdata, mm);
}
pub const SetLengthError = error{
/// 无法原子地更改映射长度。调用方必须
/// 使用 `destroy` 和 `create` 调整映射大小。
OperationUnsupported,
/// 以下任一情况:
/// * `File.Kind` 不是 `file`。
/// * 文件未以读取方式打开,且启用了读取访问保护。
/// * 文件未以写入方式打开,且启用了写入访问保护。
AccessDenied,
/// `prot` 参数请求 `PROT_EXEC`,但映射区域属于
/// 挂载为禁止执行的文件系统中的文件。
PermissionDenied,
LockedMemoryLimitExceeded,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
} || Allocator.Error || File.SetLengthError;
/// 改变映射大小,不同步内容。调用后,
/// 在调用 `write` 之前,文件大小未指定。
///
/// 可能改变 `memory` 的指针地址。
pub fn setLength(mm: *MemoryMap, io: Io, new_len: usize) SetLengthError!void {
return io.vtable.fileMemoryMapSetLength(io.userdata, mm, new_len);
}
/// 将 `file` 的内容同步到 `memory`。
pub fn read(mm: *MemoryMap, io: Io) File.ReadPositionalError!void {
return io.vtable.fileMemoryMapRead(io.userdata, mm);
}
/// 将 `memory` 的内容同步到 `file`。
///
/// 若 `memory.len` 大于文件大小,文件末尾以外的
/// 字节可能被丢弃,也可能被写入,
/// 使文件扩展。
pub fn write(mm: *MemoryMap, io: Io) File.WritePositionalError!void {
return io.vtable.fileMemoryMapWrite(io.userdata, mm);
}