Rand Stats

Mmap::Native

zef:massa

Actions Status Actions Status

NAME

Mmap::Native - interface to posix mmap() and mmunmap() calls

SYNOPSIS

use Mmap::Native;

my $f = $*CWD.add('META6.json'); $f = $f.open;
my $d = mmap Pointer, 50, PROT_READ, MAP_SHARED, $f.native-descriptor, 0;
my $e = blob-from-pointer $d, :50elems, :type(Buf[uint8]);

is $e.decode('utf8'), /'"auth": "zef:massa"'/;

DESCRIPTION

Mmap::Native is a raw interface to the C library mmap and munmap calls.

It's mostly used for mmaping Blob objects and other raw C pointers. It's recommended that the library using it present a most Raku-esque interface and hide the mmapping altogether. This is just a low level library.

CONSTANTS

Remember to always use +| to combine flag values!

The $prot argument flags

Describes the desired memory protection of the mapping (and must not conflict with the open mode of the file). It is either PROT_NONE or the bitwise OR of one or more of the following flags:

FlagDescription
PROT_READpage can be read
PROT_WRITEpage can be written
PROT_EXECpage can be executed
PROT_SEMpage may be used for atomic ops
PROT_NONEpage can not be accessed
PROT_GROWSDOWNmprotect flag: extend change to start of growsdown vma
PROT_GROWSUPmprotect flag: extend change to end of growsup vma

The $flags argument

Determines whether updates to the mapping are visible to other processes mapping the same region, and whether updates are carried through to the underlying file. This behavior is determined by including exactly one of the following values:

FlagDescription
MAP_SHAREDShare changes
MAP_PRIVATEChanges are private
MAP_SHARED_VALIDATEshare and validate extension flags
MAP_TYPEMask for type of mapping
MAP_FIXEDInterpret addr exactly
MAP_ANONYMOUSdon't use a file
MAP_GROWSDOWNstack-like segment
MAP_DENYWRITEETXTBSY
MAP_EXECUTABLEmark it as an executable
MAP_LOCKEDpages are locked
MAP_NORESERVEdon't check for reservations
MAP_POPULATEpopulate (prefault) pagetables
MAP_NONBLOCKdo not block on IO
MAP_STACKgive out an address that is best suited for process/thread stacks
MAP_HUGETLBcreate a huge page mapping
MAP_SYNCperform synchronous page faults for the mapping
MAP_FIXED_NOREPLACEMAP_FIXED which doesn't unmap underlying mapping
MAP_UNINITIALIZEDFor anonymous mmap, memory could be * uninitialized
MLOCK_ONFAULTLock pages in range after they are faulted in, do not prefault
MS_ASYNCsync memory asynchronously
MS_INVALIDATEinvalidate the caches
MS_SYNCsynchronous memory sync
MADV_NORMALno further special treatment
MADV_RANDOMexpect random page references
MADV_SEQUENTIALexpect sequential page references
MADV_WILLNEEDwill need these pages
MADV_DONTNEEDdon't need these pages
MADV_FREEfree pages only if memory pressure
MADV_REMOVEremove these pages & resources
MADV_DONTFORKdon't inherit across fork
MADV_DOFORKdo inherit across fork
MADV_HWPOISONpoison a page for testing
MADV_SOFT_OFFLINEsoft offline page for testing
MADV_MERGEABLEKSM may merge identical pages
MADV_UNMERGEABLEKSM may not merge identical pages
MADV_HUGEPAGEWorth backing with hugepages
MADV_NOHUGEPAGENot worth backing with hugepages
MADV_DONTDUMPExplicity exclude from the core dump, overrides the coredump filter bits
MADV_DODUMPClear the MADV_DONTDUMP flag
MADV_WIPEONFORKZero memory on fork, child only
MADV_KEEPONFORKUndo MADV_WIPEONFORK
MADV_COLDdeactivate these pages
MADV_PAGEOUTreclaim these pages
MADV_POPULATE_READpopulate (prefault) page tables readable
MADV_POPULATE_WRITEpopulate (prefault) page tables writable
MADV_DONTNEED_LOCKEDlike DONTNEED, but drop locked pages too
MADV_COLLAPSESynchronous hugepage collapse

FUNCTIONS

sub mmap

sub mmap(
    NativeCall::Types::Pointer $addr is rw,
    uint64 $len,
    int64 $prot,
    int64 $flags,
    int64 $fd,
    int64 $offset
) returns NativeCall::Types::Pointer

Creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in $addr. The $length argument specifies the length of the mapping (which must be greater than 0). If $addr is undefined, then the kernel chooses the (page-aligned) address at which to create the mapping; this is the most portable method of creating a new mapping. If $addr is defined, then the kernel takes it as a hint about where to place the mapping; on Linux, the kernel will pick a nearby page boundary and attempt to create the mapping there. If another mapping already exists there, the kernel picks a new address that may or may not depend on the hint. The address of the new mapping is returned as the result of the call. The contents of a file mapping are initialized using length bytes starting at offset $offset in the file (or other object) referred to by the file descriptor $fd. $offset must be a multiple of the page size. After the mmap() call has returned, the file descriptor, $fd, can be closed immediately without invalidating the mapping. The $prot argument describes the desired memory protection of the mapping (and must not conflict with the open mode of the file).

sub munmap

sub munmap(
    NativeCall::Types::Pointer $addr is rw,
    uint64 $len
) returns uint64

Deletes the mappings for the specified address range, and causes further references to addresses within the range to generate invalid memory references. The region is also automatically unmapped when the process is terminated. On the other hand, closing the file descriptor does not unmap the region. The address $addr must be a multiple of the page size (but $length need not be). All pages containing a part of the indicated range are unmapped, and subsequent references to these pages will generate SIGSEGV. It is not an error if the indicated range does not contain any mapped pages.

AUTHOR

Humberto Massa humbertomassa@gmail.com

COPYRIGHT AND LICENSE

Copyright © 2024 Humberto Massa

This library is free software; you can redistribute it and/or modify it under either the Artistic License 2.0 or the LGPL v3.0, at your convenience.