123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177 |
- [/
- Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- ]
- [section:File File]
- The [*File] concept abstracts access to files in the underlying file system.
- To support other platform interfaces, users may author their own [*File]
- types which meet these requirements.
- [heading Associated Types]
- * [link beast.ref.boost__beast__file_mode `file_mode`]
- * [link beast.ref.boost__beast__is_file `is_file`]
- [heading Requirements]
- In this table:
- * `F` is a [*File] type
- * `f` is an instance of `F`
- * `p` is a value of type `char const*` which points to a null
- terminated utf-8 encoded string.
- * `m` is an instance of [link beast.ref.boost__beast__file_mode `file_mode`]
- * `n` is a number of bytes, convertible to `std::size_t`
- * `o` is a byte offset in the file, convertible to `std::uint64_t`
- * `b` is any non-const pointer to memory
- * `c` is any possibly-const pointer to memory
- * `ec` is a reference of type [link beast.ref.boost__beast__error_code `error_code`]
- [table Valid expressions
- [[Expression] [Type] [Semantics, Pre/Post-conditions]]
- [[Operation] [Return Type] [Semantics, Pre/Post-conditions]]
- [
- [`F()`]
- [ ]
- [
- Default constructable
- ]
- ]
- [
- [`f.~F()`]
- [ ]
- [
- Destructible.
- If `f` refers to an open file, it is first closed
- as if by a call to `close` with the error ignored.
- ]
- ]
- [
- [`f.is_open()`]
- [`bool`]
- [
- Returns `true` if `f` refers to an open file, `false` otherwise.
- ]
- ]
- [
- [`f.close(ec)`]
- []
- [
- If `f` refers to an open file, this function attempts to
- close the file.
- Regardless of whether an error occurs or not, a subsequent
- call to `f.is_open()` will return `false`.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.open(p,m,ec)`]
- []
- [
- Attempts to open the file at the path specified by `p`
- with the mode specified by `m`.
- Upon success, a subsequent call to `f.is_open()` will
- return `true`.
- If `f` refers to an open file, it is first closed
- as if by a call to `close` with the error ignored.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.size(ec)`]
- [`std::uint64_t`]
- [
- If `f` refers to an open file, this function attempts to
- determine the file size and return its value.
- If `f` does not refer to an open file, the function will
- set `ec` to `errc::invalid_argument` and return 0.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.pos(ec)`]
- [`std::uint64_t`]
- [
- If `f` refers to an open file, this function attempts to
- determine the current file offset and return it.
- If `f` does not refer to an open file, the function will
- set `ec` to `errc::invalid_argument` and return 0.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.seek(o,ec)`]
- []
- [
- Attempts to reposition the current file offset to the value
- `o`, which represents a byte offset relative to the beginning
- of the file.
- If `f` does not refer to an open file, the function will
- set `ec` to `errc::invalid_argument` and return immediately.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.read(b,n,ec)`]
- [`std::size_t`]
- [
- Attempts to read `n` bytes starting at the current file offset
- from the open file referred to by `f`.
- Bytes read are stored in the memory buffer at address `b` which
- must be at least `n` bytes in size.
- The function advances the file offset by the amount read, and
- returns the number of bytes actually read, which may be less
- than `n`.
- If `f` does not refer to an open file, the function will
- set `ec` to `errc::invalid_argument` and return immediately.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- [
- [`f.write(c,n,ec)`]
- [`std::size_t`]
- [
- Attempts to write `n` bytes from the buffer pointed to by `c` to
- the current file offset of the open file referred to by `f`.
- The memory buffer at `c` must point to storage of at least `n`
- bytes meant to be copied to the file.
- The function advances the file offset by the amount written,
- and returns the number of bytes actually written, which may be
- less than `n`.
- If `f` does not refer to an open file, the function will
- set `ec` to `errc::invalid_argument` and return immediately.
- The function will ensure that `!ec` is `true` if there was
- no error or set to the appropriate error code if an error
- occurred.
- ]
- ]
- ]
- [heading Exemplar]
- [concept_File]
- [heading Models]
- * [link beast.ref.boost__beast__file_posix `file_posix`]
- * [link beast.ref.boost__beast__file_stdio `file_stdio`]
- * [link beast.ref.boost__beast__file_win32 `file_win32`]
- [endsect]
|