#include <fstream.h>
typedef long streampos;
typedef long streamoff;
class ios : virtual public unsafe_ios, public stream_MT {
public:
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
};
enum seek_dir { beg=0, cur=1, end=2 };
// see ios(3CC4) for remainder ...
};
class filebuf : public streambuf {
public:
static const int openprot ; /* default protection for open */
filebuf() ;
~filebuf() ;
filebuf(int f);
filebuf(int f, char* p, int len) ;
filebuf* attach(int f) ;
filebuf* attach_unlocked(int);
filebuf* close();
filebuf* close_unlocked();
int detach() ;
int detach_unlocked();
int fd();
int is_open();
int is_open_unlocked();
filebuf* open(char *name, int omode, int prot=openprot) ;
filebuf* open_unlocked(const char*, int,
int=filebuf::openprot);
streampos seekoff(streamoff, seek_dir, int omode) ;
streampos seekpos(streampos, int omode) ;
streambuf* setbuf(char* p, int len) ;
int sync() ;
};
The filebuf class is a specialization of streambufs using a file as the source or destination of characters. Characters are fetched (input) from a file and consumed by (written to) a file. When the filebuf is connected (attached) to an open file, the filebuf is said to be open; otherwise it is closed. A file is opened by default with protection mode filebuf::openprot, which is 0666.
If the attached file is seekable, the filebuf allows seeks; for example, an ordinary disk file is seekable, the terminal is not. If the attached file allows reading (writing), the filebuf allows fetching (storing); for example, standard input allows only reading, standard output allows only writing. Unlike C stdio, no seek is required between gets and puts to the same filebuf. At least four characters of putback are initially allowed.
The basic streambuf operations are as described in sbufprot(3CC4) and sbufpub(3CC4). The reserve area is allocated automatically if one is not supplied to a constructor or with a call to setbuf (calls to setbuf are usually honored). If the filebuf is made unbuffered, each input and output character requires a system call. The get and put pointers act like a single pointer; conceptually, they are tied together.
A filebuf operates on files via a Unix file descriptor, a small integer passed in system calls. C stdio is not used. Note: Supplied file descriptors are not checked for validity.
Several of the member functions are defined in two versions: an ``unsafe'' version (with suffix _unlocked) that is not protected against multi-threaded access; and a ``safe'' version (the default), that uses mutex locks to protect against simultaneous access by multiple threads.
Creates a closed filebuf.
Creates an open filebuf attached to file descriptor f, which is assumed to be open.
Creates an open filebuf attached to file descriptor f, which is assumed to be open. Uses the array of len chars beginning at p as the initial reserve area. If p is zero or len is not greater than zero, the filebuf is unbuffered.
If fbuf is closed, connects it to file descriptor f, assumed to be open, and returns the address of fbuf. If fbuf is already open, ignores f and returns zero. This member is mt-safe.
Functionally identical to attach, except that it does not perform any mutex locks, and is thus not mt-safe.
Flushes any waiting output to the file associated with the file descriptor, and disconnects the file descriptor from f. The file descriptor is returned. Applications which do not want the attached file descriptor to be closed by close() should call this function before close(). This member is mt-safe.
Functionally identical to detach, except that it does not perform any mutex locks, and is thus not mt-safe.
Flushes any pending output, unconditionally closes the file descriptor and closes fbuf. Returns zero on error, the address of fbuf otherwise. This member is mt-safe.
Functionally identical to close, except that it does not perform any mutex locks, and is thus not mt-safe.
Returns the file descriptor attached to fbuf, or EOF if fbuf is not open.
Returns non-zero if fbuf is open (connected to a file descriptor), zero otherwise. This member is mt-safe.
Functionally identical to is_open, except that it does not perform any mutex locks, and is thus not mt-safe.
If fbuf is not already open, this function opens file name and connects its file descriptor to fbuf; otherwise it is an error. If the file does not exist, and ios::nocreate is not set in mode, open attempts to create the file with the protection bits specified in prot (with default value 0666). The mode parameter is a collection of bits from ios::open_mode, described in fstream(3CC4), which may be or'd together. This function returns the address of fbuf on success, zero on any failure. This member is mt-safe.
Functionally identical to open, except that it does not perform any mutex locks, and is thus not mt-safe.
Moves the combined get/put pointer as described in sbufpub(3CC4) by off and dir, except that the mode parameter is ignored. If fbuf is not open, if the attached file does not support seeking, or if the seek cannot otherwise be performed (such as off either end of the file), the operation fails. off is the relative offset to the place in the file specified by dir. Returns the new file position on success, EOF on failure. The position of the file in the event of an error is undefined.
Equivalent to the call fbuf.seekoff((streamoff)pos, ios::beg, mode). The value of pos should be one obtained from a previous call to seekoff or seekpos, or the value zero representing the beginning of the file. See also sbufpub(3CC4).
If fbuf is open and a reserve area has been allocated, no change is made and setbuf returns zero. Otherwise, the new reserve area becomes the len chars beginning at the location pointed to by p, and the function returns the address of fbuf. If p is zero or len is not greater than zero, there will be no reserve area and fbuf is unbuffered.
Attempts to make the get/put pointer to agree (be synchronized) with the actual position of the attached file. This might involve flushing unwritten characters or backing up the file over characters already input. Returns zero on success, EOF on error. If it is necessary to ensure that a group of characters is written at the same time to a file, allocate a reserve area larger than the largest such group, sync just before storing the characters, then again just afterward.
fstream(3CC4), ios(3CC4), ios.intro(3CC4), sbufprot(3CC4), sbufpub(3CC4), stream_locker(3CC4), stream_MT(3CC4)
C++ Library Reference, Chapter 3, "The Classic iostream Library" and Chapter 4, "Using Classic iostreams in a Multithreaded Environment."
UNIX does not usually report seek failures, so neither will filebuf.