memory-mapped-files

Interface to memory-mapped files for POSIX and Windows systems.

Usage

(require-extension memory-mapped-files)

Programming interface

memory-mapped-file?

[procedure] (memory-mapped-file? X)

Returns #t, if X is an object representing a memory mapped file, or #f otherwise.

map-file-to-memory

[procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])

Maps a section of a file to memory using the C function mmap(). ADDRESS should be a foreign pointer object or #f; LEN specifies the size of the section to be mapped; PROTECTION should be one or more of the flags prot/read, prot/write, prot/exec or prot/none bitwise-iored together; FLAG should be one or more of the flags map/fixed, map/shared, map/private, map/anonymous or map/file; FILENO should be the file-descriptor of the mapped file. The optional argument OFFSET gives the offset of the section of the file to be mapped and defaults to 0. This procedure returns an object representing the mapped file section. The procedure move-memory! can be used to access the mapped memory.

memory-mapped-file-pointer

[procedure] (memory-mapped-file-pointer MMAP)

Returns a machine pointer to the start of the memory region to which the file is mapped.

unmap-file-from-memory

[procedure] (unmap-file-from-memory MMAP [LEN])

Unmaps the section of a file mapped to memory using the C function munmap(). MMAP should be a mapped file as returned by the procedure map-file-to-memory. The optional argument LEN specifies the length of the section to be unmapped and defaults to the complete length given when the file was mapped.

Memory Mapped I/O Example

;; example-mmap.scm
;;
;; basic example of memory mapped I/O
;;
;; This example does no error checking or cleanup, and serves
;; only to demonstrate how the mmap functions work together.
;;
(use memory-mapped-files)
(use posix lolevel)

       ; open a file using the posix module, so we have the file descriptor.
(let* ((fd   (file-open "example-mmap.scm" (+ open/rdonly open/nonblock)))
       ; fstat(2) the file descriptor fd to determine its size
       (size (file-size fd))
       ; mmap(2) the file for reading.
       (mmap (map-file-to-memory #f
                                 size
                                 prot/read
                                 (+ map/file map/shared)
                                 fd))
       ; return a pointer object to the beginning of the memory map.
       (buf  (memory-mapped-file-pointer mmap))
       ; allocate a string the same size as the file.
       (str  (make-string size)))
  ; copy the mapped memory into a string
  (move-memory! buf str size)
  (display str)
  ; alternately, print the string byte-by-byte without copying.
  (let loop ((p buf)
             (i 0))
    (unless (= i size)
      (display (integer->char (pointer-s8-ref p)))
      (loop (pointer+ p 1) (+ i 1)))))

Author

The CHICKEN Team

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/memory-mapped-files

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

License

Copyright (c) 2014-2018, The CHICKEN Team
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the authors may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Version History

0.3: Fix build on Haiku and other platforms without MAP_FILE
0.2: Fixed Windows build.
0.1: Extracted from posix core library unit and released as an egg.

Introduction