fopen modes and text versus binary streams

Understanding fopen modes and text versus binary streams

fopen's second argument looks like a tiny word, but it is really three independent answers packed together. The first character says whether the file must already exist: "r" fails if it does not, while "w" and "a" create it. It also says what happens to bytes that are already there: "w" truncates the file to zero length during the call to fopen, before your program writes anything, while "a" leaves them alone and forces every later write to the current end of the file. Adding "+" grants the missing direction of I/O, so "r+" reads and writes an existing file in place and "w+" still truncates first, but the "+" never changes the existence or truncation rule the first letter already set.

The optional "b" picks between two kinds of stream. A text stream is allowed to translate between your program's '\n' and whatever the host uses to end a line: on Windows every '\n' you write becomes the two bytes 0x0D 0x0A, and every 0x0D 0x0A you read collapses back into one '\n'. A binary stream is a plain byte pipe: what you hand fwrite is what lands on disk, byte for byte. On Linux and macOS a line already ends with a single 0x0A, so the two stream types are the same thing and "b" does nothing, which is precisely why a missing "b" in code that writes a struct or a PNG is a bug you cannot see until someone builds it on Windows.

Because the mode decides what the operating system is asked to do, it also decides how fopen can fail, and fopen reports every failure the same way: it returns NULL. "r" on a path that does not exist, "w" in a directory you cannot write to, "wx" (added in C11) on a file that already exists, all give NULL, and the stream must not be touched afterwards. Update modes add one rule that has nothing to do with permissions: with "r+", "w+" or "a+" you may not follow a write with a read unless fflush or a positioning call comes between them, and you may not follow a read with a write without a positioning call or hitting end-of-file. Ignore that and you read whatever the buffer happened to hold, which is the standard's way of saying the behaviour is undefined.

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

static void dump(const char *path)
{
    FILE *f = fopen(path, "rb");
    long n = 0;
    int c;

    if (f == NULL) {
        printf("%-10s missing\n", path);
        return;
    }
    printf("%-10s \"", path);
    while ((c = fgetc(f)) != EOF) {
        if (c == '\n')
            printf("\\n");
        else
            putchar(c);
        n++;
    }
    printf("\" (%ld bytes)\n", n);
    fclose(f);
}

static FILE *open_or_die(const char *path, const char *mode)
{
    FILE *f = fopen(path, mode);

    if (f == NULL) {
        fprintf(stderr, "cannot open %s in mode \"%s\"\n", path, mode);
        exit(EXIT_FAILURE);
    }
    return f;
}

int main(void)
{
    FILE *f;

    remove("notes.txt");                 /* start from a known state */
    remove("absent.txt");
    dump("notes.txt");

    f = open_or_die("notes.txt", "w");   /* create, or truncate to 0 bytes */
    fputs("alpha\n", f);
    fclose(f);
    dump("notes.txt");

    f = open_or_die("notes.txt", "a");   /* keep old bytes, write at the end */
    fputs("beta\n", f);
    fclose(f);
    dump("notes.txt");

    f = open_or_die("notes.txt", "w");   /* truncation happens inside fopen */
    fclose(f);
    dump("notes.txt");

    f = fopen("absent.txt", "r");        /* "r" never creates a file */
    printf("fopen(\"absent.txt\", \"r\") -> %s\n", f == NULL ? "NULL" : "stream");
    if (f != NULL)
        fclose(f);

    return 0;
}

Worked examples

#include <stdio.h>

static long count_bytes(const char *path, const char *mode)
{
    FILE *f = fopen(path, mode);
    long n = 0;

    if (f == NULL)
        return -1;
    while (fgetc(f) != EOF)
        n++;
    fclose(f);
    return n;
}

int main(void)
{
    FILE *f = fopen("crlf.bin", "wb");

    if (f == NULL)
        return 1;
    fputs("a\r\nb\r\n", f);   /* six bytes, stored exactly as given */
    fclose(f);

    printf("binary mode read: %ld\n", count_bytes("crlf.bin", "rb"));
    printf("text mode read:   %ld\n", count_bytes("crlf.bin", "r"));
    return 0;
}

#include <stdio.h>

int main(void)
{
    FILE *f;
    int c;

    f = fopen("log.txt", "w");
    if (f == NULL)
        return 1;
    fputs("AAAA", f);
    fclose(f);

    f = fopen("log.txt", "a");     /* append mode */
    if (f == NULL)
        return 1;
    fseek(f, 0, SEEK_SET);         /* ask for the start of the file */
    fputs("Z", f);                 /* the write goes to the end anyway */
    fclose(f);

    f = fopen("log.txt", "r+");    /* update in place, no truncation */
    if (f == NULL)
        return 1;
    fseek(f, 0, SEEK_SET);
    fputs("B", f);                 /* this one really lands on byte 0 */
    fclose(f);

    f = fopen("log.txt", "r");
    if (f == NULL)
        return 1;
    while ((c = fgetc(f)) != EOF)
        putchar(c);
    putchar('\n');
    fclose(f);
    return 0;
}

Important notes

Common mistakes

Try it yourself