FILEBUF(3CC4)FILEBUF(3CC4)NAMEfilebuf - buffer class for file I/O
SYNOPSIS
#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() ;
};
DESCRIPTION
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 exam‐
ple, 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 multi‐
ple threads.
filebuf() Creates a closed filebuf.
filebuf(f)
Creates an open filebuf attached to file descriptor f, which is
assumed to be open.
filebuf(f, p, len)
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.
Member Functions
filebuf* fb = fbuf.attach(f)
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.
filebuf *fb = fbuf.attach_unlocked(f)
Functionally identical to attach, except that it does not per‐
form any mutex locks, and is thus not mt-safe.
int i = fbuf.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(). This member is mt-safe.
int i = fbuf.detach_unlocked()
Functionally identical to detach, except that it does not per‐
form any mutex locks, and is thus not mt-safe.
filebuf* fb = fbuf.close()
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.
filebuf* fb = fbuf.close_unlocked()
Functionally identical to close, except that it does not perform
any mutex locks, and is thus not mt-safe.
int f = fbuf.fd()
Returns the file descriptor attached to fbuf, or EOF if fbuf is
not open.
int i = fbuf.is_open()
Returns non-zero if fbuf is open (connected to a file descrip‐
tor), zero otherwise. This member is mt-safe.
int i = fbuf.is_open_unlocked()
Functionally identical to is_open, except that it does not per‐
form any mutex locks, and is thus not mt-safe.
filebuf* fb = fbuf.open(name, mode, prot)
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.
filebuf* fb = fbuf.open_unlocked(name, mode, prot)
Functionally identical to open, except that it does not perform
any mutex locks, and is thus not mt-safe.
streampos pos2 = fbuf.seekoff(off, dir, mode)
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 off‐
set 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.
streampos pos2 = fbuf.seekpos(pos, mode)
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).
streambuf* sb = fbuf.setbuf(p, len)
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.
int i = fbuf.sync()
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.
SEE ALSOios.intro(3CC4), fstream(3CC4), ios(3CC4), sbufprot(3CC4), sbuf‐
pub(3CC4), stream_locker(3CC4), stream_MT(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Chapter 4, "Using Classic iostreams in a Multithreaded Environ‐
ment."
WARNINGS
Unix does not usually report seek failures, so neither will filebuf.
18 June 1998 FILEBUF(3CC4)
