This is the mmap Reference Manual, version 1.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:05:12 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
mmapPortable mmap (file memory mapping) utility library.
Yukari Hafner <shinmera@tymoon.eu>
Yukari Hafner <shinmera@tymoon.eu>
(GIT https://github.com/Shinmera/mmap.git)
zlib
1.1.0
trivial-features (system).
documentation-utils (system).
cffi (system).
package.lisp (file).
generic.lisp (file).
posix.lisp (file).
windows.lisp (file).
documentation.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
mmap/mmap.asdmmap/package.lispmmap/generic.lispmmap/posix.lispmmap/windows.lispmmap/documentation.lispmmap/generic.lisppackage.lisp (file).
mmap (system).
code (reader method).
message (reader method).
mmap-error (condition).
with-mmap (macro).
cfold (function).
error-mmap (function).
translate-path (function).
mmap/posix.lisp:unix
generic.lisp (file).
mmap (system).
%mmap (function).
%var-accessor-errno (function).
(setf %var-accessor-errno) (function).
check-posix (function).
create-anonymous-fd (function).
errno (symbol macro).
getenv (function).
memfd-create (function).
mkostemp (function).
mremap (function).
shm-open (function).
strerror (function).
u-close (function).
u-ftruncate (function).
u-madvise (function).
u-mmap (function).
u-mprotect (function).
u-mremap (function).
u-msync (function).
u-munmap (function).
u-open (function).
u-unlink (function).
mmap/windows.lisp:windows
posix.lisp (file).
generic.lisp (file).
mmap (system).
mmap/documentation.lispwindows.lisp (file).
posix.lisp (file).
generic.lisp (file).
mmap (system).
Packages are listed by definition order.
mmaporg.shirakumo.fraf.trial.mmap
common-lisp.
%mmap (function).
%var-accessor-errno (function).
(setf %var-accessor-errno) (function).
cfold (function).
check-posix (function).
create-anonymous-fd (function).
errno (symbol macro).
error-mmap (function).
getenv (function).
memfd-create (function).
mkostemp (function).
mremap (function).
shm-open (function).
strerror (function).
translate-path (function).
u-close (function).
u-ftruncate (function).
u-madvise (function).
u-mmap (function).
u-mprotect (function).
u-mremap (function).
u-msync (function).
u-munmap (function).
u-open (function).
u-unlink (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Map the file or number of bytes to a memory region within the body.
This is a convenience macro that calls MMAP with the given arguments,
binds the results to the variables ADDR, FD, and SIZE, and automatically
ensures that MUNMAP is called with the correct values when the body is
exited.
If the flag DONT-CLOSE is set, WITH-MMAP will not free the file
descriptor on unwind. This is useful primarily if you pass in an FD
for the path yourself and are either not responsible for closing it,
or would like to continue using it for other purposes.
It is safe to change the ADDR, FD, and SIZE bindings, though probably not
very good style to do so. It is NOT safe to save the ADDR and SIZE values
somewhere and use them outside of the dynamic scope of the body. Attempting
to do so is very likely going to burn your process to the ground.
See MMAP
See MUNMAP
mmap.
Gives hints about the usage patterns of the memory to better tune mapping behaviour.
The values passed to this function must be the ones retrieved from a call
to MMAP.
The following advice hints are supported:
:NORMAL — [POSIX] This is the default.
:SEQUENTIAL — [POSIX] Expect memory to be addressed sequentially.
:RANDOM — [POSIX] Expect memory to be addressed randomly.
:WILL-NEED — [POSIX] Expect the memory to be used very soon.
:DONT-NEED — [POSIX] Expect the memory to not be needed any
time soon. This will most likely cause
pages to be offloaded until they are
accessed again.
:FREE — [LINUX] The pages in the specified range are no
longer needed and can be freed at any
time, for instance to make space in case
of memory pressure.
:REMOVE — [LINUX] Free the given pages and the associated
backing store.
:DONT-FORK — [LINUX] Don’t make changes available in children.
:DO-FORK — [LINUX] Undo :DONT-FORK behaviour.
:MERGEABLE — [LINUX] The pages in the specified range may be
merged with ones with identical content.
:UNMERGEABLE — [LINUX] Undo :MERGEABLE behaviour.
:HUGE-PAGE — [LINUX] Enable transparent huge pages for the
specified page range.
:NO-HUGE-PAGE — [LINUX] Ensure that the memory in the given
range is not backed by transparent huge
pages.
:DONT-DUMP — [LINUX] The pages in the specified range should
be excluded from core dumps.
:DO-DUMP — [LINUX] Undo :DONT-DUMP behaviour.
:WIPE-ON-FORK — [LINUX] Memory in the given range is zeroed out
for children.
:KEEP-ON-FORK — [LINUX] Undo :WIPE-ON-FORK behaviour.
:COLD — [LINUX] Deactivate the given range of
pages. This makes them a more likely
target for reclamation in the presence
of memory pressure.
:PAGEOUT — [LINUX] The pages in the specified range should
be reclaimed and their data flushed out.
This function returns nothing useful.
This function may signal an MMAP-ERROR in case the operating system notices
a problem.
See MMAP
See MMAP-ERROR
See https://pubs.opengroup.org/onlinepubs/007904875/functions/posix_madvise.html
See https://man7.org/linux/man-pages/man2/madvise.2.html
mmap.
Map the given path or number of bytes into the address space.
PATH can be either a pathname designator, FD, or NIL. If it is NIL, an
anonymous file is mapped and the MMAP flag list must include the flag
:ANONYMOUS. If it is a path or an open POSIX file descriptor, then the
contents of the given file on the file system are mapped into the
address space. The file contents can then be read, written, or
executed depending on the given flags as if normal memory was
accessed. If the file is NIL or its size cannot be automatically
determined, you must pass a valid SIZE. You may optionally pass an
OFFSET (in bytes) into the file from which the mapping begins.
[POSIX] PATH may also be the symbol :ANONYMOUS, in which case an anonymous
file descriptor is created and returned for you. This can be useful when
sharing a file descriptor with another process without needing to involve
a disk-backed file.
If the map attempt fails, an error of type MMAP-ERROR is signalled.
If the call succeeds, three values are returned:
PTR — A CFFI:FOREIGN-POINTER that points to the start of the place in
memory where the file contents have been mapped. The contents
should be placed in increasing address order, unless the flag
:GROWS-DOWN is active.
FD — An opaque file descriptor. You should not touch this.
SIZE — The size of the region of memory that has been mapped in bytes.
All three values need to be passed on to MUNMAP completely unchanged. Any
change could cause severe issues.
The three options OPEN, PROTECTION, and MMAP are lists of flags. Not all of
those flags are portable, some are only allowed on Linux, some only on non-
Windows systems. To indicate support, the flags are marked as EVERY, POSIX
(non-Windows), LINUX, or WINDOWS.
OPEN
:READ — [EVERY] Opens the file for read access.
:WRITE — [EVERY] Opens the file for write access.
:CREATE — [EVERY] Creates the file if it does not exist yet.
:ENSURE-CREATE — [EVERY] Creates the file if it does not exist yet and
errors if it does.
:TRUNCATE — [EVERY] Truncates the file and replaces it if it exists.
:DIRECT — [EVERY] Causes system buffers to be bypassed.
:FILE-SYNC — [EVERY] Causes writes to the file to be flushed asap.
:DATA-SYNC — [POSIX] Similar to FILE-SYNC, but uses data integrity
semantics rather than file integrity semantics.
:DONT-CLAIM-TTY— [POSIX] If the file is a tty and the process does not
already have a controlling tty, this file will
not become the process’ controlling tty.
:NON-BLOCK — [POSIX] Attempt to open the file in non-blocking mode,
causing operations on the fd to return asap.
:NO-FOLLOW — [LINUX] Errors if the file is a symlink.
:ASYNC — [LINUX] Enable signal driven IO.
:DIRECTORY — [LINUX] Errors if the file is not a directory.
:LARGE-FILE — [LINUX] Allows opening files with size not representable
by a 32 bit unsigned integer.
PROTECTION
:READ — [EVERY] Allows reading from the memory region. The OPEN
flag :READ is required for this protection mode.
This flag is required on windows.
:WRITE — [EVERY] Allows writing to the memory region.
:EXEC — [EVERY] Allows executing code in the memory region.
:NONE — [POSIX] Prevents accessing the memory region.
MMAP
:PRIVATE — [EVERY] The underlying file is not changed if the memory
area is written to. Copy-on-write is employed to
ensure separation.
:SHARED — [EVERY] The underlying file is changed if the memory
area is written to and the change will be
visible to other processes. In this case the
OPEN flag :WRITE must be specified.
:ANONYMOUS — [LINUX/WINDOWS] The path should be a number of bytes to
map to memory. The memory region is then mapped
against an "anonymous" file.
:NO-RESERVE — [LINUX] Don’t reserve swap for this mapping. If memory
runs out, a segfault will be generated instead.
:LOCKED — [LINUX] Locks the region to RAM, preventing it from
being swapped out.
:GROWS-DOWN — [LINUX] Causes the memory region to be mapped with a
decreasing address, like in a stack.
:POPULATE — [LINUX] Pre-populate the memory region with the file
contents, which can help performance.
:NON-BLOCK — [LINUX] Only useful with :POPULATE – do not perform a
read-ahead.
The default values for the flags are:
:OPEN (:READ) :PROTECTION (:READ) :MMAP (:PRIVATE)
Note that if you are intending to use MPROTECT to change the protection of
the mapped file at a later date, you need to call MMAP with the maximal
combination of protection flags first. If this is not the protection that
you want to start out with, call MPROTECT with the correct combination
immediately after. For instance, if you would like to start with (:READ) and
later want to change it to (:READ :WRITE), call MMAP with (:READ :WRITE),
and immediately after call MPROTECT with (:READ).
See MUNMAP
See WITH-MMAP
See MMAP-ERROR
See http://pubs.opengroup.org/onlinepubs/7908799/xsh/mmap.html
See http://pubs.opengroup.org/onlinepubs/009604499/functions/stat.html
See http://man7.org/linux/man-pages/man2/mmap.2.html
See http://man7.org/linux/man-pages/man2/stat.2.html
See https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-createfilew
See https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-getfilesize
See https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-createfilemappinga
See https://msdn.microsoft.com/en-us/library/windows/desktop/aa366761(v=vs.85).aspx
mmap.
Changes the access protection of the mapped memory region.
The values passed to this function must be the ones retrieved from a call
to MMAP.
The following protection flags are supported:
:READ — [EVERY] Allows reading from the memory region. The OPEN
flag :READ is required for this protection mode.
This flag is required on windows.
:WRITE — [EVERY] Allows writing to the memory region.
:EXEC — [EVERY] Allows executing code in the memory region.
:NONE — [POSIX] Prevents accessing the memory region.
This function returns nothing useful.
This function may signal an MMAP-ERROR in case the operating system notices
a problem.
See MMAP
See MMAP-ERROR
See http://pubs.opengroup.org/onlinepubs/9699919799/functions/mprotect.html
See http://man7.org/linux/man-pages/man2/mprotect.2.html
See https://msdn.microsoft.com/en-us/library/windows/desktop/aa366898(v=vs.85).aspx
mmap.
Causes writes to the mapped file area to be written to disk.
The values passed to this function must be the ones retrieved from a call
to MMAP.
The following flags are supported:
:SYNC — [EVERY] Writing is synchronous. A call to this function
will not return until the data is flushed to
disk.
:ASYNC — [EVERY] Writing is asynchronous and a call will return
immediately.
:INVALIDATE — [POSIX] Asks to invalidate other mappings of the same
file, ensuring the view is synchronised.
This function returns nothing useful.
This function may signal an MMAP-ERROR in case the operating system notices
a problem.
See MMAP
See MMAP-ERROR
See http://pubs.opengroup.org/onlinepubs/000095399/functions/msync.html
See http://man7.org/linux/man-pages/man2/msync.2.html
See https://msdn.microsoft.com/en-us/library/windows/desktop/aa366563(v=vs.85).aspx
See https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-flushfilebuffers
mmap.
Unmaps the memory region, freeing the address space and its file.
The values passed to this function must be the ones retrieved from a call
to MMAP. Calling MUNMAP with the same values more than once will lead to
undefined consequences and may very well corrupt your system to crash. The
same goes for calling MUNMAP with values not directly returned by MMAP,
calling it with changed values returned by MMAP, or attempting to
dereference the PTR after a call to MUNMAP.
This function returns nothing useful.
On POSIX systems you may pass NIL for the FD argument, in which case
the file descriptor is not closed. It is then your responsibility to
close it appropriately at a later point.
This function may signal an MMAP-ERROR in case the operating system notices
a problem.
See MMAP
See MMAP-ERROR
See WITH-MMAP
See http://pubs.opengroup.org/onlinepubs/9699919799/functions/mprotect.html
See http://man7.org/linux/man-pages/man2/mprotect.2.html
See https://msdn.microsoft.com/en-us/library/windows/desktop/aa366882(v=vs.85).aspx
See https://msdn.microsoft.com/en-us/library/windows/desktop/ms724211(v=vs.85).aspx
mmap.
The OS-specific error code returned for the mmap failure.
See MMAP-ERROR
mmap.
mmap-error)) ¶code.
The (hopefully) user-readable error message for the mmap failure.
See MMAP-ERROR
mmap.
mmap-error)) ¶Error signalled if the mmap attempt fails for some reason.
Possible reasons include, but are not limited to:
- File not found
- File access denied
- Out of memory
- Out of address space
- Mapping not allowed
- Invalid combination of flags
See MMAP
See CODE
See MESSAGE
Changes the size of the mapped segment.
The values passed to this function must be the ones retrieved from a
call to MMAP.
The values returned from this function are the same kind as returned
from MMAP and should be used in place of the original values for
further operations.
When the mapped segment is backed by a file, the file is truncated to
fit the newly requested size.
See MMAP
See MUNMAP
See MMAP-ERROR
See https://man7.org/linux/man-pages/man2/mremap.2.html
mmap.
| Jump to: | %
(
C E F G M S T U W |
|---|
| Jump to: | %
(
C E F G M S T U W |
|---|
| Jump to: | C E M S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| C | |||
code: | Public conditions | ||
| | |||
| E | |||
errno: | Private symbol macros | ||
| | |||
| M | |||
message: | Public conditions | ||
| | |||
| S | |||
Slot, code: | Public conditions | ||
Slot, message: | Public conditions | ||
Symbol Macro, errno: | Private symbol macros | ||
| | |||
| Jump to: | C E M S |
|---|
| Jump to: | C D F G M P S W |
|---|
| Jump to: | C D F G M P S W |
|---|