# A Little C Primer/C File-IO Through Library Functions

The file-I/O library functions are much like the console-I/O functions. In fact, most of the console-I/O functions can be thought of as special cases of the file-I/O functions. The library functions include:
All these library functions depend on definitions made in the "stdio.h" header file, and so require the declaration:
C documentation normally refers to these functions as performing "stream I/O", not "file I/O". The distinction is that they could just as well handle data being transferred through a modem as a file, and so the more general term "data stream" is used rather than "file". However, we'll stay with the "file" terminology in this document for the sake of simplicity.
The "fopen" function opens and, if need be, creates a file. Its syntax is:
The "fopen" function returns a "file pointer", declared as follows:
The file pointer will be returned with the value NULL, defined in "stdio.h", if there is an error. The "access modes" are defined as follows:
The "filename" is simply a string of characters.
It is often useful to use the same statements to communicate either with files or with standard I/O. For this reason, the "stdio.h" header file includes predefined file pointers with the names "stdin" and "stdout". There's no need to do an "fopen" on them—they can just be assigned to a file pointer:
—and any following file-I/O functions won't know the difference.
The "fclose" function simply closes the file given by its file pointer parameter. It has the syntax:
The "fseek" function call allows the byte location in a file to be selected for reading or writing. It has the syntax:
The offset is a "long" and specifies the offset into the file, in bytes. The "origin" is an "int" and is one of three standard values, defined in "stdio.h":
The "fseek" function returns 0 on success and non-zero on failure.
The "rewind", "rename", and "remove" functions are straightforward. The "rewind" function resets an open file back to its beginning. It has the syntax:
The "rename" function changes the name of a file:
The "remove" function deletes a file:
The "fprintf" function allows formatted ASCII data output to a file, and has the syntax:
The "fprintf" function is identical in syntax to "printf", except for the addition of a file pointer parameter. For example, the "fprintf" call in this little program:
—stores the following ASCII data:
The formatting codes are exactly the same as for "printf":
Field-width specifiers can be used as well. The "fprintf" function returns the number of characters it dumps to the file, or a negative number if it terminates with an error.
The "fscanf" function is to "fprintf" what "scanf" is to "printf": it reads ASCII-formatted data into a list of variables. It has the syntax:
However, the "string" contains only format codes, no text, and the "variable list" contains the addresses of the variables, not the variables themselves. For example, the program below reads back the two numbers that were stored with "fprintf" in the last example:
The "fscanf" function uses the same format codes as "fprintf", with the familiar exceptions:
* There is no "%g" format code.
* The "%f" and "%e" format codes work the same.
* There is a "%h" format code for reading short integers.
Numeric modifiers can be used, of course. The "fscanf" function returns the number of items that it successfully read, or the EOF code, an "int", if it encounters the end of the file or an error.
The following program demonstrates the use of "fprintf" and "fscanf":
The program generates the output:
The "fwrite" and "fread" functions are used for binary file I/O. The syntax of "fwrite" is as follows:
The array pointer is of type "void", and so the array can be of any type. The element size and count, which give the number of bytes in each array element and the number of elements in the array, are of type "size_t", which are equivalent to "unsigned int".
The "fread" function similarly has the syntax:
The "fread" function returns the number of items it actually read.
The following program stores an array of data to a file and then reads it back using "fwrite" and "fread":
The "putc" function is used to write a single character to an open file. It has the syntax:
The "getc" function similarly gets a single character from an open file. It has the syntax:
The "getc" function returns "EOF" on error. The console I/O functions "putchar" and "getchar" are really only special cases of "putc" and "getc" that use standard output and input.
The "fputs" function writes a string to a file. It has the syntax:
The "fputs" function will return an EOF value on error. For example:
The "fgets" function reads a string of characters from a file. It has the syntax:
The "fgets" function reads a string from a file until if finds a newline or grabs <string_length-1> characters. It will return the value NULL on an error.
The following example program simply opens a file and copies it to another file, using "fgets" and "fputs":