# std::basic_istream<CharT,Traits>::read

> C++ Atlas: `cppatlas.com/w/cpp/io/basic_istream/read` | Source: https://en.cppreference.com/w/cpp/io/basic_istream/read | Domain: Input/output

Extracts characters from stream.

## Official Specification Summary (cppreference)

```cpp
basic_istream& read( char_type* s, std::streamsize count );
```

Extracts characters from stream.

Behaves as *UnformattedInputFunction*. After constructing and checking the sentry object, extracts characters and stores them into successive locations of the character array whose first element is pointed to by `s`. Characters are extracted and stored until any of the following conditions occurs:

- `count` characters were extracted and stored.

- end of file condition occurs on the input sequence (in which case, `setstate(failbit|eofbit)` is called). The number of successfully extracted characters can be queried using `gcount()`.

### Parameters

- `s` - pointer to the character array to store the characters to
- `count` - number of characters to read

### Return value

`*this`

### Exceptions

`failure`

if an error occurred (the error state flag is not

`goodbit`

) and

`exceptions()`

is set to throw for that state.

If an internal operation throws an exception, it is caught and `badbit` is set. If `exceptions()` is set for `badbit`, the exception is rethrown.

### Notes

When using a non-converting locale (the default locale is non-converting), the overrider of this function in `std::basic_ifstream` may be optimized for zero-copy bulk I/O (by means of overriding `std::streambuf::xsgetn`).

### Example

```cpp
#include <cstdint>
#include <fstream>
#include <iostream>
#include <sstream>
#include <string>

int main()
{
    // read() is often used for binary I/O
    std::string bin = {'\x12', '\x12', '\x12', '\x12'};
    std::istringstream raw(bin);
    std::uint32_t n;
    if (raw.read(reinterpret_cast<char*>(&n), sizeof n))
        std::cout << std::hex << std::showbase << n << '\n';

    // prepare file for next snippet
    std::ofstream("test.txt", std::ios::binary) << "abcd1\nabcd2\nabcd3";

    // read entire file into string
    if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate})
    {
        auto size = is.tellg();
        std::string str(size, '\0'); // construct string to stream size
        is.seekg(0);
        if (is.read(&str[0], size))
            std::cout << str << '\n';
    }
}
```

Output:

```text
0x12121212
abcd1
abcd2
abcd3
```

### See also

- [`write`](https://en.cppreference.com/w/cpp/io/basic_ostream/write): inserts blocks of characters (public member function of `std::basic_ostream<CharT,Traits>`)
- [`operator>>`](https://en.cppreference.com/w/cpp/io/basic_istream/operator_gtgt): extracts formatted data (public member function)
- [`readsome`](https://en.cppreference.com/w/cpp/io/basic_istream/readsome): extracts already available blocks of characters (public member function)
- [`get`](https://en.cppreference.com/w/cpp/io/basic_istream/get): extracts characters (public member function)
- [`getline`](https://en.cppreference.com/w/cpp/io/basic_istream/getline): extracts characters until the given character is found (public member function)
- [`fread`](https://en.cppreference.com/w/cpp/io/c/fread): reads from a file (function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/basic_istream/read (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.