streambuf - Member Functions and Data by Group

Constructors & Destructor

Objects of the streambuf class can be constructed and destructed.

~streambuf
public:virtual ~streambuf()

This is supported on AIX OS/400 z/OS

The destructor for streambuf calls sync(). If a stream buffer has been set up and ios::alloc is set, sync() deletes the stream buffer.

streambuf
Overload 1
public:streambuf(char* p, long l)

This is supported on AIX z/OS

Constructs an empty stream buffer of length l starting at the position pointed to by p.

This constructor is available for 64-bit applications. The second argument is a long value.

Overload 2
public:streambuf(char* p, int l)

This is supported on AIX OS/400 z/OS

Constructs an empty stream buffer of length l starting at the position pointed to by p.

AIX and z/OS Considerations

This constructor is available for 32-bit applications. The second argument is an int value.

Overload 3
public:streambuf(char* p, int l, int c)

This is supported on AIX OS/400 z/OS

This constructor is obsolete. It is included for compatibility with the AT&T C++ Language System Release 1.2. Use strstreambuf.

Overload 4
public:streambuf()

This is supported on AIX OS/400 z/OS

Constructs an empty stream buffer corresponding to an empty sequence. The values returned by base(), eback(), ebuf(), egptr(), epptr(), pptr(), gptr(), and pbase() are initially all zero for this stream buffer.

Extraction Functions

Functions that extract characters from the ultimate producer, determine if characters are waiting to be extracted and handle underflow situations.

in_avail

Returns the number of characters that are available to be extracted from the get area of the stream buffer object. You can extract the number of characters equal to the value that in_avail() returns without causing an error.

Overload 1
public:int in_avail()

This is supported on AIX OS/400 z/OS

AIX and z/OS Considerations

This function returns an int value for 32-bit applications. It is not available for 64-bit applications.

Overload 2
public:long in_avail()

This is supported on AIX z/OS

This function returns a long value for 64-bit applications. It is not available for 32-bit applications.

optim_in_avail
public:int optim_in_avail()

This is supported on AIX OS/400 z/OS

Returns true if the current get pointer is less then the end of the get area.

optim_sbumpc
public:int optim_sbumpc()

This is supported on AIX OS/400 z/OS

Moves the get pointer past one character and returns the character that it moved past.

sbumpc
public:int sbumpc()

This is supported on AIX OS/400 z/OS

Moves the get pointer past one character and returns the character that it moved past. sbumpc() returns EOF if the get pointer is already at the end of the get area.

sgetc
public:int sgetc()

This is supported on AIX OS/400 z/OS

Returns the character after the get pointer without moving the get pointer itself. If no character is available, sgetc() returns EOF.

Note: sgetc() does not change the position of the get pointer.

sgetn
Overload 1
public:long sgetn(char* s, long n)

This is supported on AIX z/OS

Extracts the n characters following the get pointer, and copies them to the area starting at the position pointed to by s. If there are fewer than n characters following the get pointer, sgetn() takes the characters that are available and stores them in the position pointed to by s. sgetn() repositions the get pointer following the extracted characters and returns the number of extracted characters.

This function is available for 64-bit applications. It accepts a long argument.

Overload 2
public:int sgetn(char* s, int n)

This is supported on AIX OS/400 z/OS

Extracts the n characters following the get pointer, and copies them to the area starting at the position pointed to by s. If there are fewer than n characters following the get pointer, sgetn() takes the characters that are available and stores them in the position pointed to by s. sgetn() repositions the get pointer following the extracted characters and returns the number of extracted characters.

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

snextc
public:int snextc()

This is supported on AIX OS/400 z/OS

Moves the get pointer forward one character and returns the character following the new position of the get pointer. snextc() returns EOF if the get pointer is at the end of the get area either before or after it is moved forward.

underflow
public:virtual int underflow()

This is supported on AIX OS/400 z/OS

Takes characters from the ultimate producer and puts them in the get area.

The default definition of underflow() is compatible with the AT&T C++ Language System Release 1.2 version of the stream package, but it is not considered part of the current I/O Stream Library. Thus the default definition of underflow() should not be used, and every class derived from streambuf should define underflow() itself.

