Provided by: libbobcat-dev_4.08.02-2build1_amd64 bug

NAME

       FBB::SharedStreambuf - streambuf interfacing to shared memory

SYNOPSIS

       #include <bobcat/sharedstreambuf>
       Linking option: -lpthread -lbobcat

DESCRIPTION

       This  class  implements  a  specialization  of  the  std::streambuf class, allowing stream
       classes   (std::istream,   std::ostream,   FBB::ISharedStream,   FBB::OSharedStream    and
       FBB::SharedStream)  to  perform  I/O  operations  on  shared  memory. FBB::SharedStreambuf
       objects interface to a FBB::SharedMemory objects.

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned  in  this  man-page,  are
       defined in the namespace FBB.

INHERITS FROM

       std::streambuf,  FBB::SharedEnum__  (cf.  sharedmemory(3bobcat)  for  a description of the
       latter class).

SIZEUNIT ENUMERATION

       The enum SizeUnit defines the following symbolic constants:

       o      kB, representing 1024 (2**10) bytes of memory;

       o      MB, representing 1048576 (2**20) bytes of memory;

       o      GB, representing 1073741824 (2**30) bytes of memory

CONSTRUCTORS

       o      SharedStreambuf():
              The  default  constructor  defines  a  stub  SharedStreambuf  object  that   cannot
              immediately  be  used  to  access  shared  memory. Before it can be used by, shared
              stream classes like FBB::SharedStream, its member setMemory must  first  have  been
              called.

       o      SharedStreambuf(size_t  maxSize,  SizeUnit  sizeUnit, std::ios::openmode openMode =
              std::ios::in | std::ios::out, size_t access = 0600):
              This constructor creates a shared memory segment having  a  capacity  of  at  least
              maxSize * sizeUnit bytes.

              By  default, the shared memory segment is opened for reading and writing. Different
              from the open modes used for file streams, creating a  shared  memory  stream  with
              open  modes  ios::in  |  ios::out  is OK. In this case the shared memory segment is
              created and once information has been written to the shared memory it can  also  be
              read again.

              The  shared memory’s access rights are defined by the access parameter, interpreted
              as an octal value, using the well-known (chmod(1)) way to define the access  rights
              for owner, group and others.

              If construction fails, an FBB::Exception is thrown.

       o      SharedStreambuf(int    id,    std::ios::openmode    openMode   =   std::ios::in   |
              std::ios::out):
              This constructor connects to a shared memory segment having ID id.

              Specifying the ios::trunc flag  immediately  clears  the  contents  of  the  shared
              memory.

              An  FBB::Exception  is thrown if construction fails (e.g., no shared memory segment
              having ID id exists), Copy and move constructors are not available.

OVERLOADED OPERATORS

       Overloaded move and copy assignment operators are not available.

MEMBER FUNCTIONS

       All  members  of  std::streambuf  and  the  enum  values  kB,  MB,  and  GB,  defined   by
       FBB::SharedEnum__ are available.

       o      void clear():
              The  shared  memory  is first locked. Next, all shared data segment are returned to
              the operating system, after which the shared  memory  segment  is  unlocked  again.
              Returning  from clear the shared memory The FBB::SharedMemory object is effectively
              re-initialized, with offset and nReadable returning 0.

       o      int id() const:
              The ID of the shared memory segment is returned.

       o      void kill():
              Without locking the shared  memory  the  FBB::SharedStreambuf’s  shared  memory  is
              deleted. The FBB::SharedStreambuf object is unusable after returning from kill.

       o      void memInfo(std::ostream &out):
              Information  about  the  SharedMemory  object  is inserted into the provide ostream
              object. The IDs of the shared segments, their sizes, the maximum number  of  shared
              memory  segments,  the number of bytes that can be read from the shared memory, and
              its actual storage capacity, etc., are displayed. The inserted information  is  not
              terminated by a final newline character.

       o      void remove():
              The  shared  memory  is  locked,  and  the  FBB::SharedStreambuf’s shared memory is
              deleted. The FBB::SharedStreambuf object is unusable after returning from remove.

       o      void setMemory(SharedMemory &&tmp):
              The anonymous temporary SharedMemory object that is passed to setMemory defines the
              new  shared  memory segment to which the FBB::SharedStreambuf object interfaces. It
              can also be called to reuse a FBB::SharedStreambuf object again after calling  kill
              or remove.

       o      FBB::SharedMemory &sharedMemory():
              A  reference  to  the  FBB::SharedMemory  object  to which the FBB::SharedStreambuf
              object interfaces is returned.

PROTECTED MEMBER FUNCTIONS

       o      FBB::SharedCondition        attachSharedCondition(std::ios::off_type        offset,
              std::ios::seekdir origin):
              Returns  an  FBB::SharedCondition(3)  object,  interfacing  to  a  shared condition
              variable located at offset offset (relative to origin) in the  SharedMemory  object
              to which the SharedStreamBuf object interfaces.

              An  FBB::Exception  is  thrown  if  the  FBB::SharedCondition  object  could not be
              constructed.

       o      FBB::SharedCondition createSharedCondition():
              Returns an FBB::SharedCondition(3) object, interfacing to a  newly  created  shared
              condition  variable  which  is  created  at  the current offset of the SharedMemory
              object to which the SharedStream object interfaces (or at the first offset  of  the
              next physical shared memory data block, cf. sharedcondition(3bobcat)).

              An  FBB::Exception  is  thrown  if  the  FBB::SharedCondition  object  could not be
              constructed.

       o      void setOpenMode(std::ios::openmode flag):
              The streambuf’s openmode is changed to the settings defined by flag. This member is
              used  by, e.g., SharedStream::open, to adapt the FBB::SharedStreambuf’s openmode to
              the flags that are passed to open.

       o      FBB::SharedMemory &sharedMemory():
              Returns a reference to the FBB::SharedMemory object to  which  the  SharedStreambuf
              object interfaces.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/sharedstreambuf - defines the class interface

SEE ALSO

       bobcat(7),         chmod(1),        isharedstream(3bobcat),        osharedstream(3bobcat),
       sharedblock(3bobcat),           sharedcondition(3bobcat),            sharedmemory(3bobcat)
       sharedmutex(3bobcat),  sharedpos(3bobcat),  sharedreadme(7bobcat), sharedsegment(3bobcat),
       sharedstream(3bobcat)

BUGS

       Note that by default exceptions thrown from within a std::stream object are caught by  the
       stream  object,  setting  its  ios::failbit  flag.  To  allow exceptions to leave a stream
       object, its exceptions member can be called, e.g., using:

           myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);

DISTRIBUTION FILES

       o      bobcat_4.08.02-x.dsc: detached signature;

       o      bobcat_4.08.02-x.tar.gz: source archive;

       o      bobcat_4.08.02-x_i386.changes: change log;

       o      libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries,  headers  and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This  is  free  software,  distributed  under  the terms of the GNU General Public License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).