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

NAME

       FBB::OSharedStream - std::ostream operations on shared memory

SYNOPSIS

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

DESCRIPTION

       This class offers the features of the std::ostream class, operating on shared memory.

NAMESPACE

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

INHERITS FROM

       FBB::OSharedStreambuf (private inheritance),
       std::ostream,
       FBB::SharedEnum__ (cf. sharedmemory(3bobcat) for a description of this last base 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      OSharedStream():
              The default constructor defines a stub a OSharedStream object that cannot immediately be  used  to
              access shared memory. To use it, its member open must first be called.

       o      OSharedStream(size_t  maxSize,  SizeUnit  sizeUnit,  std::ios::openmode  openMode = std::ios::out,
              size_t access = 0600):
              This constructor creates an std::ostream that interfaces to  a  shared  memory  segment  having  a
              capacity of at least maxSize * sizeUnit bytes. By default, the shared memory segment is opened for
              writing. The shared memory’s access  rights  are  defined  by  the  access  parameter,  using  the
              well-known  (chmod(1))  way to define the access rights for the owner, the group and others, using
              octal digits. If construction succeeds the shared memory is ready for use. If construction  fails,
              an FBB::Exception is thrown.

       o      OSharedStreambuf(int id, std::ios::openmode openMode = std::ios::out | std::ios::in):
              This constructor creates an std::istream that connects to a shared memory segment having ID id. If
              construction succeeds the shared memory is ready for use. If construction fails (e.g.,  no  shared
              memory  segment having ID id exists), an FBB::Exception is thrown.  Copy and move constructors are
              not available.

OVERLOADED OPERATORS

              The overloaded move and copy assignment operators are not available.

MEMBER FUNCTIONS

              All members of std::istream and std::ostream and the enum  values  kB,  MB,  and  GB,  defined  by
              FBB::OSharedEnum__ are available.

       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  OSharedStream  object
              interfaces.  This member does not alter the value returned by the stream’s tellp member.

              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
              OSharedStream  object  interfaces  (or at the first offset of the next physical shared memory data
              block, cf. sharedcondition(3bobcat)).  Creating a SharedCondition object does not alter the  value
              returned by the stream’s tellp member.

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

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

       o      void kill():
              Without  locking  the shared memory first,  all shared memory is returned to the operating system.
              The FBB::OSharedStream object is unusable after returning from kill.  Other  processes  that  were
              using the shared memory can continue to do so.

       o      void memInfo(std::ostream &out, char const *end = "\n"):
              Information about the OSharedMemory 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. Following the information about the shaed memory, end is inserted into out.

       o      void open(size_t maxSize, SizeUnit sizeUnit, std::ios::openmode openMode =  std::ios::out,  size_t
              access = 0600):
              This  member  creates  a  shared  memory  segment having a capacity of at least maxSize * sizeUnit
              bytes, and connects the shared memory segment to the FBB::OSharedStream. A matching  close  member
              does  not  exist and is not required. By default, the shared memory segment is opened for reading.
              Different from the open modes used for file streams, creating a shared  memory  stream  with  open
              modes  ios::in  is  OK. In this case the shared memory segment is created and once information has
              been written to the shared memory by another process it can be read. The  shared  memory’s  access
              rights  are  defined  by  the  access parameter, using the well-known (chmod(1)) way to define the
              access rights for the owner, the group and others, using octal digits.  If  opening  succeeds  the
              shared memory is ready for use. If opening fails, an FBB::Exception is thrown.

       o      void open(int id, std::ios::openmode openMode = std::ios::in | std::ios::out):
              This  member  connects  the  FBB::OSharedStream  object to a shared memory segment having ID id. A
              matching close member does not exist and is not required. If opening succeeds the shared memory is
              ready  for  use.  If  opening  fails  (e.g.,  no  shared  memory  segment having ID id exists), an
              FBB::Exception is thrown.

       o      void remove():
              The shared memory is first locked. Next, all shared memory is returned to  the  operating  system.
              The  FBB::OSharedStream  object is unusable after returning from remove. Other processes that were
              using the shared memory can continue to do so.

       o      bool truncate(std::streamsize offset):
              If offset is not exceeding the value returned by seekp(0,  std::ios::end)  this  latter  value  is
              changed  to  offset  and  true is returned. Otherwise false is returned, and the value returned by
              seekp is not altered. If the value returned by tellp exceeded  offset,  tellp’s  return  value  is
              reduced to offset as well.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/osharedstream - defines the class interface

SEE ALSO

       bobcat(7),     chmod(1),    isharedstream(3bobcat),    sharedblock(3bobcat),    sharedcondition(3bobcat),
       sharedmemory(3bobcat)       sharedmutex(3bobcat),       sharedpos(3bobcat),        sharedreadme(7bobcat),
       sharedsegment(3bobcat), sharedstream(3bobcat), sharedstreambuf(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).