If you derive underflow() in a class derived from streambuf, it should return the first character in the get area if the get area is not empty. If the get area is empty, underflow() should create a get area that is not empty and return the next character. If no more characters are available in the ultimate producer, underflow() should return EOF and leave the get area empty.

xsgetn
Overload 1
public:virtual int xsgetn(char* s, int n)

This is supported on AIX OS/400 z/OS

Similar to sputn.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 2
public:virtual long xsgetn(char* s, long n)

This is supported on AIX z/OS

Similar to sgetn.

This function is available for 64-bit applications. The second argument is a long value.

Get/Put Pointer Functions

dbp
public:void dbp()

This is supported on AIX OS/400 z/OS

Writes to standard output the values returned by the following functions:

dbp() is intended for debugging. streambuf does not specify anything about the form of the output. dbp() is considered part of the protected interface because the information that it prints can only be understood in relation to that interface. It is declared as a public function so that it can be called anywhere during debugging.

The following example shows the output produced by dbp() when it is called as part of a filebuf object:

   #include < iostream.h >
   int main()
   {
      cout << "Here is some sample output." << endl;
      cout.rdbuf()->dbp();
   }

If you compile and run this example, your output will look like this:

   Here is some sample output.
   buf at 0x90210, base=0x91010, ebuf=0x91410,
   pptr=0x91010, epptr=0x91410, eback=0, gptr=0, egptr=0
pptr_non_null
public:int pptr_non_null()

This is supported on AIX

Returns true if the put pointer is not null.

seekoff
public:virtual streampos
  seekoff( streamoff,
           ios::seek_dir,
           int = ios::in|ios::out )

This is supported on AIX OS/400 z/OS

Repositions the get or put pointer of the ultimate producer or ultimate consumer. seekoff() does not change the values returned by gptr() or pptr().

The default definition of seekoff() returns EOF.

If you define your own seekoff() function, it should return EOF if the derived class does not support repositioning. If the class does support repositioning, seekoff() should return the new position of the affected pointer, or EOF if an error occurs.

The first argument is an offset from a position in the ultimate producer or ultimate consumer. The second argument is a position in the ultimate produce or ultimate consumer. It can have the following values:

The new position of the affected pointer is the position specified by the seek dir offset by the value of the stream offset. If you derive your own classes from streambuf, certain values of the seek dir may not be valid depending on the nature of the ultimate consumer or producer.

If ios::in is set in the third argument, the seekoff() should modify the get pointer. If ios::out is set, the put pointer should be modified. If both ios::in and ios::out are set, both the get pointer and the put pointer should be modified.

seekpos
public:virtual streampos
  seekpos( streampos,
           int = ios::in|ios::out )

This is supported on AIX OS/400 z/OS

Repositions the get or put pointer of the ultimate producer or consumer to the streampos position. If ios::in is set, the get pointer is repositioned. If ios::out is set, the put pointer is repositioned. If both ios::in and ios::out are set, both the get pointer and the put pointer are affected. seekpos() does not change the values returned by gptr() or pptr().

The default definition of seekpos() returns the return value of the function seekoff(streamoff(pos), ios::beg, mode). Thus, if you want to define seeking operations in a class derived from streambuf, you can define seekoff() and use the default definition of seekpos().

If you define seekpos() in a class derived from streambuf, seekpos() should return EOF if the class does not support repositioning or if the streampos points to a position equal to or greater than the end of the stream. If not, seekpos() should return the streampos.

stossc
public:void stossc()

This is supported on AIX OS/400 z/OS

Moves the get pointer forward one character. If the get pointer is already at the end of the get area, stossc() does not move it.

base
protected:char* base()

This is supported on AIX OS/400 z/OS

Returns a pointer to the first byte of the stream buffer. The stream buffer consists of the space between the pointer returned by base() and the pointer returned by ebuf().

eback
protected:char* eback()

This is supported on AIX OS/400 z/OS

Returns a pointer to the lower bound of the space available for the get area of the streambuf. The space between the pointer returned by eback() and the pointer returned by gptr() is available for putback.

ebuf
protected:char* ebuf()

This is supported on AIX OS/400 z/OS

Returns a pointer to the byte after the last byte of the stream buffer.

egptr
protected:char* egptr()

This is supported on AIX OS/400 z/OS

