The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

sbufpub (3)
  • >> sbufpub (3) ( Solaris man: Библиотечные вызовы )
  • 
    NAME
         sbufpub - public interface of the stream buffer base class
    
    SYNOPSIS
         #include <iostream.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
                 };
    
                 // stream seek direction
                 enum seek_dir { beg=0, cur=1, end=2 };
    
                 // see ios(3C++) for remainder ...
         } ;
    
         class streambuf : public stream_MT {
         public :
    
                 int             in_avail();
                 int             out_waiting();
                 int             sbumpc();
                 streambuf*      setbuf(char* ptr, int len);
                 streampos       seekpos(streampos, int =ios::in|ios::out);
                 streampos       seekoff(streamoff, seek_dir, int =ios::in|ios::out);
                 int             sgetc();
                 int             sgetn(char* ptr, int n);
                 int             snextc();
                 int             sputbackc(char);
                 int             sputc(int c);
                 int             sputn(const char* s, int n);
                 void            stossc();
                 virtual int     sync();
    
                 int             in_avail_unlocked();
                 int             out_waiting_unlocked();
                 int             sbumpc_unlocked();
                 int             sgetc_unlocked();
                 int             sgetn_unlocked(char* ptr, int n);
                 int             snextc_unlocked();
                 int             sputbackc_unlocked(char);
                 int             sputc_unlocked(int c);
                 int             sputn_unlocked(const char* s, int n);
                 void            stossc_unlocked();
         };
    
    DESCRIPTION
         The streambuf class defines  the  basic  buffer-class  func-
         tionality  from  which  actual  buffer  classes are derived.
         This public interface represents  the  functions  which  any
         stream  class might need to call upon to perform its buffer-
         related functions.  No object of  type  is  expected  to  be
         created.   Rather,  buffer  objects  must be of a class type
         derived from streambuf. See sbufprot (3C++) for a discussion
         of the protected interface necessary for such derivations.
    
      ENVIRONMENT
         The discussion about thread safety applies only  to  Solaris
         2.x.
    
         To make streambuf multi-threaded safe (MT  safe),  that  is,
         able  to  work  correctly  in  a multi-threaded environment,
         locks have been used in  each  public  member  function.  An
         alternative set of public member functions without locks has
         been introduced for  use  in  single  threaded  applications
         where  performance is critical. These member functions share
         the same name as the original function with the addition  of
         the  suffix:  _unlocked.  Other  than  being MT unsafe these
         member functions have identical functionality.
    
         Class streambuf supports an abstract buffer class.  It  con-
         sists  logically  of a sequence of characters and one or two
         pointers defining the location where the next character will
         be  stored and/or fetched.  A buffer class intended only for
         input (or output) will have only the get (or  put)  pointer.
         A  buffer class intended for both input and output will have
         both pointers.
    
         The get and put pointers should be  understood  as  pointing
         between  characters  in the sequence.  The next character to
         be fetched from an input buffer is the one  just  after  the
         get  pointer.   The  next  character  placed  into an output
         stream will be stored just after the put pointer.   When  at
         the  beginning of the sequence, a pointer points just before
         the first character; at the end of the  sequence  it  points
         just after the last character.
    
         There can be different kinds of buffers (also called reserve
         areas)  with different strategies, due to different underly-
         ing devices.  Queue-like buffers, such as strstreambuf  (see
         ssbuf(3C++)),  have  independent  get and put pointers.  The
         strstreambuf is an in-memory array of  characters  and  sup-
         ports  stores and fetches at arbitrary locations.  File-like
         buffers, such as filebuf  (see  filebuf(3C++)),  may  permit
         both  get  and put operations, but there is effectively only
         one pointer; the next get or  put  will  always  be  at  the
         current  location.   (In practice there may be two pointers,
         but they always point to the same place.)
    
         The streambuf uses an array of characters as the buffer, and
         calls  upon  virtual functions to fill an empty input buffer
         or to flush a full output buffer.  (See  sbufprot(3C++)  for
         details.)   The  storing, fetching, and pointer manipulation
         functions  are  generally  inline  for  maximum  efficiency.
         These are described below.
    
      Input functions
         int c = sbuf.sgetc()
              This function  returns  the  character  after  the  get
              pointer, or EOF if the get pointer is at the end of the
              sequence.  Despite its name,  this  function  does  NOT
              move the get pointer.
    
         int c = sbuf.snextc()
              This function moves the get pointer forward  one  posi-
              tion,   then   returns  the  character  after  the  get
              pointer's new position.  If the get pointer is  at  the
              end  of  the  sequence before or after the call to this
              function (no character  is  available),  this  function
              returns  EOF.  Example:  Suppose the input buffer looks
              like this:
                   abc|def
              where `|' marks the position of the get pointer.   This
              function will advance the get pointer and return `e'.
    
         int c = sbuf.sbumpc()
              This  function  should  probably   have   been   called
              ``sgetc''.   It moves the get pointer forward one posi-
              tion and returns the character it moved past.   If  the
              get  pointer  is  currently at the end of the sequence,
              this function returns EOF.
    
         sbuf.stossc()
              This function moves the get pointer forward  one  posi-
              tion; it returns nothing.  The combination of sgetc and
              stossc can be used to implement a scanner without using
              putback, since sgetc provides lookahead.
    
         int i = sbuf.sgetn(ptr, len)
              This function gets the next  len  characters  following
              the get pointer, copying them to the char array pointed
              to by ptr; it advances the get pointer  past  the  last
              character  fetched.   If  fewer than len characters are
              left, it gets as many as are available.  It returns the
              number of characters fetched.
    
         int c = sbuf.sputbackc(c)
              This function attempts to move the get pointer back one
              character  and put c at the new location.  Depending on
              the underlying buffer mechanism, it may not be possible
              to  move the pointer back, or it may not be possible to
              store c at that location.  Therefore, the effect of the
              function is uncertain if c is not the same as the char-
              acter just ahead of the get pointer.   Again  depending
              on   the  underlying  mechanism,  this  function  might
              require  resynchronization  with  an  external  device.
              This  function  returns  EOF  if  the attempted putback
              fails.  What constitutes failure depends on the details
              of  the actual buffer class, but would probably include
              already being at the beginning of a device.
    
         int i = sbuf.in_avail()
              This function returns the number of characters  immedi-
              ately  available in the get area.  It is certain that i
              characters may be fetched without  error,  and  without
              accessing any external device.
    
      Output functions
         int i = sbuf.sputc(c)
              This function stores c just after the put pointer,  and
              advances  the  pointer one position, possibly extending
              the sequence.  It returns c, or  EOF  on  error.   What
              constitutes  an  error  depends  on  the actual derived
              buffer class.
    
         int i = sbuf.sputn(ptr, len)
              From the location pointed to by ptr, stores exactly len
              characters  after  the  put  pointer, advancing the put
              pointer just past the last character.  It  returns  the
              number  of  characters  stored,  which ought to be len.
              Fewer than len characters stored indicates some sort of
              error.
    
         int i = sbuf.out_waiting()
              This function returns the number of characters  in  the
              put  area;  that  is,  the number of characters pending
              output to the ultimate destination.
    
      Positioning functions
         streampos pos = sbuf.seekoff(off, dir, mode)
              This  function  repositions  the  get  and/or  the  put
              pointers,  depending  on  the  bits  set  in  mode.  If
              ios::in is set in mode, the get pointer  is  moved;  if
              ios::out is set in mode, the put pointer is moved.  The
              distance to move is off, a signed quantity.  The possi-
              ble values for dir are
                   ios::beg - move off bytes from  the  beginning  of
                   the stream;
                   ios::cur - move off bytes from the  current  posi-
                   tion;
                   ios::end - move off bytes  from  the  end  of  the
                   stream.
              This function returns the new position, or EOF  if  the
              stream  could  not  be  positioned as requested.  Note:
              not all streams support positioning.  Note:  the  posi-
              tion  returned  (of  type  streampos) should not be the
              subject of any arithmetic  operations,  but  should  be
              treated as a ``magic'' value.
    
         streampos newpos = sbuf.seekpos(pos, mode)
              This  function  repositions  the  get  and/or  the  put
              pointers,  depending  on the bits set in mode, to posi-
              tion pos.  If ios::in is set in mode, the  get  pointer
              is  moved;  if ios::out is set in mode, the put pointer
              is moved.  The value of pos should  be  one  which  was
              returned  by a previous call of seekoff or seekpos, but
              there are two special values  which  have  conventional
              meanings:
                   (streampos)0   - the beginning of the stream;
                   (streampos)EOF - error indicator.
    
         int i = sbuf.sync()
              This  function  synchronizes  the  streambuf  with  its
              actual stream of characters.  The details depend on the
              particular derived buffer class.  Generally, any  char-
              acters  in  the put area will be flushed to their final
              destination, and any characters  in  the  input  buffer
              will  be given back to their source, if possible.  This
              generally means that in_avail() and out_waiting()  will
              both  return  zero after a sync.  This function returns
              EOF on any error, zero on success.
    
      Miscellaneous functions
         streambuf* sb = sbuf.setbuf(ptr, len)
              This function logically belongs in the protected inter-
              face, but was placed in the public interface for compa-
              tibility with the original stream package.  This  func-
              tion attempts to use the array of len bytes starting at
              the location pointed to by  ptr  as  the  buffer  area.
              Setting  ptr  to  zero  or len to less than or equal to
              zero requests an unbuffered state.   Depending  on  the
              details of the derived class, it may not be possible to
              honor the request.  This function returns a pointer  to
              the streambuf on success, zero if the request could not
              be honored.
    
    SEE ALSO
         ios.intro(3C++), ios(3C++), sbufprot(3C++),
    
         C++ 4.1 Library Reference Manual:
                 Chapter 4, "The Iostream Library",
    
                 Chapter 5, "Using libC in a Multithreaded Environment."
    
    
    
    


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру