source: project/release/4/memory-mapped-files/memory-mapped-files.wiki

Last change on this file was 31138, checked in by felix winkelmann, 6 years ago

added preliminary eggs for extraction from core libraries

File size: 4.6 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== memory-mapped-files
5
6
7=== Introduction
8
9Interface to memory-mapped files for POSIX and Windows systems.
10
11
12=== Usage
13
14{{(require-extension memory-mapped-files)}}
15
16
17=== Programming interface
18
19==== memory-mapped-file?
20
21<procedure>(memory-mapped-file? X)</procedure>
22
23Returns {{#t}}, if {{X}} is an object representing a memory
24mapped file, or {{#f}} otherwise.
25
26==== map-file-to-memory
27
28<procedure>(map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])</procedure>
29
30Maps a section of a file to memory using the C function
31{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
32or {{#f}}; {{LEN}} specifies the size of the section to
33be mapped; {{PROTECTION}} should be one or more of the flags
34{{prot/read, prot/write, prot/exec}} or {{prot/none}}
35'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
36the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
37{{map/file}}; {{FILENO}} should be the file-descriptor of the
38mapped file. The optional argument {{OFFSET}} gives the offset of
39the section of the file to be mapped and defaults to 0. This procedure
40returns an object representing the mapped file section.  The procedure
41{{move-memory!}} can be used to access the mapped memory.
42
43==== memory-mapped-file-pointer
44
45<procedure>(memory-mapped-file-pointer MMAP)</procedure>
46
47Returns a machine pointer to the start of the memory region to which
48the file is mapped.
49
50==== unmap-file-from-memory
51
52<procedure>(unmap-file-from-memory MMAP [LEN])</procedure>
53
54Unmaps the section of a file mapped to memory using the C function
55{{munmap()}}.  {{MMAP}} should be a mapped file as returned
56by the procedure {{map-file-to-memory}}.  The optional argument
57{{LEN}} specifies the length of the section to be unmapped and
58defaults to the complete length given when the file was mapped.
59
60=== Memory Mapped I/O Example
61
62<enscript highlight=scheme>
63;; example-mmap.scm
64;;
65;; basic example of memory mapped I/O
66;;
67;; This example does no error checking or cleanup, and serves
68;; only to demonstrate how the mmap functions work together.
69;;
70(use memory-mapped-files)
71(use posix lolevel)
72
73       ; open a file using the posix module, so we have the file descriptor.
74(let* ((fd   (file-open "example-mmap.scm" (+ open/rdonly open/nonblock)))
75       ; fstat(2) the file descriptor fd to determine its size
76       (size (file-size fd))
77       ; mmap(2) the file for reading.
78       (mmap (map-file-to-memory #f
79                                 size
80                                 prot/read
81                                 (+ map/file map/shared)
82                                 fd))
83       ; return a pointer object to the beginning of the memory map.
84       (buf  (memory-mapped-file-pointer mmap))
85       ; allocate a string the same size as the file.
86       (str  (make-string size)))
87  ; copy the mapped memory into a string
88  (move-memory! buf str size)
89  (display str)
90  ; alternately, print the string byte-by-byte without copying.
91  (let loop ((p buf)
92             (i 0))
93    (unless (= i size)
94      (display (integer->char (pointer-s8-ref p)))
95      (loop (pointer+ p 1) (+ i 1)))))
96</enscript>
97
98
99=== Author
100
101The CHICKEN Team
102
103
104=== License
105
106 Copyright (c) 2014, The CHICKEN Team
107 All rights reserved.
108 
109 Redistribution and use in source and binary forms, with or without
110 modification, are permitted provided that the following conditions
111 are met:
112 1. Redistributions of source code must retain the above copyright
113    notice, this list of conditions and the following disclaimer.
114 2. Redistributions in binary form must reproduce the above copyright
115    notice, this list of conditions and the following disclaimer in the
116    documentation and/or other materials provided with the distribution.
117 3. The name of the authors may not be used to endorse or promote products
118    derived from this software without specific prior written permission.
119 
120 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
121 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
122 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
123 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
124 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
125 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
126 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
127 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
128 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
129 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
130 
131
132=== Version History
133
134; 1.0 : Extracted from {{posix}} core library unit and released as an egg.
Note: See TracBrowser for help on using the repository browser.