basic_streambuf man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

basic_streambuf(3C++)		       -		 basic_streambuf(3C++)

Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.

NAME
       basic_streambuf, streambuf, wstreambuf

	-  Abstract  base class for deriving various stream buffers to facili‐
       tate control of character sequences.

SYNOPSIS
       #include <streambuf>
       template<class charT, class traits = char_traits<charT> >
       class basic_streambuf;

DESCRIPTION
       The class template basic_streambuf<charT,traits> serves as an  abstract
       base class for deriving various stream buffers to facilitate control of
       character sequences such as:

       ·    A character input sequence;

       ·    A character output sequence.

       Each sequence is associated with three pointers (as  described  below),
       which,  if  non-null,  all  point into the same charT array object. The
       array object represents, at any moment, a segment  of  characters  from
       the  sequence.  Operations  performed  on  a  sequence alter the values
       pointed to by these pointers, perform reads and writes directly	to  or
       from  associated sequences, and alter "the stream position" and conver‐
       sion state as needed to maintain this segment to sequence relationship.
       The three pointers are:

       ·    The beginning pointer, or lowest element address in the array;

       ·    The next pointer, or next element address that is a current candi‐
	    date for reading or writing;

       ·    The end pointer, or first element address beyond the  end  of  the
	    array.

       Stream  buffers	can  impose  various constraints on the sequences they
       control, including:

       ·    The controlled input sequence may be unreadable;

       ·    The controlled output sequence may be unwriteable;

       ·    The controlled sequences can be associated with  the  contents  of
	    other  representations  for	 character sequences, such as external
	    files;

       ·    The controlled sequences can impose limitations on how the program
	    can	 read  characters  from	 a  sequence,  write  characters  to a
	    sequence, put characters back into an input sequence, or alter the
	    stream position.

INTERFACE
       template<class charT, class traits = char_traits<charT> >
       class basic_streambuf {

       public:

typedef charT			    char_type;
typedef traits			    traits_type;

typedef typename traits::int_type    int_type;
typedef typename traits::pos_type    pos_type;
typedef typename traits::off_type    off_type;

virtual ~basic_streambuf();

locale pubimbue( const locale& loc);
locale getloc() const;

basic_streambuf<;char_type, traits> *
  pubsetbuf(char_type *s, streamsize n);

pos_type pubseekoff(off_type off, ios_base::seekdir way,
		    ios_base::openmode which =
		    ios_base::in | ios_base::out);

pos_type pubseekpos(pos_type sp, ios_base::openmode which =
		    ios_base::in | ios_base::out);

int pubsync();

ios_base::openmode which_open_mode();

streamsize   in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
streamsize sgetn(char_type *s, streamsize n);

int_type sputbackc(char_type c);
int sungetc();

int_type sputc(char_type c);
streamsize sputn(const char_type *s, streamsize n);

protected:

basic_streambuf();

char_type *eback() const;
char_type *gptr()  const;
char_type *egptr() const;

void gbump(int n);
void setg(char_type *gbeg_arg,char_type *gnext_arg,
	  char_type *gend_arg);

char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int n);
void setp(char_type *pbeg_arg,char_type *pend_arg);

virtual void imbue( const locale& loc);

virtual basic_streambuf<;charT, traits>*
  setbuf(char_type *s, streamsize n);

virtual pos_type seekoff(off_type off,
			 ios_base::seekdir way,
			 ios_base::openmode which =
			 ios_base::in | ios_base::out);

virtual pos_type seekpos(pos_type sp,
			 ios_base::openmode which =
			 ios_base::in | ios_base::out);

virtual int showmanyc();
virtual streamsize xsgetn(char_type *s, streamsize n);

virtual int_type underflow();
virtual int_type uflow();

virtual int_type pbackfail(int_type c = traits::eof());
virtual streamsize xsputn(const char_type *s,
			  streamsize n);
virtual int_type overflow(int_type c = traits::eof());

virtual int sync();

};

TYPES
       char_type

   The type char_type is a synonym for the template parameter charT.

int_type

   The type int_type is a synonym of type traits::in_type.

off_type

   The type off_type is a synonym of type traits::off_type.

