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    ]
146]
147[
148    [`f.write(c,n,ec)`]
149    [`std::size_t`]
150    [
151        Attempts to write `n` bytes from the buffer pointed to by `c` to
152        the current file offset of the open file referred to by `f`.
153        The memory buffer at `c` must point to storage of at least `n`
154        bytes meant to be copied to the file.
155        The function advances the file offset by the amount written,
156        and returns the number of bytes actually written, which may be
157        less than `n`.
158        If `f` does not refer to an open file, the function will
159        set `ec` to `errc::invalid_argument` and return immediately.
160        The function will ensure that `!ec` is `true` if there was
161        no error or set to the appropriate error code if an error
162        occurred.
163    ]
164]
165]
166
167[heading Exemplar]
168
169[concept_File]
170
171[heading Models]
172
173* [link beast.ref.boost__beast__file_posix `file_posix`]
174* [link beast.ref.boost__beast__file_stdio `file_stdio`]
175* [link beast.ref.boost__beast__file_win32 `file_win32`]
176
177[endsect]
178