1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff 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:SyncRandomAccessReadDevice Buffer-oriented synchronous random-access
9read device requirements]
10
11In the table below, `a` denotes a synchronous random-access read device object,
12`o` denotes an offset of type `boost::uint64_t`, `mb` denotes an object
13satisfying [link boost_asio.reference.MutableBufferSequence mutable buffer sequence]
14requirements, and `ec` denotes an object of type `error_code`.
15
16[table Buffer-oriented synchronous random-access read device requirements
17  [[operation] [type] [semantics, pre/post-conditions]]
18  [
19    [`a.read_some_at(o, mb);`]
20    [`size_t`]
21    [Equivalent to:
22     ``
23       error_code ec;
24       size_t s = a.read_some_at(o, mb, ec);
25       if (ec) throw system_error(ec);
26       return s;
27     ``]
28  ]
29  [
30    [`a.read_some_at(o, mb, ec);`]
31    [`size_t`]
32    [
33      Reads one or more bytes of data from the device `a` at offset `o`.[br]
34      [br]
35      The mutable buffer sequence `mb` specifies memory where the data should
36      be placed. The `read_some_at` operation shall always fill a buffer in the
37      sequence completely before proceeding to the next.[br]
38      [br]
39      If successful, returns the number of bytes read and sets `ec` such that
40      `!ec` is true. If an error occurred, returns `0` and sets `ec` such that
41      `!!ec` is true.[br]
42      [br]
43      If the total size of all buffers in the sequence `mb` is `0`, the
44      function shall return `0` immediately.
45    ]
46  ]
47]
48
49[endsect]
50