1[/ 2 Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6] 7 8[section:File File] 9 10The [*File] concept abstracts access to files in the underlying file system. 11To support other platform interfaces, users may author their own [*File] 12types which meet these requirements. 13 14[heading Associated Types] 15 16* [link beast.ref.boost__beast__file_mode `file_mode`] 17* [link beast.ref.boost__beast__is_file `is_file`] 18 19[heading Requirements] 20 21In this table: 22 23* `F` is a [*File] type 24* `f` is an instance of `F` 25* `p` is a value of type `char const*` which points to a null 26 terminated utf-8 encoded string. 27* `m` is an instance of [link beast.ref.boost__beast__file_mode `file_mode`] 28* `n` is a number of bytes, convertible to `std::size_t` 29* `o` is a byte offset in the file, convertible to `std::uint64_t` 30* `b` is any non-const pointer to memory 31* `c` is any possibly-const pointer to memory 32* `ec` is a reference of type [link beast.ref.boost__beast__error_code `error_code`] 33 34[table Valid expressions 35[[Expression] [Type] [Semantics, Pre/Post-conditions]] 36[[Operation] [Return Type] [Semantics, Pre/Post-conditions]] 37[ 38 [`F()`] 39 [ ] 40 [ 41 Default constructable 42 ] 43] 44[ 45 [`f.~F()`] 46 [ ] 47 [ 48 Destructible. 49 If `f` refers to an open file, it is first closed 50 as if by a call to `close` with the error ignored. 51 ] 52] 53[ 54 [`f.is_open()`] 55 [`bool`] 56 [ 57 Returns `true` if `f` refers to an open file, `false` otherwise. 58 ] 59] 60[ 61 [`f.close(ec)`] 62 [] 63 [ 64 If `f` refers to an open file, this function attempts to 65 close the file. 66 Regardless of whether an error occurs or not, a subsequent 67 call to `f.is_open()` will return `false`. 68 The function will ensure that `!ec` is `true` if there was 69 no error or set to the appropriate error code if an error 70 occurred. 71 ] 72] 73[ 74 [`f.open(p,m,ec)`] 75 [] 76 [ 77 Attempts to open the file at the path specified by `p` 78 with the mode specified by `m`. 79 Upon success, a subsequent call to `f.is_open()` will 80 return `true`. 81 If `f` refers to an open file, it is first closed 82 as if by a call to `close` with the error ignored. 83 The function will ensure that `!ec` is `true` if there was 84 no error or set to the appropriate error code if an error 85 occurred. 86 87 ] 88] 89[ 90 [`f.size(ec)`] 91 [`std::uint64_t`] 92 [ 93 If `f` refers to an open file, this function attempts to 94 determine the file size and return its value. 95 If `f` does not refer to an open file, the function will 96 set `ec` to `errc::invalid_argument` and return 0. 97 The function will ensure that `!ec` is `true` if there was 98 no error or set to the appropriate error code if an error 99 occurred. 100 ] 101] 102[ 103 [`f.pos(ec)`] 104 [`std::uint64_t`] 105 [ 106 If `f` refers to an open file, this function attempts to 107 determine the current file offset and return it. 108 If `f` does not refer to an open file, the function will 109 set `ec` to `errc::invalid_argument` and return 0. 110 The function will ensure that `!ec` is `true` if there was 111 no error or set to the appropriate error code if an error 112 occurred. 113 ] 114] 115[ 116 [`f.seek(o,ec)`] 117 [] 118 [ 119 Attempts to reposition the current file offset to the value 120 `o`, which represents a byte offset relative to the beginning 121 of the file. 122 If `f` does not refer to an open file, the function will 123 set `ec` to `errc::invalid_argument` and return immediately. 124 The function will ensure that `!ec` is `true` if there was 125 no error or set to the appropriate error code if an error 126 occurred. 127 ] 128] 129[ 130 [`f.read(b,n,ec)`] 131 [`std::size_t`] 132 [ 133 Attempts to read `n` bytes starting at the current file offset 134 from the open file referred to by `f`. 135 Bytes read are stored in the memory buffer at address `b` which 136 must be at least `n` bytes in size. 137 The function advances the file offset by the amount read, and 138 returns the number of bytes actually read, which may be less 139 than `n`. 140 If `f` does not refer to an open file, the function will 141 set `ec` to `errc::invalid_argument` and return immediately. 142 The function will ensure that `!ec` is `true` if there was 143 no error or set to the appropriate error code if an error 144 occurred. 145 If an end-of-file condition is detected prior to reading any 146 bytes, the function will ensure that `!ec` is `true` and the 147 return value shall be 0. 148 ] 149] 150[ 151 [`f.write(c,n,ec)`] 152 [`std::size_t`] 153 [ 154 Attempts to write `n` bytes from the buffer pointed to by `c` to 155 the current file offset of the open file referred to by `f`. 156 The memory buffer at `c` must point to storage of at least `n` 157 bytes meant to be copied to the file. 158 The function advances the file offset by the amount written, 159 and returns the number of bytes actually written, which may be 160 less than `n`. 161 If `f` does not refer to an open file, the function will 162 set `ec` to `errc::invalid_argument` and return immediately. 163 The function will ensure that `!ec` is `true` if there was 164 no error or set to the appropriate error code if an error 165 occurred. 166 ] 167] 168] 169 170[heading Exemplar] 171 172[concept_File] 173 174[heading Models] 175 176* [link beast.ref.boost__beast__file_posix `file_posix`] 177* [link beast.ref.boost__beast__file_stdio `file_stdio`] 178* [link beast.ref.boost__beast__file_win32 `file_win32`] 179 180[endsect] 181