filebuf(C++)

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

The reservearea (or buffer, see streambuf_pub(C++) and streambuf_prot(C++)) 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.

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(C++).

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(C++). 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 streambuf_pub(C++). 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.

Usage

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