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"><boost/iostreams/code_converter.hpp></SPAN></A> 48 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/device/mapped_file.hpp"><SPAN CLASS="literal"><boost/iostreams/device/mapped_file.hpp></SPAN></A> 49 50 <SPAN CLASS="keyword">typedef</SPAN> code_converter<mapped_file_source> <SPAN CLASS="defined">wmapped_file_source</SPAN>; 51 <SPAN CLASS="keyword">typedef</SPAN> code_converter<mapped_file_sink> <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><libs/iostreams/src/mapped_file.cpp></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><boost/iostreams/device/mapped_file.hpp></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 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& 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& 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 iterator <A CLASS='documented' HREF='#mapped_file_source_begin'>begin</A>() <SPAN CLASS='keyword'>const</SPAN>; 181 iterator <A CLASS='documented' HREF='#mapped_file_source_end'>end</A>() <SPAN CLASS='keyword'>const</SPAN>; 182 <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_source_alignment'>alignment</A>(); 183}; 184 185} } // End namespace boost::io</PRE> 186 187<A NAME="mapped_file_source_default_ctor"></A> 188<H4><CODE>mapped_file_source::mapped_file_source</CODE></H4> 189 190<PRE CLASS="broken_ie"> mapped_file_source();</PRE> 191 192<P>Constructs a <CODE>mapped_file_source</CODE> which must be opened before it can be used to perform i/o.</P> 193 194<A NAME="mapped_file_source_params_ctor"></A> 195<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> 196 197<P>Constructs a <CODE>mapped_file_source</CODE> from the given parameters.</P> 198 199<A NAME="mapped_file_source_basic_ctor"></A> 200<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_source( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 201 size_type length = max_length, 202 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 203 204<P>Constructs a <CODE>mapped_file_source</CODE> to access a specified file. The parameters have the following interpretation:</P> 205 206<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 207<TR> 208 <TR> 209 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 210 <TD>The pathname of the file to map.</TD> 211 </TR> 212 <TR> 213 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 214 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 215 </TR> 216 <TR> 217 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 218 <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> 219 </TR> 220</TABLE> 221 222<A NAME="mapped_file_source_params_open"></A> 223<H4><CODE>mapped_file_source::open</CODE></H4> 224 225<PRE CLASS="broken_ie"> void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE> 226 227<P>Connects this <CODE>mapped_file_source</CODE> to a memory-mapped file obtained as described by the given parameters.</P> 228 229<A NAME="mapped_file_source_basic_open"></A> 230<PRE CLASS="broken_ie"> void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 231 size_type length = max_length, 232 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 233 234<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> 235 236<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 237<TR> 238 <TR> 239 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 240 <TD>The pathname of the file to map.</TD> 241 </TR> 242 <TR> 243 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 244 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 245 </TR> 246 <TR> 247 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 248 <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> 249 </TR> 250</TABLE> 251 252<A NAME="mapped_file_source_is_open"></A> 253<H4><CODE>mapped_file_source::is_open</CODE></H4> 254 255<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 256 257<P>Returns <CODE>true</CODE> if this <CODE>mapped_file_source</CODE> has been successfully opened without subsequently having been closed.</P> 258 259<A NAME="mapped_file_source_close"></A> 260<H4><CODE>mapped_file_source::close</CODE></H4> 261 262<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>void</SPAN> close();</PRE> 263 264<P>Frees the mapping associated with this <CODE>mapped_file_source</CODE>.</P> 265 266<A NAME="mapped_file_source_size"></A> 267<H4><CODE>mapped_file_source::size</CODE></H4> 268 269<PRE CLASS="broken_ie"> size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 270 271<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_source</CODE>.</P> 272 273<A NAME="mapped_file_source_data"></A> 274<H4><CODE>mapped_file_source::data</CODE></H4> 275 276<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 277 278<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_source</CODE>.</P> 279 280<A NAME="mapped_file_source_begin"></A> 281<H4><CODE>mapped_file_source::begin</CODE></H4> 282 283<PRE CLASS="broken_ie"> iterator begin() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 284 285<P>Returns an iterator to the first byte of data in the mapping associated with this <CODE>mapped_file_source</CODE>.</P> 286 287<A NAME="mapped_file_source_end"></A> 288<H4><CODE>mapped_file_source::end</CODE></H4> 289 290<PRE CLASS="broken_ie"> iterator end() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 291 292<P>Returns an iterator to just past the last byte of data in the mapping associated with this <CODE>mapped_file_source</CODE>.</P> 293 294<A NAME="mapped_file_source_alignment"></A> 295<H4><CODE>mapped_file_source::alignment</CODE></H4> 296 297<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE> 298 299<P>Returns the operating system's virtual memory allocation granularity.</P> 300 301<A NAME="mapped_file_sink"></A> 302<H3>3. Class <CODE>mapped_file_sink</CODE></H3> 303 304<H4>Description</H4> 305 306<P>Model of <A HREF="../concepts/sink.html">Sink</A> providing write-only access to memory-mapped files on Windows and POSIX systems.</P> 307 308<H4>Synopsis</H4> 309 310<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 311 312<SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file_sink</SPAN> { 313<SPAN CLASS="keyword">public</SPAN>: 314 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN> char_type; 315 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; 316 <SPAN CLASS='keyword'>enum</SPAN> mapmode { readwrite, priv }; 317 <A CLASS='documented' HREF='#mapped_file_sink_default_ctor'>mapped_file_sink</A>(); 318 <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); 319 <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, 320 size_type length = max_length, 321 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>, 322 mapmode flags = readwrite ); 323 void <A CLASS='documented' HREF='#mapped_file_sink_params_open'>open</A>(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params); 324 void <A CLASS='documented' HREF='#mapped_file_sink_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 325 size_type length = max_length, 326 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN>, 327 mapmode flags = readwrite ); 328 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>; 329 mapmode <A CLASS='documented' HREF='#mapped_file_sink_flags'>flags</A>() <SPAN CLASS='keyword'>const</SPAN>; 330 <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_close'>close</A>(); 331 size_type <A CLASS='documented' HREF='#mapped_file_sink_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>; 332 <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_sink_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>; 333 iterator <A CLASS='documented' HREF='#mapped_file_sink_begin'>begin</A>() <SPAN CLASS='keyword'>const</SPAN>; 334 iterator <A CLASS='documented' HREF='#mapped_file_sink_end'>end</A>() <SPAN CLASS='keyword'>const</SPAN>; 335 <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_sink_alignment'>alignment</A>(); 336}; 337 338} } // End namespace boost::io</PRE> 339 340<A NAME="mapped_file_sink_default_ctor"></A> 341<H4><CODE>mapped_file_sink::mapped_file_sink</CODE></H4> 342 343<PRE CLASS="broken_ie"> mapped_file_sink();</PRE> 344 345<P>Constructs a <CODE>mapped_file_sink</CODE> which must be opened before it can be used to perform i/o.</P> 346 347<A NAME="mapped_file_sink_params_ctor"></A> 348<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> 349 350<P>Constructs a <CODE>mapped_file_sink</CODE> from the given parameters.</P> 351 352<A NAME="mapped_file_sink_basic_ctor"></A> 353<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> mapped_file_sink( <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>, 356 mapmode flags );</PRE> 357 358<P>Constructs a <CODE>mapped_file_sink</CODE> to access a specified file. The parameters have the following interpretation:</P> 359 360<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 361<TR> 362 <TR> 363 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 364 <TD>The pathname of the file to map.</TD> 365 </TR> 366 <TR> 367 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 368 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 369 </TR> 370 <TR> 371 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 372 <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> 373 </TR> 374 <TR> 375 <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 376 <TD>Indicates whether the <CODE>mapped_file_sink</CODE> should be opened for read-write access or private access.</TD> 377 </TR> 378</TABLE> 379 380<A NAME="mapped_file_sink_params_open"></A> 381<H4><CODE>mapped_file_sink::open</CODE></H4> 382 383<PRE CLASS="broken_ie"> void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE> 384 385<P>Connects this <CODE>mapped_file_sink</CODE> to a memory-mapped file obtained as described by the given parameters.</P> 386 387<A NAME="mapped_file_sink_basic_open"></A> 388<PRE CLASS="broken_ie"> void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 389 size_type length = max_length, 390 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> 391 mapmode flags );</PRE> 392 393<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> 394 395<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 396<TR> 397 <TR> 398 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 399 <TD>The pathname of the file to map.</TD> 400 </TR> 401 <TR> 402 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 403 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 404 </TR> 405 <TR> 406 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 407 <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> 408 </TR> 409 <TR> 410 <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 411 <TD>Indicates whether the <CODE>mapped_file_sink</CODE> should be opened for read-write access or private access.</TD> 412 </TR> 413</TABLE> 414 415<A NAME="mapped_file_sink_is_open"></A> 416<H4><CODE>mapped_file_sink::is_open</CODE></H4> 417 418<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 419 420<P>Returns <CODE>true</CODE> if this <CODE>mapped_file_sink</CODE> has been successfully opened without subsequently having been closed.</P> 421 422<A NAME="mapped_file_sink_flags"></A> 423<H4><CODE>mapped_file_sink::flags</CODE></H4> 424 425<PRE CLASS="broken_ie"> mapmode flags() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 426 427<P>Indicates whether the <CODE>mapped_file_sink</CODE> was opened for read/write-access or private-access.</P> 428 429<A NAME="mapped_file_sink_close"></A> 430<H4><CODE>mapped_file_sink::close</CODE></H4> 431 432<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>void</SPAN> close();</PRE> 433 434<P>Frees the mapping associated with this <CODE>mapped_file_sink</CODE>.</P> 435 436<A NAME="mapped_file_sink_size"></A> 437<H4><CODE>mapped_file_sink::size</CODE></H4> 438 439<PRE CLASS="broken_ie"> size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 440 441<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file_sink</CODE>.</P> 442 443<A NAME="mapped_file_sink_data"></A> 444<H4><CODE>mapped_file_sink::data</CODE></H4> 445 446<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 447 448<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file_sink</CODE>.</P> 449 450<A NAME="mapped_file_sink_begin"></A> 451<H4><CODE>mapped_file_sink::begin</CODE></H4> 452 453<PRE CLASS="broken_ie"> iterator begin() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 454 455<P>Returns an iterator to the first byte of data in the mapping associated with this <CODE>mapped_file_sink</CODE>.</P> 456 457<A NAME="mapped_file_sink_end"></A> 458<H4><CODE>mapped_file_sink::end</CODE></H4> 459 460<PRE CLASS="broken_ie"> iterator end() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 461 462<P>Returns an iterator to just past the last byte of data in the mapping associated with this <CODE>mapped_file_sink</CODE>.</P> 463 464<A NAME="mapped_file_sink_alignment"></A> 465<H4><CODE>mapped_file_sink::alignment</CODE></H4> 466 467<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE> 468 469<P>Returns the operating system's virtual memory allocation granularity.</P> 470 471<A NAME="mapped_file"></A> 472<H3>4. Class <CODE>mapped_file</CODE></H3> 473 474<H4>Description</H4> 475 476<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> 477 478<H4>Synopsis</H4> 479 480<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 481 482<SPAN CLASS="keyword">class</SPAN> <SPAN CLASS="defined">mapped_file</SPAN> { 483<SPAN CLASS="keyword">public</SPAN>: 484 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN> char_type; 485 <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; 486 <SPAN CLASS='keyword'>enum</SPAN> mapmode { readonly, readwrite, priv }; 487 <A CLASS='documented' HREF='#mapped_file_default_ctor'>mapped_file</A>(); 488 <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); 489 <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_basic_ctor'>mapped_file</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 490 std::ios_base::openmode mode = 491 std::ios_base::in | std::ios_base::out, 492 size_type length = max_length, 493 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> ); 494 <SPAN CLASS='keyword'>explicit</SPAN> <A CLASS='documented' HREF='#mapped_file_mapmode_ctor'>mapped_file</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 495 mapmode mode, 496 size_type length = max_length, 497 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> ); 498 <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); 499 <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_basic_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 500 std::ios_base::openmode mode = 501 std::ios_base | std::ios_base, 502 size_type length = max_length, 503 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> ); 504 <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_mapmode_open'>open</A>( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 505 mapmode mode, 506 size_type length = max_length, 507 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> ); 508 <SPAN CLASS='keyword'>bool</SPAN> <A CLASS='documented' HREF='#mapped_file_is_open'>is_open</A>() <SPAN CLASS='keyword'>const</SPAN>; 509 mapmode <A CLASS='documented' HREF='#mapped_file_flags'>flags</A>() <SPAN CLASS='keyword'>const</SPAN>; 510 <SPAN CLASS='keyword'>void</SPAN> <A CLASS='documented' HREF='#mapped_file_close'>close</A>(); 511 size_type <A CLASS='documented' HREF='#mapped_file_size'>size</A>() <SPAN CLASS='keyword'>const</SPAN>; 512 <SPAN CLASS='keyword'>char</SPAN>* <A CLASS='documented' HREF='#mapped_file_data'>data</A>() <SPAN CLASS='keyword'>const</SPAN>; 513 <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>; 514 iterator <A CLASS='documented' HREF='#mapped_file_begin'>begin</A>() <SPAN CLASS='keyword'>const</SPAN>; 515 const_iterator <A CLASS='documented' HREF='#mapped_file_const_begin'>const_begin</A>() <SPAN CLASS='keyword'>const</SPAN>; 516 iterator <A CLASS='documented' HREF='#mapped_file_end'>end</A>() <SPAN CLASS='keyword'>const</SPAN>; 517 const_iterator <A CLASS='documented' HREF='#mapped_file_const_end'>const_end</A>() <SPAN CLASS='keyword'>const</SPAN>; 518 <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> <A CLASS='documented' HREF='#mapped_file_alignment'>alignment</A>(); 519}; 520 521} } // End namespace boost::iostreams</PRE> 522 523<A NAME="mapped_file_default_ctor"></A> 524<H4><CODE>mapped_file::mapped_file</CODE></H4> 525 526<PRE CLASS="broken_ie"> mapped_file();</PRE> 527 528<P>Constructs a <CODE>mapped_file</CODE> which must be opened before it can be used to perform i/o.</P> 529 530<A NAME="mapped_file_params_ctor"></A> 531<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> mapped_file(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE> 532 533<P>Constructs a <CODE>mapped_file</CODE> from the given parameters.</P> 534 535<A NAME="mapped_file_basic_ctor"></A> 536<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> mapped_file( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 537 std::ios_base::openmode mode = 538 std::ios_base | std::ios_base, 539 size_type length = max_length, 540 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 541 542<P>Constructs a <CODE>mapped_file</CODE> to access a specified file. The parameters have the following interpretation:</P> 543 544<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 545<TR> 546 <TR> 547 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 548 <TD>The pathname of the file to map.</TD> 549 </TR> 550 <TR> 551 <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 552 <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> 553 </TR> 554 <TR> 555 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 556 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 557 </TR> 558 <TR> 559 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 560 <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> 561 </TR> 562</TABLE> 563 564<A NAME="mapped_file_mapmode_ctor"></A> 565<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>explicit</SPAN> mapped_file( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 566 mapmode mode, 567 size_type length = max_length, 568 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 569 570<P>Constructs a <CODE>mapped_file</CODE> to access a specified file. The parameters 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, read/write-access or private-access.</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_params_open"></A> 593<H4><CODE>mapped_file::open</CODE></H4> 594 595<PRE CLASS="broken_ie"> void open(<A CLASS='documented' HREF='#mapped_file_params'>mapped_file_params</A> params);</PRE> 596 597<P>Connects this <CODE>mapped_file</CODE> to a memory-mapped file obtained as described by the given parameters.</P> 598 599<A NAME="mapped_file_basic_open"></A> 600<PRE CLASS="broken_ie"> void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 601 std::ios_base::openmode mode = 602 std::ios_base | std::ios_base, 603 size_type length = max_length, 604 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 605 606<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> 607 608<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 609<TR> 610 <TR> 611 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 612 <TD>The pathname of the file to map.</TD> 613 </TR> 614 <TR> 615 <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 616 <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> 617 </TR> 618 <TR> 619 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 620 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 621 </TR> 622 <TR> 623 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 624 <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> 625 </TR> 626</TABLE> 627 628<A NAME="mapped_file_mapmode_open"></A> 629<PRE CLASS="broken_ie"> void open( <SPAN CLASS='keyword'>const</SPAN> std::string& path, 630 mapmode mode, 631 size_type length = max_length, 632 boost::intmax_t offset = <SPAN CLASS='numeric_literal'>0</SPAN> );</PRE> 633 634<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> 635 636<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 637<TR> 638 <TR> 639 <TD VALIGN="top"><I>path</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 640 <TD>The pathname of the file to map.</TD> 641 </TR> 642 <TR> 643 <TD VALIGN="top"><I>mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 644 <TD>Indicates whether the file should be opened with read-access, read/write-access or private access.</TD> 645 </TR> 646 <TR> 647 <TD VALIGN="top"><I>length</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 648 <TD>The number of bytes to map. If this parameter is not specified, the entire file is mapped.</TD> 649 </TR> 650 <TR> 651 <TD VALIGN="top"><I>offset</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 652 <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> 653 </TR> 654</TABLE> 655 656<A NAME="mapped_file_is_open"></A> 657<H4><CODE>mapped_file::is_open</CODE></H4> 658 659<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>bool</SPAN> is_open() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 660 661<P>Returns <CODE>true</CODE> if this <CODE>mapped_file</CODE> has been successfully opened without subsequently having been closed.</P> 662 663<A NAME="mapped_file_flags"></A> 664<H4><CODE>mapped_file::flags</CODE></H4> 665 666<PRE CLASS="broken_ie"> mapmode flags() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 667 668<P>Indicates whether the <CODE>mapped_file</CODE> was opened for read-access, read/write-access or private-access.</P> 669 670<A NAME="mapped_file_close"></A> 671<H4><CODE>mapped_file::close</CODE></H4> 672 673<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>void</SPAN> close();</PRE> 674 675<P>Frees the mapping associated with this <CODE>mapped_file</CODE>.</P> 676 677<A NAME="mapped_file_size"></A> 678<H4><CODE>mapped_file::size</CODE></H4> 679 680<PRE CLASS="broken_ie"> size_type size() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 681 682<P>Returns the size in bytes of the mapping associated with this <CODE>mapped_file</CODE>.</P> 683 684<A NAME="mapped_file_data"></A> 685<H4><CODE>mapped_file::data</CODE></H4> 686 687<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>char</SPAN>* data() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 688 689<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> 690 691<A NAME="mapped_file_const_data"></A> 692<H4><CODE>mapped_file::const_data</CODE></H4> 693 694<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>const</SPAN> <SPAN CLASS='keyword'>char</SPAN>* const_data() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 695 696<P>Returns a pointer to the first byte of data in the mapping associated with this <CODE>mapped_file</CODE>.</P> 697 698<A NAME="mapped_file_begin"></A> 699<H4><CODE>mapped_file::begin</CODE></H4> 700 701<PRE CLASS="broken_ie"> iterator begin() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 702 703<P>Returns an iterator 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 iterator otherwise.</P> 704 705<A NAME="mapped_file_const_begin"></A> 706<H4><CODE>mapped_file::const_begin</CODE></H4> 707 708<PRE CLASS="broken_ie"> const_iterator const_begin() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 709 710<P>Returns a const_iterator to the first byte of data in the mapping associated with this <CODE>mapped_file</CODE>.</P> 711 712<A NAME="mapped_file_end"></A> 713<H4><CODE>mapped_file::end</CODE></H4> 714 715<PRE CLASS="broken_ie"> iterator end() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 716 717<P>Returns an iterator to just past the last 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> 718 719<A NAME="mapped_file_const_end"></A> 720<H4><CODE>mapped_file::const_end</CODE></H4> 721 722<PRE CLASS="broken_ie"> const_iterator const_end() <SPAN CLASS='keyword'>const</SPAN>;</PRE> 723 724<P>Returns a const_iterator to just past the last byte of data in the mapping associated with this <CODE>mapped_file</CODE>.</P> 725 726<A NAME="mapped_file_alignment"></A> 727<H4><CODE>mapped_file::alignment</CODE></H4> 728 729<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>static</SPAN> <SPAN CLASS='keyword'>int</SPAN> alignment();</PRE> 730 731<P>Returns the operating system's virtual memory allocation granularity.</P> 732 733<!-- Begin Footer --> 734 735<HR> 736 737<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P> 738<P CLASS="copyright"> 739 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>) 740</P> 741 742<!-- End Footer --> 743 744</BODY> 745