Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/iostreams/doc/classes/mapped_file.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 30.3 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4    <TITLE>Memory-Mapped Files</TITLE>
5    <LINK REL="stylesheet" HREF="../../../../boost.css">
6    <LINK REL="stylesheet" HREF="../theme/iostreams.css">
7</HEAD>
8<BODY>
9
10<!-- Begin Banner -->
11
12    <H1 CLASS="title">Memory-Mapped Files</H1>
13    <HR CLASS="banner">
14
15<!-- End Banner -->
16
17<DL class="page-index">
18  <DT><A href="#overview">Overview</A></DT>
19  <DT><A href="#acknowledgments">Acknowledgments</A></DT>
20  <DT><A href="#installation">Installation</A></DT>
21  <DT><A href="#headers">Headers</A></DT>
22  <DT><A href="#reference">Reference</A>
23    <OL>
24      <LI CLASS="square"><A href="#mapped_file_params">Class <CODE>mapped_file_params</CODE></A></LI>
25      <LI CLASS="square"><A href="#mapped_file_source">Class <CODE>mapped_file_source</CODE></A></LI>
26      <LI CLASS="square"><A href="#mapped_file_sink">Class <CODE>mapped_file_sink</CODE></A></LI>
27      <LI CLASS="square"><A href="#mapped_file">Class <CODE>mapped_file</CODE></A></LI>
28    </OL>
29  </DT>
30</DL>
31
32<HR>
33
34<A NAME="overview"></A>
35<H2>Overview</H2>
36
37<P>
38    The classes <CODE>mapped_file_source</CODE>, <CODE>mapped_file_sink</CODE> and <CODE>mapped_file</CODE> provide access to memory-mapped files on Windows and POSIX systems. These <A HREF="../guide/concepts.html#device_concepts">Devices</A> behave much like the <A HREF="file.html">File Wrappers</A> <CODE>basic_file_source</CODE>, <CODE>basic_file_sink</CODE> and <CODE>basic_file</CODE>, with the following important differences:
39</P>
40    <UL>
41        <LI CLASS="square">By default, files must exist before being opened, and are not truncated; attempting to write past the end of a file results in an error. To map a file which does not yet exist, use <A HREF="#mapped_file_params_size"><CODE>mapped_file_params::new_file_size</CODE></A>.
42        <LI CLASS="square">Files are always opened in binary mode.
43        <LI CLASS="square">Wide-character streams are not supported.
44    </UL>
45<P>
46    Wide-character versions of the memory-mapped file Devices may be defined as follows, using the template <A HREF="code_converter.html"><CODE>code_converter</CODE></A>:
47    <PRE CLASS="broken_ie">    <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/code_converter.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/code_converter.hpp&gt;</SPAN></A>
48    <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/device/mapped_file.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/maped_file.hpp&gt;</SPAN></A>
49
50    <SPAN CLASS="keyword">typedef</SPAN> code_converter&lt;mapped_file_source&gt;  <SPAN CLASS="defined">wmapped_file_source</SPAN>;
51    <SPAN CLASS="keyword">typedef</SPAN> code_converter&lt;mapped_file_sink&gt;    <SPAN CLASS="defined">wmapped_file_sink</SPAN>;</PRE>
52</P>
53
54<A NAME="acknowledgments"></A>
55<H2>Acknowledgments</H2>
56
57<P>
58The memory-mapped file Devices are based on the work of Craig Henderson (<A CLASS="bib_ref" HREF="../bibliography.html#henderson">[Henderson]</A>). Additionals features were implemented by Jonathan Graehl.
59</P>
60
61<A NAME="installation"></A>
62<H2>Installation</H2>
63
64<P>
65    The memory-mapped file Devices depend on the source file <A CLASS="header" HREF="../../src/mapped_file.cpp"><CODE>&lt;libs/iostreams/src/mapped_file.cpp&gt;</CODE></A>. This source file makes use of Windows or POSIX headers depending on the user's operating system. For installation instructions see <A HREF="../installation.html">Installation</A>.
66</P>
67
68<A NAME="headers"></A>
69<H2>Headers</H2>
70
71<DL class="page-index">
72  <DT><A CLASS="header" HREF="../../../../boost/iostreams/device/mapped_file.hpp"><CODE>&lt;boost/iostreams/device/mapped_file.hpp&gt;</CODE></A></DT>
73</DL>
74
75<A NAME="reference"></A>
76<H2>Reference</H2>
77
78<A NAME="mapped_file_params"></A>
79<H3>1. Class <CODE>mapped_file_params</CODE></H3>
80
81<H4>Description</H4>
82
83<P>Class encapsulating the parameters used to open a memory-mapped file.</P>
84
85<H4>Synopsis</H4>
86
87<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
88
89<SPAN CLASS="keyword">struct</SPAN> <SPAN CLASS="defined">mapped_file_params</SPAN> {
90    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_params();
91    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_params(<SPAN CLASS='keyword'>const</SPAN> std::string& path);
92    std::string              <A CLASS='documented' HREF='#mapped_file_params_hint'>path</A>;
93    std::ios_base::openmode  <A CLASS='documented' HREF='#mapped_file_params_mode'>mode</A>;
94    stream_offset            <A CLASS='documented' HREF='#mapped_file_params_offset'>offset</A>;
95    std::size_t              <A CLASS='documented' HREF='#mapped_file_params_length'>length</A>;
96    stream_offset            <A CLASS="documented" HREF="#mapped_file_params_size">new_file_size</A>;
97    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>*              <A CLASS='documented' HREF='#mapped_file_params_hint'>hint</A>;
98};
99
100} } // End namespace boost::io</PRE>
101
102<A NAME="mapped_file_params_path"></A>
103<H4><CODE>mapped_file_params::path</CODE></H4>
104
105<PRE CLASS="broken_ie">    std::string              path;</PRE>
106   
107<P>The pathname of the file to map.</P>
108
109<A NAME="mapped_file_params_mode"></A>
110<H4><CODE>mapped_file_params::mode</CODE></H4>
111
112<PRE CLASS="broken_ie">    std::ios_base::openmode  mode;</PRE>
113   
114<P>Indicates whether the file should be opened with read-access, write-access or both. Ignored by <CODE>mapped_file_source</CODE> and <CODE>mapped_file_sink</CODE> .</P>
115
116<A NAME="mapped_file_params_offset"></A>
117<H4><CODE>mapped_file_params::offset</CODE></H4>
118
119<PRE CLASS="broken_ie">    stream_offset            offset;</PRE>
120   
121<P>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be abotained via the static member function <A HREF="#mapped_file_alignment"><CODE>alignment</CODE></A> of  <CODE>mapped_file_source</CODE>, <CODE>mapped_file_sink</CODE> or <CODE>mapped_file</CODE>. Defaults to <CODE>0</CODE>.</P>
122
123<A NAME="mapped_file_params_length"></A>
124<H4><CODE>mapped_file_params::length</CODE></H4>
125
126<PRE CLASS="broken_ie">    std::size_t              length;</PRE>
127   
128<P>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</P>
129
130<A NAME="mapped_file_params_size"></A>
131<H4><CODE>mapped_file_params::new_file_size</CODE></H4>
132
133<PRE CLASS="broken_ie">    stream_offset            new_file_size;</PRE>
134   
135<P>If this value is non-zero it specifies the size of a file to be created. If a file with pathname <I>path</I> already exists, it will be overwritten.</P>
136
137<A NAME="mapped_file_params_hint"></A>
138<H4><CODE>mapped_file_params::hint</CODE></H4>
139
140<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>*              hint;</PRE>
141   
142<P>Suggests a location in the process's address space for the mapping to begin.</P>
143
144<A NAME="mapped_file_source"></A>
145<H3>2. Class <CODE>mapped_file_source</CODE></H3>
146
147<H4>Description</H4>
148
149<P>Model of <A HREF="../concepts/source.html">Source</A> providing read-only access to memory-mapped files on Windows and POSIX systems.</P>
150
151<H4>Synopsis</H4>
152
153<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
154
155<SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file_source</SPAN> {
156<SPAN CLASS="keyword">public</SPAN>:
157    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
158    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
159    <A CLASS='documented' HREF='#mapped_file_source_default_ctor'>mapped_file_source</A>();
160    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_source_params_ctor'>mapped_file_source</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
161    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_source_basic_ctor'>mapped_file_source</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
162                                 size_type length = max_length,
163                                 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
164    void <A CLASS='documented' HREF='#mapped_file_source_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
165    void <A CLASS='documented' HREF='#mapped_file_source_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
166               size_type length = max_length,
167               boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
168    <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_source_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
169    <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_source_close'>close</A>();
170    size_type <A CLASS='documented' HREF='#mapped_file_source_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
171    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_source_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>;
172    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_source_alignment'>alignment</A>();
173};
174
175} } // End namespace boost::io</PRE>
176
177<A NAME="mapped_file_source_default_ctor"></A>
178<H4><CODE>mapped_file_source::mapped_file_source</CODE></H4>
179
180<PRE CLASS="broken_ie">    mapped_file_source();</PRE>
181   
182<P>Constructs a <CODE>mapped_file_source</CODE> which must be opened before it can be used to perform i/o.</P>
183
184<A NAME="mapped_file_source_params_ctor"></A>
185<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_source(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
186   
187<P>Constructs a <CODE>mapped_file_source</CODE> from the given parameters.</P>
188
189<A NAME="mapped_file_source_basic_ctor"></A>
190<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_source( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
191                                 size_type length = max_length,
192                                 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
193   
194<P>Constructs a <CODE>mapped_file_source</CODE> to access a specified file. The parameters have the following interpretation:</P>
195
196<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
197<TR>
198    <TR>
199        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
200        <TD>The pathname of the file to map.</TD>
201    </TR>
202    <TR>
203        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
204        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
205    </TR>
206    <TR>
207        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
208        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_source_alignment'><CODE>alignment</CODE></A>.</TD>
209    </TR>
210</TABLE>
211
212<A NAME="mapped_file_source_params_open"></A>
213<H4><CODE>mapped_file_source::open</CODE></H4>
214
215<PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
216   
217<P>Connects this <CODE>mapped_file_source</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
218
219<A NAME="mapped_file_source_basic_open"></A>
220<PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
221                   size_type length = max_length,
222                   boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
223   
224<P>Connects this <CODE>mapped_file_source</CODE> to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:</P>
225
226<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
227<TR>
228    <TR>
229        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
230        <TD>The pathname of the file to map.</TD>
231    </TR>
232    <TR>
233        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
234        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
235    </TR>
236    <TR>
237        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
238        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_source_alignment'><CODE>alignment</CODE></A>.</TD>
239    </TR>
240</TABLE>
241
242<A NAME="mapped_file_source_is_open"></A>
243<H4><CODE>mapped_file_source::is_open</CODE></H4>
244
245<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
246   
247<P>Returns <CODE>true</CODE> if this <CODE>mapped_file_source</CODE> has been successfully opened without subsequently having been closed.</P>
248
249<A NAME="mapped_file_source_close"></A>
250<H4><CODE>mapped_file_source::close</CODE></H4>
251
252<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
253   
254<P>Frees the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
255
256<A NAME="mapped_file_source_size"></A>
257<H4><CODE>mapped_file_source::size</CODE></H4>
258
259<PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
260   
261<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
262
263<A NAME="mapped_file_source_data"></A>
264<H4><CODE>mapped_file_source::data</CODE></H4>
265
266<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
267   
268<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
269
270<A NAME="mapped_file_source_alignment"></A>
271<H4><CODE>mapped_file_source::alignment</CODE></H4>
272
273<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
274   
275<P>Returns the operating system's virtual memory allocation granularity.</P>
276
277<A NAME="mapped_file_sink"></A>
278<H3>3. Class <CODE>mapped_file_sink</CODE></H3>
279
280<H4>Description</H4>
281
282<P>Model of <A HREF="../concepts/sink.html">Sink</A> providing write-only access to memory-mapped files on Windows and POSIX systems.</P>
283
284<H4>Synopsis</H4>
285
286<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
287
288<SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file_sink</SPAN> {
289<SPAN CLASS="keyword">public</SPAN>:
290    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
291    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
292    <A CLASS='documented' HREF='#mapped_file_sink_default_ctor'>mapped_file_sink</A>();
293    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_params_ctor'>mapped_file_sink</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
294    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_basic_ctor'>mapped_file_sink</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
295                               size_type length = max_length,
296                               boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
297    void <A CLASS='documented' HREF='#mapped_file_sink_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
298    void <A CLASS='documented' HREF='#mapped_file_sink_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
299               size_type length = max_length,
300               boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
301    <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
302    <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_close'>close</A>();
303    size_type <A CLASS='documented' HREF='#mapped_file_sink_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
304    <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_sink_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>;
305    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_alignment'>alignment</A>();
306};
307
308} } // End namespace boost::io</PRE>
309
310<A NAME="mapped_file_sink_default_ctor"></A>
311<H4><CODE>mapped_file_sink::mapped_file_sink</CODE></H4>
312
313<PRE CLASS="broken_ie">    mapped_file_sink();</PRE>
314   
315<P>Constructs a <CODE>mapped_file_sink</CODE> which must be opened before it can be used to perform i/o.</P>
316
317<A NAME="mapped_file_sink_params_ctor"></A>
318<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_sink(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
319   
320<P>Constructs a <CODE>mapped_file_sink</CODE> from the given parameters.</P>
321
322<A NAME="mapped_file_sink_basic_ctor"></A>
323<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_sink( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
324                               size_type length = max_length,
325                               boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
326   
327<P>Constructs a <CODE>mapped_file_sink</CODE> to access a specified file. The parameters have the following interpretation:</P>
328
329<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
330<TR>
331    <TR>
332        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
333        <TD>The pathname of the file to map.</TD>
334    </TR>
335    <TR>
336        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
337        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
338    </TR>
339    <TR>
340        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
341        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_sink_alignment'><CODE>alignment</CODE></A>.</TD>
342    </TR>
343</TABLE>
344
345<A NAME="mapped_file_sink_params_open"></A>
346<H4><CODE>mapped_file_sink::open</CODE></H4>
347
348<PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
349   
350<P>Connects this <CODE>mapped_file_sink</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
351
352<A NAME="mapped_file_sink_basic_open"></A>
353<PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
354                   size_type length = max_length,
355                   boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
356   
357<P>Connects this <CODE>mapped_file_sink</CODE> to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:</P>
358
359<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
360<TR>
361    <TR>
362        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
363        <TD>The pathname of the file to map.</TD>
364    </TR>
365    <TR>
366        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
367        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
368    </TR>
369    <TR>
370        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
371        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_sink_alignment'><CODE>alignment</CODE></A>.</TD>
372    </TR>
373</TABLE>
374
375<A NAME="mapped_file_sink_is_open"></A>
376<H4><CODE>mapped_file_sink::is_open</CODE></H4>
377
378<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
379   
380<P>Returns <CODE>true</CODE> if this <CODE>mapped_file_sink</CODE> has been successfully opened without subsequently having been closed.</P>
381
382<A NAME="mapped_file_sink_close"></A>
383<H4><CODE>mapped_file_sink::close</CODE></H4>
384
385<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
386   
387<P>Frees the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
388
389<A NAME="mapped_file_sink_size"></A>
390<H4><CODE>mapped_file_sink::size</CODE></H4>
391
392<PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
393   
394<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
395
396<A NAME="mapped_file_sink_data"></A>
397<H4><CODE>mapped_file_sink::data</CODE></H4>
398
399<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
400   
401<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
402
403<A NAME="mapped_file_sink_alignment"></A>
404<H4><CODE>mapped_file_sink::alignment</CODE></H4>
405
406<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
407   
408<P>Returns the operating system's virtual memory allocation granularity.</P>
409
410<A NAME="mapped_file"></A>
411<H3>4. Class <CODE>mapped_file</CODE></H3>
412
413<H4>Description</H4>
414
415<P>Model of <A HREF="../concepts/seekable_device.html">SeekableDevice</A> providing read-write access to memory-mapped files on Windows and POSIX systems.</P>
416
417<H4>Synopsis</H4>
418
419<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
420
421<SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file</SPAN> {
422<SPAN CLASS="keyword">public</SPAN>:
423    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
424    <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
425    <A CLASS='documented' HREF='#mapped_file_default_ctor'>mapped_file</A>();
426    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_params_ctor'>mapped_file</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
427    <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_basic_ctor'>mapped_file</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
428                          std::ios_base::openmode mode =
429                              std::ios_base | std::ios_base,
430                          size_type length = max_length,
431                          boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
432    void <A CLASS='documented' HREF='#mapped_file_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
433    void <A CLASS='documented' HREF='#mapped_file_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
434               std::ios_base::openmode mode =
435                   std::ios_base | std::ios_base,
436               size_type length = max_length,
437               boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
438    <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
439    <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_close'>close</A>();
440    size_type <A CLASS='documented' HREF='#mapped_file_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
441    <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>;
442    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_data'>const_data</A>() <SPAN CLASS='keyword'>const</SPAN>;
443    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_alignment'>alignment</A>();
444};
445
446} } // End namespace boost::io</PRE>
447
448<A NAME="mapped_file_default_ctor"></A>
449<H4><CODE>mapped_file::mapped_file</CODE></H4>
450
451<PRE CLASS="broken_ie">    mapped_file();</PRE>
452   
453<P>Constructs a <CODE>mapped_file</CODE> which must be opened before it can be used to perform i/o.</P>
454
455<A NAME="mapped_file_params_ctor"></A>
456<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
457   
458<P>Constructs a <CODE>mapped_file</CODE> from the given parameters.</P>
459
460<A NAME="mapped_file_basic_ctor"></A>
461<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
462                          std::ios_base::openmode mode =
463                              std::ios_base | std::ios_base,
464                          size_type length = max_length,
465                          boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
466   
467<P>Constructs a <CODE>mapped_file</CODE> to access a specified file. The parameters have the following interpretation:</P>
468
469<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
470<TR>
471    <TR>
472        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
473        <TD>The pathname of the file to map.</TD>
474    </TR>
475    <TR>
476        <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
477        <TD>Indicates whether the file should be opened with read-access, write-access or both.</TD>
478    </TR>
479    <TR>
480        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
481        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
482    </TR>
483    <TR>
484        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
485        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_alignment'><CODE>alignment</CODE></A>.</TD>
486    </TR>
487</TABLE>
488
489<A NAME="mapped_file_params_open"></A>
490<H4><CODE>mapped_file::open</CODE></H4>
491
492<PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
493   
494<P>Connects this <CODE>mapped_file</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
495
496<A NAME="mapped_file_basic_open"></A>
497<PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path,
498                   std::ios_base::openmode mode =
499                       std::ios_base | std::ios_base,
500                   size_type length = max_length,
501                   boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
502   
503<P>Connects this <CODE>mapped_file</CODE> to a memory-mapped file obtained as described by the given parameters, which have the following interpretation:</P>
504
505<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
506<TR>
507    <TR>
508        <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
509        <TD>The pathname of the file to map.</TD>
510    </TR>
511    <TR>
512        <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
513        <TD>Indicates whether the file should be opened with read-access, write-access or both.</TD>
514    </TR>
515    <TR>
516        <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
517        <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
518    </TR>
519    <TR>
520        <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
521        <TD>The offset where the mapping is to begin. This value must be a multiple of the operating system's virtual memory allocation granularity, which can be obtained using the static member function <A HREF='#mapped_file_alignment'><CODE>alignment</CODE></A>.</TD>
522    </TR>
523</TABLE>
524
525<A NAME="mapped_file_is_open"></A>
526<H4><CODE>mapped_file::is_open</CODE></H4>
527
528<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
529   
530<P>Returns <CODE>true</CODE> if this <CODE>mapped_file</CODE> has been successfully opened without subsequently having been closed.</P>
531
532<A NAME="mapped_file_close"></A>
533<H4><CODE>mapped_file::close</CODE></H4>
534
535<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
536   
537<P>Frees the mapping associated with this <CODE>mapped_file</CODE>.</P>
538
539<A NAME="mapped_file_size"></A>
540<H4><CODE>mapped_file::size</CODE></H4>
541
542<PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
543   
544<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file</CODE>.</P>
545
546<A NAME="mapped_file_data"></A>
547<H4><CODE>mapped_file::data</CODE></H4>
548
549<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
550   
551<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file</CODE>, if it was opened with write-access, and a null pointer otherwise.</P>
552
553<A NAME="mapped_file_data"></A>
554<H4><CODE>mapped_file::data</CODE></H4>
555
556<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* const_data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
557   
558<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file</CODE>.</P>
559
560<A NAME="mapped_file_alignment"></A>
561<H4><CODE>mapped_file::alignment</CODE></H4>
562
563<PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
564   
565<P>Returns the operating system's virtual memory allocation granularity.</P>
566
567<!-- Begin Footer -->
568
569<HR>
570<P CLASS="copyright">Revised
571<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
57220 May, 2004
573<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
574</P>
575
576<P CLASS="copyright">&copy; Copyright <A HREF="http://www.kangaroologic.com" TARGET="_top">Jonathan Turkanis</A>, 2004</P>
577<P CLASS="copyright"> 
578    Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)
579</P>
580
581<!-- End Footer -->
582
583</BODY>
Note: See TracBrowser for help on using the repository browser.