Returns a pointer to the byte after the last byte of the get area of the streambuf.

epptr
protected:char* epptr()

This is supported on AIX OS/400 z/OS

Returns a pointer to the byte after the last byte of the put area of the streambuf.

gbump
Overload 1
protected:void gbump(long n)

This is supported on AIX z/OS

Offsets the beginning of the get area by the value of n. The value of n can be positive or negative. gbump() does not check to see if the new value returned by gptr() is valid.

The beginning of the get area is equal to the value returned by gptr().

This function is available for 64-bit applications. It accepts a long argument.

Overload 2
protected:void gbump(int n)

This is supported on AIX OS/400 z/OS

Offsets the beginning of the get area by the value of n. The value of n can be positive or negative. gbump() does not check to see if the new value returned by gptr() is valid.

The beginning of the get area is equal to the value returned by gptr().

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

gptr
protected:char* gptr()

This is supported on AIX OS/400 z/OS

Returns a pointer to the first byte of the get area of the streambuf. The get area consists of the space between the pointer returned by gptr() and the pointer returned by egptr(). Characters are extracted from the stream buffer beginning at the character pointed to be gptr().

pbase
protected:char* pbase()

This is supported on AIX OS/400 z/OS

Returns a pointer to the beginning of the space available for the put area of the streambuf. Characters between the pointer returned by pbase() and the pointer returned by pptr() have been stored in the stream buffer, but they have not been consumed by the ultimate consumer.

pbump
Overload 1
protected:void pbump(long n)

This is supported on AIX z/OS

Offsets the beginning of the put area by the value of n. The value of n can be positive or negative. pbump() does not check to see if the new value returned by pptr() is valid.

The beginning of the put area is equal to the value returned by pptr().

This function is available for 64-bit applications. It accepts a long argument.

Overload 2
protected:void pbump(int n)

This is supported on AIX OS/400 z/OS

Offsets the beginning of the put area by the value of n. The value of n can be positive or negative. pbump() does not check to see if the new value returned by pptr() is valid.

The beginning of the put area is equal to the value returned by pptr().

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

pptr
protected:char* pptr()

This is supported on AIX OS/400 z/OS

Returns a pointer to the beginning of the put area of the streambuf. The put area consists of the space between the pointer returned by pptr() and the pointer returned by epptr().

setb
protected:void setb(char* b, char* eb, int a = 0)

This is supported on AIX OS/400 z/OS

Sets the beginning of the existing stream buffer (the pointer returned by base()) to the position pointed to by b, and sets the end of the stream buffer (the pointer returned by ebuf()) to the position pointed to by eb.

If a is a nonzero value, the stream buffer will be deleted when setb() is called again. If b and eb are both equal to 0, no stream buffer is established. If b is not equal to 0, a stream buffer is established, even if eb is less than b. If this is the case, the stream buffer has length zero.

setg
protected:void setg(char* eb, char* g, char* eg)

This is supported on AIX OS/400 z/OS

Sets the beginning of the get area of streambuf (the pointer returned by gptr()) to g, and sets the end of the get area (the pointer returned by egptr()) to eg. setg() also sets the beginning of the area available for putback (the pointer returned by eback()) to eb.

setp
protected:void setp(char* p, char* ep)

This is supported on AIX OS/400 z/OS

Sets the spaces available for the put area. Both the start (pbase()) and the beginning (pptr()) of the put area are set to the value p.

Sets the beginning of the put area of the streambuf (the pointer returned by pptr()) to the position pointed to by p, and sets the end of the put area (the pointer returned by epptr()) to the position pointed to by ep.

Insertion Functions

Functions that insert characters into the ultimate consumer, determine if characters are waiting to be inserted and handle overflow situations.

out_waiting

Returns the number of characters that are in the put area waiting to be sent to the ultimate consumer.

Overload 1
public:int out_waiting()

This is supported on AIX OS/400 z/OS

AIX and z/OS Considerations

This function returns an int value for 32-bit applications. It is not available for 64-bit applications.

Overload 2
public:long out_waiting()

This is supported on AIX z/OS

This function returns a long value for 64-bit applications. It is not available for 32-bit applications.

overflow
public:virtual int overflow(int c = EOF)

This is supported on AIX OS/400 z/OS

