Skip to content

std.Io.File.MemoryMap

Standard libraryZig 0.17.0Official documentation
Sourcestd/Io/File/MemoryMap.zig

Source line 1

Fields

file: File
offset: u64

Byte index inside file where memory starts. Page-aligned.

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

Memory that may or may not remain consistent with file contents. Use read and write to ensure synchronization points. Length has no alignment requirement.

section: ?Section

Tells whether it is memory-mapped or file operations. On Windows this also has a section handle.

std.Io.File.MemoryMap.Allocator

alias

Source line 10

Alias of std.mem.Allocator

std.Io.File.MemoryMap.builtin

constant

Source line 3

std.Io.File.MemoryMap.create

function

Source line 66

To release the resources associated with the returned MemoryMap, call destroy.

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

Parameters

io: Io
file: File
options: CreateOptions

Errors

AccessDenied

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.
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 Io implementation, 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 prot argument asks for PROT_EXEC but 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

Source line 25

Errors

AccessDenied

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.
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 Io implementation, 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 prot argument asks for PROT_EXEC but 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

Source line 39

Fields

len: usize

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.

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 = false

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.

populate: bool = true

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.

offset: u64 = 0

Asserted to be a multiple of page size which can be obtained via std.heap.pageSize.

std.Io.File.MemoryMap.destroy

function

Source line 72

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

mm: *MemoryMap
io: Io

std.Io.File.MemoryMap.File

alias

Source line 9

Alias of std.Io.File

std.Io.File.MemoryMap.Io

alias

Source line 8

Alias of std.Io

std.Io.File.MemoryMap.is_windows

constant

Source line 5

std.Io.File.MemoryMap.MemoryMap

alias

Source line 1

Alias of std.Io.File.MemoryMap

std.Io.File.MemoryMap.native_os

constant

Source line 4

std.Io.File.MemoryMap.read

function

Source line 102

Synchronizes the contents of memory from file.

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

Parameters

mm: *MemoryMap
io: Io

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 Io implementation, 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

Source line 23

std.Io.File.MemoryMap.setLength

function

Source line 97

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

mm: *MemoryMap
io: Io
new_len: usize

Errors

AccessDenied

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.
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 destroy and create to resize the mapping.

OutOfMemory Error
PermissionDenied

The prot argument asks for PROT_EXEC but 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

Source line 76

Errors

AccessDenied

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.
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 destroy and create to resize the mapping.

OutOfMemory Error
PermissionDenied

The prot argument asks for PROT_EXEC but 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

Source line 7

Alias of std

std.Io.File.MemoryMap.write

function

Source line 111

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

mm: *MemoryMap
io: Io

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