跳转到内容

std.Io.File.MemoryMap

标准库Zig 0.17.0官方原文
源码std/Io/File/MemoryMap.zig

第 1 行

字段

file: File
offset: u64

memory 在 file 内的起始字节索引。按页对齐。

memory: []align(std.heap.page_size_min) u8

内存内容可能与文件内容保持一致,也可能不一致。使用 read 和 write 确保同步点。长度不要求对齐。

section: ?Section

表示使用内存映射还是文件操作。在 Windows 上还 包含节句柄。

std.Io.File.MemoryMap.Allocator

别名

第 10 行

别名目标 std.mem.Allocator

std.Io.File.MemoryMap.builtin

常量

第 3 行

std.Io.File.MemoryMap.create

函数

第 66 行

要释放返回的 MemoryMap 关联的资源,请调用 destroy。

pub fn create(io: Io, file: File, options: CreateOptions) CreateError!MemoryMap

参数

io: Io
file: File
options: CreateOptions

错误

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

错误集合

第 25 行

错误

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

容器

第 39 行

字段

len: usize

映射大小,以字节为单位。如果超过文件大小, memory 中超出文件末尾的部分填零;调用 write 后 文件长度会设置为 len 还是保持不变, 没有规定。

此值没有最小对齐要求,但若为 File.Stat.block_size 的整数倍,可能提高效率。

protection: std.process.MemoryProtection = .{ .read = true, .write = true }

当 read 设为 false 时,同步前未修改的字节 可能保留原文件内容,也可能被置零。

undefined_contents: bool = false

若设为 true,则允许调用 read 之前观察到的字节 为未定义值;也允许将调用 write 之前尚未写入的字节 作为未定义内存写入文件。

populate: bool = true

预先触发页面缺页处理。若不支持此选项,则静默 忽略。除自定义 Io 实现外,此选项仅在 Linux 和 Windows 上受支持。

offset: u64 = 0

断言为页大小的整数倍, 页大小可通过 std.heap.pageSize 获取。

std.Io.File.MemoryMap.destroy

函数

第 72 行

如果未在此函数之前调用 write,则 memory 的更改可能 同步到 file,也可能不同步。

pub fn destroy(mm: *MemoryMap, io: Io) void

参数

mm: *MemoryMap
io: Io

std.Io.File.MemoryMap.File

别名

第 9 行

别名目标 std.Io.File

std.Io.File.MemoryMap.Io

别名

第 8 行

别名目标 std.Io

std.Io.File.MemoryMap.is_windows

常量

第 5 行

std.Io.File.MemoryMap.MemoryMap

别名

第 1 行

别名目标 std.Io.File.MemoryMap

std.Io.File.MemoryMap.native_os

常量

第 4 行

std.Io.File.MemoryMap.read

函数

第 102 行

将 file 的内容同步到 memory。

pub fn read(mm: *MemoryMap, io: Io) File.ReadPositionalError!void

参数

mm: *MemoryMap
io: Io

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.File.MemoryMap.Section

类型

第 23 行

std.Io.File.MemoryMap.setLength

函数

第 97 行

改变映射大小,不同步内容。调用后, 在调用 write 之前,文件大小未指定。

可能改变 memory 的指针地址。

pub fn setLength(mm: *MemoryMap, io: Io, new_len: usize) SetLengthError!void

参数

mm: *MemoryMap
io: Io
new_len: usize

错误

AccessDenied

以下任一情况:

  • File.Kind 不是 file。
  • 文件未以读取方式打开,且启用了读取访问保护。
  • 文件未以写入方式打开,且启用了写入访问保护。
Canceled Cancelable

调用方请求停止异步操作。

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
LockedMemoryLimitExceeded
NonResizable SetLengthError
OperationUnsupported

无法原子地更改映射长度。调用方必须 使用 destroy 和 create 调整映射大小。

OutOfMemory Error
PermissionDenied

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.MemoryMap.SetLengthError

错误集合

第 76 行

错误

AccessDenied

以下任一情况:

  • File.Kind 不是 file。
  • 文件未以读取方式打开,且启用了读取访问保护。
  • 文件未以写入方式打开,且启用了写入访问保护。
Canceled Cancelable

调用方请求停止异步操作。

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
LockedMemoryLimitExceeded
NonResizable SetLengthError
OperationUnsupported

无法原子地更改映射长度。调用方必须 使用 destroy 和 create 调整映射大小。

OutOfMemory Error
PermissionDenied

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.File.MemoryMap.std

别名

第 7 行

别名目标 std

std.Io.File.MemoryMap.write

函数

第 111 行

将 memory 的内容同步到 file。

若 memory.len 大于文件大小,文件末尾以外的 字节可能被丢弃,也可能被写入, 使文件扩展。

pub fn write(mm: *MemoryMap, io: Io) File.WritePositionalError!void

参数

mm: *MemoryMap
io: Io

错误

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);
}