Memory v0.1.0
getpagesize
pub extern func getpagesize() -> int32
Reports the system page size, in bytes.
Darwin's page size is not the same on every machine: Apple Silicon uses 16 KiB where x86-64 uses 4 KiB, which
is why this is asked rather than assumed. Cannot fail — a process that could not be told its own page size
could not have been started.
Memory::QueryPageSize is the wrapper to call; this is the raw entry point it binds, and is the only
declaration in this block that is reachable from outside the package.
Returns: the page size in bytes
ProtectionNone
pub const ProtectionNone: int32 = 0x00;
PROT_NONE: the pages may not be touched at all.
ProtectionRead
pub const ProtectionRead: int32 = 0x01;
PROT_READ: the pages may be read.
ProtectionWrite
pub const ProtectionWrite: int32 = 0x02;
PROT_WRITE: the pages may be written.
ProtectionExecute
pub const ProtectionExecute: int32 = 0x04;
PROT_EXEC: the pages may be executed.
Apple Silicon refuses a mapping that is writable and executable at once unless the process carries the
com.apple.security.cs.allow-jit entitlement and uses MAP_JIT, which this package does not wrap.
MapShared
pub const MapShared: int32 = 0x0001;
MAP_SHARED: writes are visible to other mappings of the same object and reach it.
MapPrivate
pub const MapPrivate: int32 = 0x0002;
MAP_PRIVATE: writes are private to this mapping and never reach the object.
MapFixed
pub const MapFixed: int32 = 0x0010;
MAP_FIXED: place the mapping exactly at the requested address, replacing whatever was there.
MapAnonymous
pub const MapAnonymous: int32 = 0x1000;
MAP_ANON: the mapping is backed by zeroed pages rather than by a file.
AdviseFree
pub const AdviseFree: int32 = 5;
MADV_FREE: the pages may be reclaimed, and read back as zero if they are.
AdviseDontNeed
pub const AdviseDontNeed: int32 = 4;
MADV_DONTNEED: the pages are not needed soon. Advisory on Darwin, as on FreeBSD.
AdviseWillNeed
pub const AdviseWillNeed: int32 = 3;
MADV_WILLNEED: the pages will be read soon.
Mmap
pub func Mmap(
address: *opaque,
length: uint,
protection: int32,
flags: int32,
fd: int32,
offset: uint64
) -> int64
Creates a mapping and returns its address, or a negative error number.
address is a hint unless MapFixed is set. fd is the object to map, or -1 with MapAnonymous.
libSystem reports failure here as MAP_FAILED, which is -1 cast to a pointer rather than a small negative
number, so the failure is folded into the same normalized form every other wrapper uses. Test the result with
IsError, not for a sign: a valid address may have its top bit set.
MapFixed replaces whatever occupies the address, including a mapping this program depends on.
Parameters
| Name | Type | Description |
|---|---|---|
address | *opaque | a hint for where to map, or null to let the kernel choose |
length | uint | how many bytes, rounded up to whole pages |
protection | int32 | what may be done with the pages, as Protection* flags |
flags | int32 | the mapping flags, as Map* values |
fd | int32 | the file to map, or -1 with MapAnonymous |
offset | uint64 | where in the file the mapping starts |
Returns: the mapping's address, or a negative error number
Munmap
pub func Munmap(address: *opaque, length: uint) -> int64
Releases the mapping that begins at address and spans length bytes.
Returns zero, or a negative error number.
Every pointer into the range becomes invalid.
Parameters
| Name | Type | Description |
|---|---|---|
address | *opaque | a page-aligned address to release from |
length | uint | how many bytes to release |
Returns: zero, or a negative error number
Mprotect
pub func Mprotect(
address: *opaque,
length: uint,
protection: int32
) -> int64
Changes what may be done with the pages covering a range.
address must be page-aligned. Returns zero, or a negative error number.
Apple Silicon refuses to make a range writable and executable at once without the JIT entitlement.
Parameters
| Name | Type | Description |
|---|---|---|
address | *opaque | a page-aligned address |
length | uint | how many bytes, rounded up to whole pages |
protection | int32 | what may be done with them afterwards |
Returns: zero, or a negative error number
Madvise
pub func Madvise(
address: *opaque,
length: uint,
advice: int32
) -> int64
Tells the kernel how the pages covering a range are about to be used.
Advice is advice, with the exception of AdviseFree, which actually releases.
AdviseFree loses whatever the range held.
Parameters
| Name | Type | Description |
|---|---|---|
address | *opaque | a page-aligned address |
length | uint | how many bytes the advice covers |
advice | int32 | one of the Advise* values |
Returns: zero, or a negative error number
QueryPageSize
pub func QueryPageSize() -> int64
The size of a page, asked of libSystem. Darwin's page size is not the same on every machine: Apple Silicon uses 16 KiB where x86-64 uses 4 KiB, so this is asked rather than assumed. The underlying call cannot fail, which is why this one cannot either — the negative-error return exists so that one call shape reaches all three POSIX systems, not because Darwin has a failure to report.
Returns: the page size in bytes, always positive on this system