pos_type

   The type pos_type is a synonym of type traits::pos_type.

streambuf

   The	type  streambuf	 is  an instantiation of class basic_streambuf on type
   char:

   typedef basic_streambuf<char> streambuf;

traits_type

   The type traits_type is a synonym for the template parameter traits.

wstreambuf

   The type wstreambuf is an instantiation of class  basic_streambuf  on  type
   wchar_t:

   typedef basic_streambuf<wchar_t> wstreambuf;

PUBLIC CONSTRUCTORS
       basic_streambuf();

   Constructs  an object of class basic_streambuf. Initializes all its pointer
   member objects to null pointers, and initializes the getloc() member	 func‐
   tion to return the value of locale::locale().

PUBLIC DESTRUCTORS
       virtual ~basic_streambuf();

   Destroys an object of class basic_streambuf.

PUBLIC MEMBER FUNCTIONS
       locale
       getloc() const;

   If pubimbue() has ever been called, returns the last value of loc supplied.
   Otherwise, it returns  the  default	(global)  locale  locale::locale()  in
   effect at the time of construction.

streamsize
in_avail();

   If a read position is available, returns the number of available characters
   in the input sequence. Otherwise calls the protected function showmanyc().

locale
pubimbue(const locale& loc);

   Calls the protected function imbue(loc).

pos_type
pubseekoff(off_type off, ios_base::seekdir way,
	  ios_base::openmode which =
	  ios_base::in | ios_base::out );

   Calls the protected function seekoff(off,way,which).

pos_type
pubseekpos(pos_type sp, ios_base::openmode which=
	  ios_base::in | ios_base::out );

   Calls the protected function seekpos(sp,which).

basic_streambuf<;char_type,traits>*
pubsetbuf(char_type* s,streamsize n);

   Calls the protected function setbuf(s,n) .

int
pubsync();

   Calls the protected function sync().

int_type
sbumpc();

   If the input sequence read position is not available,  calls	 the  function
   uflow().  Otherwise	it returns *gptr() and increments the next pointer for
   the input sequence.

int_type
sgetc();

   If the input sequence read position is not available, calls	the  protected
   function underflow(). Otherwise it returns *gptr().

streamsize
sgetn(char_type* s, streamsize n);

   Calls the protected function xsgetn(s,n).

int_type
snextc();

   Calls  the  function	 sbumpc()  and	if  it	returns traits::eof(), returns
   traits::eof(). Otherwise it calls the function sgetc().

int_type
sputbackc(char_type c);

   If  the  input  sequence  putback  position	is   not   available   or   if
   traits::eq(c,gptr()	[-1])  returns	false,	calls  the  protected function
   pbackfail(c). Otherwise it  decrements  the	next  pointer  for  the	 input
   sequence and returns *gptr().

int_type
sputc(char_type c);

   If the output sequence write position is not available, calls the protected
   function overflow(traits::to_int_type( c )). Otherwise, it stores c at  the
   next	 pointer  for the output sequence, increments the pointer, and returns
   *pptr().

streamsize
sputn(const char_type* s, streamsize n);

   Calls the protected function xsputn(s,n).

int_type
sungetc();

   If the input sequence putback position is not  available,  calls  the  pro‐
   tected  function  pbackfail(). Otherwise it decrements the next pointer for
   the input sequence and returns *gptr().

ios_base::openmode
which_open_mode();

   Returns the mode in which the stream buffer is opened. This function is not
   described in the C++ standard.

PROTECTED MEMBER FUNCTIONS
       char_type*
       eback() const;

   Returns the beginning pointer for the input sequence.

char_type*
egptr() const;

   Returns the end pointer for the input sequence.

char_type*
epptr() const;

   Returns the end pointer for the output sequence.

void
gbump(int n);

   Advances the next pointer for the input sequence by n.

char_type*
gptr() const;

   Returns the next pointer for the input sequence.

void
imbue(const locale&);

   Changes  any	 translations  based  on locale. The default behavior is to do
   nothing. This function has to be overloaded in  the	classes	 derived  from
   basic_streambuf. The purpose of this function is to allow the derived class
   to be informed of changes in locale at the time they occur. The new	imbued
   locale  object  is  only  used by the stream buffer; it does not affect the
   stream itself.

