ceph/src/boost/libs/iostreams/doc/classes/mapped_file.html

   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/device/mapped_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>
  58 The 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&amp; path);
  92     std::string              <A CLASS='documented' HREF='#mapped_file_params_hint'>path</A>;
  93     mapped_file::mapmode     <A CLASS='documented' HREF='#mapped_file_params_flags'>flags</A>;
  94     std::ios_base::openmode  <A CLASS='documented' HREF='#mapped_file_params_mode'>mode</A>;  // Deprecated
  95     stream_offset            <A CLASS='documented' HREF='#mapped_file_params_offset'>offset</A>;
  96     std::size_t              <A CLASS='documented' HREF='#mapped_file_params_length'>length</A>;
  97     stream_offset            <A CLASS="documented" HREF="#mapped_file_params_size">new_file_size</A>;
  98     <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>*              <A CLASS='documented' HREF='#mapped_file_params_hint'>hint</A>;
  99 };
 100
 101 } } // End namespace boost::io</PRE>
 102
 103 <A NAME="mapped_file_params_path"></A>
 104 <H4><CODE>mapped_file_params::path</CODE></H4>
 105
 106 <PRE CLASS="broken_ie">    std::string              path;</PRE>
 107
 108 <P>The pathname of the file to map.</P>
 109
 110 <A NAME="mapped_file_params_mode"></A>
 111 <H4><CODE>mapped_file_params::mode</CODE></H4>
 112
 113 <PRE CLASS="broken_ie">    std::ios_base::openmode  mode;</PRE>
 114
 115 <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>. This member is deprecated.  Please use flags in new code instead.</P>
 116
 117 <A NAME="mapped_file_params_flags"></A>
 118 <H4><CODE>mapped_file_params::flags</CODE></H4>
 119
 120 <PRE CLASS="broken_ie">    mapped_file::mapmode  flags;</PRE>
 121
 122 <P>Indicates whether the file should be opened with read-access, read-write-access, or private access.  A file opened with private access can be written to, but the changes will not affect the underlying file.</P>
 123
 124 <A NAME="mapped_file_params_offset"></A>
 125 <H4><CODE>mapped_file_params::offset</CODE></H4>
 126
 127 <PRE CLASS="broken_ie">    stream_offset            offset;</PRE>
 128
 129 <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>
 130
 131 <A NAME="mapped_file_params_length"></A>
 132 <H4><CODE>mapped_file_params::length</CODE></H4>
 133
 134 <PRE CLASS="broken_ie">    std::size_t              length;</PRE>
 135
 136 <P>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</P>
 137
 138 <A NAME="mapped_file_params_size"></A>
 139 <H4><CODE>mapped_file_params::new_file_size</CODE></H4>
 140
 141 <PRE CLASS="broken_ie">    stream_offset            new_file_size;</PRE>
 142
 143 <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>
 144
 145 <A NAME="mapped_file_params_hint"></A>
 146 <H4><CODE>mapped_file_params::hint</CODE></H4>
 147
 148 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>*              hint;</PRE>
 149
 150 <P>Suggests a location in the process's address space for the mapping to begin.</P>
 151
 152 <A NAME="mapped_file_source"></A>
 153 <H3>2. Class <CODE>mapped_file_source</CODE></H3>
 154
 155 <H4>Description</H4>
 156
 157 <P>Model of <A HREF="../concepts/source.html">Source</A> providing read-only access to memory-mapped files on Windows and POSIX systems.</P>
 158
 159 <H4>Synopsis</H4>
 160
 161 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
 162
 163 <SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file_source</SPAN> {
 164 <SPAN CLASS="keyword">public</SPAN>:
 165     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
 166     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
 167     <A CLASS='documented' HREF='#mapped_file_source_default_ctor'>mapped_file_source</A>();
 168     <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);
 169     <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&amp; path,
 170                                  size_type length = max_length,
 171                                  boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 172     void <A CLASS='documented' HREF='#mapped_file_source_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
 173     void <A CLASS='documented' HREF='#mapped_file_source_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 174                size_type length = max_length,
 175                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 176     <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_source_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
 177     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_source_close'>close</A>();
 178     size_type <A CLASS='documented' HREF='#mapped_file_source_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
 179     <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>;
 180     <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_source_alignment'>alignment</A>();
 181 };
 182
 183 } } // End namespace boost::io</PRE>
 184
 185 <A NAME="mapped_file_source_default_ctor"></A>
 186 <H4><CODE>mapped_file_source::mapped_file_source</CODE></H4>
 187
 188 <PRE CLASS="broken_ie">    mapped_file_source();</PRE>
 189
 190 <P>Constructs a <CODE>mapped_file_source</CODE> which must be opened before it can be used to perform i/o.</P>
 191
 192 <A NAME="mapped_file_source_params_ctor"></A>
 193 <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>
 194
 195 <P>Constructs a <CODE>mapped_file_source</CODE> from the given parameters.</P>
 196
 197 <A NAME="mapped_file_source_basic_ctor"></A>
 198 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_source( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 199                                  size_type length = max_length,
 200                                  boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 201
 202 <P>Constructs a <CODE>mapped_file_source</CODE> to access a specified file. The parameters have the following interpretation:</P>
 203
 204 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 205 <TR>
 206     <TR>
 207         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 208         <TD>The pathname of the file to map.</TD>
 209     </TR>
 210     <TR>
 211         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 212         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 213     </TR>
 214     <TR>
 215         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 216         <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>
 217     </TR>
 218 </TABLE>
 219
 220 <A NAME="mapped_file_source_params_open"></A>
 221 <H4><CODE>mapped_file_source::open</CODE></H4>
 222
 223 <PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
 224
 225 <P>Connects this <CODE>mapped_file_source</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
 226
 227 <A NAME="mapped_file_source_basic_open"></A>
 228 <PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 229                    size_type length = max_length,
 230                    boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 231
 232 <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>
 233
 234 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 235 <TR>
 236     <TR>
 237         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 238         <TD>The pathname of the file to map.</TD>
 239     </TR>
 240     <TR>
 241         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 242         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 243     </TR>
 244     <TR>
 245         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 246         <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>
 247     </TR>
 248 </TABLE>
 249
 250 <A NAME="mapped_file_source_is_open"></A>
 251 <H4><CODE>mapped_file_source::is_open</CODE></H4>
 252
 253 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 254
 255 <P>Returns <CODE>true</CODE> if this <CODE>mapped_file_source</CODE> has been successfully opened without subsequently having been closed.</P>
 256
 257 <A NAME="mapped_file_source_close"></A>
 258 <H4><CODE>mapped_file_source::close</CODE></H4>
 259
 260 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
 261
 262 <P>Frees the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
 263
 264 <A NAME="mapped_file_source_size"></A>
 265 <H4><CODE>mapped_file_source::size</CODE></H4>
 266
 267 <PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 268
 269 <P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
 270
 271 <A NAME="mapped_file_source_data"></A>
 272 <H4><CODE>mapped_file_source::data</CODE></H4>
 273
 274 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 275
 276 <P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_source</CODE>.</P>
 277
 278 <A NAME="mapped_file_source_alignment"></A>
 279 <H4><CODE>mapped_file_source::alignment</CODE></H4>
 280
 281 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
 282
 283 <P>Returns the operating system's virtual memory allocation granularity.</P>
 284
 285 <A NAME="mapped_file_sink"></A>
 286 <H3>3. Class <CODE>mapped_file_sink</CODE></H3>
 287
 288 <H4>Description</H4>
 289
 290 <P>Model of <A HREF="../concepts/sink.html">Sink</A> providing write-only access to memory-mapped files on Windows and POSIX systems.</P>
 291
 292 <H4>Synopsis</H4>
 293
 294 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
 295
 296 <SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file_sink</SPAN> {
 297 <SPAN CLASS="keyword">public</SPAN>:
 298     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
 299     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
 300     <SPAN CLASS='keyword'>enum</SPAN> mapmode { readwrite, priv };
 301     <A CLASS='documented' HREF='#mapped_file_sink_default_ctor'>mapped_file_sink</A>();
 302     <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);
 303     <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&amp; path,
 304                                size_type length = max_length,
 305                                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>,
 306                                mapmode flags = readwrite );
 307     void <A CLASS='documented' HREF='#mapped_file_sink_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
 308     void <A CLASS='documented' HREF='#mapped_file_sink_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 309                size_type length = max_length,
 310                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>,
 311                mapmode flags = readwrite );
 312     <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
 313     mapmode <A CLASS='documented' HREF='#mapped_file_sink_flags'>flags</A>() <SPAN CLASS='keyword'>const</SPAN>;
 314     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_close'>close</A>();
 315     size_type <A CLASS='documented' HREF='#mapped_file_sink_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
 316     <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_sink_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>;
 317     <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_alignment'>alignment</A>();
 318 };
 319
 320 } } // End namespace boost::io</PRE>
 321
 322 <A NAME="mapped_file_sink_default_ctor"></A>
 323 <H4><CODE>mapped_file_sink::mapped_file_sink</CODE></H4>
 324
 325 <PRE CLASS="broken_ie">    mapped_file_sink();</PRE>
 326
 327 <P>Constructs a <CODE>mapped_file_sink</CODE> which must be opened before it can be used to perform i/o.</P>
 328
 329 <A NAME="mapped_file_sink_params_ctor"></A>
 330 <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>
 331
 332 <P>Constructs a <CODE>mapped_file_sink</CODE> from the given parameters.</P>
 333
 334 <A NAME="mapped_file_sink_basic_ctor"></A>
 335 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_sink( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 336                                size_type length = max_length,
 337                                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>,
 338                                mapmode flags );</PRE>
 339
 340 <P>Constructs a <CODE>mapped_file_sink</CODE> to access a specified file. The parameters have the following interpretation:</P>
 341
 342 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 343 <TR>
 344     <TR>
 345         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 346         <TD>The pathname of the file to map.</TD>
 347     </TR>
 348     <TR>
 349         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 350         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 351     </TR>
 352     <TR>
 353         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 354         <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>
 355     </TR>
 356     <TR>
 357         <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 358         <TD>Indicates whether the <CODE>mapped_file_sink</CODE> should be opened for read-write access or private access.</TD>
 359     </TR>
 360 </TABLE>
 361
 362 <A NAME="mapped_file_sink_params_open"></A>
 363 <H4><CODE>mapped_file_sink::open</CODE></H4>
 364
 365 <PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
 366
 367 <P>Connects this <CODE>mapped_file_sink</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
 368
 369 <A NAME="mapped_file_sink_basic_open"></A>
 370 <PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 371                    size_type length = max_length,
 372                    boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>
 373                    mapmode flags );</PRE>
 374
 375 <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>
 376
 377 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 378 <TR>
 379     <TR>
 380         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 381         <TD>The pathname of the file to map.</TD>
 382     </TR>
 383     <TR>
 384         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 385         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 386     </TR>
 387     <TR>
 388         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 389         <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>
 390     </TR>
 391     <TR>
 392         <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 393         <TD>Indicates whether the <CODE>mapped_file_sink</CODE> should be opened for read-write access or private access.</TD>
 394     </TR>
 395 </TABLE>
 396
 397 <A NAME="mapped_file_sink_is_open"></A>
 398 <H4><CODE>mapped_file_sink::is_open</CODE></H4>
 399
 400 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 401
 402 <P>Returns <CODE>true</CODE> if this <CODE>mapped_file_sink</CODE> has been successfully opened without subsequently having been closed.</P>
 403
 404 <A NAME="mapped_file_sink_flags"></A>
 405 <H4><CODE>mapped_file_sink::flags</CODE></H4>
 406
 407 <PRE CLASS="broken_ie">    mapmode flags() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 408
 409 <P>Indicates whether the <CODE>mapped_file_sink</CODE> was opened for read/write-access or private-access.</P>
 410
 411 <A NAME="mapped_file_sink_close"></A>
 412 <H4><CODE>mapped_file_sink::close</CODE></H4>
 413
 414 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
 415
 416 <P>Frees the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
 417
 418 <A NAME="mapped_file_sink_size"></A>
 419 <H4><CODE>mapped_file_sink::size</CODE></H4>
 420
 421 <PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 422
 423 <P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
 424
 425 <A NAME="mapped_file_sink_data"></A>
 426 <H4><CODE>mapped_file_sink::data</CODE></H4>
 427
 428 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 429
 430 <P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_sink</CODE>.</P>
 431
 432 <A NAME="mapped_file_sink_alignment"></A>
 433 <H4><CODE>mapped_file_sink::alignment</CODE></H4>
 434
 435 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
 436
 437 <P>Returns the operating system's virtual memory allocation granularity.</P>
 438
 439 <A NAME="mapped_file"></A>
 440 <H3>4. Class <CODE>mapped_file</CODE></H3>
 441
 442 <H4>Description</H4>
 443
 444 <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>
 445
 446 <H4>Synopsis</H4>
 447
 448 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
 449
 450 <SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file</SPAN> {
 451 <SPAN CLASS="keyword">public</SPAN>:
 452     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN>                      char_type;
 453     <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN>  category;
 454     <SPAN CLASS='keyword'>enum</SPAN> mapmode { readonly, readwrite, priv };
 455     <A CLASS='documented' HREF='#mapped_file_default_ctor'>mapped_file</A>();
 456     <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);
 457     <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_basic_ctor'>mapped_file</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 458                           std::ios_base::openmode mode =
 459                               std::ios_base::in | std::ios_base::out,
 460                           size_type length = max_length,
 461                           boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 462     <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_mapmode_ctor'>mapped_file</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 463                           mapmode mode,
 464                           size_type length = max_length,
 465                           boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 466     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);
 467     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 468                std::ios_base::openmode mode =
 469                    std::ios_base | std::ios_base,
 470                size_type length = max_length,
 471                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 472     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_mapmode_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 473                mapmode mode,
 474                size_type length = max_length,
 475                boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );
 476     <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>;
 477     mapmode <A CLASS='documented' HREF='#mapped_file_flags'>flags</A>() <SPAN CLASS='keyword'>const</SPAN>;
 478     <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_close'>close</A>();
 479     size_type <A CLASS='documented' HREF='#mapped_file_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>;
 480     <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>;
 481     <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_const_data'>const_data</A>() <SPAN CLASS='keyword'>const</SPAN>;
 482     <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_alignment'>alignment</A>();
 483 };
 484
 485 } } // End namespace boost::iostreams</PRE>
 486
 487 <A NAME="mapped_file_default_ctor"></A>
 488 <H4><CODE>mapped_file::mapped_file</CODE></H4>
 489
 490 <PRE CLASS="broken_ie">    mapped_file();</PRE>
 491
 492 <P>Constructs a <CODE>mapped_file</CODE> which must be opened before it can be used to perform i/o.</P>
 493
 494 <A NAME="mapped_file_params_ctor"></A>
 495 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
 496
 497 <P>Constructs a <CODE>mapped_file</CODE> from the given parameters.</P>
 498
 499 <A NAME="mapped_file_basic_ctor"></A>
 500 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 501                           std::ios_base::openmode mode =
 502                               std::ios_base | std::ios_base,
 503                           size_type length = max_length,
 504                           boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 505
 506 <P>Constructs a <CODE>mapped_file</CODE> to access a specified file. The parameters have the following interpretation:</P>
 507
 508 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 509 <TR>
 510     <TR>
 511         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 512         <TD>The pathname of the file to map.</TD>
 513     </TR>
 514     <TR>
 515         <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 516         <TD>Indicates whether the file should be opened with read-access, write-access or both. Use of <CODE>std::ios_base::openmode</CODE> with <CODE>mapped_file</CODE> is deprecated.  Please use <CODE>mapmode</CODE> instead in new code.</TD>
 517     </TR>
 518     <TR>
 519         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 520         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 521     </TR>
 522     <TR>
 523         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 524         <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>
 525     </TR>
 526 </TABLE>
 527
 528 <A NAME="mapped_file_mapmode_ctor"></A>
 529 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>explicit</SPAN> mapped_file( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 530                           mapmode mode,
 531                           size_type length = max_length,
 532                           boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 533
 534 <P>Constructs a <CODE>mapped_file</CODE> to access a specified file. The parameters have the following interpretation:</P>
 535
 536 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 537 <TR>
 538     <TR>
 539         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 540         <TD>The pathname of the file to map.</TD>
 541     </TR>
 542     <TR>
 543         <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 544         <TD>Indicates whether the file should be opened with read-access, read/write-access or private-access.</TD>
 545     </TR>
 546     <TR>
 547         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 548         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 549     </TR>
 550     <TR>
 551         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 552         <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>
 553     </TR>
 554 </TABLE>
 555
 556 <A NAME="mapped_file_params_open"></A>
 557 <H4><CODE>mapped_file::open</CODE></H4>
 558
 559 <PRE CLASS="broken_ie">    void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE>
 560
 561 <P>Connects this <CODE>mapped_file</CODE> to a memory-mapped file obtained as described by the given parameters.</P>
 562
 563 <A NAME="mapped_file_basic_open"></A>
 564 <PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 565                    std::ios_base::openmode mode =
 566                        std::ios_base | std::ios_base,
 567                    size_type length = max_length,
 568                    boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 569
 570 <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>
 571
 572 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 573 <TR>
 574     <TR>
 575         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 576         <TD>The pathname of the file to map.</TD>
 577     </TR>
 578     <TR>
 579         <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 580         <TD>Indicates whether the file should be opened with read-access, write-access or both. Use of <CODE>std::ios_base::openmode</CODE> with <CODE>mapped_file</CODE> is deprecated. Please use <CODE>mapmode</CODE> in new code.</TD>
 581     </TR>
 582     <TR>
 583         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 584         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 585     </TR>
 586     <TR>
 587         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 588         <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>
 589     </TR>
 590 </TABLE>
 591
 592 <A NAME="mapped_file_mapmode_open"></A>
 593 <PRE CLASS="broken_ie">        void open( <SPAN CLASS='keyword'>const</SPAN> std::string&amp; path,
 594                    mapmode mode,
 595                    size_type length = max_length,
 596                    boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE>
 597
 598 <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>
 599
 600 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 601 <TR>
 602     <TR>
 603         <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 604         <TD>The pathname of the file to map.</TD>
 605     </TR>
 606     <TR>
 607         <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 608         <TD>Indicates whether the file should be opened with read-access, read/write-access or private access.</TD>
 609     </TR>
 610     <TR>
 611         <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 612         <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD>
 613     </TR>
 614     <TR>
 615         <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 616         <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>
 617     </TR>
 618 </TABLE>
 619
 620 <A NAME="mapped_file_is_open"></A>
 621 <H4><CODE>mapped_file::is_open</CODE></H4>
 622
 623 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 624
 625 <P>Returns <CODE>true</CODE> if this <CODE>mapped_file</CODE> has been successfully opened without subsequently having been closed.</P>
 626
 627 <A NAME="mapped_file_flags"></A>
 628 <H4><CODE>mapped_file::flags</CODE></H4>
 629
 630 <PRE CLASS="broken_ie">    mapmode flags() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 631
 632 <P>Indicates whether the <CODE>mapped_file</CODE> was opened for read-access, read/write-access or private-access.</P>
 633
 634 <A NAME="mapped_file_close"></A>
 635 <H4><CODE>mapped_file::close</CODE></H4>
 636
 637 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>void</SPAN> close();</PRE>
 638
 639 <P>Frees the mapping associated with this <CODE>mapped_file</CODE>.</P>
 640
 641 <A NAME="mapped_file_size"></A>
 642 <H4><CODE>mapped_file::size</CODE></H4>
 643
 644 <PRE CLASS="broken_ie">    size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 645
 646 <P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file</CODE>.</P>
 647
 648 <A NAME="mapped_file_data"></A>
 649 <H4><CODE>mapped_file::data</CODE></H4>
 650
 651 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 652
 653 <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>
 654
 655 <A NAME="mapped_file_const_data"></A>
 656 <H4><CODE>mapped_file::const_data</CODE></H4>
 657
 658 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* const_data() <SPAN CLASS='keyword'>const</SPAN>;</PRE>
 659
 660 <P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file</CODE>.</P>
 661
 662 <A NAME="mapped_file_alignment"></A>
 663 <H4><CODE>mapped_file::alignment</CODE></H4>
 664
 665 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE>
 666
 667 <P>Returns the operating system's virtual memory allocation granularity.</P>
 668
 669 <!-- Begin Footer -->
 670
 671 <HR>
 672
 673 <P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" target="_top">Jonathan Turkanis</a></P>
 674 <P CLASS="copyright">
 675     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>)
 676 </P>
 677
 678 <!-- End Footer -->
 679
 680 </BODY>