fstream Specialization of iostream and streambuf for files

This section describes the classes ifstream, ofstream, and fstream, which provide low level operations on files and streams.

---

#include <iostream.h>

class ios
{
public:

enum seek_dir {beg, cur, end};
enum open_mode {in, out, ate, app, trunc, nocreate, noreplace,

bin, tabexp};

enum io_state {goodbit=0, eofbit, failbit, badbit};
// see ios for other class members ...

};

#include <fstream.h>

class fstreambase : virtual public ios
{
public:

fstreambase();
˜fstreambase();
fstreambase(const char* name, int mode, int prot=filebuf::openprot);
fstreambase(int fd);
fstreambase(int fd, char * p, int l);

void void void	attach(int fd); close(); open(const char* name, int mode, int prot=filebuf::openprot);
filebuf* void	(); setbuf(char* p, int l);

};

class ifstream : public fstreambase, public istream
{
public:

ifstream();
˜ifstream();
ifstream(const char* name, int mode=ios::in, int prot=filebuf::openprot);
ifstream(int fd);
ifstream(int fd, char* p, int l);

void	open(const char* name, int mode=ios::in, int prot=filebuf::openprot);
filebuf*	rdbuf();

};

class ofstream : public fstreambase, public ostream
{
public:

ofstream();
˜ofstream();
ofstream(const char* name, int mode=ios::out, int prot =filebuf::openprot);ofstream(int fd);
ofstream(int fd, char* p, int l);

void	open(const char* name, int mode=ios::out, int prot=filebuf::openprot);
filebuf*	rdbuf();

};

class fstream : public fstreambase, public iostream
{
public:

fstream();
˜fstream();
fstream(const char* name, int mode, int prot =filebuf::openprot);
fstream(int fd);
fstream(int fd, char* p, int l);

void	open(const char* name, int mode, int prot=filebuf::openprot);
filebuf*	rdbuf();

};

---

Base class fstreambase contains the standard definitions for constructors and memberfunctions for derived classes.

ifstream, ofstream, and fstream specialize istream, ostream, and iostream, respectively, to files. That is, the associated streambuf is a filebuf.

In the following descriptions, assume that:

• f is any of ifstream, ofstream, or fstream.
• mode is an int representing an open_mode.

Constructors

In xstream, x is either:

• if
• of, or
• f,

so that xstream stands for:

• ifstream
• ofstream, or
• fstream.

The constructors for xstream are:

xstream()

Constructs an unopened xstream.

xstream(char * name, int mode, int prot)

Constructs an xstream and opens file name using mode as the open mode. For a description of parameters name and mode, see under open() below. prot is ignored under BS2000.
The error state (io_state) of the constructed xstream indicates failure in case the open fails.

xstream(int fd)

Constructs an xstream connected to file descriptor fd, which must be already open.

xstream(int fd, char * ptr, int len)

Constructs an xstream connected to file descriptor fd, and, in addition, initializes the

associated filebuf to use the len bytes at ptr as the reserve area. If ptr is NULL or len is 0, the filebuf is unbuffered.

Member functions

void f.attach(int fd)

Connects f to the file descriptor fd. A failure occurs when f is already connected to afile. A failure sets ios::failbit in f’s error state.

void f.close()

Closes any associated filebuf and thereby breaks the connection of the f to a file. f’serror state is cleared except on failure, which is when the C runtime system detects afailure in the system call close().

void f.open(char * name, int mode, int prot)

Opens file name and connects f to it. If the file does not already exist, an attempt is made to create it unless ios::nocreate or ios::in is set. Failure occurs if f is already open, or the C runtime system call open() fails. ios::failbit is set in f’s error status on failure. prot is ignored under BS2000.

name may be:

• any valid BS2000 file name
• "link=linkname", where linkname is a BS2000 link name
• "(SYSDTA)", "(SYSOUT)", "(SYSLST)" for the appropriate system file
• "(SYSTERM)" for terminal input/output
• "(INCORE)" for a temporary binary file that is only set up in virtual memory

For more detailed information, please refer to the "C Library Functions" manual.

The members of open_mode are bits that may be or’ed together. (Because the or’ingreturns an int, open() takes an int rather than an open_mode argument.) The meanings of these bits in mode are:

ios::app

A seek to the end of file is performed. Subsequent data written to the file is always appended to the end of file. ios::app implies ios::out.

ios::ate

A seek to the end of the file is performed during the open(). ios::ate does not imply ios::out.

ios::in

The file is opened for input. ios::in is implied by construction and opens of ifstreams. For fstreams it indicates that input operations should be allowed if possible. It is legal to include ios::in in the modes of an ostream, in which case it implies that the original file (if it exists) should not be truncated. If the file does not already exist, the open() fails.

ios::out

The file is opened for output. ios::out is implied by construction and opens of ofstreams. For fstream it says that output operations are to be allowed.

ios::trunc

If the file already exists, its contents are truncated (discarded). This mode is implied when ios::out is specified (including implicit specification for ofstream) and neither ios::ate nor ios::app is specified.

ios::nocreate

If the file does not already exist, the open() fails.

ios::noreplace

If the file already exists, the open() fails.

ios::bin

The file is opened as a binary file. If this parameter is omitted the file is opened as a text file.

ios::tabexp

Is ignored for binary files and input files.
For text files, the tab character (\t) is converted to the corresponding number of spaces. Tab positions are spaced 8 columns apart (1, 9, 17, ...). When this parameter is omitted, the tab character is mapped as the corresponding EBCDIC value in the text file (see the "C Library Functions" manual).

Note

If open() of class istream is used, ios::in is always set.
If open() of class ostream is used, ios::out is always set.

filebuf * pfb=f.rdbuf()

Returns a pointer to the filebuf associated with f.
fstream::rdbuf() has the same meaning as iostream::rdbuf() but is typed differently.

void f.setbuf(char * p, int len)

Has the usual effect of a setbuf() (see filebuf()), offering space for a reserve area or requesting unbuffered I/O. An error occurs if f is open or the call to f.rdbuf()->setbuf fails.

EXAMPLE

The following program opens the file #TEMP. On success, text is written to the file.

#include <fstream.h>
#include <iostream.h>
int main()
{
  static char * name = "#TEMP";
  ofstream q(name, ios::out);
  cout << " File " << name;
  if (q.ios::failbit)
  {
     cout << " is open.\n";
     q << "This is the first line of file " << name << ".\n";
  }
  else
  {
     cout << " could not be opened.\n";
     exit (1);
  }
  return 0;
}

The result of executing the program is:

File #TEMP is open.
%  CCM0998 CPU time used: 0.0395 seconds

SEE ALSO

filebuf, ios, istream, ostream, sbufpub
close(), open() in the C runtime system