int_type
overflow(int_type c = traits::eof() );

   The member functions sputc() and sputn() call this function when not enough
   room	 can  be found in the put buffer to accommodate the argument character
   sequence. The function returns traits::eof() if it fails to make more  room
   available  or  if it fails to empty the buffer by writing the characters to
   their output device.

int_type
pbackfail(int_type c = traits::eof() );

   If c is equal to traits::eof(), gptr() is moved back one  position.	Other‐
   wise	 c  is prepended. The function returns traits::eof() to indicate fail‐
   ure.

char_type*
pbase() const;

   Returns the beginning pointer for the output sequence.

void
pbump(int n);

   Advances the next pointer for the output sequence by n.

char_type*
pptr() const;

   Returns the next pointer for the output sequence.

pos_type
seekoff(off_type off, ios_base::seekdir way,
       ios_base::openmode which =
       ios_base::in | ios_base::out );

   Alters the stream positions within one or more of the controlled  sequences
   in	a  way	that  is  defined  separately  for  each  class	 derived  from
   basic_streambuf. The default behavior  is  to  return  an  object  of  type
   pos_type that stores an invalid stream position.

pos_type
seekpos(pos_type sp, ios_base::openmode which=
       ios_base::in | ios_base::out );

   Alters  the stream positions within one or more of the controlled sequences
   in  a  way  that  is	 defined  separately  for  each	 class	derived	  from
   basic_streambuf.  The  default  behavior  is	 to  return an object of class
   pos_type that stores an invalid stream position.

basic_streambuf*
setbuf(char_type* s, streamsize n);

   Performs an operation that is defined separately  for  each	class  derived
   from	 basic_streambuf. The purpose of this function is to allow the user to
   provide his own buffer or to resize the current buffer.

void
setg(char_type* gbeg, char_type* gnext, char_type* gend);

   Sets up a private member for the following to be true:

  eback() == gbeg, gptr() == gnext and egptr() == gend

void
setp(char_type* pbeg, char_type* pend);

   Sets up a private member for the following to be true:

  pbase() == pbeg, pptr() == pbeg and epptr() == pend

int
showmanyc();

   Returns the number of characters  available	in  the	 internal  buffer,  or
   returns -1.


int
sync();

   Synchronizes	 the  controlled  sequences with the internal buffer, in a way
   that is defined separately for each class derived from basic_streambuf. The
   default behavior is to do nothing. On failure the return value is -1.


int_type
underflow();

   The	public members of basic_streambuf call this function only if gptr() is
   null or gptr() >= egptr(). This function returns the character  pointed  to
   by  gptr(),	if  gptr()  is not null and if gptr() < egptr(). Otherwise the
   function tries to read character into the buffer. If it fails,  it  returns
   traits::eof().

int_type
uflow();

   Calls   underflow()	and  if	 underflow()  returns  traits::eof(),  returns
   traits::eof(). Otherwise, does gbump(1) and returns the value of *gptr().

streamsize
xsgetn(char_type* s, streamsize n);

   Assigns up to n characters to successive elements of the array whose	 first
   element  is	designated  by	s.  The	 characters  are  read	from the input
   sequence. Assigning stops when either n characters have been assigned or  a
   call	 to sbumpc() would return traits::eof(). The function returns the num‐
   ber of characters read.

streamsize
xsputn(const char_type* s, streamsize n);

   Writes up to n characters to the output sequence.  The  characters  written
   are	obtained  from successive elements of the array whose first element is
   designated by s. Writing stops when either n characters have	 been  written
   or  a  call to sputc() would return traits::eof(). The function returns the
   number of characters written.

SEE ALSO
       char_traits(3C++),     basic_filebuf(3C++),	basic_stringbuf(3C++),
       strstreambuf(3C++)

       Working Paper for Draft Proposed International Standard for Information
       Systems--Programming Language C++, Section 27.5.2

STANDARDS CONFORMANCE
       ANSI X3J16/ISO WG21 Joint C++ Committee

Rogue Wave Software		  02 Apr 1998		 basic_streambuf(3C++)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net