Fields
file: File
offset: u64Byte index inside file where memory starts. Page-aligned.
memory: []align(std.heap.page_size_min) u8Memory that may or may not remain consistent with file contents. Use read
and write to ensure synchronization points. Length has no alignment
requirement.
section: ?SectionTells whether it is memory-mapped or file operations. On Windows this also has a section handle.
std.Io.File.MemoryMap.Allocator
alias
Alias of std.mem.Allocator
std.Io.File.MemoryMap.builtin
constant
std.Io.File.MemoryMap.create
function
pub fn create(io: Io, file: File, options: CreateOptions) CreateError!MemoryMap
Parameters
Errors
- AccessDenied
One of the following:
- The
File.Kindis notfile. - The file is not open for reading and read access protections enabled.
- The file is not open for writing and write access protections enabled.
- The
- Canceled Cancelable
Caller has requested the async operation to stop.
- InputOutput ReadPositionalError
- IsDir ReadPositionalError
Trying to read a directory file descriptor as if it were a file.
- LockViolation ReadPositionalError
Unable to read file due to lock. Depending on the
Ioimplementation, reading from a locked file may return this error, or may ignore the lock.- LockedMemoryLimitExceeded
- NotOpenForReading ReadPositionalError
File was not opened with read capability.
- OutOfMemory Error
- PermissionDenied
The
protargument asks forPROT_EXECbut the mapped area belongs to a file on a filesystem that was mounted no-exec.- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- SystemResources ReadPositionalError
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
- Unseekable ReadPositionalError
This file cannot be read positionally.
- WouldBlock ReadPositionalError
Non-blocking has been enabled, and reading from the file descriptor would block.
std.Io.File.MemoryMap.CreateError
error-set
Errors
- AccessDenied
One of the following:
- The
File.Kindis notfile. - The file is not open for reading and read access protections enabled.
- The file is not open for writing and write access protections enabled.
- The
- Canceled Cancelable
Caller has requested the async operation to stop.
- InputOutput ReadPositionalError
- IsDir ReadPositionalError
Trying to read a directory file descriptor as if it were a file.
- LockViolation ReadPositionalError
Unable to read file due to lock. Depending on the
Ioimplementation, reading from a locked file may return this error, or may ignore the lock.- LockedMemoryLimitExceeded
- NotOpenForReading ReadPositionalError
File was not opened with read capability.
- OutOfMemory Error
- PermissionDenied
The
protargument asks forPROT_EXECbut the mapped area belongs to a file on a filesystem that was mounted no-exec.- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- SystemResources ReadPositionalError
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
- Unseekable ReadPositionalError
This file cannot be read positionally.
- WouldBlock ReadPositionalError
Non-blocking has been enabled, and reading from the file descriptor would block.
std.Io.File.MemoryMap.CreateOptions
container
Fields
len: usizeSize of the mapping, in bytes. If this is longer than the file size,
memory beyond the file end will be filled with zeroes and it is
unspecified whether, after calling write, the file length will be
set to len or remain unchanged.
This value has no minimum alignment requirement, but may gain
efficiency benefits from being a multiple of File.Stat.block_size.
protection: std.process.MemoryProtection = .{ .read = true, .write = true }When this has read set to false, bytes that are not modified before a sync may have the original file contents, or may be set to zero.
undefined_contents: bool = falseIf set to true, allows bytes observed before calling read to be
undefined, and bytes unwritten before calling write to write
undefined memory to the file.
populate: bool = truePrefault the pages. If this option is unsupported, it is silently ignored. Aside from custom Io implementations, this option is only supported on Linux and Windows.
offset: u64 = 0Asserted to be a multiple of page size which can be obtained via
std.heap.pageSize.
std.Io.File.MemoryMap.destroy
function
If write is not called before this function, changes to memory may or may
not be synchronized to file.
pub fn destroy(mm: *MemoryMap, io: Io) void
Parameters
std.Io.File.MemoryMap.File
alias
Alias of std.Io.File
std.Io.File.MemoryMap.Io
alias
Alias of std.Io
std.Io.File.MemoryMap.is_windows
constant
std.Io.File.MemoryMap.MemoryMap
alias
Alias of std.Io.File.MemoryMap
std.Io.File.MemoryMap.native_os
constant
std.Io.File.MemoryMap.read
function
Synchronizes the contents of memory from file.
pub fn read(mm: *MemoryMap, io: Io) File.ReadPositionalError!void
Parameters
Errors
- AccessDenied
In WASI, this error occurs when the file descriptor does not hold the required rights to read from it.
- Canceled Cancelable
Caller has requested the async operation to stop.
- InputOutput
- IsDir
Trying to read a directory file descriptor as if it were a file.
- LockViolation
Unable to read file due to lock. Depending on the
Ioimplementation, reading from a locked file may return this error, or may ignore the lock.- NotOpenForReading
File was not opened with read capability.
- SystemResources
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
- Unseekable
This file cannot be read positionally.
- WouldBlock
Non-blocking has been enabled, and reading from the file descriptor would block.
std.Io.File.MemoryMap.Section
type
std.Io.File.MemoryMap.setLength
function
Change the size of the mapping. This does not sync the contents. The size
of the file after calling this is unspecified until write is called.
May change the pointer address of memory.
pub fn setLength(mm: *MemoryMap, io: Io, new_len: usize) SetLengthError!void
Parameters
Errors
- AccessDenied
One of the following:
- The
File.Kindis notfile. - The file is not open for reading and read access protections enabled.
- The file is not open for writing and write access protections enabled.
- The
- Canceled Cancelable
Caller has requested the async operation to stop.
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
Changing the mapping length could not be done atomically. Caller must use
destroyandcreateto resize the mapping.- OutOfMemory Error
- PermissionDenied
The
protargument asks forPROT_EXECbut the mapped area belongs to a file on a filesystem that was mounted no-exec.- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
std.Io.File.MemoryMap.SetLengthError
error-set
Errors
- AccessDenied
One of the following:
- The
File.Kindis notfile. - The file is not open for reading and read access protections enabled.
- The file is not open for writing and write access protections enabled.
- The
- Canceled Cancelable
Caller has requested the async operation to stop.
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
Changing the mapping length could not be done atomically. Caller must use
destroyandcreateto resize the mapping.- OutOfMemory Error
- PermissionDenied
The
protargument asks forPROT_EXECbut the mapped area belongs to a file on a filesystem that was mounted no-exec.- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
std.Io.File.MemoryMap.std
alias
Alias of std
std.Io.File.MemoryMap.write
function
Synchronizes the contents of memory to file.
If memory.len is greater than file size, the bytes beyond the end of the
file may be dropped, or they may be written, extending the size of the
file.
pub fn write(mm: *MemoryMap, io: Io) File.WritePositionalError!void
Parameters
Errors
- AccessDenied
File descriptor does not hold the required rights to write to it.
- BrokenPipe
File is an unconnected socket, or closed its read end.
- Canceled Cancelable
Caller has requested the async operation to stop.
- DeviceBusy
- DiskQuota
- FileBusy
- FileTooBig
- InputOutput
- LockViolation
The process cannot access the file because another process has locked a portion of the file. Windows-only.
- NoDevice
This error occurs when a device gets disconnected before or mid-flush while it's being written to - errno(6): No such device or address.
- NoSpaceLeft
- NotOpenForWriting
File was not opened with write capability.
- PermissionDenied
- SystemResources
Insufficient kernel memory to read from in_fd.
- Unexpected UnexpectedError
The Operating System returned an undocumented error code.
This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.
When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.
- Unseekable
This file cannot be written positionally.
- WouldBlock
Non-blocking has been enabled and this operation would block.
Source code
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,
/// Byte index inside `file` where `memory` starts. Page-aligned.
offset: u64,
/// Memory that may or may not remain consistent with file contents. Use `read`
/// and `write` to ensure synchronization points. Length has no alignment
/// requirement.
memory: []align(std.heap.page_size_min) u8,
/// Tells whether it is memory-mapped or file operations. On Windows this also
/// has a section handle.
section: ?Section,
pub const Section = if (is_windows) std.os.windows.HANDLE else void;
pub const CreateError = error{
/// One of the following:
/// * The `File.Kind` is not `file`.
/// * The file is not open for reading and read access protections enabled.
/// * The file is not open for writing and write access protections enabled.
AccessDenied,
/// The `prot` argument asks for `PROT_EXEC` but the mapped area belongs to a file on
/// a filesystem that was mounted no-exec.
PermissionDenied,
LockedMemoryLimitExceeded,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
} || Allocator.Error || File.ReadPositionalError;
pub const CreateOptions = struct {
/// Size of the mapping, in bytes. If this is longer than the file size,
/// `memory` beyond the file end will be filled with zeroes and it is
/// unspecified whether, after calling `write`, the file length will be
/// set to `len` or remain unchanged.
///
/// This value has no minimum alignment requirement, but may gain
/// efficiency benefits from being a multiple of `File.Stat.block_size`.
len: usize,
/// When this has read set to false, bytes that are not modified before a
/// sync may have the original file contents, or may be set to zero.
protection: std.process.MemoryProtection = .{ .read = true, .write = true },
/// If set to `true`, allows bytes observed before calling `read` to be
/// undefined, and bytes unwritten before calling `write` to write
/// undefined memory to the file.
undefined_contents: bool = false,
/// Prefault the pages. If this option is unsupported, it is silently
/// ignored. Aside from custom Io implementations, this option is only
/// supported on Linux and Windows.
populate: bool = true,
/// Asserted to be a multiple of page size which can be obtained via
/// `std.heap.pageSize`.
offset: u64 = 0,
};
/// To release the resources associated with the returned `MemoryMap`, call
/// `destroy`.
pub fn create(io: Io, file: File, options: CreateOptions) CreateError!MemoryMap {
return io.vtable.fileMemoryMapCreate(io.userdata, file, options);
}
/// If `write` is not called before this function, changes to `memory` may or may
/// not be synchronized to `file`.
pub fn destroy(mm: *MemoryMap, io: Io) void {
io.vtable.fileMemoryMapDestroy(io.userdata, mm);
}
pub const SetLengthError = error{
/// Changing the mapping length could not be done atomically. Caller must
/// use `destroy` and `create` to resize the mapping.
OperationUnsupported,
/// One of the following:
/// * The `File.Kind` is not `file`.
/// * The file is not open for reading and read access protections enabled.
/// * The file is not open for writing and write access protections enabled.
AccessDenied,
/// The `prot` argument asks for `PROT_EXEC` but the mapped area belongs to a file on
/// a filesystem that was mounted no-exec.
PermissionDenied,
LockedMemoryLimitExceeded,
ProcessFdQuotaExceeded,
SystemFdQuotaExceeded,
} || Allocator.Error || File.SetLengthError;
/// Change the size of the mapping. This does not sync the contents. The size
/// of the file after calling this is unspecified until `write` is called.
///
/// May change the pointer address of `memory`.
pub fn setLength(mm: *MemoryMap, io: Io, new_len: usize) SetLengthError!void {
return io.vtable.fileMemoryMapSetLength(io.userdata, mm, new_len);
}
/// Synchronizes the contents of `memory` from `file`.
pub fn read(mm: *MemoryMap, io: Io) File.ReadPositionalError!void {
return io.vtable.fileMemoryMapRead(io.userdata, mm);
}
/// Synchronizes the contents of `memory` to `file`.
///
/// If `memory.len` is greater than file size, the bytes beyond the end of the
/// file may be dropped, or they may be written, extending the size of the
/// file.
pub fn write(mm: *MemoryMap, io: Io) File.WritePositionalError!void {
return io.vtable.fileMemoryMapWrite(io.userdata, mm);
}