filebuf(3C++) filebuf(3C++)
NAME
filebuf - 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) ;
int detach() ;
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 four 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
Copyright 1994 Novell, Inc. Page 1
filebuf(3C++) filebuf(3C++)
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 streambuf_pub(3C++) and
streambuf_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 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.
Copyright 1994 Novell, Inc. Page 2
filebuf(3C++) filebuf(3C++)
d=f.detach()
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.
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, 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 streambuf_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.
Copyright 1994 Novell, Inc. Page 3
filebuf(3C++) filebuf(3C++)
p=f.seekpos(pos, mode)
Moves the file to a position pos as described in
streambuf_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.
USAGE
attach and the constructors should test if the file descriptor
they are given is open.
There is no way to force atomic reads.
The UNIX system does not usually report failures of seek
(e.g., on a tty), so a filebuf does not either.
REFERENCES
streambuf_pub(3C++), streambuf_prot(3C++), fstream(3C++).
Copyright 1994 Novell, Inc. Page 4