.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)fstream.3 1.4 92/12/01 SMI; .\" .TH FSTREAM 3CC4 "18 June 1998" .\" .SH NAME fstream \- stream class for file I/O .SH SYNOPSIS .LP .nf .ft B #include .sp .5v typedef long streampos; typedef long streamoff; .sp .5v class unsafe_ios { public: // exported types // stream status bits enum io_state { goodbit = 0x00, // no bit set: all is ok eofbit = 0x01, // at end of file failbit = 0x02, // last I/O operation failed badbit = 0x04, // invalid operation attempted hardfail = 0x80 // unrecoverable error }; // stream operation mode enum open_mode { in = 0x01, // open for reading out = 0x02, // open for writing ate = 0x04, // seek to eof upon original open app = 0x08, // append mode: all additions at eof trunc = 0x10, // truncate file if already exists nocreate = 0x20, // open fails if file doesn't exist noreplace= 0x40 // open fails if file already exists }; // stream seek direction enum seek_dir { beg=0, cur=1, end=2 }; // \fIsee \fBios\fR(3CC4)\fI for remainder ...\fB }; .sp .5v class filebuf : public streambuf { // \fIsee \fBfilebuf\fR(3CC4)\fI ...\fB }; .sp .5v class unsafe_fstreambase : virtual public unsafe_ios { unsafe_fstreambase(); unsafe_fstreambase(const char*, int, int = filebuf::openprot); unsafe_fstreambase(int); unsafe_fstreambase(int _f, char*, int); ~unsafe_fstreambase(); void open(const char*, int, int = filebuf::openprot); void attach(int); void close(); void setbuf(char*, int); filebuf* rdbuf(); }; .sp .5v class fstreambase : virtual public ios, public unsafe_fstreambase { public: fstreambase() ; fstreambase(const char*, int, int=filebuf::openprot) ; fstreambase(int) ; fstreambase(int, char*, int) ; void open(const char*, int, int=filebuf::openprot) ; void attach(int); void close() ; void setbuf(char*, int) ; filebuf* rdbuf(); }; .sp .5v class ifstream : public fstreambase, public istream { public: // exported functions void open(const char* fname, int omode=ios::in, int prot=filebuf::openprot); filebuf* rdbuf(); public: // exported constructors ifstream(); ifstream(const char* fname, int omode=ios::in, int prot=filebuf::openprot); ifstream(int fileno); ifstream(int fileno, char* buf, int size); }; .sp .5v class ofstream : public fstreambase, public ostream { public: // exported functions void open(const char* fname, int omode=ios::out, int prot=filebuf::openprot); filebuf* rdbuf(); public: // exported constructors ofstream(); ofstream(const char* fname, int omode=ios::out, int prot=filebuf::openprot); ofstream(int fileno); ofstream(int fileno, char* buf, int size); }; .sp .5v class fstream : public fstreambase, public iostream { public: // exported functions void open(const char * fname, int omode, int prot=filebuf::openprot); filebuf* rdbuf(); public: // exported constructors fstream(); fstream(const char* fname, int omode, int prot=filebuf::openprot); fstream(int fileno); fstream(int fileno, char* buf, int size); }; .ft R .fi .PP .SH DESCRIPTION .LP Classes .BR ifstream ", " ofstream ", and " fstream are specialization of classes .BR istream ", " ostream ", and " iostream , respectively, for I/O using files. That is, the associated \fBstreambuf\fR is a \fBfilebuf\fR. .LP An auxiliary class \fBfstreambase\fR is an implementation detail, primarily to provide a set of common functions. It is not further discussed. .LP We will discuss these classes together, using the notation \fIX\fBstream\fR to refer equally to any of .BR ifstream ", " ofstream ", or " fstream. .\" .PP Objects of type .BR fstream , .BR ifstream , .BR ofstream are protected against simultaneous access by multiple threads by the useof mutex locks. Class .BR unsafe_fstreambase is available to derive new file classes that do not require mt-safety. Class .BR fstreambase , which is a base class for the three provided file classes, does use mutex locks to provide mt-safety. .PP As for other iostream classes, the mutex locking may be disabled by calling the member function .BR set_safe_flag defined by class .BR stream_MT . .SS "Constructors" .TP .IB X stream() Constructs a closed \fIX\fBstream\fR not connected to any file. .TP .IB X "stream(name, mode, prot)" Constructs an \fIX\fBstream\fR and opens file \fBname\fR using \fBmode\fR for the open mode bits and \fBprot\fR for the file protection bits. (See \fBopen\fR below.) The default open mode is input for an \fBifstream\fR and output for an \fBofstream\fR. The default protection is \fBfilebuf::openprot\fR, which is 0666. Any errors will be stored in the \fIX\fBstream\fR error state; see \fBios\fR(3CC4). .TP .IB X "stream(f)" Constructs an \fIX\fBstream\fR attached to file descriptor \fBf\fR, which must already be open. (It does not test for this condition.) .TP .IB X "stream(f, ptr, len)" Constructs an \fIX\fBstream\fR attached to file descriptor \fBf\fR, which must already be open. (It does not test for this condition.) The \fBfilebuf\fR will use the \fBlen\fR \fBchar\fRs beginning at the location pointed to by \fBptr\fR as the buffer (reserve area). If \fBptr\fR is zero or \fBlen\fR is not greater than zero, there will be no reserve area and \fBfbuf\fR will be unbuffered. .\" .SS "Member functions" .TP .B "fs.attach(f)" Connects \fBfs\fR to an open file descriptor \fBf\fR. If \fBfs\fR is already connected to a file, ignores the request, and sets \fBios::failbit\fR in the \fBfs\fR error state. .TP .B "fs.close()" Closes the associated \fBfilebuf\fR and disconnects the file from \fBfs\fR. If the \fBfilebuf\fR's \fBclose\fR call succeeds, clears the error state; otherwise sets \fBios::failbit\fR in the \fBfs\fR error state. .TP .B "fs.open(name, mode, prot)" Opens file \fBname\fR and connects its file descriptor to \fBfs\fR; If the file does not exist, and \fBios::nocreate\fR is not set in \fBmode\fR, \fBopen\fR attempts to create the file with the protection bits specified in \fBprot\fR (with default value 0666). The \fBmode\fR parameter is a collection of bits from \fBios::open_mode\fR which may be or'd together: .in +.5i .ti -.5i .B ios::app .br Initially seeks to the end of the file. Any subsequent write always appends to the end of the file. This flag implies \fBios::out\fR. .ti -.5i .B ios::ate .br Initially seeks to the end of the file. This flag does not imply \fBios::out\fR, but only begins operations at end of file. .ti -.5i .B ios::in .br Open the file for input. If a file is opened for input and the file does not exist, it will not be created. Construction or opening of an \fBifstream\fR always implies this bit, meaning the bit need not be set. When set for an \fBfstream\fR, means that input should be allowed if possible. When set for an \fBofstream\fR, means that the file should not be truncated when it is opened. .ti -.5i .B ios::out .br Open the file for output. Construction or opening of an \fBofstream\fR always implies this bit, meaning the bit need not be set. When set for an \fBfstream\fR, means that output should be allowed if possible. May be set for an \fRifstream\fR, but output to the file is not permitted. .ti -.5i .B ios::trunc .br If the file exists, truncate to zero length upon opening it. When \fBios::out\fR is specified or implied and neither \fBios::ate\fR nor \fBios::app\fR is specified, this bit is implied. .ti -.5i .B ios::nocreate .br If the file does not already exist, do not create it; \fBopen\fR will fail in this case. .ti -.5i .B ios::noreplace .br The file should not already exist; \fBopen\fR will fail if it does. This bit makes sense only when opening for output. .in -.5i .TP .B "filebuf* fb = fs.rdbuf()" Returns a pointer to the \fBfilebuf\fR associated with \fBfs\fR. This is the same as base class versions of this function, except that the return type is specifically a \fBfilebuf\fR. .TP .B "fs.setbuf(ptr, len)" This offers the buffer of \fBlen\fR \fBchar\fRs at \fBptr\fR as the reserve area. It calls the \fBfilebuf\fR version of \fBsetbuf\fR, and uses its return value to adjust the error state of \fBfs\fR. That is, it clears the error state on success, and sets \fBios::failbit\fR on error. .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR filebuf (3CC4), .BR ios (3CC4), .BR istream (3CC4), .BR ostream (3CC4), .BR sbufpub (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????