Ch26.9: I/O Operations
1. The Layer Below print, scan and transmit
The raw operations move characters or bytes and report how much moved. They do not format, parse or choose a buffer. They are what a device implementation is built on, and they are the escape hatch when a protocol needs exact control over one read, one write or one offset.
Application code normally uses print, scan and
transmit. Those three handle formatting, buffered input lookahead and the
zero-copy staging. The operations on this page are for the layer underneath, or for the
rare case where the application really does need a raw byte window.
2. Read Operations
| Operation | Return | Meaning |
|---|---|---|
read_some(in, char* buf, count) |
std::size_t |
Read at most count characters. Returns how many were read;
0 means EOF. |
read_all(in, char* buf, count) |
void |
Read exactly count characters or fail. |
read_some_bytes(in, std::byte* buf, count) |
std::size_t |
The byte-addressed form; returns bytes read. |
read_all_bytes(in, std::byte* buf, count) |
void |
Read exactly count bytes or fail. |
char buf[4096];
auto const n{::fast_io::operations::read_some(in, buf, sizeof(buf))};
if (n == 0)
{
// end of input
}
read_some is the primitive. It may return less than requested even when
more data will arrive later. read_all is the convenience form that keeps
reading until the requested count is satisfied.
3. Write Operations
| Operation | Return | Meaning |
|---|---|---|
write_some(out, char const* buf, count) |
std::size_t |
Write at most count characters; returns how many were accepted. |
write_all(out, char const* buf, count) |
void |
Write every character or fail. |
write_some_bytes(out, std::byte const* buf, count) |
std::size_t |
The byte-addressed form; returns bytes written. |
write_all_bytes(out, std::byte const* buf, count) |
void |
Write every byte or fail. |
A short write is normal on pipes and sockets. write_all loops until the
whole buffer is accepted; write_some lets the caller decide what to do with
the unsent suffix.
4. Positioned Operations
pread_* and pwrite_* take an explicit
::fast_io::intfpos_t offset. They do not consume the device's own position;
this is the same distinction as POSIX pread/pwrite. Use them
when several readers or writers share one file or when you are patching a record at a
known offset.
| Operation | Return | Meaning |
|---|---|---|
pread_some(in, char* buf, count, off) |
std::size_t |
Read at off without advancing the stream position. |
pread_all(in, char* buf, count, off) |
void |
Read exactly count characters at off. |
pwrite_some(out, char const* buf, count, off) |
std::size_t |
Write at off without advancing the stream position. |
pwrite_all(out, char const* buf, count, off) |
void |
Write every character at off. |
The *_bytes forms take std::byte* and an offset in the same
way. A pipe or socket is not seekable, so passing an offset there is a failure, not a
silent fallback.
5. Scatter Operations
Scatter/gather operations take an array of ::fast_io::io_scatter_t entries
instead of one contiguous buffer. Each entry is a base pointer plus a length. This avoids
copying a set of buffers into one contiguous block just to write them.
::fast_io::io_scatter_t parts[2]{
{header.data(), header.size()},
{body.data(), body.size()}};
::fast_io::operations::scatter_write_all(out, parts, 2);
| Family | Forms |
|---|---|
| Read | scatter_read_some, scatter_read_all,
scatter_read_some_bytes, scatter_read_all_bytes |
| Write | scatter_write_some, scatter_write_all,
scatter_write_some_bytes, scatter_write_all_bytes |
| Positioned read | scatter_pread_some, scatter_pread_all,
scatter_pread_some_bytes, scatter_pread_all_bytes |
| Positioned write | scatter_pwrite_some, scatter_pwrite_all,
scatter_pwrite_some_bytes, scatter_pwrite_all_bytes |
The *_some forms return io_scatter_status_t, which identifies
the position in the scatter array and the position inside that entry. The
*_all forms return void and fail if the whole scatter is not
transferred.
6. Seek, Flush and Single Characters
| Operation | Meaning |
|---|---|
io_stream_seek_bytes(stream, off, seekdir) |
Seek a bidirectional stream; returns the new position. |
input_stream_seek_bytes, output_stream_seek_bytes |
Direction-specific seek. Header-side. |
input_stream_buffer_flush, output_stream_buffer_flush,
io_stream_buffer_flush |
Flush buffered data. Header-side. |
char_put(out, ch) |
Write one character. Header-side. |
seekdir is beg, cur or end. A
buffered stream flushes or adjusts its buffer before the seek, so the position you get
back is the one the device will use, not the stale buffer cursor.
7. Failure and Partial Progress
All of these operations report device failures as herbceptions. The difference between
some and all is the partial-progress policy:
*_somereturns the amount transferred; a short count is not an error.*_allkeeps going until the requested amount is transferred or fails.read_somereturning0means EOF, not failure.- A non-seekable device plus a positioned operation is a failure.
8. Module Export Boundary
The fast_io module exports the read, write, pread, pwrite and scatter
families, plus io_stream_seek_bytes. The direction-specific seek forms,
buffer-flush operations, char_put and some reference accessors are
header-side today. Use #include <fast_io.h> for those.
print, scan and transmit unless you are
implementing a device or a layer below fast_io. The raw operations move the buffer
bookkeeping back into your code.
Key Takeaways
read_some/write_somereport partial progress;read_all/write_allcomplete or fail.- The
*_bytesforms usestd::byte*and byte counts. pread/pwriteuse an explicit offset and do not consume the stream position.- Scatter operations take
io_scatter_tarrays; the*_someforms return anio_scatter_status_t. seekdirisbeg/cur/end; a positioned operation on a non-seekable device fails.- The module exports the main read/write/pread/pwrite/scatter families and
io_stream_seek_bytes; flush,char_putand direction-specific seeks are header-side. - Application code should use
print,scanandtransmitinstead.