Functions HI-TECH C FOPEN

FOPEN

SYNOPSIS

#include  <stdio.h>

FILE * fopen(char * name, char * mode);

DESCRIPTION

Fopen() attempts to open file for reading or writing (or both) according to the mode string supplied. The mode string is interpreted as follows:

r

The file is opend for reading if it exists. If the file does not exist the call fails.

r+

If the file exists it is opened for reading and writing. If the file does not already exist the call fails.

w

The file is created if it does not exist, or truncated if it does. It is then opened for writing.

w+

The file is created if it does not already exist, or truncated if it does. The file is opened for reading and writing.

a

The file is created if it does not already exist, and opened for writing. All writes will be dynamically forced to the end of file, thus this mode is known as append mode.

a+

The file is created if it does not already exist, and opened for reading and writing. All writes to the file will be dynamically forced to the end of the file, i.e. while any portion of the file may be read, all writes will take place at the end of the file and will not overwrite any existing data. Calling fseek() in an attempt to write at any other place in the file will not be effective.

The "b" modifier may be appended to any of the above modes, e.g. "r+b" or "rb+" are equivalent. Adding the "b" modifier will cause the file to be opened in binary rather than ASCII mode. Opening in ASCII mode ensures that text files are read in a manner compatible with the Unix-derived conventions for C programs, i.e. that text files contain lines delimited by newline characters. The special treatment of read or written characters varies with the operating system, but includes some or all of the following:

NEWLINE (LINE FEED)

Converted to carriage return, line feed on output.

RETURN

Ignored on input, inserted before NEWLINE on output.

CTRL-Z

Signals EOF on input, appended on fclose on output if necessary on CP/M.

Opening a file in binary mode will allow each character to be read just as written, but because the exact size of a file is not known to CP/M, the file may contain more bytes than were written to it. See open() for a description of what constitutes a file name.

When using one of the read/write modes (with a '+' character in the string), although they permits reading and writing on the same stream, it is not possible to arbitrarily mix input and output calls to the same stream. At any given time a stream opened with a "+" mode will be in either an input or output state. The state may only be changed when the associated buffer is empty, which is only guaranteed immediately after a call to fflush() or one of the file positioning functions fseek() or rewind(). The buffer will also be empty after encountering EOF while reading a binary stream, but it is recommended that an explicit call to fflush() be used to ensure this situation. Thus after reading from a stream you should call fflush() or fseek() before attempting to write on that stream, and vice versa.

SEE ALSO

fclose, fgetc, fputc, freopen