Called when the put area is full, and an attempt is made to store another character in it. overflow() may be called at other times.

The default definition of overflow() is compatible with the AT&T C++ Language System Release 1.2 version of the stream package, but it is not considered part of the current I/O Stream Library. Thus, the default definition of overflow() should not be used, and every class derived from streambuf should define overflow() itself.

The definition of overflow() in your classes derived from streambuf should cause the ultimate consumer to consume the characters in the put area, call setp() to establish a new put area, and store the argument c in the put area if c does not equal EOF. overflow() should return EOF if an error occurs, and it should return a value not equal to EOF otherwise.

pbackfail
public:virtual int pbackfail(int c)

This is supported on AIX OS/400 z/OS

Called when both of the following conditions are true:

The default definition of pbackfail() returns EOF.

If you define pbackfail() in your own classes, your definition of pbackfail() should attempt to deal with the full putback area by, for instance, repositioning the get pointer of the ultimate producer. If this is possible, pbackfail() should return the argument c. If not, pbackfail() should return EOF.

sputbackc
public:int sputbackc(char c)

This is supported on AIX OS/400 z/OS

Moves the get pointer back one character. The get pointer may simply move, or the ultimate producer may rearrange the internal data structures so that the character c is saved. The argument c must equal the character that precedes the get pointer in the stream buffer. The effect of sputbackc() is undefined if c is not equal to the character before the get pointer. sputbackc() returns EOF if an error occurs. The conditions that cause errors depend on the derived class.

sputc
public:int sputc(int c)

This is supported on AIX OS/400 z/OS

Stores the argument c after the put pointer and moves the put pointer past the stored character. If there is enough space in the stream buffer, this will extend the size of the put area. sputc() returns EOF if an error occurs. The conditions that cause errors depend on the derived class.

sputn
Overload 1
public:int sputn(const char* s, int n)

This is supported on AIX OS/400 z/OS

Stores the n characters starting at s after the put pointer and moves the put pointer to the end of the series. sputn() returns the number of characters successfully stored. If an error occurs, sputn() returns a value less than n.

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

Overload 2
public:long sputn(const char* s, long n)

This is supported on AIX z/OS

Stores the n characters starting at s after the put pointer and moves the put pointer to the end of the series. sputn() returns the number of characters successfully stored. If an error occurs, sputn() returns a value less than n.

This function is available for 64-bit applications. It accepts a long argument.

xsputn
Overload 1
public:virtual int xsputn(const char* s, int n)

This is supported on AIX OS/400 z/OS

Similar to sputn.

AIX and z/OS Considerations

This function is available for use when building 32-bit applications. The second argument is an int value.

Overload 2
public:virtual long xsputn(const char* s, long n)

This is supported on AIX z/OS

Similar to sputn.

This function is available for use when building 64-bit applications. The second argument is a long value.

Locking functions

streambuf_resource
public:IRTLResource& streambuf_resource() const

This is supported on z/OS

Stream Buffer Functions

Functions that work with the underlying streambuf object.

setbuf
Overload 1
public:streambuf* setbuf(unsigned char* p, long len)

This is supported on AIX z/OS

Sets up a stream buffer consisting of the array of bytes starting at p with length len.

This function is different from setb(). setb() sets pointers to an existing stream buffer. setbuf(), however, creates the stream buffer.

The default definition of setbuf() sets up the stream buffer if the streambuf object does not already have a stream buffer.

If you define setbuf() in a class derived from streambuf, setbuf() can either accept or ignore a request for an unbuffered streambuf object. The call to setbuf() is a request for an unbuffered streambuf object if p equals 0 or len equals 0. setbuf() should return a pointer to the streambuf if it accepts the request, and 0 otherwise.

This function is available for 64-bit applications. It accepts an long argument.

Overload 2
public:virtual streambuf* setbuf(char* p, long len)

This is supported on AIX z/OS

Sets up a stream buffer consisting of the array of bytes starting at p with length len.

This function is different from setb(). setb() sets pointers to an existing stream buffer. setbuf(), however, creates the stream buffer.

The default definition of setbuf() sets up the stream buffer if the streambuf object does not already have a stream buffer.

