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 <stdio.h>.

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
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, snprintf - prints 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

Reading from a stream using fgetc

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

int fgetc(FILE *fp);

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

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

The standard function getchar, also defined in <stdio.h>, takes no arguments, and is equivalent to getc(stdin).

EOF pitfall

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

Mistake	Correction
char c; while ((c = getchar()) != EOF) putchar(c);	int c; /* This will hold the EOF value */ while ((c = getchar()) != EOF) putchar(c);

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

When getchar's result is assigned to a char, 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 EOF value, when converted to char, 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 char is unsigned, then because EOF is negative, it can never be equal to any unsigned char, so the above example will not terminate at end-of-file. It will loop forever, repeatedly printing the character which results from converting EOF to char.

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),^[1] assuming the commonly used EOF value of -1. However, the fundamental issue remains that if the EOF value is defined outside of the range of the char type, when assigned to a char that value is sliced and will no longer match the full EOF value necessary to exit the loop. On the other hand, if EOF is within range of char, this guarantees a collision between EOF and a char value. Thus, regardless of how system types are defined, never use char types when testing against EOF.

On systems where int and char 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 EOF and some character's value. The proper way to handle this situation is to check feof and ferror after getchar returns EOF. If feof indicates that end-of-file has not been reached, and ferror indicates that no errors have occurred, then the EOF returned by getchar 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 char" systems. Another way is to use a compile-time assertion to make sure that UINT_MAX > UCHAR_MAX, which at least prevents a program with such an assumption from compiling in such a system.

fwrite

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

Writing a file using fwrite

fwrite is defined as

size_t fwrite (const void *array, size_t size, size_t count, FILE *stream);

fwrite function writes a block of data to the stream. It will write an array of count elements to the current position in the stream. For each element, it will write size 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 count if the write completes successfully. In case of a write error, the return value will be less than count.

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

#include <stdio.h>
#include <string.h>
#include <stdlib.h>

int main(void)
{
    FILE *fp;
    size_t count;
    const char *str = "hello\n";

    fp = fopen("sample.txt", "w");
    if(fp == NULL) {
        perror("failed to open sample.txt");
        return EXIT_FAILURE;
    }
    count = fwrite(str, 1, strlen(str), fp);
    printf("Wrote %zu bytes. fclose(fp) %s.\n", count, fclose(fp) == 0 ? "succeeded" : "failed");
    return EXIT_SUCCESS;
}

Writing to a stream using fputc

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

int fputc(int c, FILE *fp);

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

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

The standard function putchar, also defined in <stdio.h>, takes only the first argument, and is equivalent to putc(c, stdout) where c 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.

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  const int count = 5;  /* count of bytes to read from file */
  char buffer[count] = {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 < count; buffer[i++] = rc)
    ;
  fclose(fp);
  if (i == count) {
    puts("The bytes read were...");
    for (i = 0; i < count; i++)
      printf("%x ", buffer[i]);
    puts("");
  } else
    fputs("There was an error reading the file.\n", stderr);
  return EXIT_SUCCESS;
}

References

↑ C99 §6.2.5/15

[1] C99 §6.2.5/15

[1]