C Programming/stdio.h

The C programming language provides many standard library functions for file input and output. These functions make up the bulk of the C standard library header.

The I/O functionality of C is fairly low-level by modern standards; C abstracts all file operations into operations on streams of bytes, which may be "input streams" or "output streams". Unlike some earlier programming languages, C has no direct support for random-access data files; to read from a record in the middle of a file, the programmer must create a stream, seek to the middle of the file, and then read bytes in sequence from the stream.

The stream model of file I/O was popularized by the Unix operating system, which was developed concurrently with the C programming language itself. The vast majority of modern operating systems have inherited streams from Unix, and many languages in the C programming language family have inherited C's file I/O interface with few if any changes (for example, PHP). The C++ standard library reflects the "stream" concept in its syntax; see iostream.

Function overview
Most of the C file input/output functions are defined in /stdio.h (/cstdio header in C++).


 * File access
 * fopen - opens a file
 * freopen - opens a different file with an existing stream
 * fflush - synchronizes an output stream with the actual file
 * fclose - closes a file
 * setbuf - sets the buffer for a file stream
 * setvbuf - sets the buffer and its size for a file stream
 * <tt>fwide</tt> - switches a file stream between wide character I/O and narrow character I/O
 * Direct input/output
 * <tt>fread</tt> - reads from a file
 * <tt>fwrite</tt> - writes to a file
 * Unformatted input/output
 * Narrow character


 * <tt>fgetc</tt>, <tt>getc</tt> - reads a character from a file stream
 * <tt>fgets</tt> - reads a character string from a file stream
 * <tt>fputc</tt>, <tt>putc</tt> - writes a character to a file stream
 * <tt>fputs</tt> - writes a character string to a file stream
 * <tt>getchar</tt> - reads a character from stdin
 * <tt>gets</tt> - reads a character string from stdin
 * <tt>putchar</tt> - writes a character to stdout
 * <tt>puts</tt> - writes a character string to stdout
 * <tt>ungetc</tt> - puts a character back into a file stream
 * Wide character


 * <tt>fgetwc</tt>, <tt>getwc</tt> - reads a wide character from a file stream
 * <tt>fgetws</tt> - reads a wide character string from a file stream
 * <tt>fputwc</tt>, <tt>putwc</tt> - writes a wide character to a file stream
 * <tt>fputws</tt> - writes a wide character string to a file stream
 * <tt>getwchar</tt> - reads a wide character from stdin
 * <tt>putwchar</tt> - writes a wide character to stdout
 * <tt>ungetwc</tt> - puts a wide character back into a file stream
 * Formatted input/output
 * Narrow character


 * <tt>scanf</tt>, <tt>fscanf</tt>, <tt>sscanf</tt> - reads formatted input from stdin, a file stream or a buffer
 * <tt>vscanf</tt>, <tt>vfscanf</tt>, <tt>wsscanf</tt> - reads formatted input from stdin, a file stream or a buffer using variable argument list
 * <tt>printf</tt>, <tt>fprintf</tt>, <tt>sprintf</tt>, <tt>snprintf</tt> - prints formatted output to stdout, a file stream or a buffer
 * <tt>vprintf</tt>, <tt>vfprintf</tt>, <tt>vsprintf</tt>, <tt>vsnprintf</tt> - prints formatted output to stdout, a file stream, or a buffer using variable argument list


 * Wide character


 * <tt>wscanf</tt>, <tt>fwscanf</tt>, <tt>swscanf</tt> - reads formatted wide character input from stdin, a file stream or a buffer
 * <tt>vwscanf</tt>, <tt>vfwscanf</tt>, <tt>vswscanf</tt> - reads formatted wide character input from stdin, a file stream or a buffer using variable argument list
 * <tt>wprintf</tt>, <tt>fwprintf</tt>, <tt>swprintf</tt> - prints formatted wide character output to stdout, a file stream or a buffer
 * <tt>vwprintf</tt>, <tt>vfwprintf</tt>, <tt>vswprintf</tt> - prints formatted wide character output to stdout, a file sttream or a buffer using variable argument list


 * File positioning
 * <tt>ftell</tt> - returns the current file position indicator
 * <tt>fgetpos</tt> - gets the file position indicator
 * <tt>fseek</tt> - moves the file position indicator to a specific location in a file
 * <tt>fsetpos</tt> - moves the file position indicator to a specific location in a file
 * <tt>rewind</tt> - moves the file position indicator to the beginning in a file
 * Error handling
 * <tt>clearerr</tt> - clears errors
 * <tt>feof</tt> - checks for the end-of-file
 * <tt>ferror</tt> - checks for a file error
 * <tt>perror</tt> - displays a character string corresponding of the current error to stderr
 * Operations on files
 * <tt>remove</tt> - erases a file
 * <tt>rename</tt> - renames a file
 * <tt>tmpfile</tt> - returns a pointer to a temporary file
 * <tt>tmpnam</tt> - returns a unique filename

