CARVIEW |
Select Language
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Wed, 23 Jul 2025 02:53:06 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Location: /reference/istream/basic_istream/read/
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 23 Jul 2025 02:53:06 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
ETag: W/"8484-n1StK79pnUSWDSpOyjbxgbBu6w4"
Content-Encoding: gzip
Extracts n characters from the stream and stores them in the array pointed by by s.
This function simply copies a block of data, without checking its contents nor appending a null character at the end.
If the input sequence runs out of characters to extract (i.e., the end-of-file is reached) before n characters have been successfully read, the array pointed by s contains all the characters read until that point, and both the eofbit and failbit flags are set for the stream.
Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to
The number of characters successfully read and stored by this function can be accessed by calling member gcount.
Errors are signaled by modifying the internal state flags:
Multiple flags may be set by a single operation.
If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.
Possible output:
Concurrent access to the same stream object may cause data races, except for the standard stream objects cin and wcin when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.
Reference
C library:
- <cassert> (assert.h)
- <cctype> (ctype.h)
- <cerrno> (errno.h)
-
<cfenv> (fenv.h)C++11
- <cfloat> (float.h)
-
<cinttypes> (inttypes.h)C++11
- <ciso646> (iso646.h)
- <climits> (limits.h)
- <clocale> (locale.h)
- <cmath> (math.h)
- <csetjmp> (setjmp.h)
- <csignal> (signal.h)
- <cstdarg> (stdarg.h)
-
<cstdbool> (stdbool.h)C++11
- <cstddef> (stddef.h)
-
<cstdint> (stdint.h)C++11
- <cstdio> (stdio.h)
- <cstdlib> (stdlib.h)
- <cstring> (string.h)
-
<ctgmath> (tgmath.h)C++11
- <ctime> (time.h)
-
<cuchar> (uchar.h)C++11
- <cwchar> (wchar.h)
- <cwctype> (wctype.h)
Containers:
-
<array>C++11
- <deque>
-
<forward_list>C++11
- <list>
- <map>
- <queue>
- <set>
- <stack>
-
<unordered_map>C++11
-
<unordered_set>C++11
- <vector>
-
Input/Output:
Multi-threading:
-
<atomic>C++11
-
<condition_variable>C++11
-
<future>C++11
-
<mutex>C++11
-
<thread>C++11
-
Other:
- <algorithm>
- <bitset>
-
<chrono>C++11
-
<codecvt>C++11
- <complex>
- <exception>
- <functional>
-
<initializer_list>C++11
- <iterator>
- <limits>
- <locale>
- <memory>
- <new>
- <numeric>
-
<random>C++11
-
<ratio>C++11
-
<regex>C++11
- <stdexcept>
- <string>
-
<system_error>C++11
-
<tuple>C++11
-
<type_traits>C++11
-
<typeindex>C++11
- <typeinfo>
- <utility>
- <valarray>
<istream>
class templates
classes
manipulators
basic_istream
- basic_istream::~basic_istream
- basic_istream::basic_istream
member classes
member functions
non-member overloads
protected members
-
basic_istream::operator=C++11
-
basic_istream::swapC++11
-
public member function
<istream> <iostream>
std::basic_istream::read
basic_istream& read (char_type* s, streamsize n);
Read block of data
This function simply copies a block of data, without checking its contents nor appending a null character at the end.
If the input sequence runs out of characters to extract (i.e., the end-of-file is reached) before n characters have been successfully read, the array pointed by s contains all the characters read until that point, and both the eofbit and failbit flags are set for the stream.
Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to
true
). Then (if good), it extracts characters from its associated stream buffer object as if calling its member functions sbumpc or sgetc, and finally destroys the sentry object before returning.The number of characters successfully read and stored by this function can be accessed by calling member gcount.
Parameters
- s
- Pointer to an array where the extracted characters are stored.
Member type char_type is the type of characters used by the stream (i.e., its first class template parameter, charT).
- n
- Number of characters to extract.
streamsize is a signed integral type.
Return Value
The basic_istream object (*this
).Errors are signaled by modifying the internal state flags:
flag | error |
---|---|
eofbit | The function stopped extracting characters because the input sequence has no more characters available (end-of-file reached). |
failbit | Either the function could not extract n characters or the construction of sentry failed. |
badbit | Error on stream (such as when this function catches an exception thrown by an internal operation). When set, the integrity of the stream may have been affected. |
If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.
Example
|
|
Possible output:
Reading 640 characters... all characters read successfully. |
Data races
Modifies the elements in the array pointed by s and the stream object.Concurrent access to the same stream object may cause data races, except for the standard stream objects cin and wcin when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).
Exception safety
Basic guarantee: if an exception is thrown, the object is in a valid state.It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.
See also
- basic_istream::get
- Get characters (public member function)
- basic_istream::readsome
- Read data available in buffer (public member function)
- basic_istream::operator>>
- Extract formatted input (public member function)
Home page | Privacy policy
© cplusplus.com, 2000-2025 - All rights reserved - v3.3.4s
Spotted an error? contact us
© cplusplus.com, 2000-2025 - All rights reserved - v3.3.4s
Spotted an error? contact us