C-style file input/output
The C I/O subset of the C++ standard library implements C-style stream input/output operations. The <cstdio> header provides generic file operation support and supplies functions with narrow and multibyte character input/output capabilities, and the <cwchar> header provides functions with wide character input/output capabilities.
C streams are objects of type std::FILE that can only be accessed and manipulated through pointers of type std::FILE* (Note: while it may be possible to create a local object of type std::FILE by dereferencing and copying a valid std::FILE*, using the address of such copy in the I/O functions is undefined behavior). Each C stream is associated with an external physical device (file, standard input stream, printer, serial port, etc).
C streams can be used for both unformatted and formatted input and output. They are locale-sensitive and may perform wide/multibyte conversions as necessary. Unlike C++ streams, where each stream is associated with its own locale, all C streams access the same locale object: the one most recently installed with std::setlocale.
Besides the system-specific information necessary to access the device (e.g. a POSIX file descriptor), each C stream object holds the following:
std::fpos_t), which, for wide character streams, includes the parse state (an object of type std::mbstate_t).Narrow and wide orientation
A newly opened stream has no orientation. The first call to std::fwide or to any I/O function establishes the orientation: wide I/O function makes the stream wide-oriented, narrow I/O function makes the stream narrow-oriented. Once set, orientation can only be changed with std::freopen. Narrow I/O functions cannot be called on a wide-oriented stream, wide I/O functions cannot be called on a narrow-oriented stream. Wide I/O functions convert between wide and multibyte characters as if by calling std::mbrtowc and std::wcrtomb. Unlike the multibyte character strings that are valid in a program, multibyte characters in the file may contain embedded nulls and do not have to begin or end in the initial shift state.
POSIX requires that the LC_CTYPE facet of the currently installed C locale is stored within the stream object the moment its orientation becomes wide, and is used for all future I/O on this stream until the orientation is changed, regardless of any subsequent calls to std::setlocale.
Binary and text modes
A text stream is an ordered sequence of characters composed into lines (zero or more characters plus a terminating '\n'). Whether the last line requires a terminating '\n' is implementation-defined. Characters may have to be added, altered, or deleted on input and output to conform to the conventions for representing text in the OS (in particular, C streams on Windows OS convert \n to \r\n on output, and convert \r\n to \n on input).
Data read in from a text stream is guaranteed to compare equal to the data that were earlier written out to that stream only if all of the following is true:
- the data consist only of printing characters and the control characters
\tand\n(in particular, on Windows OS, the character'\0x1A'terminates input) - no \n is immediately preceded by a space character (space characters that are written out immediately before a \n may disappear when read)
- the last character is \n
A binary stream is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream always equals to the data that were earlier written out to that stream. Implementations are only allowed to append a number of null characters to the end of the stream. A wide binary stream doesn't need to end in the initial shift state.
POSIX implementations do not distinguish between text and binary streams (there is no special mapping for \n or any other characters).
Functions
Defined in header <cstdio> |
|
|---|---|
File access |
|
| opens a file (function) |
|
| open an existing stream with a different name (function) |
|
| closes a file (function) |
|
| synchronizes an output stream with the actual file (function) |
|
| switches a file stream between wide character I/O and narrow character I/O (function) |
|
| sets the buffer for a file stream (function) |
|
| sets the buffer and its size for a file stream (function) |
|
Direct input/output |
|
| reads from a file (function) |
|
| writes to a file (function) |
|
Unformatted input/output |
|
Byte/multibyte character |
|
| gets a character from a file stream (function) |
|
| gets a character string from a file stream (function) |
|
| writes a character to a file stream (function) |
|
| writes a character string to a file stream (function) |
|
reads a character from stdin (function) |
|
|
(deprecated in C++11)(removed in C++14) | reads a character string from stdin (function) |
writes a character to stdout (function) |
|
writes a character string to stdout (function) |
|
| puts a character back into a file stream (function) |
|
Wide character |
|
| gets a wide character from a file stream (function) |
|
| gets a wide string from a file stream (function) |
|
| writes a wide character to a file stream (function) |
|
| writes a wide string to a file stream (function) |
|
reads a wide character from stdin (function) |
|
writes a wide character to stdout (function) |
|
| puts a wide character back into a file stream (function) |
|
Formatted input/output |
|
Byte/multibyte character |
|
reads formatted input from stdin, a file stream or a buffer (function) |
|
|
(C++11)(C++11)(C++11) | reads formatted input from stdin, a file stream or a bufferusing variable argument list (function) |
|
(C++11) | prints formatted output to stdout, a file stream or a buffer (function) |
|
(C++11) | prints formatted output to stdout, a file stream or a bufferusing variable argument list (function) |
Wide character |
|
reads formatted wide character input from stdin, a file stream or a buffer (function) |
|
|
(C++11)(C++11)(C++11) | reads formatted wide character input from stdin, a file streamor a buffer using variable argument list (function) |
prints formatted wide character output to stdout, a file stream or a buffer (function) |
|
prints formatted wide character output to stdout, a file streamor a buffer using variable argument list (function) |
|
File positioning |
|
| returns the current file position indicator (function) |
|
| gets the file position indicator (function) |
|
| moves the file position indicator to a specific location in a file (function) |
|
| moves the file position indicator to a specific location in a file (function) |
|
| moves the file position indicator to the beginning in a file (function) |
|
Error handling |
|
| clears errors (function) |
|
| checks for the end-of-file (function) |
|
| checks for a file error (function) |
|
displays a character string corresponding of the current error to stderr (function) |
|
Operations on files |
|
| erases a file (function) |
|
| renames a file (function) |
|
| creates and opens a temporary, auto-removing file (function) |
|
| returns a unique filename (function) |
|
Types
Defined in header <cstdio> |
|
|---|---|
| Type | Definition |
FILE | object type, capable of holding all information needed to control a C I/O stream |
fpos_t | complete non-array object type, capable of uniquely specifying a position in a file, including its multibyte parse state |
unsigned integer type returned by the sizeof operator (typedef) |
|
Macros
Defined in header <cstdio> |
|
|---|---|
| stdinstdoutstderr | expression of type FILE* associated with the input streamexpression of type FILE* associated with the output streamexpression of type FILE* associated with the error output stream (macro constant) |
| EOF | integer constant expression of type int and negative value (macro constant) |
| FOPEN_MAX | number of files that can be open simultaneously (macro constant) |
| FILENAME_MAX | size needed for an array of char to hold the longest supported file name (macro constant) |
| BUFSIZ | size of the buffer used by std::setbuf (macro constant) |
| _IOFBF_IOLBF_IONBF | argument to std::setbuf indicating fully buffered I/Oargument to std::setbuf indicating line buffered I/Oargument to std::setbuf indicating unbuffered I/O (macro constant) |
| SEEK_SETSEEK_CURSEEK_END | argument to std::fseek indicating seeking from beginning of the fileargument to std::fseek indicating seeking from the current file positionargument to std::fseek indicating seeking from end of the file (macro constant) |
| TMP_MAX | maximum number of unique filenames that can be generated by std::tmpnam (macro constant) |
| L_tmpnam | size needed for an array of char to hold the result of std::tmpnam (macro constant) |
See also
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/io/c