1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>File</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast"> 8<link rel="up" href="../concepts.html" title="Concepts"> 9<link rel="prev" href="FieldsWriter.html" title="FieldsWriter"> 10<link rel="next" href="RatePolicy.html" title="RatePolicy"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="FieldsWriter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="RatePolicy.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="beast.concepts.File"></a><a class="link" href="File.html" title="File">File</a> 28</h3></div></div></div> 29<p> 30 The <span class="bold"><strong>File</strong></span> concept abstracts access to files 31 in the underlying file system. To support other platform interfaces, users 32 may author their own <span class="bold"><strong>File</strong></span> types which meet 33 these requirements. 34 </p> 35<h5> 36<a name="beast.concepts.File.h0"></a> 37 <span class="phrase"><a name="beast.concepts.File.associated_types"></a></span><a class="link" href="File.html#beast.concepts.File.associated_types">Associated 38 Types</a> 39 </h5> 40<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 41<li class="listitem"> 42 <a class="link" href="../ref/boost__beast__file_mode.html" title="file_mode"><code class="computeroutput"><span class="identifier">file_mode</span></code></a> 43 </li> 44<li class="listitem"> 45 <a class="link" href="../ref/boost__beast__is_file.html" title="is_file"><code class="computeroutput"><span class="identifier">is_file</span></code></a> 46 </li> 47</ul></div> 48<h5> 49<a name="beast.concepts.File.h1"></a> 50 <span class="phrase"><a name="beast.concepts.File.requirements"></a></span><a class="link" href="File.html#beast.concepts.File.requirements">Requirements</a> 51 </h5> 52<p> 53 In this table: 54 </p> 55<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 56<li class="listitem"> 57 <code class="computeroutput"><span class="identifier">F</span></code> is a <span class="bold"><strong>File</strong></span> 58 type 59 </li> 60<li class="listitem"> 61 <code class="computeroutput"><span class="identifier">f</span></code> is an instance of 62 <code class="computeroutput"><span class="identifier">F</span></code> 63 </li> 64<li class="listitem"> 65 <code class="computeroutput"><span class="identifier">p</span></code> is a value of type 66 <code class="computeroutput"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span></code> which points to a null terminated utf-8 67 encoded string. 68 </li> 69<li class="listitem"> 70 <code class="computeroutput"><span class="identifier">m</span></code> is an instance of 71 <a class="link" href="../ref/boost__beast__file_mode.html" title="file_mode"><code class="computeroutput"><span class="identifier">file_mode</span></code></a> 72 </li> 73<li class="listitem"> 74 <code class="computeroutput"><span class="identifier">n</span></code> is a number of bytes, 75 convertible to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> 76 </li> 77<li class="listitem"> 78 <code class="computeroutput"><span class="identifier">o</span></code> is a byte offset in 79 the file, convertible to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span></code> 80 </li> 81<li class="listitem"> 82 <code class="computeroutput"><span class="identifier">b</span></code> is any non-const pointer 83 to memory 84 </li> 85<li class="listitem"> 86 <code class="computeroutput"><span class="identifier">c</span></code> is any possibly-const 87 pointer to memory 88 </li> 89<li class="listitem"> 90 <code class="computeroutput"><span class="identifier">ec</span></code> is a reference of 91 type <a class="link" href="../ref/boost__beast__error_code.html" title="error_code"><code class="computeroutput"><span class="identifier">error_code</span></code></a> 92 </li> 93</ul></div> 94<div class="table"> 95<a name="beast.concepts.File.valid_expressions"></a><p class="title"><b>Table 1.43. Valid expressions</b></p> 96<div class="table-contents"><table class="table" summary="Valid expressions"> 97<colgroup> 98<col> 99<col> 100<col> 101</colgroup> 102<thead><tr> 103<th> 104 <p> 105 Expression 106 </p> 107 </th> 108<th> 109 <p> 110 Type 111 </p> 112 </th> 113<th> 114 <p> 115 Semantics, Pre/Post-conditions 116 </p> 117 </th> 118</tr></thead> 119<tbody> 120<tr> 121<td> 122 <p> 123 Operation 124 </p> 125 </td> 126<td> 127 <p> 128 Return Type 129 </p> 130 </td> 131<td> 132 <p> 133 Semantics, Pre/Post-conditions 134 </p> 135 </td> 136</tr> 137<tr> 138<td> 139 <p> 140 <code class="computeroutput"><span class="identifier">F</span><span class="special">()</span></code> 141 </p> 142 </td> 143<td> 144 </td> 145<td> 146 <p> 147 Default constructable 148 </p> 149 </td> 150</tr> 151<tr> 152<td> 153 <p> 154 <code class="computeroutput"><span class="identifier">f</span><span class="special">.~</span><span class="identifier">F</span><span class="special">()</span></code> 155 </p> 156 </td> 157<td> 158 </td> 159<td> 160 <p> 161 Destructible. If <code class="computeroutput"><span class="identifier">f</span></code> 162 refers to an open file, it is first closed as if by a call to 163 <code class="computeroutput"><span class="identifier">close</span></code> with the 164 error ignored. 165 </p> 166 </td> 167</tr> 168<tr> 169<td> 170 <p> 171 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">()</span></code> 172 </p> 173 </td> 174<td> 175 <p> 176 <code class="computeroutput"><span class="keyword">bool</span></code> 177 </p> 178 </td> 179<td> 180 <p> 181 Returns <code class="computeroutput"><span class="keyword">true</span></code> if <code class="computeroutput"><span class="identifier">f</span></code> refers to an open file, <code class="computeroutput"><span class="keyword">false</span></code> otherwise. 182 </p> 183 </td> 184</tr> 185<tr> 186<td> 187 <p> 188 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">close</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 189 </p> 190 </td> 191<td> 192 </td> 193<td> 194 <p> 195 If <code class="computeroutput"><span class="identifier">f</span></code> refers to 196 an open file, this function attempts to close the file. Regardless 197 of whether an error occurs or not, a subsequent call to <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">()</span></code> 198 will return <code class="computeroutput"><span class="keyword">false</span></code>. 199 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 200 if there was no error or set to the appropriate error code if an 201 error occurred. 202 </p> 203 </td> 204</tr> 205<tr> 206<td> 207 <p> 208 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">open</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span><span class="identifier">m</span><span class="special">,</span><span class="identifier">ec</span><span class="special">)</span></code> 209 </p> 210 </td> 211<td> 212 </td> 213<td> 214 <p> 215 Attempts to open the file at the path specified by <code class="computeroutput"><span class="identifier">p</span></code> with the mode specified by 216 <code class="computeroutput"><span class="identifier">m</span></code>. Upon success, 217 a subsequent call to <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">is_open</span><span class="special">()</span></code> will return <code class="computeroutput"><span class="keyword">true</span></code>. 218 If <code class="computeroutput"><span class="identifier">f</span></code> refers to 219 an open file, it is first closed as if by a call to <code class="computeroutput"><span class="identifier">close</span></code> with the error ignored. 220 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 221 if there was no error or set to the appropriate error code if an 222 error occurred. 223 </p> 224 </td> 225</tr> 226<tr> 227<td> 228 <p> 229 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">size</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 230 </p> 231 </td> 232<td> 233 <p> 234 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span></code> 235 </p> 236 </td> 237<td> 238 <p> 239 If <code class="computeroutput"><span class="identifier">f</span></code> refers to 240 an open file, this function attempts to determine the file size 241 and return its value. If <code class="computeroutput"><span class="identifier">f</span></code> 242 does not refer to an open file, the function will set <code class="computeroutput"><span class="identifier">ec</span></code> to <code class="computeroutput"><span class="identifier">errc</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> 243 and return 0. The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 244 if there was no error or set to the appropriate error code if an 245 error occurred. 246 </p> 247 </td> 248</tr> 249<tr> 250<td> 251 <p> 252 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">pos</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span></code> 253 </p> 254 </td> 255<td> 256 <p> 257 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span></code> 258 </p> 259 </td> 260<td> 261 <p> 262 If <code class="computeroutput"><span class="identifier">f</span></code> refers to 263 an open file, this function attempts to determine the current file 264 offset and return it. If <code class="computeroutput"><span class="identifier">f</span></code> 265 does not refer to an open file, the function will set <code class="computeroutput"><span class="identifier">ec</span></code> to <code class="computeroutput"><span class="identifier">errc</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> 266 and return 0. The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 267 if there was no error or set to the appropriate error code if an 268 error occurred. 269 </p> 270 </td> 271</tr> 272<tr> 273<td> 274 <p> 275 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">seek</span><span class="special">(</span><span class="identifier">o</span><span class="special">,</span><span class="identifier">ec</span><span class="special">)</span></code> 276 </p> 277 </td> 278<td> 279 </td> 280<td> 281 <p> 282 Attempts to reposition the current file offset to the value <code class="computeroutput"><span class="identifier">o</span></code>, which represents a byte offset 283 relative to the beginning of the file. If <code class="computeroutput"><span class="identifier">f</span></code> 284 does not refer to an open file, the function will set <code class="computeroutput"><span class="identifier">ec</span></code> to <code class="computeroutput"><span class="identifier">errc</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> 285 and return immediately. The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> 286 is <code class="computeroutput"><span class="keyword">true</span></code> if there was 287 no error or set to the appropriate error code if an error occurred. 288 </p> 289 </td> 290</tr> 291<tr> 292<td> 293 <p> 294 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span><span class="identifier">n</span><span class="special">,</span><span class="identifier">ec</span><span class="special">)</span></code> 295 </p> 296 </td> 297<td> 298 <p> 299 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> 300 </p> 301 </td> 302<td> 303 <p> 304 Attempts to read <code class="computeroutput"><span class="identifier">n</span></code> 305 bytes starting at the current file offset from the open file referred 306 to by <code class="computeroutput"><span class="identifier">f</span></code>. Bytes 307 read are stored in the memory buffer at address <code class="computeroutput"><span class="identifier">b</span></code> 308 which must be at least <code class="computeroutput"><span class="identifier">n</span></code> 309 bytes in size. The function advances the file offset by the amount 310 read, and returns the number of bytes actually read, which may 311 be less than <code class="computeroutput"><span class="identifier">n</span></code>. 312 If <code class="computeroutput"><span class="identifier">f</span></code> does not refer 313 to an open file, the function will set <code class="computeroutput"><span class="identifier">ec</span></code> 314 to <code class="computeroutput"><span class="identifier">errc</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> and return immediately. 315 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 316 if there was no error or set to the appropriate error code if an 317 error occurred. If an end-of-file condition is detected prior to 318 reading any bytes, the function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> 319 is <code class="computeroutput"><span class="keyword">true</span></code> and the return 320 value shall be 0. 321 </p> 322 </td> 323</tr> 324<tr> 325<td> 326 <p> 327 <code class="computeroutput"><span class="identifier">f</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span><span class="identifier">c</span><span class="special">,</span><span class="identifier">n</span><span class="special">,</span><span class="identifier">ec</span><span class="special">)</span></code> 328 </p> 329 </td> 330<td> 331 <p> 332 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code> 333 </p> 334 </td> 335<td> 336 <p> 337 Attempts to write <code class="computeroutput"><span class="identifier">n</span></code> 338 bytes from the buffer pointed to by <code class="computeroutput"><span class="identifier">c</span></code> 339 to the current file offset of the open file referred to by <code class="computeroutput"><span class="identifier">f</span></code>. The memory buffer at <code class="computeroutput"><span class="identifier">c</span></code> must point to storage of at 340 least <code class="computeroutput"><span class="identifier">n</span></code> bytes meant 341 to be copied to the file. The function advances the file offset 342 by the amount written, and returns the number of bytes actually 343 written, which may be less than <code class="computeroutput"><span class="identifier">n</span></code>. 344 If <code class="computeroutput"><span class="identifier">f</span></code> does not refer 345 to an open file, the function will set <code class="computeroutput"><span class="identifier">ec</span></code> 346 to <code class="computeroutput"><span class="identifier">errc</span><span class="special">::</span><span class="identifier">invalid_argument</span></code> and return immediately. 347 The function will ensure that <code class="computeroutput"><span class="special">!</span><span class="identifier">ec</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 348 if there was no error or set to the appropriate error code if an 349 error occurred. 350 </p> 351 </td> 352</tr> 353</tbody> 354</table></div> 355</div> 356<br class="table-break"><h5> 357<a name="beast.concepts.File.h2"></a> 358 <span class="phrase"><a name="beast.concepts.File.exemplar"></a></span><a class="link" href="File.html#beast.concepts.File.exemplar">Exemplar</a> 359 </h5> 360<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">File</span> 361<span class="special">{</span> 362 <span class="comment">/** Default constructor 363 364 There is no open file initially. 365 */</span> 366 <span class="identifier">File</span><span class="special">();</span> 367 368 <span class="comment">/** Destructor 369 370 If the file is open it is first closed. 371 */</span> 372 <span class="special">~</span><span class="identifier">File</span><span class="special">();</span> 373 374 <span class="comment">/// Returns `true` if the file is open</span> 375 <span class="keyword">bool</span> 376 <span class="identifier">is_open</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 377 378 <span class="comment">/// Close the file if open</span> 379 <span class="keyword">void</span> 380 <span class="identifier">close</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">);</span> 381 382 <span class="comment">/// Open a file at the given path with the specified mode</span> 383 <span class="keyword">void</span> 384 <span class="identifier">open</span><span class="special">(</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">path</span><span class="special">,</span> <span class="identifier">file_mode</span> <span class="identifier">mode</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">);</span> 385 386 <span class="comment">/// Return the size of the open file</span> 387 <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> 388 <span class="identifier">size</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 389 390 <span class="comment">/// Return the current position in the open file</span> 391 <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> 392 <span class="identifier">pos</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 393 394 <span class="comment">/// Adjust the current position in the open file</span> 395 <span class="keyword">void</span> 396 <span class="identifier">seek</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> <span class="identifier">offset</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">);</span> 397 398 <span class="comment">/// Read from the open file</span> 399 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> 400 <span class="identifier">read</span><span class="special">(</span><span class="keyword">void</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 401 402 <span class="comment">/// Write to the open file</span> 403 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> 404 <span class="identifier">write</span><span class="special">(</span><span class="keyword">void</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">error_code</span><span class="special">&</span> <span class="identifier">ec</span><span class="special">);</span> 405<span class="special">};</span> 406</pre> 407<h5> 408<a name="beast.concepts.File.h3"></a> 409 <span class="phrase"><a name="beast.concepts.File.models"></a></span><a class="link" href="File.html#beast.concepts.File.models">Models</a> 410 </h5> 411<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 412<li class="listitem"> 413 <a class="link" href="../ref/boost__beast__file_posix.html" title="file_posix"><code class="computeroutput"><span class="identifier">file_posix</span></code></a> 414 </li> 415<li class="listitem"> 416 <a class="link" href="../ref/boost__beast__file_stdio.html" title="file_stdio"><code class="computeroutput"><span class="identifier">file_stdio</span></code></a> 417 </li> 418<li class="listitem"> 419 <a class="link" href="../ref/boost__beast__file_win32.html" title="file_win32"><code class="computeroutput"><span class="identifier">file_win32</span></code></a> 420 </li> 421</ul></div> 422</div> 423<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 424<td align="left"></td> 425<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 426 Falco<p> 427 Distributed under the Boost Software License, Version 1.0. (See accompanying 428 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 429 </p> 430</div></td> 431</tr></table> 432<hr> 433<div class="spirit-nav"> 434<a accesskey="p" href="FieldsWriter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../concepts.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="RatePolicy.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 435</div> 436</body> 437</html> 438
