78 Streams in reality — <stdio.h> ①

78.1 Open, write, close — failure can happen three times#

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

/* Three realities of a stream — buffering, return values, knowing the end */
int main(void)
{
    const char *path = "stream_demo.txt";

    /* (1) writing: fopen returns null on failure */
    FILE *f = fopen(path, "w");
    if (!f) { perror("fopen"); return 1; }

    /* fprintf can fail too — the return value is the number of characters printed */
    int written = fprintf(f, "one\ntwo\nthree\n");
    printf("fprintf wrote %d chars\n", written);

    /* (2) closing can fail too: a failure while flushing the buffer surfaces here */
    if (fclose(f) != 0) { perror("fclose"); return 1; }

    /* (3) reading: a line at a time */
    f = fopen(path, "r");
    if (!f) { perror("fopen"); return 1; }

    char line[64];
    int n = 0;
    while (fgets(line, sizeof line, f)) {
        line[strcspn(line, "\n")] = '\0';   /* the idiom for stripping the newline */
        printf("line %d: [%s]\n", ++n, line);
    }

    /* (4) why did it stop — end of file or an error? */
    if (ferror(f))      printf("stopped by an error\n");
    else if (feof(f))   printf("stopped at end of file\n");

    /* (5) a line longer than the buffer is cut and arrives in pieces */
    rewind(f);
    char tiny[4];
    printf("with a 4-byte buffer:\n");
    for (int i = 0; i < 3 && fgets(tiny, sizeof tiny, f); i++)
        printf("  chunk %d: [%s] (has newline: %s)\n",
               i + 1, tiny, strchr(tiny, '\n') ? "yes" : "no");

    fclose(f);
    remove(path);
    return 0;
}

fprintf wrote 14 chars
line 1: [one]
line 2: [two]
line 3: [three]
stopped at end of file
with a 4-byte buffer:
  chunk 1: [one] (has newline: no)
  chunk 2: [
] (has newline: yes)
  chunk 3: [two] (has newline: no)

It is worth noticing that the example checks for failure in three places.

① fopen — on failure it returns null. The reason is left in errno, and perror prints it as a sentence a human can read (chapter 90). The file may not exist, permission may be lacking, or too many files may be open.

② Writing — fprintf returns the number of characters printed and gives a negative value on failure. Code that checks it is rare, but if the disk fills or a pipe breaks it shows itself here.

③ fclose — here is the real trap. It is the place where what remained in the buffer is finally sent out, so it is common for a write failure to show itself for the first time on closing. A program that must not lose data therefore always checks fclose’s return value.

fprintf(f, "%s\n", important);
fclose(f);                  /* nobody asked whether it failed */
puts("saved");              /* it may in fact not have been saved */

78.2 How to know the end of a file — the misuse of feof#

The most widespread wrong answer is here.

#include <stdio.h>

/* Drive a loop with feof and the last item is processed once more —
   the classic wrong answer of the C introductory books. */
int main(void)
{
    const char *path = "feof_demo.txt";
    FILE *f = fopen(path, "w");
    if (!f) return 1;
    fputs("10\n20\n30\n", f);
    fclose(f);

    printf("the wrong version — while (!feof(f)):\n");
    f = fopen(path, "r");
    if (!f) return 1;
    while (!feof(f)) {
        int v;
        fscanf(f, "%d", &v);          /* it goes round once more even after the last read fails */
        printf("  read %d\n", v);      /* 30 is printed twice */
    }
    fclose(f);

    printf("the right version — driven by the read's return value:\n");
    f = fopen(path, "r");
    if (!f) return 1;
    int v;
    while (fscanf(f, "%d", &v) == 1)
        printf("  read %d\n", v);
    if (ferror(f)) printf("  (read error)\n");
    fclose(f);

    remove(path);
    return 0;
}

the wrong version — while (!feof(f)):
  read 10
  read 20
  read 30
  read 30
the right version — driven by the read's return value:
  read 10
  read 20
  read 30

Why is while (!feof(f)) wrong? feof is not a prophet but a recorder — the mark saying “the end of the file was reached” is turned on only after a read has failed. So right after reading the last value it is still off, the loop turns once more, and the result of the failed read (= the previous value, unchanged) is used as it stands. That 30 was printed twice in the example is the evidence.

There is one rule. Control the loop by the reading function’s return value. feof and ferror are used after the loop ends, to tell “why did it end”.

78.3 Lines longer than the buffer#

The last part of the first example (streams.c) shows such a line. If the buffer is too small fgets reads only that far and stops — it is not an error. So without checking whether a newline is in there, what you believed to be “one line” may in fact be the front piece of a line.

Read one\n with a 4-byte buffer and it comes split in two: one (no newline) and \n (a newline only). When code handling long lines in the field forgets this fact, one line is quietly processed as two records.

78.4 Text mode and binary mode#

The b attached to fopen’s second argument selects binary mode. On the Unix family there is no difference, but on Windows there is — text mode turns \n into \r\n when writing and turns it back when reading. So opening a binary file in text mode quietly changes the bytes.

scanf("%d", &n);
fflush(stdin);      /* the intent is to empty the input buffer — it is outside the contract */

int c;
while ((c = getchar()) != '\n' && c != EOF) { }

78.5 File position and size#

fseek and ftell handle position, but with restrictions. On a text stream the value ftell returns is not guaranteed to be a byte offset, and fseek is safe only with that value or with the combination of SEEK_SET and 0. On a large file long may be too small, so the non-standard fseeko and ftello (POSIX) or a platform API become necessary.

The idiom “to learn a file’s size, go to the end and ftell” is safe only in binary mode, and even then it is meaningless if the file is changing.

We have seen the skeleton of streams. The next chapter is the functions that actually read and write on top of it — and the story of a function deleted from the standard.