File input/output

 

C

Language

Standard Library

Type support

Dynamic memory management

Error handling

Program utilities

Date and time utilities

Strings library

Algorithms

Numerics

Input/output support

Localization support

Thread support (C11)

Atomic operations (C11)

 

File input/output

Functions
File access
fopen freopen fclose fflush	fwide setbuf setvbuf
Direct input/output
fread
fwrite
Unformatted input/output
fgetc fgets fputc fputs getchar gets putchar puts ungetc	fgetwc fgetws fputwc fputws getwchar putwchar ungetwc
Formatted input/output
scanffscanfsscanf vscanfvfscanfvsscanf (C99)(C99)(C99) printffprintfsprintfsnprintf (C99) vprintfvfprintfvsprintfvsnprintf (C99)	wscanffwscanfswscanf vwscanfvfwscanfvswscanf (C99)(C99)(C99) wprintffwprintfswprintf vwprintfvfwprintfvswprintf
File positioning
ftell
fgetpos
fseek
fsetpos
rewind
Error handling
clearerr
feof
ferror
perror
Operations on files
remove
rename
tmpfile
tmpnam

 

The <stdio.h> header provides generic file operation support and supplies functions with narrow character input/output capabilities.

The <wchar.h> header supplies functions with wide character input/output capabilities.

I/O streams are objects of type FILE that can only be accessed and manipulated through pointers of type FILE* (Note: while it may be possible to create a local object of type FILE by dereferencing and copying a valid FILE*, using the address of such copy in the I/O functions is undefined behavior). Each stream is associated with an external physical device (file, standard input stream, printer, serial port, etc).

I/O streams can be used for both unformatted and formatted input and output. They are locale-sensitive and may perform wide/multibyte conversions as necessary. All streams access the same locale object: the one most recently installed with setlocale.

Besides the system-specific information necessary to access the device (e.g. a POSIX file descriptor), each stream object holds the following:

1) Character width: unset, narrow, or wide

2) Buffering state: unbuffered, line-buffered, fully buffered.

3) The buffer, which may be replaced by an external, user-provided buffer.

4) I/O mode: input, output, or update (both input and output).

5) Binary/text mode indicator.

6) End-of-file status indicator.

7) Error status indicator.

8) File position indicator (an object of type fpos_t), which, for wide character streams, includes the parse state (an object of type mbstate_t).

9) (C11) Reentrant lock used to prevent data races when multiple threads read, write, position, or query the position of a stream.

Narrow and wide orientation

A newly opened stream has no orientation. The first call 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 freopen and fwide. 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 mbrtowc and wcrtomb. Unlike the multibyte character strings that are valid in a program, multibyte character sequences 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 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 \t and \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

File access
fopen	opens a file (function)
freopen	open an existing stream with a different name (function)
fclose	closes a file (function)
fflush	synchronizes an output stream with the actual file (function)
fwide	switches a file stream between wide character I/O and narrow character I/O (function)
setbuf	sets the buffer for a file stream (function)
setvbuf	sets the buffer and its size for a file stream (function)
Direct input/output
fread	reads from a file (function)
fwrite	writes to a file (function)
Unformatted input/output
Narrow character
fgetcgetc	gets a character from a file stream (function)
fgets	gets a character string from a file stream (function)
fputcputc	writes a character to a file stream (function)
fputs	writes a character string to a file stream (function)
getchar	reads a character from stdin (function)
gets (until C11)	reads a character string from stdin (function)
putchar	writes a character to stdout (function)
puts	writes a character string to stdout (function)
ungetc	puts a character back into a file stream (function)
Wide character
fgetwcgetwc	gets a wide character from a file stream (function)
fgetws	gets a wide string from a file stream (function)
fputwcputwc	writes a wide character to a file stream (function)
fputws	writes a wide string to a file stream (function)
getwchar	reads a wide character from stdin (function)
putwchar	writes a wide character to stdout (function)
ungetwc	puts a wide character back into a file stream (function)
Formatted input/output
Narrow character
scanffscanfsscanf	reads formatted input from stdin, a file stream or a buffer (function)
vscanfvfscanfvsscanf (C99)(C99)(C99)	reads formatted input from stdin, a file stream or a buffer using variable argument list (function)
printffprintfsprintfsnprintf (C99)	prints formatted output to stdout, a file stream or a buffer (function)
vprintfvfprintfvsprintfvsnprintf (C99)	prints formatted output to stdout, a file stream or a buffer using variable argument list (function)
Wide character
wscanffwscanfswscanf	reads formatted wide character input from stdin, a file stream or a buffer (function)
vwscanfvfwscanfvswscanf (C99)(C99)(C99)	reads formatted wide character input from stdin, a file stream or a buffer using variable argument list (function)
wprintffwprintfswprintf	prints formatted wide character output to stdout, a file stream or a buffer (function)
vwprintfvfwprintfvswprintf	prints formatted wide character output to stdout, a file stream or a buffer using variable argument list (function)
File positioning
ftell	returns the current file position indicator (function)
fgetpos	gets the file position indicator (function)
fseek	moves the file position indicator to a specific location in a file (function)
fsetpos	moves the file position indicator to a specific location in a file (function)
rewind	moves the file position indicator to the beginning in a file (function)
Error handling
clearerr	clears errors (function)
feof	checks for the end-of-file (function)
ferror	checks for a file error (function)
perror	displays a character string corresponding of the current error to stderr (function)
Operations on files
remove	erases a file (function)
rename	renames a file (function)
tmpfile	returns a pointer to a temporary file (function)
tmpnam	returns a unique filename (function)

Types

Defined in header <stdio.h>
Type	Definition
FILE	type, capable of holding all information needed to control a C I/O stream
fpos_t	type, capable of uniquely specifying a position in a file

Macros

Defined in header <stdio.h>
stdin stdout stderr	expression of type FILE* associated with the input stream expression of type FILE* associated with the output stream expression 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 setbuf() (macro constant)
_IOFBF _IOLBF _IONBF	argument to setvbuf() indicating fully buffered I/O argument to setvbuf() indicating line buffered I/O argument to setvbuf() indicating unbuffered I/O (macro constant)
SEEK_SET SEEK_CUR SEEK_END	argument to fseek() indicating seeking from beginning of the file argument to fseek() indicating seeking from the current file position argument to fseek() indicating seeking from end of the file (macro constant)
TMP_MAX	maximum number of unique filenames that can be generated by tmpnam() (macro constant)
L_tmpnam	size needed for an array of char to hold the result of tmpnam() (macro constant)

See also

C++ documentation for C-style file input/output