Function mmap [src]

Map files or devices into memory. length does not need to be aligned. Use of a mapped region can result in these signals: SIGSEGV - Attempted write into a region mapped as read-only. SIGBUS - Attempted access to a portion of the buffer that does not correspond to the file

Prototype

 pub fn mmap( ptr: ?[*]align(page_size_min) u8, length: usize, prot: u32, flags: system.MAP, fd: fd_t, offset: u64, ) MMapError![]align(page_size_min) u8

Parameters

ptr: ?[*]align(page_size_min) u8length: usizeprot: u32flags: system.MAPfd: fd_toffset: u64

Possible Errors

AccessDenied

A file descriptor refers to a non-regular file. Or a file mapping was requested, but the file descriptor is not open for reading. Or MAP.SHARED was requested and PROT_WRITE is set, but the file descriptor is not open in RDWR mode. Or PROT_WRITE is set, but the file is append-only.

LockedMemoryLimitExceeded

MappingAlreadyExists

Using FIXED_NOREPLACE flag and the process has already mapped memory at the given address

MemoryMappingNotSupported

The underlying filesystem of the specified file does not support memory mapping.

OutOfMemory

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.

Source

  pub fn mmap(
    ptr: ?[*]align(page_size_min) u8,
    length: usize,
    prot: u32,
    flags: system.MAP,
    fd: fd_t,
    offset: u64,
) MMapError![]align(page_size_min) u8 {
    const mmap_sym = if (lfs64_abi) system.mmap64 else system.mmap;
    const rc = mmap_sym(ptr, length, prot, @bitCast(flags), fd, @bitCast(offset));
    const err: E = if (builtin.link_libc) blk: {
        if (rc != std.c.MAP_FAILED) return @as([*]align(page_size_min) u8, @ptrCast(@alignCast(rc)))[0..length];
        break :blk @enumFromInt(system._errno().*);
    } else blk: {
        const err = errno(rc);
        if (err == .SUCCESS) return @as([*]align(page_size_min) u8, @ptrFromInt(rc))[0..length];
        break :blk err;
    };
    switch (err) {
        .SUCCESS => unreachable,
        .TXTBSY => return error.AccessDenied,
        .ACCES => return error.AccessDenied,
        .PERM => return error.PermissionDenied,
        .AGAIN => return error.LockedMemoryLimitExceeded,
        .BADF => unreachable, // Always a race condition.
        .OVERFLOW => unreachable, // The number of pages used for length + offset would overflow.
        .NODEV => return error.MemoryMappingNotSupported,
        .INVAL => unreachable, // Invalid parameters to mmap()
        .MFILE => return error.ProcessFdQuotaExceeded,
        .NFILE => return error.SystemFdQuotaExceeded,
        .NOMEM => return error.OutOfMemory,
        .EXIST => return error.MappingAlreadyExists,
        else => return unexpectedErrno(err),
    }
}  