Ignore too small data snippets.

[rrq/lsp-utils.git] / lsp-misc.a.8.adoc

diff --git a/lsp-misc.a.8.adoc b/lsp-misc.a.8.adoc
index 5dd0b042d58fe7e5036884ec04b1841ea342a7f2..7f8a5d05c4257a1db4d02a671f56ebdfb4a5c646 100644 (file)
--- a/lsp-misc.a.8.adoc
+++ b/lsp-misc.a.8.adoc
@@ -28,7 +28,7 @@ packnl _main.lsp_ *-A lsp-misc.a*
 The *prog1* function is like a *begin* function except that it returns
 the value of the first term rather than the last.
 
-(die [_N_ [_term_]])::
+(die _N_ [_term_]*)::
 
 The *die* function printes to stderr the join of term values as
 strings with space separation, and if _N_ is a number, then the
@@ -93,6 +93,41 @@ the respective naming formats (:%name obj) and (:!name obj value).
 --> A = (EX 1 4 3)
 ----
 
+=== mmap.lsp API
+
+This newlisp module implements a small FOOP model based memory mapping
+API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and
+_lseek_.
+
+(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]])::
+
+This function creates a FOOP object that represents the memory mapping
+of the given file descriptor. _FD_ may be the pathname string of a
+file to memory map or an already opened file descriptor. The MMap
+object represents the memory block starting at (:%base) and (%len)
+bytes in length where the file is memory mapped.
++
+.Access example (from test.lsp)
+[caption=""]
+----
+(println (setf X (MMap "mmap.lsp")))
+(println (get-string (:%base X)))
+----
++
+Note that only a plain text file would be accessed with _get-string_.
+A binary file would rather be accessed with _unpack_. The memory
+mapping provides read-only "random access" to the file content.
++
+To set up read-write acces requires an _OFFSET_ and the _PROT_
+argument 0x3, and writing should be accompanied by _MMap:msync_ calls
+so as to synchronize with the backing file.
++
+The FOOP object includes get and set methods for the fields (in
+order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_.
+
+=== test.lsp
+
+This file is a small test of the MMap memory mapping.
 
 == SEE ALSO