FOPEN - open a file for I/O.
(ANSI Standard)
Usage:
#include <stdio.h>
ret = fopen( name, options )
Where:
- const char *name;
- is a string containing the name of the file to be opened.
- const char *options;
- is a string specifying whether the file should be opened for reading
or writing (see below).
- FILE *ret;
- is a "file pointer".
This points to a structure that contains information needed for subsequent
I/O on the file being opened.
This file pointer is used by most I/O functions.
Description:
"fopen" opens a file for subsequent reading or writing.
If successful, "fopen" returns a pointer-to-structure; if it fails,
it returns NULL.
"name" is the file descriptor for a file.
The file will be created (if necessary) if "options" includes "w" or "a".
Filecode 'XX' can be directly accessed using a filename of "fc*XX".
If the filename has any other format, "fopen" tries to access it
as a permfile.
"options" points to a string containing one of
- r
- open for reading.
- w
- open for writing.
- a
- open for appending.
- r+
- open for both reading and writing.
The stream will be positioned at the beginning of the file.
- w+
- open for both reading and writing.
The stream will be created if it does not exist, and will be truncated
if it does exist.
- a+
- open for both reading and writing.
The stream will be positioned at the end of the existing file content.
- rb
- open for reading.
The 'b' indicates binary data (as opposed to text); by default,
this will be a sequential file in Media 4 format.
- wb
- open for writing.
The 'b' indicates binary data.
- ab
- open for appending.
The 'b' indicates binary data.
Several additional options can be specified by adding one or more letters
to the possibilities listed above.
All of the following options are unique to the GCOS-8 version of C and will
not be portable to other implementations.
- d
- tells "fopen" to abort the program (die) with an error message if an error
occurs in the open operation or in I/O performed later on the opened file.
- o
- opens the file for some purpose "other" than character or record
processing.
The file will be accessed random,
no buffer will be allocated for processing SSF records.
Only block mode I/O routines like "_rblock" and "_wblock"
may be used to manipulate the file.
If you do not specify this option, the default is to open the file
for character stream or record processing.
- s
- tells "fopen" that you are opening a string for I/O instead of a normal file.
In this instance, the "filename" argument is a pointer to the string
being opened.
- t
- makes the file Transient, so that it is detached from the job when it
is closed, even if the file is a temporary file.
Examples:
/* open file "uid/f" for writing binary */
f1 = fopen("uid/f", "wb");
/* open the string "str" for reading */
char *str;
f2 = fopen(str, "rs");
Notes:
When you specify "r+", you indicate that you want to read the file before
you write to it.
Thus the file must already exist.
When a file is opened with a "+" option, you may both read and write on it.
However, you may not perform an output operation immediately after an
input operation; you must perform an intervening "rewind" or "fseek".
Similarly, you may not perform an input operation immediately after an
output operation; you must perform an intervening "rewind" or "fseek".
The use of the 'b' or '+' options cause the file to be written in
fixed-length, 318-word media 4 GFRC records.
The length of the last record is adjusted to suit to actual length (in bytes)
of the file.
Since the file is not one of the standard text media codes, such a file cannot,
in general, be read by other programs, unless they too are written in
C and open the file with 'b' or '+' options.
When a file is opened for appending, it is impossible to overwrite
the existing contents of the file.
Every write operation automatically begins with a seek to the
current end of the file.
For example, if you use "fseek" or "fsetpos" to move into the
middle of the file and then try a write operation, the library
will automatically move back to the end of the file before the
write takes place.
This behavior is required by the ANSI standard for C.
See Also:
expl nsc lib fclose
expl nsc lib fseek
expl nsc lib rewind
expl nsc lib _rblock
expl nsc lib _wblock
Copyright © 2000, Thinkage Ltd.