Reading from a stream using fgetc
The  function is used to read a character from a stream.

If successful,  returns the next byte or character from the stream (depending on whether the file is "binary" or "text", as discussed under   above). If unsuccessful, fgetc returns. (The specific type of error can be determined by calling  or   with the file pointer.)

The standard macro, also defined in  , behaves in almost the same way as  , except that—being a macro—it may evaluate its arguments more than once.

The standard function, also defined in  , takes no arguments, and is equivalent to.

EOF pitfall
A mistake when using,  , or   is to assign the result to a variable of type   before comparing it to. The following code fragments exhibit this mistake, and then show the correct approach (using type int):

Consider a system in which the type  is 8 bits wide, representing 256 different values. may return any of the 256 possible characters, and it also may return  to indicate end-of-file, for a total of 257 different possible return values.

When 's result is assigned to a , which can represent only 256 different values, there is necessarily some loss of information—when packing 257 items into 256 slots, there must be a collision. The  value, when converted to , becomes indistinguishable from whichever one of the 256 characters shares its numerical value. If that character is found in the file, the above example may mistake it for an end-of-file indicator; or, just as bad, if type  is unsigned, then because   is negative, it can never be equal to any unsigned , so the above example will not terminate at end-of-file. It will loop forever, repeatedly printing the character which results from converting  to.

However, this looping failure mode does not occur if the char definition is signed (C makes the signedness of the default char type implementation-dependent), assuming the commonly used   value of -1. However, the fundamental issue remains that if the  value is defined outside of the range of the   type, when assigned to a   that value is sliced and will no longer match the full   value necessary to exit the loop. On the other hand, if  is within range of , this guarantees a collision between   and a char value. Thus, regardless of how system types are defined, never use  types when testing against.

On systems where  and   are the same size (i.e., systems incompatible with minimally the POSIX and C99 standards), even the "good" example will suffer from the indistinguishability of   and some character's value. The proper way to handle this situation is to check  and   after   returns. If  indicates that end-of-file has not been reached, and   indicates that no errors have occurred, then the   returned by   can be assumed to represent an actual character. These extra checks are rarely done, because most programmers assume that their code will never need to run on one of these "big " systems. Another way is to use a compile-time assertion to make sure that, which at least prevents a program with such an assumption from compiling in such a system.

fwrite
In the C programming language, the  and   functions respectively provide the file operations of input and output. and  are declared in.

Writing a file using fwrite
fwrite is defined as

function writes a block of data to the stream. It will write an array of  elements to the current position in the stream. For each element, it will write  bytes. The position indicator of the stream will be advanced by the number of bytes written successfully.

The function will return the number of elements written successfully. The return value will be equal to  if the write completes successfully. In case of a write error, the return value will be less than.

The following program opens a file named <tt>sample.txt</tt>, writes a string of characters to the file, then closes it.

Writing to a stream using fputc
The  function is used to write a character to a stream.

The parameter  is silently converted to an   before being output. If successful,  returns the character written. If unsuccessful, fputc returns.

The standard macro, also defined in  , behaves in almost the same way as  , except that—being a macro—it may evaluate its arguments more than once.

The standard function, also defined in  , takes only the first argument, and is equivalent to   where   is that argument.

Example usage
The following C program opens a binary file called myfile, reads five bytes from it, and then closes the file.