Партнёры:
Хостинг:
NAME
filebuf - 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(3C++) 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 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 writ-
ing. Unlike C stdio, no seek is required between gets and
puts to the same filebuf. At least four characters of put-
back are initially allowed.
The basic streambuf operations are as described in
sbufprot(3C++) and sbufpub(3C++). The reserve area is allo-
cated 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 vali-
dity.
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'' ver-
sion (the default), that uses mutex locks to protect against
simultaneous access by multiple threads.
ENVIRONMENT
The discussion about thread safety applies only to Solaris
2.x. On Solaris 1.x the ``safe'' and ``unsafe'' functions
behave identically.
Constructors
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 perform 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 descrip-
tor from f. The file descriptor is returned. Applica-
tions 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 perform 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
descriptor), zero otherwise. This member is mt-safe.
int i = fbuf.is_open_unlocked()
Functionally identical to is_open, except that it does
not perform 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; other-
wise 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(3C++), which may be or'd together. This func-
tion 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(3C++) 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.
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(3C++).
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 syn-
chronized) 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 neces-
sary 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 ALSO
ios.intro(3C++), fstream(3C++), ios(3C++), sbufprot(3C++),
sbufpub(3C++), stream_locker(3C++), stream_MT(3C++),
C++ 4.1 Library Reference Manual:
Chapter 4, "The Iostream Library",
Chapter 5, "Using libC in a Multithreaded Environment."
WARNINGS
Unix does not usually report seek failures, so neither will
filebuf.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |