C file input/output

C Standard Library
Data types Character classification Strings Mathematics File input/output Date/time Localization Memory allocation Process control Signals Alternative tokens Miscellaneous headers: <assert.h> <errno.h> <setjmp.h> <stdarg.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 <stdio.h>. The functionality descends from a "portable I/O package" written by Mike Lesk at Bell Labs in the early 1970s.

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.

Overview of functions

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

	Byte character	Wide character	Description
File access	fopen		opens a file (with a non unicode filename on windows and possible utf8 filename on linux)
	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
	fwide		switches a file stream between wide character I/O and narrow character I/O
Direct input/output	fread		reads from a file
	fwrite		writes to a file
Unformatted input/output	fgetc getc	fgetwc getwc	reads a byte/wchar_t from a file stream
	fgets	fgetws	reads a byte/wchar_t line from a file stream
	fputc putc	fputwc putwc	writes a byte/wchar_t to a file stream
	fputs	fputws	writes a byte/wchar_t string to a file stream
	getchar	getwchar	reads a byte/wchar_t from stdin
	gets	N/A	reads a byte string from stdin (deprecated in C99, obsoleted in C11)
	putchar	putwchar	writes a byte/wchar_t to stdout
	puts	N/A	writes a byte string to stdout
	ungetc	ungetwc	puts a byte/wchar_t back into a file stream
Formatted input/output	scanf fscanf sscanf	wscanf fwscanf swscanf	reads formatted byte/wchar_t input from stdin, a file stream or a buffer
	vscanf vfscanf vsscanf	vwscanf vfwscanf vswscanf	reads formatted input byte/wchar_t from stdin, a file stream or a buffer using variable argument list
	printf fprintf sprintf snprintf	wprintf fwprintf swprintf	prints formatted byte/wchar_t output to stdout, a file stream or a buffer
	vprintf vfprintf vsprintf vsnprintf	vwprintf vfwprintf vswprintf	prints formatted byte/wchar_t output to stdout, a file stream, or a buffer using variable argument list
	perror	N/A	writes a description of the current error to stderr
File positioning	ftell		returns the current file position indicator
	fgetpos		gets the file position indicator
	fseek		moves the file position indicator to a specific location in a file
	fsetpos		moves the file position indicator to a specific location in a file
	rewind		moves the file position indicator to the beginning in a file
Error handling	clearerr		clears errors
	feof		checks for the end-of-file
	ferror		checks for a file error
Operations on files	remove		erases a file
	rename		renames a file
	tmpfile		returns a pointer to a temporary file
	tmpnam		returns a unique filename

Constants

Constants defined in the stdio.h header include:

Name	Notes
EOF	a negative integer of type int used to indicate end-of-file conditions
BUFSIZ	an integer which is the size of the buffer used by the setbuf() function
FILENAME_MAX	the size of a char array which is large enough to store the name of any file that can be opened
FOPEN_MAX	the number of files that may be open simultaneously; will be at least 8
_IOFBF	an abbreviation for "input/output fully buffered"; it is an integer which may be passed to the setvbuf() function to request block buffered input and output for an open stream
_IOLBF	an abbreviation for "input/output line buffered"; it is an integer which may be passed to the setvbuf() function to request line buffered input and output for an open stream
_IONBF	an abbreviation for "input/output not buffered"; it is an integer which may be passed to the setvbuf() function to request unbuffered input and output for an open stream
L_tmpnam	the size of a char array which is large enough to store a temporary filename generated by the tmpnam() function
NULL	a macro expanding to the null pointer constant; that is, a constant representing a pointer value which is guaranteed not to be a valid address of an object in memory
SEEK_CUR	an integer which may be passed to the fseek() function to request positioning relative to the current file position
SEEK_END	an integer which may be passed to the fseek() function to request positioning relative to the end of the file
SEEK_SET	an integer which may be passed to the fseek() function to request positioning relative to the beginning of the file
TMP_MAX	the maximum number of unique filenames generable by the tmpnam() function; will be at least 25

Variables

Variables defined in the stdio.h header include:

Name	Notes
stdin	a pointer to a FILE which refers to the standard input stream, usually a keyboard.
stdout	a pointer to a FILE which refers to the standard output stream, usually a display terminal.
stderr	a pointer to a FILE which refers to the standard error stream, often a display terminal.

Member types

Data types defined in the stdio.h header include:

• FILE - a structure containing the information about a file or text stream needed to perform input or output operations on it, including:
  • a file descriptor
  • the current stream position
  • an end-of-file indicator
  • an error indicator
  • a pointer to the stream's buffer, if applicable
• fpos_t - a non-array type capable of uniquely identifying the position of every byte in a file.
• size_t - an unsigned integer type which is the type of the result of the sizeof operator.

Example

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

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    char buffer[5] = {0};  /* initialized to zeroes */
    int i;
    FILE *fp = fopen("myfile", "rb");
 
    if (fp == NULL) {
        perror("Failed to open file \"myfile\"");
        return EXIT_FAILURE;
    }
 
    /* be sure to never read more than 5 char */
    for (i = 0; i < 5; i++) {
      int rc = getc(fp);
      if (rc == EOF) {
       fputs("An error occurred while reading the file.\n", stderr);
       return EXIT_FAILURE;
      }
      buffer[i] = rc;
    }
 
    fclose(fp);
 
    printf("The bytes read were... %x %x %x %x %x\n", buffer[0], buffer[1], buffer[2], buffer[3], buffer[4]);
 
    return EXIT_SUCCESS;
}

See also

• printf format string