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". In Batch GCOS, file code 'XX' can be directly accessed using a filename of "fc*XX". In TSS, a name of the form "fc*anything" always refers to a file in the AFT. 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.
e: displays an error message (on "stderr") if an error occurs in the open operation or in any I/O performed later on the opened file. In this case, the program is not aborted; the I/O function that finds the error will return the normal error status (if any) once the message has been printed.
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. If the file is a temporary file in the AFT under TSS, the file will be removed and therefore deleted.
u: generates a unique AFT name for the file if a duplicate name is already in the AFT.

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");
 
/* open file with unique AFT name, remove when done */
f3 = fopen("x","w+btu");

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.