C file input/output

C Standard Library
Data types Character classification Strings Mathematics File input/output Date/time Localization Memory allocation Program control Miscellaneous headers: <assert.h> <errno.h> <iso646.h> <setjmp.h> <signal.h> <stdarg.h> <wchar.h>
v · d · e

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>.^[1] The functionality descends from a "portable I/O package" written by Mike Lesk at Bell Labs in the early 1970s.^[2]

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++).

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
• 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

Narrow character

• fgetc, getc - reads a character from a file stream
• fgets - reads a character string from a file stream
• fputc, putc - writes a character to a file stream
• fputs - writes a character string to a file stream
• getchar - reads a character from stdin
• gets - reads a character string from stdin
• putchar - writes a character to stdout
• puts - writes a character string to stdout
• ungetc - puts a character back into a file stream

Wide character

• fgetwc, getwc - reads a wide character from a file stream
• fgetws - reads a wide character string from a file stream
• fputwc, putwc - writes a wide character to a file stream
• fputws - writes a wide character string to a file stream
• getwchar - reads a wide character from stdin
• putwchar - writes a wide character to stdout
• ungetwc - puts a wide character back into a file stream

Formatted input/output

Narrow character

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

Wide character

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

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
• perror - displays a character string corresponding of the current error to stderr

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, rc;
    FILE *fp = fopen("myfile", "rb");
    if (fp == NULL) {
        perror("Failed to open file \"myfile\"");
        return EXIT_FAILURE;
    }
    for (i = 0; (rc = getc(fp)) != EOF && i < 5; buffer[i++] = rc)
        ;
    fclose(fp);
    if (i == 5) {
        puts("The bytes read were...");
        printf("%x %x %x %x %x\n", buffer[0], buffer[1], buffer[2], buffer[3], buffer[4]);
    } else
        fputs("There was an error reading the file.\n", stderr);
    return EXIT_SUCCESS;
}

References

1. ^ ISO/IEC 9899:1999 specification. p. 274, § 7.19. http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf. 
2. ^ Kernighan, Brian; Rob Pike (1984). The UNIX Programming Environment. Englewood Cliffs: Prentice Hall. p. 200. 

External links