FILEBUF(3C++) FILEBUF(3C++)
NAMEfilebuf - buffer for file I/O.
SYNOPSIS
#include <iostream.h>
typedef long streamoff, streampos;
class ios {
public:
enum seek_dir { beg, cur, end };
enum open_mode { in, out, ate, app, trunc, nocreate, noreplace } ;
// and lots of other stuff, see ios(3C++) ...
} ;
#include <fstream.h>
class filebuf : public streambuf {
public:
static const int openprot ; /* default protection for open */
filebuf() ;
~filebuf() ;
filebuf(int d);
filebuf(int d, char* p, int len) ;
filebuf* attach(int d) ;
filebuf* close();
int fd();
int is_open();
filebuf* open(char *name, int omode, int prot=openprot) ;
streampos seekoff(streamoff, seek_dir, int omode) ;
streampos seekpos(streampos, int omode) ;
streambuf*setbuf(char* p, int len) ;
int sync() ;
};
DESCRIPTION
filebufs specialize streambufs to use a file as a source or sink of
characters. Characters are consumed by doing writes to the file, and are
produced by doing reads. When the file is seekable, a filebuf allows
seeks. At least 4 characters of putback are guaranteed. When the file
permits reading and writing, the filebuf permits both storing and
fetching. No special action is required between gets and puts (unlike
stdio). A filebuf that is connected to a file descriptor is said to be
open. Files are opened by default with a protection mode of openprot,
which is 0644.
The reserve area (or buffer, see sbuf.pub(3C++) and sbuf.prot(3C++)) is
allocated automatically if one is not specified explicitly with a
constructor or a call to setbuf(). filebufs can also be made unbuffered
with certain arguments to the constructor or setbuf(), in which case a
system call is made for each character that is read or written. The get
Page 1
FILEBUF(3C++) FILEBUF(3C++)
and put pointers into the reserve area are conceptually tied together;
they behave as a single pointer. Therefore, the descriptions below refer
to a single get/put pointer.
In the descriptions below, assume:
- f is a filebuf.
- pfb is a filebuf*.
- psb is a streambuf*.
- i, d, len, and prot are ints.
- name and ptr are char*s.
- mode is an int representing an open_mode.
- off is a streamoff.
- p and pos are streampos's.
- dir is a seek_dir.
Constructors:
filebuf()
Constructs an initially closed filebuf.
filebuf(d)
Constructs a filebuf connected to file descriptor d.
filebuf(d, p, len)
Constructs a filebuf connected to file descriptor d and initialized
to use the reserve area starting at p and containing len bytes. If
p is null or len is zero or less, the filebuf will be unbuffered.
Members:
pfb=f.attach(d)
Connects f to an open file descriptor, d. attach() normally returns
&f, but returns 0 if f is already open.
pfb=f.close()
Flushes any waiting output, closes the file descriptor, and
disconnects f. Unless an error occurs, f's error state will be
cleared. close() returns &f unless errors occur, in which case it
returns 0. Even if errors occur, close() leaves the file descriptor
and f closed.
i=f.fd()
Returns i, the file descriptor f is connected to. If f is closed, i
is EOF.
i=f.is_open()
Returns non-zero when f is connected to a file descriptor, and zero
otherwise.
pfb=f.open(name, mode, prot)
Opens file name and connects f to it. If the file does not already
exist, an attempt is made to create it with protection mode prot,
Page 2
FILEBUF(3C++) FILEBUF(3C++)
unless ios::nocreate is specified in mode. By default, prot is
filebuf::openprot, which is 0644. Failure occurs if f is already
open. open() normally returns &f, but if an error occurs it returns
0. The members of open_mode are bits that may be or'ed together.
(Because the or'ing returns an int, open() takes an int rather than
an open_mode argument.) The meanings of these bits in mode are
described in detail in fstream(3C++).
p=f.seekoff(off, dir, mode)
Moves the get/put pointer as designated by off and dir. It may fail
if the file that f is attached to does not support seeking, or if
the attempted motion is otherwise invalid (such as attempting to
seek to a position before the beginning of file). off is
interpreted as a count relative to the place in the file specified
by dir as described in sbuf.pub(3C++). mode is ignored. seekoff()
returns p, the new position, or EOF if a failure occurs. The
position of the file after a failure is undefined.
p=f.seekpos(pos, mode)
Moves the file to a position pos as described in sbuf.pub(3C++).
mode is ignored. seekpos() normally returns pos, but on failure it
returns EOF.
psb=f.setbuf(ptr, len)
Sets up the reserve area as len bytes beginning at ptr. If ptr is
null or len is less than or equal to 0, f will be unbuffered.
setbuf() normally returns &f. However, if f is open and a buffer
has been allocated, no changes are made to the reserve area or to
the buffering status, and setbuf() returns 0.
i=f.sync()
Attempts to force the state of the get/put pointer of f to agree (be
synchronized) with the state of the file f.fd(). This means it may
write characters to the file if some have been buffered for output
or attempt to reposition (seek) the file if characters have been
read and buffered for input. Normally, sync() returns 0, but it
returns EOF if synchronization is not possible.
Sometimes it is necessary to guarantee that certain characters are
written together. To do this, the program should use setbuf() (or a
constructor) to guarantee that the reserve area is at least as large
as the number of characters that must be written together. It can
then call sync(), then store the characters, then call sync() again.
CAVEATSattach() and the constructors should test if the file descriptor they are
given is open, but I can't figure out a portable way to do that.
There is no way to force atomic reads.
Page 3
FILEBUF(3C++) FILEBUF(3C++)
The UNIX system does not usually report failures of seek (e.g., on a
tty), so a filebuf does not either.
SEE ALSO
sbuf.pub(3C++), sbuf.prot(3C++), and fstream(3C++).
Page 4
