reading about reading

I've been using the C/C++ SDK that my company provides to our customers for reading our file format as inspiration of what to learn next. The SDK consists of a header file defining the file format (which is a whole mess of structures - is that all any format is?) and some sample programs to do simple things like read the headers and dump out the first 200 data points.

I understand about 95% of the header that defines the file format (it's really vanilla data structures - no linked lists or trees, etc), and about 80% of the sample file that reads in a file and gets information from it. Luckily the sample program is console based, so there isn't any GUI mess to sift through.

The 20% of the program that I don't understand has to do with reading in the file and passing the data to an array of data structures. Specifically, the 20% of confusion is fread(). I'll just have to play with it to see if I can tease out how it works. The internet isn't helping that much.

The read data function in the sample program first uses fread() to get some info, then it calls it several more times to pass data to other data structures using practically the same function call with the exception of which data structure to pass data to.... which didn't seem right at first. How does fread() know what data goes where? Well, it turns out (after HOURS of forum crawling) that fread() is smart enough to increment the file pointer and keep it there so that the next time to call the function to get the next blob of data, you start where you left off! There is actually a companion function of sorts called fseek() that I think can put the pointer at the beginning or end or wherever. I'm not sure yet.

I'm pissed that such a vital piece of info is never actually mentioned, or if it is, it's cryptic.

For example, type "fread" into Google and you get this as your first result:

http://www.cplusplus.com/reference/clibrary/cstdio/fread/

With this description:

size_t fread ( void * ptr, size_t size, size_t count, FILE * stream );

"Reads an array of count elements, each one with a size of size bytes, from the stream and stores them in the block of memory specified by ptr. The poistion indicator of the stream is advanced by the total amount of bytes read. The total amount of bytes read if successful is (size * count)."

I understand that there are four parts - variable to hold data read, size of data to be read, how many of those sizes to read in, and the pointer to the file. What is NOT clear is the sentence "The position indicator of the stream is advanced by the total amount of bytes read" unless you know that the pointer to the file IS the position indicator.

That could be stated MUCH clearer. I kept reading that as "you go through the file by how much you asked to go through the file". Maybe stating is as "The pointer to the file will start by being a pointer to the start of the file in memory, and will be incremented and left there by the amount of data read in by fread()". I finally found some resource that stated this explicitly, and now I think I understand.