If you define setbuf() in a class derived from streambuf, setbuf() can either accept or ignore a request for an unbuffered streambuf object. The call to setbuf() is a request for an unbuffered streambuf object if p equals 0 or len equals 0. setbuf() should return a pointer to the streambuf if it accepts the request, and 0 otherwise.

This function is available for 64-bit applications. It accepts an long argument.

Overload 3
public:streambuf* setbuf(char* p, int len, int count)

This is supported on AIX OS/400 z/OS

This function is obsolete. The I/O Stream Library includes it to be compatible with AT&T C++ Language System Release 1.2

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

Overload 4
public:virtual streambuf* setbuf(char* p, int len)

This is supported on AIX OS/400 z/OS

Sets up a stream buffer consisting of the array of bytes starting at p with length len.

This function is different from setb(). setb() sets pointers to an existing stream buffer. setbuf(), however, creates the stream buffer.

The default definition of setbuf() sets up the stream buffer if the streambuf object does not already have a stream buffer.

If you define setbuf() in a class derived from streambuf, setbuf() can either accept or ignore a request for an unbuffered streambuf object. The call to setbuf() is a request for an unbuffered streambuf object if p equals 0 or len equals 0. setbuf() should return a pointer to the streambuf if it accepts the request, and 0 otherwise.

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

Overload 5
public:streambuf* setbuf(unsigned char* p, int len)

This is supported on AIX OS/400 z/OS

Sets up a stream buffer consisting of the array of bytes starting at p with length len.

This function is different from setb(). setb() sets pointers to an existing stream buffer. setbuf(), however, creates the stream buffer.

The default definition of setbuf() sets up the stream buffer if the streambuf object does not already have a stream buffer.

If you define setbuf() in a class derived from streambuf, setbuf() can either accept or ignore a request for an unbuffered streambuf object. The call to setbuf() is a request for an unbuffered streambuf object if p equals 0 or len equals 0. setbuf() should return a pointer to the streambuf if it accepts the request, and 0 otherwise.

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.

sync
public:virtual int sync()

This is supported on AIX OS/400 z/OS

Synchronizes the stream buffer with the ultimate producer or the ultimate consumer.

The default definition of sync() returns 0 if either of the following conditions is true:

Otherwise, sync() returns EOF.

If you define sync() in a class derived from streambuf, it should send any characters that are stored in the put area to the ultimate consumer, and (if possible) send any characters that are waiting in the get area back to the ultimate producer. When sync() returns, both the put area and the get area should be empty. sync() should return EOF if an error occurs.

allocate
protected:int allocate()

This is supported on AIX OS/400 z/OS

Attempts to set up a stream buffer. allocate() returns the following values:

allocate() is not called by any other nonvirtual member function of streambuf.

blen

Returns the length (in bytes) of the stream buffer.

Overload 1
protected:long blen() const

This is supported on AIX z/OS

The value returned is a long when building 64-bit aplications. This function is not available for 32-bit applications.

Overload 2
protected:int blen() const

This is supported on AIX OS/400 z/OS

AIX and z/OS Considerations

The value returned is an int when building 32-bit applications. This function is not available for 64-bit applications.

doallocate
protected:virtual int doallocate()

This is supported on AIX OS/400 z/OS

Called when allocate() determines that space is needed for a stream buffer.

The default definition of doallocate() attempts to allocate space for a stream buffer using the operator new.

If you define your own version of doallocate(), it must call setb() to provide space for a stream buffer or return EOF if it cannot allocate space. doallocate() should only be called if unbuffered() and base() return zero.

In your own version of doallocate(), you provide the size of the buffer for your constructor. Assign the buffer size you want to a variable using a #define statement. This variable can then be used in the constructor for your doallocate() function to define the size of the buffer.

unbuffered
Overload 1
protected:void unbuffered(int unb)

This is supported on AIX OS/400 z/OS

Manipulates the private streambuf variable called the buffering state. If the buffering state is nonzero, a call to allocate() does not set up a stream buffer.

Changes the value of the buffering state to unb.

Overload 2
protected:int unbuffered() const

This is supported on AIX OS/400 z/OS

Manipulates the private streambuf variable called the buffering state. If the buffering state is nonzero, a call to allocate() does not set up a stream buffer.

Returns the current value of the buffering state.