Difference between revisions of "cpp/io/c/fread"
From cppreference.com
m (typo) |
m (→Example: fmt) |
||
| (13 intermediate revisions by 9 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{cpp/title | fread}} | + | {{cpp/title|fread}} |
{{cpp/io/c/navbar}} | {{cpp/io/c/navbar}} | ||
| − | {{ddcl | header=cstdio | | + | {{ddcl|header=cstdio| |
| − | std::size_t fread( void* buffer, std::size_t size, std::size_t count, FILE* stream ); | + | std::size_t fread( void* buffer, std::size_t size, std::size_t count, std::FILE* stream ); |
}} | }} | ||
| − | Reads | + | Reads up to {{c|count}} objects into the array {{c|buffer}} from the given input stream {{c|stream}} as if by calling {{lc|std::fgetc}} {{c|size}} times for each object, and storing the results, in the order obtained, into the successive positions of {{c|buffer}}, which is reinterpreted as an array of {{c|unsigned char}}. The file position indicator for the stream is advanced by the number of characters read. |
| + | |||
| + | If the objects are not {{named req|TriviallyCopyable}}, the behavior is undefined. | ||
| + | |||
| + | If an error occurs, the resulting value of the file position indicator for the stream is | ||
| + | indeterminate. If a partial element is read, its value is indeterminate. | ||
===Parameters=== | ===Parameters=== | ||
| − | {{ | + | {{par begin}} |
| − | {{ | + | {{par|buffer|pointer to the first object in the array to be read}} |
| − | {{ | + | {{par|size|size of each object in bytes}} |
| − | {{ | + | {{par|count|the number of the objects to be read}} |
| − | {{ | + | {{par|stream|input file stream to read from}} |
| + | {{par end}} | ||
===Return value=== | ===Return value=== | ||
| − | Number of objects read successfully | + | Number of objects read successfully, which may be less than {{c|count}} if an error or end-of-file condition occurs. |
| + | |||
| + | If {{c|size}} or {{c|count}} is zero, {{tt|fread}} returns zero and performs no other action. | ||
| + | |||
| + | {{tt|fread}} does not distinguish between end-of-file and error, and callers must use {{lc|std::feof}} and {{lc|std::ferror}} to determine which occurred. | ||
===Example=== | ===Example=== | ||
| − | {{example | + | {{example |
| − | | code= | + | |code= |
| − | #include < | + | #include <cstddef> |
#include <cstdio> | #include <cstdio> | ||
#include <fstream> | #include <fstream> | ||
| + | #include <iomanip> | ||
| + | #include <iostream> | ||
#include <vector> | #include <vector> | ||
| + | |||
int main() | int main() | ||
{ | { | ||
| − | // | + | // Prepare file |
std::ofstream("test.txt") << 1 << ' ' << 2 << '\n'; | std::ofstream("test.txt") << 1 << ' ' << 2 << '\n'; | ||
| − | FILE* f = std::fopen("test.txt", "r"); | + | std::FILE* f = std::fopen("test.txt", "r"); |
| − | std::vector<char> buf(4); // char is | + | std::vector<char> buf(4); // char is trivially copyable |
| − | std::fread(&buf[0], sizeof buf[0], buf.size(), f); | + | const std::size_t n = std::fread(&buf[0], sizeof buf[0], buf.size(), f); |
| − | for(char n : buf) | + | std::cout << "Read " << n << " object" << (n > 1 ? "s" : "") << ": " |
| − | std::cout << n; | + | << std::hex << std::uppercase << std::setfill('0'); |
| + | for (char n : buf) | ||
| + | std::cout << "0x" << std::setw(2) << static_cast<short>(n) << ' '; | ||
| + | std::cout << '\n'; | ||
std::vector<std::string> buf2; // string is not trivially copyable | std::vector<std::string> buf2; // string is not trivially copyable | ||
| − | // | + | // This would result in undefined behavior: |
| − | // | + | // std::fread(&buf2[0], sizeof buf2[0], buf2.size(), f); |
} | } | ||
| − | | output= | + | |p=true |
| − | + | |output= | |
| + | Read 4 objects: 0x31 0x20 0x32 0x0A | ||
}} | }} | ||
===See also=== | ===See also=== | ||
| − | {{ | + | {{dsc begin}} |
| − | {{ | + | {{dsc inc|cpp/io/c/dsc fscanf}} |
| − | {{ | + | {{dsc inc|cpp/io/c/dsc fgets}} |
| − | {{ | + | {{dsc inc|cpp/io/c/dsc fwrite}} |
| − | {{ | + | {{dsc see c|c/io/fread}} |
| − | {{ | + | {{dsc end}} |
| − | + | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} | |
| − | + | ||
| − | + | ||
Latest revision as of 13:30, 2 October 2023
| Defined in header <cstdio>
|
||
| std::size_t fread( void* buffer, std::size_t size, std::size_t count, std::FILE* stream ); |
||
Reads up to count objects into the array buffer from the given input stream stream as if by calling std::fgetc size times for each object, and storing the results, in the order obtained, into the successive positions of buffer, which is reinterpreted as an array of unsigned char. The file position indicator for the stream is advanced by the number of characters read.
If the objects are not TriviallyCopyable, the behavior is undefined.
If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.
Contents |
[edit] Parameters
| buffer | - | pointer to the first object in the array to be read |
| size | - | size of each object in bytes |
| count | - | the number of the objects to be read |
| stream | - | input file stream to read from |
[edit] Return value
Number of objects read successfully, which may be less than count if an error or end-of-file condition occurs.
If size or count is zero, fread returns zero and performs no other action.
fread does not distinguish between end-of-file and error, and callers must use std::feof and std::ferror to determine which occurred.
[edit] Example
Run this code
#include <cstddef> #include <cstdio> #include <fstream> #include <iomanip> #include <iostream> #include <vector> int main() { // Prepare file std::ofstream("test.txt") << 1 << ' ' << 2 << '\n'; std::FILE* f = std::fopen("test.txt", "r"); std::vector<char> buf(4); // char is trivially copyable const std::size_t n = std::fread(&buf[0], sizeof buf[0], buf.size(), f); std::cout << "Read " << n << " object" << (n > 1 ? "s" : "") << ": " << std::hex << std::uppercase << std::setfill('0'); for (char n : buf) std::cout << "0x" << std::setw(2) << static_cast<short>(n) << ' '; std::cout << '\n'; std::vector<std::string> buf2; // string is not trivially copyable // This would result in undefined behavior: // std::fread(&buf2[0], sizeof buf2[0], buf2.size(), f); }
Possible output:
Read 4 objects: 0x31 0x20 0x32 0x0A
[edit] See also
| reads formatted input from stdin, a file stream or a buffer (function) | |
| gets a character string from a file stream (function) | |
| writes to a file (function) | |
| C documentation for fread
| |
