Provided by: libbobcat-dev_5.00.02-2_amd64 bug

NAME

       FBB::SharedBuf - streambuf interfacing to shared memory

SYNOPSIS

       #include <bobcat/sharedbuf>
       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::SharedBuf 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      SharedBuf():
              The default constructor defines a stub SharedBuf 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      SharedBuf(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      SharedBuf(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 (and 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::SharedBuf’s shared  memory  is  deleted.
              The FBB::SharedBuf 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::SharedBuf’s shared memory is deleted. The
              FBB::SharedBuf 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::SharedBuf object interfaces. It can
              also be called to reuse a FBB::SharedBuf object again after calling kill or remove.

       o      FBB::SharedMemory &sharedMemory():
              A reference to the FBB::SharedMemory object  to  which  the  FBB::SharedBuf  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::SharedBuf’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 SharedBuf object
              interfaces.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/sharedbuf - 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_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.00.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).