File I/O using cstdio

Often we want our programs to write data into files (rather than onto the screen) or to read data from a file (rather than the keyboard).

To do this, instead of using printf for output, we will use fprintf (i.e. file printf) and instead of using scanf for input, we will use fscanf (i.e. file scanf).

Calls to these functions will look very similar to the way we already use printf and scanf, but with one extra parameter controlling the file we are reading from or writing to.

The extra parameter that controls access to a file is called a file pointer, as it points to our current location in a file as we read our way through it or write content into it.

The general sequence we follow whenever we work on a file is as follows:

Try to open the file: here we specify the name of the file and how we want to use it: read from, write to, or append. Writing to overwrites the previous content of the file (if any), whereas append adds new content to the end of the existing file.
Check if the file opened successfully or not (we cannot read from a file that doesn't exist, and we cannot use a file if our account doesn't have the appropriate permissions to use that file).
If it did open successfully, perform all the reads and writes we want (discussed later).
Once we are finished all our reads or writes for that file, close it.

The C++ syntax for these steps is as follows:

The file type for the "file pointer" variables is FILE*, e.g.
FILE* fpin; // create a file pointer variable named fpin

To open a file we use the fopen function, and specify a filename (either a text string or in a character array) and a mode: "r" for read, "w" for write, "a" for append, and store the result in one of our file pointer variables, e.g.

FILE* fpin; // will use fpin for an input file - one we will read from
FILE* fpout; // will use fpout for an output file - one we will write to

fpin = fopen("someDataFile.txt", "r");  // open the file named someDataFile.txt
fpout = fopen(filename, "w"); // open the file whose name was stored  earlier
                              // in a char array called filename

The file pointer will be NULL if an attempted file open failed for any reason, so we can check the results as follows:

FILE *fpin;
fpin = fopen("myfile.cpp", "r");  // here we want to read from a file named myfile.cpp
if (fpin == NULL) {
   // it didn't work
   printf("Sorry, we could not open file myfile.cpp for reading\n");
}

To read from a file we can use any of the following routines, here assuming fpin is a file pointer after we successfully opened the file:

// fscanf is like scanf, but we add the file pointer first, e.g.
fscanf(fp, "%d", &i);  // read an int from the file into variable i

// fgets works as discussed previously, but we provide the file pointer instead of stdin:
fgets(array, maxsize, fpin);  // read one line from the file into the array, up to the maximum size

// getc works as discussed previously, but we use the file pointer as a parameter:
char c = getc(fpin);

// there is also an ungetc, that puts a char BACK into the input buffer:
ungetc(c, fpin);

A program needs a way to know if it has reached the end of an input file, which is accomplished using the feof function. This function returns true after we have attempted to read past the end of the file - e.g. if we read the last character in a file and then try feof it will return false, but if we try one more read after that then it will start returning true. As a result, right after every fscanf, fgets, or getc we should check if we've gone off the end of the file, e.g.:

   // try to open the file for reading
   FILE* fpin = fopen("somefile", "r");
   if (fpin == NULL) {
      printf("Could not open the file\n");
   } else {
      // read one character at a time from the input file (using getc),
      //    displaying them on the screen as we go (a regular printf),
      // and finishing when we've reached the end of the file
      do {
         char nextc = getc(fpin);
         if (!feof(fpin)) {
            printf("%c", nextc);
         }
      } while (!feof(fpin));
   }

Similarly, we could try reading a file one line at a time, until the end of file
// assuming the file is open for writing, // and const MaxLineLength is declared char nextline[MaxLineLength]; do { fgets(nextline, MaxLineLength, fpin); if (!feof(fpin)) { // do whatever with nextline } } while (!feof(fpin));

If a file has been successfully opened for writing, we can write contents into it using fprintf, which is just like printf except we specify the file pointer first, e.g.
// assuming the file is open for writing and fprintf(fpout, "blah blah %d blah %f", 10, 25.678);

We can close any open file using the file pointer, e.g.

   fclose(fpin);  // or fpout, or whatever you called your FILE* variable

If we want to re-use one of our file pointers after we have opened/closed it once (e.g. we want to open the same file a second time, or open a different file using that same file pointer) we use the function freopen instead of the function fopen. The parameters and use are identical.
Sometimes we want to be able to open a file to read from and write to, effectively allowing us to edit/update the existing content.
The three modes for doing so are "r+", "w+", and "a+". All three open for both reading and writing, but r+ requires the file already exist whereas w+ creates a new file if it doesn't already exists, and append of course adds new content to the end of the existing file.
We can "jump" from location to location within a file by specifying the where to jump from and how far to jump:
fseek(fp, N, SEEK_SET) jumps to the spot N characters from the start of the file
fseek(fp, N, SEEK_END) jumps to the N characters from the end
fseek(fp, N, SEEK_CUR) jumps N characters from the current spot
ftell(fp) tells us our current position (characters from the start)

File pointers as parameters

Sometimes we want to open a file pointer in one function, pass it as a parameter to another function, and have the called function read/write contents.

To do this, we must make sure the file pointer is passed-by-reference, and it is a good idea for the function to test the file pointer it receives to ensure it really is open, e.g.
#include <cstdio> // function to write an integer value into a file, // the file should have been opened for output earlier void writeNumberIntoFile(FILE* fp, int N); int main() { // attempt to open a file for writing FILE* fpout = fopen("somefile", "w"); if (fpout == NULL) { printf("Could not open file\n"); } else { // get the function to write value 123 into the file writeNumberIntoFile(fpout, 123); // close the file when we're done fclose(fpout); } return 0; } // function to write an integer value into a file, // the file should have been opened for output earlier void writeNumberIntoFile(FILE* fp, int N) { if (fp != NULL) { fprintf(fp, "%d\n", N); } }

Binary I/O

Everything above assumes plain text files are being processed, but sometimes we want to manipulate binary files (images, executables, etc).

To do so, we use binary mode, adding the letter b to our chosen mode, e.g. "rb", "rb+", "wb", etc.

We can then write binary variable contents directly into the file or read the file contents directly into variables (assuming we know the layout of the file content).

To read from the file, we specfiy where to put the data being read, how big each data element is, how many data elements there are, and the file pointer to read from, e.g. assuming i is an int:
fread(&i, sizeof(int), 1, fp);

Similarly, to write variable contents into the file we use fwrite:
fwrite(i, sizeof(int), 1, fp);