Creating and Writing to a Text File

The WRFILE.C program opens a text file, writes a string to it, and closes the file. This example is meant to be built as a DOS or QuickWin program.

/* WRFILE.C: Create and write to a disk file. */

#include <stdio.h>

#include <io.h>

main()

{

FILE *fp;

if( (fp = fopen( "c:\\testfile.asc","w" )) != NULL )

{

fputs( "Example string", fp );

fputc( '\n', fp );

fclose( fp );

}

else

printf( "error message\n" );

}

You must include the standard I/O header file (#include <stdio.h>) whenever you plan to call input or output functions. It contains essential definitions and prototypes that you need.

The only variable in this program, fp, is declared as a pointer to a FILE.
FILE is defined in STDIO.H as a structure of _iobuf type, but we don't need
to know the specifics. We will refer to the variable fp as a “FILE pointer.”

The first statement combines several operations in one line:

if( (fp = fopen( "c:\\testfile.asc", "w" )) != NULL )

The fopen function opens a file. It expects two parameters, both of which are literal strings or pointers to strings. You provide the name of the file to be opened and the type (read, write, or append). The six types of files are listed in Table 11.3.

Table 11.3 Disk File Types

In WRFILE.C, the file called c:\testfile.asc is opened for writing with type "w" (a string, not the character 'w' in single quotes). We plan to write to it.

Notice that the filename string as it appears in the fopen statement contains two backslashes: "c:\\testfile.asc". If you tried to use the string "c:\testfile.asc", which looks correct, the character sequence \t would be incorrectly interpreted as a tab character. C automatically converts the two backslashes in the string to a single backslash.

Getting a FILE Pointer

The fopen function returns the address of a FILE. This value is assigned to fp, which is the FILE pointer used in all subsequent file operations.

If something goes wrong—if the disk is full or not in the drive or write-protected or whatever—fopen doesn't return a FILE pointer. When fopen fails, it returns a null value.

What we're looking for is any FILE pointer that's not null:

if( (fp = fopen( "c:\\testfile.asc","w" )) != NULL )

Writing to the File

As we saw earlier, puts displays a string on the screen. Add an f to it and the
result is fputs, which works similarly. It sends the string to a specified stream
(a file) instead of to the standard output device:

fputs( "Example string", fp );

The function fputs takes two parameters: a pointer to the string and the FILE pointer. In this and other I/O functions, you refer to the file by name only once (when you use fopen). Thereafter, you use its FILE pointer.

The fputs function writes the entire string to the file but does not include the null that marks the end of the string. Nor does it write a newline character—unless the string already contains a new line.

The fputc function writes a character to a file. In the following line, the newline character is sent to the file:

fputc( '\n', fp );

Closing the File

When the writing is done, fclose closes the file or window:

fclose( fp );

Conceptually, you can imagine that file I/O functions such as fputs and fputc write directly to the disk file. In reality, they're storing strings and characters in an intermediate area (called a “memory buffer”). When the buffer fills up, the entire chunk of memory is sent to the file. The process of emptying the buffer is called “flushing.” You may forcibly flush the buffer with the fflush and fclose functions. If you do not close the file before exiting the program, the buffer is not flushed and you may lose data that might remain there.

The else clause in WRFILE.C should execute only if something has gone wrong with the fopen function:

else

printf( "error message\n" );

This line executes if an error occurs when fopen tries to create the file. Handling errors is covered in more detail later in this chapter.