I/O Class Descriptions

#include <bsamstr.h>
class bsamstream : public iostream
{
public:
   bsamstream();
   bsamstream(const char *filename,
      int mode,
      const char *keywords = 0,
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   virtual ~bsamstream();
   void open(const char *filename,
      int mode,
      const char *keywords = 0,
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   int find(const char *name);
   int init_directory();
   int delete_member(const char *name);
   int rename_member
     (const char *old_name,
      const char *new_name);
   int stow(const char *name,
      char action = 'R',
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int add_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int replace_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   void close();
   void setbuf(char *buffer,
      size_t length);
   int error_info(bsambuf::error_id& id);
   void clear_error_info();
   void set_user_data(void *user_data);
   void *get_user_data();
   const char *get_ddname();
   const char *get_member();
   bsambuf *rdbuf();
   char dcbrecfm();
   short dcblrecl();
   short dcbblksize();
   DCB_t *getdcb();
} ;
class ibsamstream : public istream
{
public:
   ibsamstream();
   ibsamstream(const char *filename,
      int mode, 
      const char *keywords = 0,
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   virtual ~ibsamstream();
   void open(const char *filename,
      int mode,
      const char *keywords = 0, 
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   int find(const char *name);
   int init_directory();
   int delete_member(const char *name);
   int rename_member
     (const char *old_name,
      const char *new_name);
   int stow(const char *name,
      char action = 'R',
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int add_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int replace_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   void close();
   void setbuf(char *buffer,
      size_t length);
   int error_info(bsambuf::error_id& id);
   void clear_error_info();
   void set_user_data(void *user_data);
   void *get_user_data();
   const char *get_ddname();
   const char *get_member();
   bsambuf *rdbuf();
   char dcbrecfm();
   short dcblrecl();
   short dcbblksize();
   DCB_t *getdcb();
};
class ibsamstream : public istream
{
public:
   ibsamstream();
   ibsamstream(const char *filename,
      int mode,
      const char *keywords = 0,
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   virtual ~ibsamstream();
   void open(const char *filename,
      int mode,
      const char *keywords = 0,
      int willseek = 0,
      bsam_exit_list *exit_list = 0);
   int find(const char *name);
   int init_directory();
   int delete_member(const char *name);
   int rename_member
     (const char *old_name,
      const char *new_name);
   int stow(const char *name,
      char action = 'R',
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int add_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int replace_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   void close();
   void setbuf(char *buffer,
      size_t length);
   int error_info(bsambuf::error_id& id);
   void clear_error_info();
   void set_user_data(void *user_data);
   void *get_user_data();
   const char *get_ddname();
   const char *get_member();
   bsambuf *rdbuf();
   char dcbrecfm();
   short dcblrecl();
   short dcbblksize();
   DCB_t *getdcb();
};

These three classes, defined in the <bsamstr.h> header file, specialize the classes iostream , istream , and ostream for file I/O using a bsambuf . class bsamstream and class obsamstream define an identical set of functions. class ibsamstream omits the set of functions that can change the file.

class bsamstream inherits characteristics from class iostream . class ibsamstream inherits characteristics from class istream . class obsamstream inherits characteristics from class ostream . All three of class bsamstream , class ibsamstream , and class obsamstream inherit characteristics from class ios . See the descriptions of these parent classes for details on functions and operators that are inherited.

Each class defines two constructors.

bsamstream::bsamstream() ibsamstream::ibsamstream() obsamstream::obsamstream(): create an unopened stream of the appropriate type.

bsamstream::bsamstream (const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

ibsamstream::ibsamstream (const char*filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

ibsamstream::ibsamstream (const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

create a stream of the appropriate type, using the DD name (and member name, if present) specified by filename , using the specified mode . The ibsamstream behaves as if ios::in was set in the mode argument, whether or not it was set by the caller. The obsamstream behaves as if ios::out was set in the mode argument, whether or not it was set by the caller.

All of the arguments are identical to the corresponding bsambuf::open arguments. Refer to class bsambuf for a description of these arguments.

If the open fails, ios::badbit is set in the stream's I/O state flags, as described in enum io_state .

class bsamstream , class ibsamstream , and class obsamstream each have one destructor:

virtual bsamstream::~bsamstream() virtual ibsamstream::~ibsamstream() virtual obsamstream::~obsamstream(): close the stream, if opened. If the close fails, ios::failbit is set in the stream's I/O state flags, as described in enum io_state .

bsamstream::open(const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

The following descriptions give the purpose and return type of the member functions, as well as any other appropriate information. Except where otherwise stated, the arguments have the same meaning, format, and use as the bsambuf arguments of the same name and function.

ibsamstream::open(const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

obsamstream::open(const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *exit_list = 0)

create a stream of the appropriate type, using the DDname (and member name, if present) specified by filename and using the specified mode . The ibsamstream constructor behaves as if ios::in was set in the mode argument, whether or not it was set by the caller. The obsamstream constructor behaves as if ios::out was set in the mode argument, whether or not it was set by the caller.

If the open fails, the ios::badbit is set in the stream's I/O state flags, as described in enum io_state .

int bsamstream::find(const char *name) int ibsamstream::find(const char *name) int obsamstream::find(const char *name)

position the file connected to the stream, which must be a PDS, to the start of the member identified by name. name may be specified in either upper- or lowercase. If name is shorter than eight characters, it will be padded on the right with blanks. find returns 0 if the file is successfully positioned or a value other than 0 otherwise.

int bsamstream::init_directory() int obsamstream::init_directory()

invoke the "initialize directory" function of the STOW macro on the file (which must be a PDS) connected to the stream. The value returned is 0 if the function succeeds or is a value other than 0 otherwise.

int bsamstream::delete_member (const char *name)

int obsamstream::delete_member (const char *name)

deletes the PDS member identified by name from the file connected to the stream . name may be specified in either upper- or lowercase. If name is shorter than eight characters, it will be padded on the right with blanks. The value returned is 0 if the member is successfully deleted or is a value other than 0 otherwise.

int bsamstream::rename_member (const char *old_name, const char *new_name)

int obsamstream::rename_member (const char *old_name, const char *new_name)

renames the PDS member identified by old_name to new_name . old_name and new_name may be specified in either upper- or lowercase. If either name is shorter than eight characters, it will be padded on the right with blanks. The value returned is 0 if the member is successfully renamed or is a value other than 0 otherwise.

int bsamstream::stow(const char *name, char action = 'R', int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

int obsamstream::stow(const char *name, char action = 'R', int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

adds or replaces a member or alias in the file connected to the bsambuf . The file must be a PDS. stow returns a value other than 0 if any of the arguments are out of bounds. If stow invokes the STOW macro, with one exception, stow returns the return code from the STOW macro. (This code can also be retrieved via the error_info function.) In general, the STOW macro returns 0 if the requested action succeeded or a value other than 0 otherwise. The exception occurs when action is 'R' and the STOW macro returns 8. This return code from the STOW macro indicates that the member or alias did not previously exist and so was added. In this case, stow returns 0.

If an error occurs, the ios::badbit is set in the stream's I/O state.

int bsamstream::add_member (const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0);

int obsamstream::add_member (const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0);

is equivalent to the stow function when action is 'A'. The arguments and return value are identical to stow .

int bsamstream::replace_member (const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

int obsamstream::replace_member (const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

is equivalent to the stow function when action is 'R'. The arguments and return value are identical to stow .

void bsamstream::close() void ibsamstream::close() void obsamstream::close()

close the connection between the appropriate object and its associated file. Unless an error occurs, all bits in the object's I/O state are set to zero. If the close fails, ios::failbit is set in the stream's I/O state. The close could fail if the call to rdbuf()->close() fails. These functions have no return value.

void bsamstream::setbuf(char *buffer, size_t length)

void ibsamstream::setbuf(char *buffer, size_t length)

void obsamstream::setbuf(char *buffer, size_t length)

call rdbuf()->setbuf(buffer, length) . These functions have no return value.

bsambuf *bsamstream::rdbuf() bsambuf *ibsamstream::rdbuf() bsambuf *obsamstream::rdbuf()

return a pointer to the bsambuf associated with the stream.

int bsamstream::error_info (bsambuf::error_id& id)

int ibsamstream::error_info (bsambuf::error_id& id)

int obsamstream::error_info (bsambuf::error_id& id)

return the return code from the first failed low-level routine. See the table under the description of bsambuf::error_info for a list of values that can be stored in the id argument.

void bsamstream::clear_error_info() void ibsamstream::clear_error_info() void obsamstream::clear_error_info()

set the stored error information to the initial state. If error_info is called in this state, the value of error_id is Enone and the return code is 0.

void bsamstream::set_user_data (void *user_data)

void ibsamstream::set_user_data (void *user_data)

void obsamstream::set_user_data (void *user_data)

stores the value in user_data for retrieval by get_user_data . The value may be any value required by the program. It is ignored by the stream.

void *bsamstream::get_user_data() void *ibsamstream::get_user_data() void *obsamstream::get_user_data()

retrieves the value stored by set_user_data .

void *bsamstream::get_ddname() void *ibsamstream::get_ddname() void *obsamstream::get_ddname()

returns a pointer to the DDname part of the filename of the associated file. The DDname is in uppercase characters.

void *bsamstream::get_member() void *ibsamstream::get_member() void *obsamstream::get_member()

returns a pointer to the member name part of the filename of the associated file. The member name is in uppercase characters. If the filename did not specify a member name, the pointer points to a 0-length string.

DCB_t *bsamstream::getdcb() DCB_t *ibsamstream::getdcb() DCB_t *obsamstream::getdcb()

return a pointer to the DCB associated with the stream.

char bsamstream::dcbrecfm() char ibsamstream::dcbrecfm() char obsamstream::dcbrecfm()

return the value of the DCBRECFM field in the DCB associated with the stream.

short bsamstream::dcblrecl() short ibsamstream::dcblrecl() short obsamstream::dcblrecl()

return the logical record length (LRECL) of the file connected to the stream.

short bsamstream::dcbblksize() short ibsamstream::dcbblksize() short obsamstream::dcbblksize()

return the physical block size (BLKSIZE) of the file connected to the stream.

Provide Formatted File I/O

class bsambuf, class bsam_exit_list

class fstream, ifstream, and ofstream

#include <fstream.h>
class ifstream : public istream
{
public:
   ifstream();
   ifstream(const char *name,
            int mode = ios::in,
            const char *amparms = "",
            const char *am = "");
   virtual ~ifstream();
   void open(const char *name,
             int mode = ios::in,
             const char *amparms = "",
             const char *am = "");
   void close();
   void setbuf(char *p, int len);
   filebuf* rdbuf();
};
class ofstream : public ostream
{
public:
   ofstream();
   ofstream(const char *name,
            int mode = ios::out,
            const char *amparms = "",
            const char *am = "");
   virtual ~ofstream();
   void open(const char *name,
             int mode = ios::out,
             const char *amparms = "",
             const char *am = "");
   void close();
   void setbuf(char *p, int len);
   filebuf* rdbuf();
};
class fstream : public iostream
{
public:
   fstream();
   fstream(const char *name, int mode,
           const char *amparms = "",
           const char *am = "");
   virtual ~fstream();
   void open(const char *name, int mode,
             const char *amparms = "",
             const char *am = "");
   void close();
   void setbuf(char *p, int len);
   filebuf* rdbuf();
};

The three classes contained in the fstream.h header file specialize the classes istream , ostream , and iostream for file I/O. In other words, the streambuf associated with the I/O operations is a filebuf . The functions associated with each of the classes in this header file, class ifstream , class ofstream , and class fstream , are very similar.

class ifstream inherits characteristics from class istream . class ofstream inherits characteristics from

class
ostream

. class fstream inherits characteristics from

class
iostream

. All three of class ifstream , ofstream , and fstream inherit characteristics from class ios . See the descriptions of these parent classes for the details on functions and operators that are inherited.

There are two sets of constructors for

class
ifstream

, class ofstream , and class fstream , as follows:

ifstream::ifstream() ofstream::ofstream() fstream::fstream()

create an unopened stream of the appropriate type.

ifstream::ifstream(const char *name, int mode = ios::in, const char *amparms = " ", const char *am = " ")

ofstream::ofstream(const char *name, int mode = ios::out, const char *amparms = "", const char *am = "")

fstream::fstream(const char *name, int mode, const char *amparms = "", const char *am = "")

create a stream of the appropriate type, named name , using the specified mode . The ifstream constructor behaves as if ios::in was set in the mode argument, whether or not it was set by the caller. The ofstream constructor behaves as if ios::out was set in the mode argument, whether or not it was set by the caller.

An explanation of filename specification, as well as the arguments amparms and am can be found in the SAS/C Library Reference, Volume 1. (Note that the order of the amparms and am , arguments in these constructors is the opposite of the order in which they appear in calls to the C afopen function.) You may also want to refer to the SAS/C Compiler and Library User's Guide.

The available modes are described in enum open_mode . If the open fails, the stream's status is reflected in its I/O state flags, as described in enum io_state .

close the stream, if opened.

class ifstream , class ofstream , and class fstream each have one destructor:

virtual ifstream::~ifstream() virtual ofstream::~ofstream()
virtual fstream::~fstream()

The following descriptions give the purpose and return type of the member functions, as well as any other appropriate information.

void ifstream::open(const char *name, int mode = ios::in, const char *amparms = " ", const char *am = " ")

void ofstream::open(const char *name, int mode = ios::out, const char *amparms = " ", const char *am = " ")

void fstream::open(const char *name, int mode, const char *amparms = "", const char *am = "")

open the named file using the specified mode . ifstream::open() behaves as if ios::in was set in the mode argument, whether or not it was set by the caller. ofstream::open() behaves as if ios::out was set in the mode argument, whether or not it was set by the caller. For fstream objects there is no default open_mode bit set.

The available open modes are described in enum open_mode . An explanation of the arguments amparms and am can be found in the SAS/C Library Reference, Volume 1. (Note that the order of the amparms and am arguments in these functions is the opposite of the order in which they appear in calls to the C afopen function.) You may also want to refer to the SAS/C Compiler and Library User's Guide.

These functions do not have a return value. If an error occurs during the open, the ios::failbit bit is set in the stream's I/O state. Reasons for a failed open include that the file already exists, or that the call to rdbuf()->open() fails.

void ifstream::close() void ofstream::close() void fstream::close()

close the connection between the appropriate object and its associated file. Unless an error occurs, all bits in the object's I/O state are set to zero. The close could fail if the call to rdbuf()->close() fails. These functions have no return value.

void ifstream::setbuf(char *p, int len) void ofstream::setbuf(char *p, int len) void fstream::setbuf(char *p, int len)

call filebuf::setbuf(p,len) . These functions have no return value.

filebuf* ifstream::rdbuf() filebuf* ofstream::rdbuf() filebuf* fstream::rdbuf()

return a pointer to the filebuf associated with the stream.

Provide Buffer and Stream Manipulation

class filebuf

class ios

#include <iostream.h>
class ios
{
public:
/* See the enum format_state, enum
   io_state, enum open_mode, and enum
   seek_dir descriptions for more
   definitions. */

   ios(streambuf *buf);
   virtual ~ios();

   int width();
   int width(int w);

   char fill();
   char fill(char c);

   int precision();
   int precision(int i);

   static unsigned long bitalloc();
   static int xalloc();
   long& iword(int i);
   void*& pword(int i);

   streambuf* rdbuf();

   ostream* tie();
   ostream* tie(ostream *s);
};

The iostream.h header file declares

class
ios

. This class and the classes derived from it provide an I/O interface for inserting information into and extracting information from streambuf . This I/O interface supports both formatted and unformatted information. This description is devoted to those operations used in stream and buffer manipulation.

Several enumerations are defined in class ios ( io_state , open_mode , seek_dir , and the format flags). These enumerations are described in subsequent sections. The open_mode and seek_dir flags are not used directly by the functions in class ios but are used by classes derived from it.

class ios is the parent of all the stream classes. It has no parent class.

class ios defines one constructor:

ios::ios(streambuf *buf): sets up buf as the associated streambuf . If buf is NULL , the effect is undefined.

BUFFER AND STREAM MANIPULATION FUNCTIONS

Here is the class ios destructor:

virtual ios::~ios(): closes the stream.

class ios defines several functions that provide buffer and stream manipulation capabilities. The following list describes these functions.

streambuf* ios::rdbuf()

returns a pointer to the streambuf associated with the ios when it was created.

ostream* ios::tie()

returns the ostream currently tied to the ios , if any; returns NULL otherwise.

ostream* ios::tie(ostream *s)

ties s to the ios and returns the stream previously tied to this stream, if any; returns NULL otherwise.

If the ios is tied to an ostream , then the ostream is flushed before every read or write from the ios . By default, cin , cerr , and clog are tied to cout .

FORMATTING FUNCTIONS

class ios defines several functions that use and set the format flags and variables. class ios also provides functions you can use to define and manipulate your own formatting flags, plus several built-in manipulators that allow you to set various format flags.

Format flag functions

The following list describes some of the functions that use and set the library-supplied format flags. The flags() , setf() , and unsetf() functions and the format flags are described in enum format_state .

int ios::width()

returns an int representing the value of the current field width.

int ios::width(int w)

sets the field width to w and returns an int representing the previous field width value.

The default field width is 0. When the field width is 0, inserters insert only as many characters as necessary to represent the value. When the field width is nonzero, inserters insert at least as many characters as are necessary to fill the field width. The fill character is used to pad the value, if necessary, in this case.

Numeric inserters do not truncate their values. Therefore, if the value being inserted is wider than the field width, the entire value is inserted, regardless of the field width overrun. As you can see, this implies that the field width value is a minimum constraint; there is no way to specify a maximum constraint on the number of characters to be inserted.

The field width variable is reset to 0 after each insertion or extraction. In this sense, the field width serves as a parameter for insertions and extractions.

You can also use the parameterized manipulator, setw , to set the field width.

char ios::fill()

returns a char representing the current fill character.

char ios::fill(char c)

sets the fill character to c and returns a char representing the previous value. The default fill character is a space. You can also set the fill character using the parameterized manipulator, setfill .

int ios::precision()

returns an int representing the current precision value.

int ios::precision(int i)

sets the precision to i and returns an int representing the previous precision. Use this function to control the number of significant digits included in floating-point values. The default precision is six. You can also set the precision using the parameterized manipulator, setprecision .

User-defined format flag functions

class ios includes four functions that you can use to define format flags and variables in addition to those described in enum format_state .

static unsigned long ios::bitalloc(): returns an unsigned long with a single, previously unallocated, bit set. This allows you to create additional format flags. This function returns 0 if there are no more bits available. Once the bit is allocated, you can set it and clear it using the flags() , setf() , and unsetf() functions.
static int ios::xalloc(): returns an int that represents a previously unused index into an array of words available for use as format state variables. These state variables can then be used in your derived classes.
long& ios::iword(int i): returns a reference to the i th user-defined word. i must be an index allocated by ios::xalloc() .
void*& ios::pword(int i): returns a reference to the i th user-defined word. i must be an index allocated by ios::xalloc() . pword() is the same as iword() except that its return type is different.

Refer to the C++ Language System Release 3.0 Library Manual for details on defining and using user-defined format flags.

Built-in manipulators

Manipulators take an ios& , an istream& , or an ostream& and return their argument. The following built-in manipulators are useful with ios objects. stream has type ios& .

stream >> dec and stream << dec: set the conversion base for the stream to decimal (by setting the ios::dec bit and clearing ios::oct and ios::hex ).
stream >> oct and stream << oct: set the conversion base for the stream to octal (by setting the ios::oct bit and clearing ios::dec and ios::hex ).
stream >> hex and stream << hex: set the conversion base for the stream to hexadecimal (by setting the ios::hex bit and clearing ios::dec and ios::oct ).
stream >> ws: extracts whitespace characters.
stream << endl: inserts a newline character and flushes the stream.
stream << ends: inserts a null ( \0 ) character into the stream.
stream << flush: flushes the given ostream object.

In addition, parameterized manipulators are available to operate on ios objects. These include setfill , setprecision , setiosflags , and resetiosflags , described in detail in class IOMANIP .

Provide Buffer and Stream Formatting

class iostream, class istream, class ostream

enum format_state

#include <iostream.h>

class ios
{
public:

/* See the class ios, enum io_state,
   enum open_mode, and enum seek_dir
   descriptions for more definitions. */

   enum {skipws, 

         left,
         right,
         internal,

         dec,
         oct,
         hex,

         showbase,
         showpoint,
         uppercase,
         showpos,

         scientific,
         fixed,

         unitbuf,
         stdio
        };
   static const unsigned long basefield;
   static const unsigned long adjustfield;
   static const unsigned long floatfield;

   unsigned long flags();
   unsigned long flags(unsigned long f);

   unsigned long setf(unsigned long mask);
   unsigned long setf(unsigned long
                      setbits, unsigned
                      long mask);
   unsigned long unsetf(unsigned long
                        mask);
};

The following list describes each format flag in detail.

class ios (defined in the iostream.h header file) provides a format state, which is used by the stream classes to control formatting. The format state is controlled by the format flags, and class ios provides several functions to manipulate these flags. The member functions flags() , setf() , and unsetf() control the majority of formatting. These functions are described further on in this section. Other member functions that have an effect on the format state are fill() , width() , and precision() . These functions are described in the previous class ios description.

In addition to the predefined format flags, users can create their own user-defined format flags. This is described in the previous class ios description, under "User-defined format flag functions".

FORMAT FLAGS

skipws

skips whitespace on input. This flag applies only to scalar extractions. If skipws is not set, whitespace is not skipped.

To protect against looping, zero-width fields are considered a bad format. Therefore, if the next character is whitespace and skipws is not set, arithmetic extractors signal an error. skipws is set by default.

padding flags

control the padding of formatted values. There are three of them:

left: causes output to be left-adjusted.
right: causes output to be right-adjusted. This is the default if none of the padding bits is set. right is set by default.
internal: causes padding to occur between the sign or base indicator and the value.

These padding flags are grouped together by the member adjustfield . To set the fill character, use the fill() function. To control the width of formatted items, use the width() function.

conversion base flags

control the conversion base of values, as follows:

`dec`	indicates the conversion base is decimal. This is the default for input if none of the conversion base flags is set. `dec` is set by default.
`oct`	indicates the conversion base is octal.
`hex`	indicates the conversion base is hexadecimal.

These conversion base flags are grouped together by the member basefield .

Although decimal is the default conversion base for insertions (if none of these flags is set), the default conversion base for extractions follows the C++ lexical conventions for integral constants. You can also use the built-in manipulators dec , oct , and hex to control the conversion base. These manipulators are described in the previous class ios description.

showbase

causes the base indicator to be shown in the output. This form of output follows the C++ lexical conventions for integral constants. showbase is not set by default.

showpoint

causes the output to include any trailing zeros and decimal points resulting from floating-point conversion. showpoint is not set by default.

uppercase

causes uppercase letters to be used in output. For example, an X is used instead of x in hexadecimal output, and an E is used instead of e in scientific notation. uppercase is not set by default.

showpos

causes a + sign to be added to the decimal conversion of positive integers. showpos is not set by default.

floating-point flags

control the format of floating-point conversions, as follows:

scientific

causes the value to be converted using scientific notation. In this form, there is one digit preceding the decimal point, and the number of digits after the decimal point is equal to the precision (set with the precision() function). The default precision is six. An e (or E if uppercase is set) precedes the exponent.

fixed

causes the value to be converted to decimal notation. The precision of the value is controlled with the precision() function. The default precision is six.

If neither scientific nor fixed is set, the value is converted to one or the other format, according to the following rules:

If the exponent resulting from the conversion is less than -4 or greater than the precision, scientific notation is used.
Otherwise, fixed notation is used.

Unless showpoint is set, trailing zeros are removed from the value, regardless of the format. A decimal point appears in the value only if it is followed by a digit. These flags are grouped together by the member floatfield . They are not set by default.

unitbuf

causes the stream to be flushed after an insertion. unitbuf is not set by default.

stdio

causes the standard C output files stdout and stderr to be flushed after an insertion. stdio is not set by default.

FORMATTING FUNCTIONS

The following functions can be used to turn format flags on and off.

unsigned long ios::flags()

returns an unsigned long representing the current format flags.

unsigned long ios::flags (unsigned long f)

sets (turns on) all the format flags specified by f and returns an unsigned long representing the previous flag values.

unsigned long ios::setf (unsigned long mask)

sets (turns on) only those format flags that are set in mask and returns an unsigned long representing the previous values of those flags. You can accomplish the same task by using the parameterized manipulator, setiosflags .

unsigned long ios::setf (unsigned long setbits, unsigned long mask)

turns on or off the flags marked by mask according to the corresponding values specified by setbits and returns an unsigned long representing the previous values of the bits specified by mask . The EXAMPLES section provides an example of using this function.

Using setf(0, mask) clears all the bits specified by field . You can accomplish the same task by using the parameterized manipulator resetiosflags .

unsigned long ios::unsetf (unsigned long mask)

clears the format flags specified by mask and returns an unsigned long representing the previous flag values.

EXAMPLES

The setf() function is used to change format flags. For example, if you want to change the conversion base in an ios object called s , you could use the following expression:

s.setf(ios::hex, ios::basefield)

In this example, ios::basefield represents the conversion base bits you want to change, and ios::hex is the new value.

To set a flag that is not part of a field, use setf() with a single argument, as in the following example, which sets the skipws flag:

s.setf(ios::skipws)

To clear the skipws flag, use unsetf() :

s.unsetf(ios::skipws)

As another example of using setf() , suppose you want to clear in your ios object s all the bits specified by the variable clearbits . You could use the following expression to accomplish this:

s.setf(0, clearbits)

enum io_state

Provide Stream I/O State

#include <iostream.h>

class ios
{
public:
   enum io_state {goodbit = 0,
                  eofbit,
                  failbit, 
                  badbit 
                 };

/* See the class ios, enum format_state,
   enum open_mode, and enum seek_dir
   descriptions for more definitions. */

   int rdstate();
   int eof();
   int fail();
   int bad();
   int good();
   void clear(int i = 0);

   operator void*();
   int operator !();
};

The following functions use and manipulate the values of the I/O state flags.

class ios (defined in the iostream.h header file) defines io_state flags that represent the internal state of an ios object. Each flag has a value that can be set or reset independently for an ios object. Note that goodbit is not a flag but rather a symbolic name for the condition in which no flags are set. The functions such as rdstate() and eof() use and manipulate the I/O state flags.

I/O STATE FLAGS

A stream is in an unusual state (error or EOF) if any of the I/O state flags are set for the stream. If none of the flags are set, the stream is in the normal (nonerror) state. The meanings of the io_state enumerators are as follows:

`goodbit`	is not a flag. It is a symbolic name for the condition in which no flags are set.
`eofbit`	indicates the end of file has been encountered. If the stream is repositioned after `eofbit` is set, the bit is cleared.
`failbit`	indicates an error other than an I/O error, such as an error in formatting. Once the `failbit` bit is cleared, I/O can usually continue. `failbit` is also set if an operator or member function fails because no more characters can be extracted.
`badbit`	indicates an I/O operation failed. Do not continue I/O operations after this bit is set.

I/O STATE FUNCTIONS

class ios also provides several functions that use or manipulate the I/O state flags. In addition to the I/O state functions, class ios also defines two operators that allow you to check the I/O state of an ios object.

int ios::rdstate(): returns the current I/O state.
int ios::eof(): returns the value of eofbit if eofbit is set; otherwise, returns 0.
int ios::fail(): returns the value of failbit if failbit is set; otherwise, returns 0.
int ios::bad(): returns the value of badbit if badbit is set; otherwise, returns 0.
int ios::good(): returns a nonzero value if no bits are set in the stream's I/O state; otherwise, returns 0.
void ios::clear(int i = 0): sets the stream's I/O state to i . The default value for i is 0. clear() has no return value.

The following two operators are useful when checking the I/O state of an ios object.

ios::operator void*(): converts an ios object to a pointer. If no bits are set in the stream's I/O state, this operator returns a pointer value that is not null. If failbit or badbit is set, the operator returns 0.
int ios::operator !(): converts an ios object to 0 if no bits are set in the stream's I/O state, or to a nonzero value if any bits are set in the stream's I/O state.

enum open_mode

Provide Buffer and Stream Open Modes

#include <iostream.h>

class ios
{
public:
/* See the class ios, enum format_state,
   enum io_state, and enum seek_dir
   descriptions for more definitions. */

   enum open_mode {in, 
                   out,
                   ate,
                   app,
                   trunc,
                   nocreate,
                   noreplace,
                   binary
                  };
};

Provide Buffer and Stream Seeking

The open_mode enumeration is defined in iostream.h . This enumeration defines a number of flags that can be used when creating or opening a stream to specify attributes of the stream. You can specify several attributes simultaneously by using the OR operator to combine them. For example, to specify both the out and binary flags, use ios::out|ios::binary .

Only the ios::ate and ios::app flags are meaningful for string streams, such as strstream objects. See the description of class strstream , class istrstream , and class ostrstream for information on how these flags are used with these classes.

The following list describes the meaning of the open_mode flags for the file-oriented stream classes:

in: means access the file for input.
out: means access the file for output. If the file already exists, it is truncated unless one of ios::in , ios::ate , or ios::app is also specified.
ate: means to position the file to the end of the file when the file is opened.
app: means to access the file in append mode. In append mode, each output operation to the file causes the file to be positioned to the end before writing.
trunc: means to truncate the file (making it empty) when it is opened. ios::trunc has no effect if the file does not yet exist.
nocreate: means the open fails if the file to be opened does not exist.
noreplace: means the open fails if the file already exists.
binary: means to access the file in binary mode. If ios::binary is not specified, the file is accessed in text mode. See the SAS/C Library Reference, Volume 1 for more information on the differences between text mode and binary mode.

enum seek_dir

#include <iostream.h>

class ios
{
public:

/* See the class ios, enum format_state,
   enum open_mode, and enum open_mode
   descriptions for more definitions. */

   enum seek_dir {beg, cur, end};
};

Provide Bidirectional Stream

When you perform a seek on a stream, you must specify the starting point for the seek. class ios (defined in the iostream.h header file) provides the seek_dir flags to control seeking. The following list describes these flags:

`beg`	means the seek is relative to the beginning of the stream.
`cur`	means the seek is relative to the current position of the stream.
`end`	means the seek is relative to the end of the stream.

class iostream

#include <iostream.h>
class iostream : public ostream,
                 public istream
{
public:
   iostream(streambuf *buf);
};

The iostream.h header file also provides class iostream , which is both an istream and an ostream. class iostream includes all the operations of both subclasses. It adds only a constructor of its own.

class iostream inherits characteristics from both class istream and class ostream . See the descriptions of these parent classes for the details on functions and operators that are inherited.

class iostream defines one constructor:

iostream::iostream(streambuf *buf): sets up buf as the associated streambuf . If buf is NULL , the effect is undefined.

Provide for Stream Extraction

class ios , class istream , class ostream

class istream

#include <iostream.h>

class istream : virtual public ios
{
public:
   istream(streambuf *buf);

   virtual ~istream();

   int ipfx(int need = 0);

   istream& operator >>(char *str);
   istream& operator >>(unsigned char *str);
   istream& operator >>(signed char *str);

   istream& operator >>(char& c);
   istream& operator >>(unsigned char& c);
   istream& operator >>(signed char& c);

   istream& operator >>(short& sh);
   istream& operator >>(unsigned short& sh);

   istream& operator >>(int& i);
   istream& operator >>(unsigned int& i);

   istream& operator >>(long& l);
   istream& operator >>(unsigned long& l);

   istream& operator >>(float& f);
   istream& operator >>(double& d);
   istream& operator >>(long double& ld);

   istream& operator >>(streambuf *buf);

   istream& operator >>(istream&(*f)
                       (istream&));
   istream& operator >>(ios&(*f)(ios&));

   istream& get(char *str, int len,
                char delim = '\n');
   istream& get(unsigned char *str,
                int len,
                char delim = '\n');
   istream& get(signed char *str,
                int len,
                char delim = '\n');
   istream& get(signed char& c);
   istream& get(unsigned char& c);
   istream& get(char& c);
   istream& get(streambuf& sb,
                char delim = '\n');

   int get();

   istream& getline(char *str, int len,
                    char delim = '\n');
   istream& getline(unsigned char *str,
                    int len,
                    char delim = '\n');

   istream& getline(signed char *str,
                    int len,
                    char delim = '\n');

   istream& ignore(int n = 1,
                   int delim = EOF);

   istream& read(char *str, int n);
   istream& read(unsigned char *str,
                 int n);
   istream& read(signed char *str,
                 int n);

   int gcount();
   int peek();

   istream& putback(char c);
   int sync();

   istream& seekg(streampos pos);
   istream& seekg(streamoff offset,
                  seek_dir place);

   streampos tellg();
};

istream& ws(istream&);

class istream is defined in the iostream.h header file and is the base class for those stream classes that support only input. It includes all the basic extraction functions (formatted input) on fundamental C++ types, as well as a number of unformatted input functions and several functions that enable you to move the get pointer. It also includes one manipulator. These members are described in the following sections.

class istream inherits characteristics from class ios . See the description of this parent class for the details on functions and operators that are inherited.

istream::istream(streambuf *buf)

class istream defines one constructor:

initializes an istream and associates a

streambuf with it.

INPUT PREFIX FUNCTION

Here is the class istream destructor:

virtual istream::~istream(): closes the istream .

class istream defines an input prefix function that performs those operations that must be done before each formatting operation. This function is defined as follows:

int istream::ipfx(int need = 0);

If any I/O state flags are set for the istream , this function returns 0 immediately. If necessary, it flushes the ios (if any) tied to this istream . Flushing is necessary if need is 0 or if there are less than need characters available for input.

If ios::skipws is set and need is 0, then this function causes any leading white space in the input to be skipped. If an error occurs during this skipping, ipfx() returns 0. If no errors have occurred, this function returns 1.

This function is called by all formatted extraction operations and should be called by user-defined extraction operators unless the first input operation used by the user-defined extraction operator is a formatted extraction. For user-defined operations, ipfx() should be called with the argument equal to 0.

FORMATTED INPUT FUNCTIONS

The functions named operator >> are called extraction operators. They are formatted input functions. They each call the input prefix function ipfx(0) and do nothing else if it returns 0. If ipfx(0) does not return 0, the formatted input functions extract leading characters from the associated streambuf according to the type of their argument and the formatting flags in the ios . They all return the address of the istream .

Errors during extraction are indicated by setting the appropriate I/O state flags for the stream, as follows:

ios::failbit: means that the actual input characters did not match the expected input format.
ios::badbit: means that an error occurred during extraction of characters from the streambuf .

Here are the functions.

istream& istream::operator >>(char *str)

istream& istream::operator >>(unsigned char *str)

istream& istream::operator >>(signed char *str)

extract characters up to the next white space character. The terminating white space character is not extracted. If width() is nonzero, these functions extract no more than width() - 1 characters and reset width() to 0. These functions add a terminating null character, even if an error occurs during extraction.

istream& istream::operator >>(char& c)

istream& istream::operator >>(unsigned char& c)

istream& istream::operator >>(signed char& c)

extract a single character and store it in the argument.

istream& istream::operator >>(short& sh)

istream& istream::operator >>(unsigned short& sh)

istream& istream::operator >>(int& i)

istream& istream::operator >>(unsigned int& i)

istream& istream::operator >>(long& l)

istream& istream::operator >>(unsigned long& l)

extract a number and store it in the argument. There may be a leading sign character (+ or -). If any of ios::dec , ios::oct , or ios::hex is set in the formatting state, characters are extracted and converted according to the bit that is set. If none of these bits is set, then these functions expect any of the following formats:

0x hhh

0X hhh

0 ooo

ddd

Extraction stops when it reaches an unacceptable character. The acceptable characters are

0-7: for octal conversion
0-9: for decimal conversion
0-9, a-f, and A-F: for hexadecimal conversion.

ios::failbit is set if no digits are found.

istream& istream::operator >>(float& f)

istream& istream::operator >>(double& d)

istream& istream::operator >>(long double& ld)

extract a floating-point number and store it in the argument. The expected input format is an optional sign, followed by a decimal mantissa (optionally including a decimal point), followed by an optional floating-point exponent. The exponent may contain either an uppercase or a lowercase E and may have a + or - following the E. Extraction stops when EOF is encountered, or when a character is read that cannot continue the previous input in a valid manner. ios::failbit is set if there are no digits to extract or if the format is not correct.

istream& istream::operator >>(streambuf *buf)

extracts all characters from the istream and inserts them into the streambuf . Extraction stops when no more characters can be obtained from the istream .

istream& istream::operator >> (istream& (*f) (istream&))

istream& istream::operator >> (ios& (*f) (ios&))

are for support of simple manipulators. Although these operators resemble an extraction in appearance, they are used to manipulate the stream rather than to extract characters from it. The argument to either of these operators is a manipulator function that modifies its ios or istream argument in some manner.

UNFORMATTED INPUT FUNCTIONS

The following functions are the unformatted input functions. They each call ipfx(1) first and do nothing else if 0 is returned.

istream& istream::get(char *str, int len, char delim = '\n')

istream& istream::get(unsigned char *str, int len, char delim = '\n')

istream& istream::get(signed char *str, int len, char delim = '\n')

extract up to len - 1 characters. Extraction stops when a delim character is extracted, when no more characters are available, or when len - 1 characters have been found. These functions store a terminating null character in the array. ios::failbit is set only if no characters at all were extracted.

istream& istream::getline(char *str, int len, char delim = '\n')

istream& istream::getline (unsigned char *str, int len, char delim = '\n')

istream& istream::getline (signed char *str, int len, char delim = '\n')

behave like the get() functions, except that the terminating delim character (if found) is extracted. A terminating null character is always stored in the array.

istream& istream::get(streambuf& sb, char delim = '\n')

extracts characters up to the next delim character or EOF and inserts them into sb . delim is not extracted or inserted. ios::failbit is set if an error occurs while inserting into sb .

istream& istream::get(signed char& c) istream& istream::get(unsigned char& c) istream& istream::get(char& c)

extract a single character. ios::failbit is set if no characters can be extracted.

int istream::get()

extracts a single character and returns it. EOF is returned if no characters can be extracted. ios::failbit is never set.

istream& istream::ignore(int n = 1, int delim = EOF)

extracts up to the next n characters or up to the next delim character. ios::failbit is never set.

istream& istream::read(char *str, int n)

istream& istream::read(unsigned char *str, int n)

istream& istream::read(signed char *str, int n)

extract the next n characters and store them into the array pointed to by s .

ios::failbit

is set if fewer than n characters can be extracted.

OTHER MEMBER FUNCTIONS

class istream includes several other functions, as follows:

int istream::gcount(): returns the number of characters extracted by the last unformatted extraction function. Formatted extraction functions may change the value of this function in unexpected ways.
int istream::peek(): returns EOF if ipfx(1) returns 0 or if no characters remain to be extracted. Otherwise it returns the next character in the stream without extracting it.
istream& istream::putback(char c): does nothing if any bits are set in the stream's I/O state. If no bits are set in the stream's I/O state, this function pushes back the character c so it will be the next character extracted. c must be the same as the last character extracted from the istream. ios::badbit is set if the streambuf cannot push c back.
int istream::sync(): calls sync() on the associated streambuf . This function returns whatever the streambuf::sync() call returned.
istream& istream::seekg(streampos pos)
istream& istream::seekg(streamoff offset, seek_dir place): move the get pointer of the associated streambuf.pos is a value returned by a previous call to tellg(). offset and place are explained in the streambuf::seekoff() .
streampos istream::tellg(): returns the current streampos of the get pointer of the associated streambuf .

MANIPULATORS

The following function is a manipulator. It is intended to be used with the extractors to manipulate the stream in a specified way. This manipulator does nothing if any of the stream's I/O state flags are set. It signals an error by setting flags in the stream's I/O state. It returns its argument.

istream& ws(istream&);: skips over any white space in the stream.

Provide for Stream Insertion

class ios, class iostream, class ostream

class ostream

#include <iostream.h>

class ostream : virtual public ios
{
public:
   ostream(streambuf *buf);
   virtual ~ostream();

   int opfx();

   void osfx();

   ostream& operator <<(char c);
   ostream& operator <<(signed char c);
   ostream& operator <<(unsigned char c);

   ostream& operator <<(const char *str);
   ostream& operator <<(const unsigned
                        char *str);
   ostream& operator <<(const signed
                        char *str);

   ostream& operator <<(short sh);
   ostream& operator <<(unsigned short sh);

   ostream& operator <<(int i);
   ostream& operator <<(unsigned int i);

   ostream& operator <<(long l);
   ostream& operator <<(unsigned long l);

   ostream& operator <<(float f);
   ostream& operator <<(double d);

   ostream& operator <<(void *vp);

   ostream& operator <<(streambuf *buf);

   ostream& operator <<(ostream&(*f)
                       (ostream&));
   ostream& operator <<(ios&(*f)(ios&));

   ostream& put(char c);

   ostream& write(const char *str, int n);
   ostream& write(const signed char *str,
                  int n);
   ostream& write(const unsigned char *str,
                  int n);
   ostream& flush();

   streampos tellp();

   ostream& seekp(streampos pos);
   ostream& seekp(streamoff offset,
                  seek_dir place);
};
ostream& endl(ostream&);
ostream& ends(ostream&);
ostream& flush(ostream&);

class ostream is declared in the iostream.h header file and is the base class for those classes that support only output. It includes all the basic insertion operators (formatted output) on fundamental C++ types, as well as a number of unformatted output functions and functions designed to change the stream position. In addition, some output manipulators are defined for use with this class.

class ostream inherits characteristics from class ios . See the description of this parent class for the details on functions and operators that are inherited.

class ostream defines one constructor:

ostream::ostream(streambuf *buf): initializes an ostream and associates a streambuf with it.

PREFIX AND SUFFIX OUTPUT FUNCTIONS

Here is the class ostream destructor:

virtual ostream::~ostream(): closes the ostream.

Certain operations are defined to happen either before or after formatted output through a ostream . The prefix operations are done by ostream::opfx() and the suffix operations are done by ostream::osfx() .

int ostream::opfx()

performs prefix operations for an ostream . This function returns 0 and does nothing else if any bits in the stream's I/O state are set; it returns 1 otherwise. If the ostream is tied (see tie() ) to another, the other stream is flushed (see flush() ).

By convention, opfx() is called before any formatted output operation on a stream. If it returns 0 (meaning one or more bits are set in the stream's I/O state), the output operation is not performed. Each of the built-in inserters follows this convention. User-defined formatted output functions should also follow this convention by calling this function and checking the return code before doing any output.

void ostream::osfx()

performs suffix operations on the stream. If ios::unitbuf is set, this ostream is flushed. If ios::stdio is set, cout and cerr are flushed. This function should be called at the end of any formatted output function that does unformatted output on the ostream . It need not be called if the last output operation on the ostream was formatted.

FORMATTED OUTPUT FUNCTIONS

The functions named operator << are called inserters (because they insert values into the output stream). All inserters are formatted output operations and as such follow the formatted output conventions mentioned previously.

All of the inserters do the following: First, they call opfx() , and if it returns 0, they do nothing else. If there is no error, they then convert the input argument to a converted value (a sequence of characters), based on the argument's type and value and on the formatting flags set for the stream. The rules for construction of the converted value are given here for each inserter.

Once a converted value has been determined, it is copied, possibly with the addition of fill characters, to an output field. The characters of the output field are then inserted into the stream's buffer. The ios::width() function for the stream determines the minimum number of characters in the output field. If the converted value had fewer characters, fill characters (defined by the value of ios::fill() for the stream) are added to pad out the field. The placement of fill characters is as follows::

ios::right: places the converted value in the rightmost portion of the field (leading padding).
ios::left: places the converted value in the leftmost portion of the field (trailing padding).
ios::internal: places the sign and base indicators of the converted value in the leftmost portion of the field and the remainder in the rightmost portion (internal padding).

Note that truncation cannot occur when copying the converted value to an output field, regardless of the value of width() .

Once the converted value is constructed and the field is padded to be at least ios::width() characters wide, ios::width() is reset to 0 and osfx() is called. All inserters indicate errors by setting I/O state flags in the ostream , as necessary. Inserters always return a reference to their ostream argument.

Here are the formatted output functions.

ostream& ostream::operator <<(char c)

ostream& ostream::operator <<(signed char c)

ostream& ostream::operator <<(unsigned char c)

convert the argument to the char c .

ostream& ostream::operator <<(const char *str)

ostream& ostream::operator <<(const unsigned char *str)

ostream& ostream::operator <<(const signed char *str)

convert the argument to a sequence of chars , up to but not including a ' \0 ' character, pointed to by str .

ostream& ostream::operator <<(short sh)

ostream& ostream::operator <<(unsigned short sh)

ostream& ostream::operator <<(int i)

ostream& ostream::operator <<(unsigned int i)

ostream& ostream::operator <<(long l)

ostream& ostream::operator <<(unsigned long l)

convert the value of the argument to a sequence of digits, preceded by a leading ' - ' if the argument is negative.

If the following format flags within the ostream are set, they affect the converted value as follows:

ios::showpos

causes a leading ' + ' to be included in the converted value if the value is positive.

ios::dec , , ios::oct , and ios::hex

determine the base used for the converted value.

ios::showbase

causes the converted value to indicate the appropriate base as follows:

`decimal`	makes no change to the converted value.
`octal`	prefixes the converted value with a single ' `0` ' digit. If the value is 0, there is only one zero digit.
`hexadecimal`	prefixes the converted value with ' `0x` '. If `ios::uppercase` is set, a leading ' `0X` ' is used instead.

If both a sign representation (+ or -) and a base representation appear in the converted value, the sign appears first.

ostream& ostream::operator <<(float f)

ostream& ostream::operator << (double d)

convert the argument to a character representation of its value in one of two formats:

fixed notation (' ± ddd.ddd ')
scientific notation (' ± d.ddde± dd ').

These formats are described in detail in enum format_state . The format of the converted value is affected by the settings of the following format flags:

ios::fixed or ios::scientific: determines the overall representation format. If neither is set, then the overall format is scientific if the exponent is less then -4 or greater than the precision. Fixed notation is chosen otherwise.
ios::showpoint: causes the decimal point to be shown, followed by at least one digit. If showpoint is not set and all digits after the decimal point are zero, these digits and the decimal point are dropped.
ios::uppercase: causes the ' e ' in scientific notation to be ' E ' instead.
ios::showpos: causes a leading '+' to be output for positive values.

ostream& ostream::operator << (void *vp)

converts the value of the pointer vp to an unsigned long and represents it as if ios::hex and ios::showbase were set.

ostream& ostream::operator << (streambuf *buf)

fetches all the characters in buf and inserts them into the output stream, provided no bits are set in buf 's I/O state. No padding is done. If any bits are set in buf 's I/O state, this function returns immediately.

ostream& ostream::operator << (ostream&(*f) (ostream&))

ostream& ostream::operator << (ios&(*f)(ios&))

are for support of simple manipulators. Although these operators resemble an insertion in appearance, they are used to manipulate the stream rather than to insert characters into it. The argument to either of these operators is a manipulator function that modifies its ios or ostream argument in some manner.

UNFORMATTED OUTPUT FUNCTIONS

The following functions are for support of unformatted output to a stream. Because they are unformatted operations they do not call opfx() and osfx() ; however, these functions do check to see whether any I/O state flags are set for the ostream and take no further action if any are found. All inserters indicate errors by setting I/O state flags in the ostream . Each of these functions returns a reference to its argument ostream .

ostream& ostream::put(char c): inserts its argument into the stream.
ostream& ostream::write(const char *str, int n)
ostream& ostream::write(const signed char *str, int n)
ostream& ostream::write(const unsigned char *str, int n): insert n characters starting at str into the stream. The characters are treated as plain chars independent of their actual type. The null character is treated the same as any other character.

OTHER MEMBER FUNCTIONS

The following functions are also members of class ostream .

ostream& ostream::flush(): calls rdbuf()->sync() . For more information, refer to the description of streambuf::sync() .
streampos ostream::tellp(): returns the stream's current put pointer position. For more information, refer to the descriptions of streambuf::seekoff() and streambuf::seekpos() .
ostream& ostream::seekp(streampos pos)
ostream& ostream::seekp(streamoff offset, seek_dir place): reposition the stream's put pointer. For more information, refer to the descriptions of streambuf::seekoff() and streambuf::seekpos() .

MANIPULATORS

The following functions are called manipulators. They are intended to be used with the inserters to manipulate the stream in specified ways. These manipulators do nothing if any of the stream's I/O state flags are set. They signal errors by setting flags in the stream's I/O state. They each return their argument.

ostream& endl(ostream&)

inserts a ' \n ' character into the stream. Here is an example:

#include <iostream.h>

float mynum=3.2;
   // Writes "mynum is:" and the value
      of mynum on one line.
cout << "mynum is: " << mynum << endl;

ostream& ends(ostream&)

inserts a ' \0 ' character into the stream. Here is an example, using a strstream :

#include <iostream.h>
strstream mystream;
float mynum=3.2;

   // Writes mynum to mystream.
mystream << "mynum is: " << mynum <<
   ends;

ostream& flush(ostream&)

calls ostream.flush() .

Provide Formatted I/O in a Mixed C and C++ Environment

class ios, class iostream, class istream

class stdiostream

#include <stdiostream.h>

class stdiostream : public iostream
{
public:
   stdiostream(FILE *file);

   FILE* stdiofile();

   stdiobuf* rdbuf();
};

class stdiostream is declared in the stdiostream.h header file. It provides iostream access to an external file accessed by C functions using the ANSI standard I/O interfaces declared in stdio.h . Use of class stdiostream enables a program to use stdio output and C++ iostream output in the same output file. Similarly, class stdiostream enables your program to use stdio input and C++ iostream input to process the same input file.

class stdiostream inherits characteristics from class iostream , which in turn inherits characteristics from

class
istream

, class ostream , and class ios . See the descriptions of these parent classes for the details on functions and operators that are inherited.

class stdiostream has one constructor:

stdiostream::stdiostream(FILE *file): creates a stream from the open FILE* file . The constructor assumes that the file is open.

The following descriptions give the purpose and return type of the member functions, as well as any other appropriate information.

stdiostream::FILE* stdiofile(): returns the FILE* associated with this stream.
stdiobuf* stdiostream::rdbuf(): returns a pointer to the stdiobuf associated with the stream.

Mark a Stream Location

class stdiobuf

class streampos

#include <iostream.h>

class streampos
{
public:
   streampos();
   streampos(long n);
   operator long();
   fpos_t* fpos();
};

class streampos is declared in the iostream.h header file and is used to record or specify a position in a stream. This class is for use only with streams that support seeking.

Most streampos values are similar to C fpos_t values; that is, they record file position values in a way private to the implementation. Because these values are probably not useful for user-defined stream classes, it is also possible to create integral-valued streampos objects. Note that integral-valued streampos objects probably are not useful for positioning fstream or stdiostream objects.

This class defines two constructors:

streampos::streampos()

creates a streampos object with an unknown value.

streampos::streampos(long n)

creates a streampos object from the value n . All kinds of stream buffers support the following values of n :

streampos(0): indicates the beginning of the stream.
streampos(EOF): indicates the end of the stream.

strstream objects created from other values of n are not useful for positioning fstream or stdiostream objects.

This class defines two member functions:

streampos::operator long(): reduces the value of the streampos to a long integer. The value of long(streampos(long_val)) is defined to be equal to long_val . The result of converting a streampos not constructed from a long is undefined.
fpos_t* streampos::fpos(): returns a pointer to an fpos_t contained in the streampos . This fpos_t contains a valid value only if this streampos was returned from a call to seekoff() or seekpos() on a filebuf or stdiobuf object.

class strstream, istrstream, and ostrstream

Provide Formatted String I/O

#include <strstream.h>

class istrstream : public strstreambuf,
                   public istream
{
public:
   istrstream(char *str);
   istrstream(char *str, int size);
   ~istrstream( );
   strstreambuf* rdbuf ( );
};

class ostrstream : public strstreambuf,
                   public ostream
{
public:
   ostrstream(char *str, int size,
              int mode = ios::out);
   ostrstream( );
   ~ostrstream( );

   char* str( );
   int pcount ( );
   strstreambuf* rdbuf( );
};

class strstream : public strstreambuf,
                  public iostream
{
public:
   ostrstream(char *str, int size,
              int mode = ios::out);
   ostrstream( );
   ~ostrstream( );

   char* str( );
   int pcount( );
   strstreambuf* rdbuf( );
};

class strstream : public strstreambuf,
                  public iostream
{
public:
   strstream(char *str, int size,
             int mode = ios::out);
   strstream( );
   ~strstream( );

   char* str( );
   int pcount( );
   strstreambuf* rdbuf( );
};

class strstream and its associated classes class istrstream and class ostrstream are declared in the strstream.h header file. These classes support string (array) I/O. They do this by customizing the I/O operations defined in the base classes istream , ostream , and iostream .

class istrstream inherits characteristics from class istream . class ostrstream inherits characteristics from

class
ostream

, and class strstream inherits characteristics from

class
iostream

. All three of class istrstream , ostrstream , and strstream inherit characteristics from class ios . See the descriptions of these parent classes for the details on functions and operators that are inherited.

class strstream , class istrstream , and class ostrstream each have two constructors. For a discussion of dynamic mode versus static mode streams, see class strstreambuf .

istrstream::istrstream(char *str): creates a static mode istrstream such that extraction operations on the stream will fetch the characters of str , up to the terminating ' \0 '. str must be null-terminated. The ' \0 ' character is not fetched. Seeks are allowed within the array.
istrstream::istrstream(char *str, int size): creates a static mode istrstream such that extraction operations on the stream will fetch characters from the array starting at str and extending for size bytes. Seeks are allowed within the array.
ostrstream::ostrstream(char *str, int size, int mode = ios::out): creates a static mode ostrstream referencing an area of size bytes starting at the character pointed to by str . The get pointer is positioned at the beginning of the array. The put pointer is also positioned at the beginning of the array unless either the ios::ate or ios::app bit is set in mode ; if either of these bits is set, the put pointer is positioned at the space that contains the first null character. Seeks are allowed anywhere within the array.
ostrstream::ostrstream(): creates a dynamic mode ostrstream . This involves dynamically allocating space to hold stored characters. Seeks are not allowed.
strstream::strstream(char *str, int size, int mode = ios::out): creates a static mode strstream referencing an area of size bytes starting at the character pointed to by str . The get pointer is positioned at the beginning of the array. The put pointer is also positioned at the beginning of the array unless either the ios::ate or ios::app bit is set in mode ; if either of these bits is set, the put pointer is positioned at the space that contains the first null character.
strstream::strstream(): creates a dynamic mode strstream . This involves allocating space to hold stored characters. Seeks are not allowed. The get pointer is positioned at the beginning of the array.

class istrstream , class ostrstream , and class strstream each have one destructor:

istrstream::~istrstream() ostrstream::~ostrstream() strstream::~strstream(): closes the stream. For dynamic stream objects, closing means delete the array, unless it has been frozen. For static stream objects, closing is meaningless.

The following functions are members of

class
istrstream

, class ostrstream , and class strstream .

char* ostrstream::str() char* strstream::str(): call str() on the associated streambuf . These functions return whatever the streambuf::str() call returned.
int ostrstream::pcount() int strstream::pcount(): return the number of stored bytes.
strstreambuf* istrstream::rdbuf() strstreambuf* ostrstream::rdbuf() strstreambuf* strstream::rdbuf(): return a pointer to the strstreambuf associated with the stream.

EXAMPLE

This example creates a strstream , inserts a string and a number, then extracts them again, writing the contents of mystream to cout .

strstream mystream;
float mynum=3.2;
float num2;

   // Write mynum to mystream.
mystream << mynum << ends;

   // Extract the contents of mystream
   // and store them in num2.
mystream >> num2;

   // Get the string from mystream and
   // write it to cout.
cout << mystream.str();

Using these classes is an advanced programming technique and is not required for simple C++ programs that use I/O. As with the stream class descriptions, the protected interface to the buffer classes is not included in the class descriptions that follow, although it is implemented.

class strstreambuf

Buffer Class Descriptions

This section provides the descriptions of the buffer classes, such as filebuf and strstreambuf .

Each class (or occasionally, a set of related classes) is listed alphabetically. All class descriptions include the following information:

a synopsis of the class
a brief description of the purpose and structure of the class
a discussion of parent classes
a detailed description of the members of the class
examples of using some of the members, if appropriate
a SEE ALSO section that points you to related classes.

In addition, some class descriptions contain other sections, as appropriate for the class.

The following classes are described in this section:

class filebuf    class stdiobuf
class streambuf  class strstreambuf
class bsambuf    class bsam_exit_list

The bsambuf class is a specialized version of class streambuf and was added with Release 6.00. It implements I/O via the record-oriented Basic Sequential Access Method (BSAM) interface of the SAS/C OS Low-Level I/O functions. In addition to providing all the functionality of the streambuf class, class bsambuf permits functions to be called as BSAM exits via objects of class bsam_exit_list .

The bsambuf class is defined in the header file <bsamstr.h> . This header file also defines a set of classes for performing formatted file I/O using a bsambuf object. These include:

class bsamstream
class ibsamstream
class obsamstream .

These classes are specialized versions of class iostream , istream , and ostream , respectively.

For details about the streams library and the parent class of class bsambuf , refer to class streambuf in the "I/O Class Descriptions" section. For details about the OS Low-Level I/O functions, refer to SAS/C Library Reference, Volume 2. For more information about BSAM, refer to the IBM publication MVS/XA Data Administration Guide (GC26-4140).

Note: The classes defined in <bsamstr.h> can be used in a C++ program that uses the Systems Programming Environment (SPE) library. [cautionend]

Note: The term character in the following class and function descriptions refers to either a char , a signed char , or an unsigned char . [cautionend]

class bsambuf

Provide File I/O via BSAM

class bsambuf : public streambuf
{
public:
   enum error_id { Enone,
                   Estorage,
                   Eabend,
                   Eopen,
                   Eclose,
                   Eget,
                   Eput,
                   Efind,
                   Estow,
                   Eflush,
                   Eseek,
                   Etell
                  };
   bsambuf();
   virtual ~bsambuf();
   int is_open();
   bsambuf *open(const char *filename, 
      int mode, const char *keywords = 0, 
      int willseek = 0,
      bsam_exit_list *user_exits = 0);
   bsambuf *attach(DCB_t *dcb, int mode, 
      int willseek = 0);
   int init_directory();
   int delete_member(const char *name);
   int rename_member(const char *old_name,
      const char *new_name);
   int stow(const char *name, 
      char action = 'R',
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0, 
      int R = 0, int TTRN = 0);
   int add_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int replace_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int find(const char *name);
   bsambuf *close();
   char dcbrecfm();
   short dcblrecl();
   short dcbblksize();
   DCB_t *getdcb();
   int error_info(error_id& id);
   void clear_error_info();
   void set_user_data(void *user_data);
   void *get_user_data();
   const char *get_ddname();
   const char *get_member();
   virtual streambuf *setbuf(char *buffer, 
      int length);
   virtual streampos seekoff(streamoff 
      offset,ios::seek_dir dir, int mode);
   virtual streampos seekpos(streampos 
      pos, int mode);
   virtual int sync();
 };

For more information about the OS Low-Level I/O functions, refer to SAS/C Library Reference, Volume 2. For more information about BSAM, refer to the IBM publication MVS/XA Data Administration Guide (GC26-4140).

The <bsamstr.h> header file defines

class
bsambuf

. The bsambuf class is a specialization of class streambuf that implements I/O via the record-oriented BSAM interface of the OS Low-Level I/O functions. bsambuf objects are intended for use in C++ programs that use the SPE version of the library, but they may also be useful in other contexts.

In addition to the expected streambuf functionality, class bsambuf permits functions to be called as BSAM exits via objects of class bsam_exit_list .

RESTRICTIONS

A file having the DCB characteristic LRECL=X cannot be connected to a bsambuf .
"Short records," that is, records in a fixed-length record data set that are shorter than the record length, are padded on the right. If the file was opened in ios::binary mode, the record is padded with null (all bits 0) characters, otherwise the record is padded with blank characters. Padding characters are not removed from records on input.
The number of pushback characters is limited to the size of the buffer, which is either the logical record length of the file or the size specified by setbuf , whichever is smaller. In no case can characters be pushed back beyond a record boundary.

class bsambuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

class bsambuf defines one constructor:

bsambuf::bsambuf(): constructs a bsambuf object for an unopened file.

Here is the class bsambuf destructor:

virtual bsambuf::~bsambuf(): closes the file, if opened.

TYPES

class bsambuf defines one type,

enum
error_id

. This type enumerates the values that may be retrieved by the error_info function, described later in this section.

int bsambuf::is_open()

The following nonvirtual functions are defined in class bsambuf . The virtual functions are described later in this section.

returns a value other than 0 if the bsambuf is connected to an open file; returns 0 otherwise.

bsambuf *bsambuf::open (const char *filename, int mode, const char *keywords = 0, int willseek = 0, bsam_exit_list *user_exits = 0)

opens a file named filename and connects the bsambuf to it. If the open is successful, open returns a pointer to the bsambuf . If an error occurs during the open, open returns 0. filename is a DDname optionally followed by a parenthesized member name. filename may be in upper- or lowercase. For example, ' sysin ' is a valid filename, as is ' obj(subrtn) '. mode is a combination of one or more enum open_mode flags. One or more of ios::in, ios::out , or ios::app must be set. keywords is a string of 0 or more DCB macro keywords. The supported keywords are DSORG, RECFM, LRECL, BLKSIZE, OPTCD, NCP, and BUFNO. The keywords and their values can be in either upper- or lowercase. If several keywords are specified, they can be separated by blanks or commas. For example, the keyword string ' recfm=fb,blksize=6400,lrecl=80 ' corresponds to the DCB specification DCB=(RECFM=FB,BLKSIZE=6400,LRECL=80). By default, no keywords are used.

DCB attributes may be specified via the keywords string or by the DD statement or TSO ALLOCATE for the DDname. If any attributes are unspecified for a new file, the following default values are used:

If the record format is not specified, it defaults to variable-length, blocked records (RECFM=VB).
If the record length is not specified, the default is 259 for a variable-length file or 80 for a fixed-length file.
If the block size(footnote 1) is not specified, the default is shown in the following table:

Format Default Blocksize

RECFM=F either the logical record length or the largest multiple of the logical record length less than 6144, whichever is larger

RECFM=V either the logical record length + 4 or 6144, whichever is larger

RECFM=U 255

If the value of willseek is 0, seeking is disabled for this file. Any attempt to use either the seekoff and seekpos function will result in an error. Specify a value other than 0 for this parameter if you intend to use either seekoff or seekpos on this file. The default value is 0. user_exits is a pointer to a bsam_exit_list object describing a number of functions to be called as BSAM exit routines. See class bsam_exit_list for information about this parameter. By default, no user exits are enabled.

Restrictions

The ios::app mode flag is treated as ios::ate .
The ios::nocreate and ios::noreplace mode flags are ignored.

bsambuf *bsambuf::attach(DCB_t *dcb, int mode, int willseek = 0)

associates a DCB that has already been created by either the osdcb or osbdcb function to a bsambuf and opens the file. If the open is successful, attach returns a pointer to the bsambuf . If an error occurs during the open, attach returns 0. mode and willseek have the same meaning as they have in the open function.

Restrictions

The DCB cannot already be open.
The bsambuf implementation reserves the DCBUSER field for its own use.
The ios::app mode flag is treated as ios::ate .
The ios::nocreate and ios::noreplace mode flags are ignored.

int bsambuf::init_directory()

invokes the "initialize directory" function of the STOW macro on the file (which must be a PDS) connected to the bsambuf . The value returned is 0 if the function succeeds or is a value other than 0 otherwise.

int bsambuf::delete_member (const char *name)

deletes the PDS member identified by name from the file connected to the bsambuf . name may be specified in either upper- or lowercase. If name is shorter than eight characters it will be padded on the right with blanks. The value returned is 0 if the member is successfully deleted or is a value other than 0 otherwise.

int bsambuf::rename_member (const char *old_name, const char *new_name)

renames the PDS member identified by old_name to new_name . old_name and new_name may be specified in either upper- or lowercase. If either name is shorter than eight characters it will be padded on the right with blanks. The value returned is 0 if the member is successfully renamed or is a value other than 0 otherwise.

int bsambuf::stow(const char *name, char action = 'R', int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

adds or replaces a member or alias in the file connected to the bsambuf . The file must be a PDS. name is the name of the member or alias. name may be specified in either upper- or lowercase. If name is shorter than eight characters, it will be padded on the right with blanks. action may be either 'R', indicating that name replaces an existing member or alias in the PDS, or 'A', which indicates that name is to be added to the PDS. The default value is 'R'. user_data_length is the length, in bytes, of the user data to be associated with name in the PDS directory. This value must be nonnegative and no greater than 62. user_data is a pointer to the user data. The default value of both user_data_length and user_data is 0.

If alias is a value other than 0, then name is treated as an alias to be added or replaced. The default value of alias is 0. TT and R are the relative track and record number, respectively, of name . These values are ignored when alias is 0. By default both are 0.(footnote 2) TTRN is the number of TTRN fields in user_data . This must be a nonnegative number no greater than 3. By default it is 0. stow returns a value other than 0 if any of the arguments are out of bounds. If stow invokes the STOW macro, with one exception, stow( ) returns the return code from the STOW macro. (This code can also be retrieved via the error_info function.) In general, the STOW macro returns 0 if the requested action succeeded, or a value other than 0 otherwise. The exception occurs when action is 'R' and the STOW macro returns 8. This return code from the STOW macro indicates that the member or alias did not previously exist and so was added. In this case, stow returns 0.

int bsambuf::add_member(const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

is equivalent to the stow function when action is 'A'. The arguments and return value are identical to stow .

int bsambuf::replace_member (const char *name, int user_data_length = 0, const void *user_data = 0, int alias = 0, int TT = 0, int R = 0, int TTRN = 0)

is equivalent to the stow function when action is 'R'. The arguments and return value are identical to stow .

int bsambuf::find(const char *name)

positions the file, which must be a PDS, to the start of the member identified by name . name may be specified in either upper- or lowercase. If name is shorter than eight characters it will be padded on the right with blanks. find returns 0 if the file is successfully positioned, or a value other than 0 otherwise.

bsambuf *bsambuf::close()

causes any outstanding output to be flushed, then closes the file and disconnects the bsambuf from it (even if errors occur). The bsambuf 's I/O state is cleared. If the close is successful, close returns a pointer to the bsambuf . If an error occurs, close returns 0.

char bsambuf::dcbrecfm()

returns the value of the DCBRECFM field in the DCB. The bits in this field describe the record format of the file connected to the bsambuf . The <osio.h> header file contains preprocessor symbol definitions for the bits that may be set in this field. The most commonly used flags are shown in the following table:

Symbol Format

DCBRECF fixed

DCBRECV variable

DCBRECU undefined (see Note)

DCBRECBR blocked

Symbol	Format
DCBRECF	fixed
DCBRECV	variable
DCBRECU	undefined (see Note)
DCBRECBR	blocked

Note: DCBRECU is equivalent to ORing DCBRECF with DCBRECV. When examining the value returned by dcbrecfm , you must always check for DCBRECU before testing the DCBRECF or DCBRECV flags. [cautionend]

short bsambuf::dcblrecl() short bsambuf::dcbblksize()

return the logical record length (LRECL) and block size (BLKSIZE) of the file connected to the bsambuf .

DCB_t *bsambuf::getdcb()

returns a pointer to the DCB associated with the file connected to the bsambuf .

int bsambuf::error_info(error_id& id)

returns the return code from the first failed low-level routine. If a function receives a value other than 0 as a return code from a low-level routine, it saves the return code and a value of type error_id indicating which routine failed. error_info retrieves this information, which may be used for a detailed error analysis.

The value returned in the id argument may have one of the values shown in the following table. Unless otherwise noted, the failing routine is a BSAM routine in the OS Low-Level I/O group of functions.

error_id Routine

Enone (no error)

Estorage GETMAIN (table note 1)

Eabend BSAM (table note 2)

Eopen osopen

Eclose osclose

Eget osget (table note 3)

Eput osput

Efind osfind

Estow osstow

Eflush osflush

Eseek osseek

Etell ostell

error_id	Routine
Enone	(no error)
Estorage	GETMAIN (table note 1)
Eabend	BSAM (table note 2)
Eopen	osopen
Eclose	osclose
Eget	osget (table note 3)
Eput	osput
Efind	osfind
Estow	osstow
Eflush	osflush
Eseek	osseek
Etell	ostell

TABLE NOTE 1: This value is set when storage cannot be allocated for a buffer. The code returned by error_info is always 4.

TABLE NOTE 2: This value is returned when an "ignorable" ABEND has occurred. An ignorable ABEND does not terminate the program but does prevent any further I/O from being performed on the file connected to the bsambuf . The value of the return code is that of the completion code field in the ABEND exit parameter list.

TABLE NOTE 3: Although end-of-file causes osget to return a value other than zero as a return code, this value is not stored as an error code.

If, after a low-level routine has failed and its error information stored, a subsequent low-level routine fails, the error information for that failure is not stored unless clear_error_info has been called.

void bsambuf::clear_error_info()

sets the stored error information to the initial state. In this state, the value of error_id is Enone and the return code is 0.

void bsambuf::set_user_data (void *user_data)

stores the value in user_data for later retrieval by get_user_data . The value may be any value required by the program. It is ignored by the stream.

void *bsambuf::get_user_data()

retrieves the value stored by set_user_data .

void *bsambuf::get_ddname()

returns a pointer to the DDname part of the filename argument to open . The DDname is uppercased and terminated by a ' \0 '. If the DCB was associated to the bsambuf by the attach function, the pointer points to a 0-length string.

void *bsambuf::get_member()

returns a pointer to the member part of the filename argument to open . The member name is uppercased and terminated by a ' \0 '. If the DCB was associated to the bsambuf by the attach function, or the filename did not specify a member name, the pointer points to a 0-length string.

virtual streambuf *bsambuf::setbuf (char *buffer, int length)

offers the character array starting at buffer and containing length bytes as a buffer for use by the bsambuf . If buffer is 0 or length is less than or equal to 0, the bsambuf is unbuffered. (However, buffering by BSAM will still take place.) This function must be called before any I/O is requested for this bsambuf and can be called only once for the bsambuf . If the buffer will be used by the bsambuf , setbuf returns a pointer to the bsambuf .

If this function is called after I/O has been requested for the bsambuf , it does nothing and returns 0. If this function is called more than once, subsequent calls for the bsambuf do nothing except return 0. This function does not affect the I/O state of the bsambuf .

By default, the buffer size is equal to the number of data characters in a record. In most cases, use of the setbuf function will have little, if any, effect on I/O performance. However, changing the bsambuf to be unbuffered will severely degrade the performance. Also note that the underlying BSAM routines will always buffer the data, whether the bsambuf is unbuffered or buffered.

virtual streampos bsambuf::seekoff (streamoff offset, ios::seek_dir dir, int mode)

sets the get and put pointers to a new position, as indicated by offset and dir . For a bsambuf , seekoff will only accept 0 as the value of offset . The only acceptable values for dir are ios::beg and ios::cur . (Refer to the description of streambuf::seekoff for an explanation of these two values.) If dir is ios::beg , the file is positioned to the beginning. If dir is ios::cur , the position of the file is not changed. The new location of the file is returned in the streampos .

For bsambuf objects, the get and put pointers are the same, so the mode argument is ignored. seekoff returns (streampos) EOF if offset is a value other than 0, if dir is neither ios::beg or ios::cur , or if the file position cannot be moved. seekoff will also always return (streampos) EOF if willseek was 0 when the file was connected to the bsambuf by either open or attach .

virtual streampos bsambuf::seekpos (streampos pos, int mode)

sets the get and/or put pointers to a new position, as indicated by streampos . This function returns the new position, or seekpos(EOF) if an error occurs. For bsambuf objects, the get and put pointers are the same, so the mode argument is ignored.

virtual int sync()

tries to force the state of the get and put pointers of the bsambuf to be synchronized with the state of the file it is associated with. If some characters have been buffered for output they will be written to the file.(footnote 3) Characters that have been buffered for input will be discarded. Note that synchronization is not possible unless the file is positioned at a record boundary.

This function returns 0 if synchronization succeeds, otherwise it returns EOF.

Define BSAM Exit Routines

class bsam_exit_list, class bsamstream, 
class ibsamstream, class obsamstream

class bsam_exit_list

#include <bsamstr.h>

class bsam_exit_list {
   bsam_exit_list();
   bsam_exit_list(exit_t *list);
   int use(_e_exit code, _e_exit_fp exit);
   int use(_e_exit code, void *exit);
   int remove(_e_exit code,_e_exit_fp exit);
   int remove(_e_exit code, void *exit);
   };

The <bsamstr.h> header file defines class bsam_exit_list . A pointer to a bsam_exit_list object can be passed to the bsambuf::open , bsamstream::open , ibsamstream::open , or obsamstream:open function to define one or more functions that are to be used as DCB exit routines.

RESTRICTIONS

Functions that serve as DCB exit routines cannot be member functions.
Only one function can be called for each type of DCB exit.
No more than 18 exits can be specified in each bsam_exit_list object. OS Low-Level I/O defines only 18 distinct exits.

bsam_exit_list::bsam_exit_list()

class bsam_exit_list defines two constructors:

constructs an object that defines no exits.

bsam_exit_list::bsam_exit_list (exit_t list[])

constructs an object that defines the exits specified by list . list is an array of type exit_t . This type is defined as shown here:

typedef struct {
         unsigned exit_code;
         union {
           _e_exit_fp exit_addr;
           void *area_addr;
          };
     } exit_t;

exit_code may be any one of the values defined for the enumeration type _e_exit , which is also defined as shown here:

enum _e_exit {INACTIVE = 0, INHDR = 1,
    OUTHDR = 2, INTLR = 3, OUTTLR = 4,
    OPEN = 5, EOV = 6, JFCB = 7,
    USER_TOTAL = 10, BLK_COUNT = 11,
    DEFER_INTLR = 12,
    DEFER_NONSTD_INTLR = 13, FCB = 16,
    ABEND = 17, JFCBE = 21,
    TAPE_MOUNT = 23, SECURITY = 24,
    LAST = 128, SYNAD = 256};

The last entry in the list must set area_addr to 0 and have an exit_code value of LAST or, if either exit_addr or area_addr is a value other than 0, you must OR the exit_code value with LAST.

Here is an example using this constructor:

static int open_exit(void *r1, void *r0)
   { 
   // DCB open exit processing...
   return 0;
   }
static int abend_exit(void *r1, void *r0)
   { 
   // DCB abend exit processing... 
   return 0; 
   }
int main()
 {    
 exit_t exit_array[] = {{OPEN, open_exit},
                      {ABEND, abend_exit},
                      {LAST, 0}
                       } ;    
   // Construct "list" with
   // two DCB exits.
     bsam_exit_list list(exit_array);

   // Open DDname "OUT"     
   // defining two DCB exits.     
     obsamstream o("out", ios::out, 0, 0,
                   &list);

   /* remainder of program */
     . 
     . 
     .

Here is the class bsam_exit_list destructor:

virtual bsam_exit_list::~bsam_exit_list()

int use(_e_exit code, _e_exit_fp exit)

The following nonvirtual functions are defined in class bsam_exit_list . This class defines no virtual functions.

Note: BSAM exits may be either functions or data areas. Therefore, class bsam_exit_list defines functions for both types. [cautionend]

adds a pointer to a function to be used as a DCB exit to the bsam_exit_list . The pointer must have type _e_exit_fp , which is defined as:

typedef _ _remote int (*_e_exit_fp)
       (void *, void *)

The exit must be a static member function or a nonmember function. The BSAM exit type is specified by code . If the exit is added, use returns 0. Otherwise it returns a value other than 0.

On entry to a BSAM exit, the first argument is the value of general register 1 as established by BSAM. Likewise, the second argument is the value of general register 0.

ABEND exit considerations

A default DCB ABEND exit is always defined for a bsambuf . If you define an DCB ABEND exit for the bsambuf , your exit will be run first, followed by the default exit. Your exit must set the option mask byte in the ABEND exit parameter list before returning. If the option mask byte is set to 4, indicating that the ABEND should be "ignored," the default exit causes the DCB to be closed and freed.

For your convenience, the <bsamstr.h> header file contains a partial definition of the parameter list BSAM creates for the DCB ABEND exit. On entry to the exit function, general register 1 (the first argument) contains a pointer to this parameter list:

struct Abend_exit_parms {
        char completion_code :12;
        char                 :4;
        char return_code;
        union {
           struct {
              char         :4;
              char recover :1;
              char ignore  :1;
              char delay   :1;
              char         :1;
              } can;
           char option_mask;
           };
        DCB_t *dcb;
       };
     // Set "option_mask" to this value
     // to ignore the ABEND.
     const int IGNORE_ABEND = 4;

int remove(_e_exit code, _e_exit_fp exit)

removes an exit function from the bsam_exit_list . If an exit having the matching exit code and function pointer is not in the bsam_exit_list , remove returns a value other than 0. Otherwise, remove removes the exit and returns 0.

int use(_e_exit code, void *exit)

adds a data pointer to be used as a DCB exit to the bsam_exit_list . The BSAM exit type is specified by code .

If the exit is added, use returns 0. Otherwise it returns a value other than 0.

int remove(_e_exit code, void *exit)

removes a data exit from the bsam_exit_list . If an exit having the matching exit code and address is not in the bsam_exit_list , remove returns a value other than 0. Otherwise, remove removes the exit and returns 0.

class bsambuf, class bsamstream, class ibsamstream,
class obsamstream

class filebuf

Provide File I/O

#include <fstream.h>
class filebuf : public streambuf
{
public:
   filebuf();
   virtual ~filebuf();
   int is_open();
   filebuf* open(const char *name,
                 int mode,
                 const char *amparms = "",
                 const char *am = "");
   filebuf* close();
   virtual streampos seekoff(streamoff
         offset, seek_dir place,
         int mode = ios::in|ios::out);
   virtual streampos seekpos(streampos pos,
         int mode = ios::in|ios::out);
   virtual streambuf* setbuf(char *p,
                             size_t len);
   virtual int sync();
};

The fstream.h header file defines

class
filebuf

. filebuf objects represent the lowest level of file I/O that is standard C++. They provide a specialized form of streambufs that uses a file as the source or destination (sink) for characters. Input corresponds to file reads and output corresponds to file writes. For filebuf objects, the get and put pointers are tied together. That is, if you move one, you move the other. If the file has a format that allows seeks, a filebuf allows seeks. filebuf I/O guarantees at least four characters of putback. You do not need to perform any special action between reads and writes (in contrast to standard C I/O, where such seeks are required).

When a filebuf is connected to a file, the filebuf is said to be open. There is no default open mode, so you must always specify the open mode when you create a filebuf .

class filebuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

class filebuf defines one constructor:

filebuf::filebuf(): creates an unopened file.

Here is the class filebuf destructor:

virtual filebuf::~filebuf(): closes the file, if opened.

int filebuf::is_open()

The following nonvirtual functions are defined in class filebuf . The virtual functions are described later in this section.

returns a nonzero value if the filebuf is connected to an open file; returns 0 otherwise.

filebuf* filebuf::open(const char *name, int mode, const char *amparms = "", const char *am = "")

opens a file named name and connects the filebuf to it. If the open is successful, open() returns a pointer to the filebuf . If an error occurs during the open (for example, if the file is already open), open() returns 0. See enum open_mode for a description of the mode argument.

An explanation of filename specification and the arguments amparms and am can be found in the SAS/C Library Reference, Volume 1. (Note that the order of the amparms and am arguments in this function is the opposite of the order in which they appear in calls to the C afopen function.) You may also want to refer to the SAS/C Compiler and Library User's Guide.

filebuf* filebuf::close()

causes any outstanding output to be flushed, then closes the file and disconnects the filebuf from it (even if errors occur). Also, the filebuf 's I/O state is cleared. If the close is successful, close() returns a pointer to the filebuf . If an error occurs during the close, close() returns 0.

virtual streampos filebuf::seekoff (streamoff offset, seek_dir place, int mode = ios::in|ios::out)

The following functions override their base class definitions (in class streambuf ).

sets the get and put pointers to a new position, as indicated by place and offset . (Descriptions of offset and place are contained in the streambuf::seekoff() description.) This function returns the new position, or it returns streampos(EOF) if an error occurs (for example, the file may not support seeking, or you may have requested a seek to a position preceding the beginning of the file). The position of the file after an error is undefined. Some files support seeking in full, and some impose lesser or greater restrictions on seeking. seekoff() corresponds to the C fseek function, and seekpos() corresponds to the C fsetpos function. Rules for these similar C functions are given in the SAS/C Library Reference, Volume 1.

For filebuf objects, the get and put pointers are the same (moving either one moves the other). Because of this, you do not have to use the last argument, mode .

virtual streampos filebuf::seekpos (streampos pos, int mode = ios::in|ios::out)

sets the get and/or put pointers to a new position, as indicated by streampos . This function returns the new position, or it returns seekpos(EOF) if an error occurs. For filebuf objects, the get and put pointers are the same (moving either one moves the other). Because of this, you do not have to use the last argument, mode .

virtual streambuf* filebuf::setbuf (char *p, size_t len)

offers the character array starting at p and containing len bytes as a buffer for use by the filebuf . If p is null or len is less than or equal to 0, the filebuf is unbuffered. (However, buffering by the SAS/C Library and the operating system may still take place.) This function must be called before any I/O is requested for this filebuf and can be called only once for the filebuf . Under normal conditions, setbuf() returns a pointer to the filebuf .

If this function is called after I/O has been requested for the filebuf , this function does nothing and returns NULL . If this function is called more than once, subsequent calls for the filebuf do nothing except return NULL . This function does not affect the I/O state of the filebuf .

virtual int filebuf::sync()

tries to force the state of the get or put pointer of the filebuf to be synchronized with the state of the file it is associated with. This attempt at synchronization may result in the following:

characters being written to the file, if some have been buffered for output. Note that all characters may not be written immediately due to additional buffering performed by the operating system.
an attempt to seek the file, if characters have been read and buffered for input.

This function usually returns 0; if synchronization is not possible, it returns EOF.

IMPLEMENTATION

Usually, filebuf objects directly access the native I/O facilities of the system on which they are implemented. For this release of the SAS/C C++ Development System, filebuf objects are implemented in terms of C FILE* s. This may be changed in later versions of this library, and no assumptions should be made of this particular implementation.

Provide I/O in a Mixed C and C++ Environment

class fstream, class ifstream,
class ofstream

class stdiobuf

#include <stdiostream.h>

class stdiobuf : public streambuf
{
public:
  stdiobuf(FILE *file);

  virtual ~stdiobuf( );

  int is_open( );

  FILE* stdiofile( );

  streampos seekoff(streamoff offset,
                    seek_dir place,
                    int mode =
                    ios::in|ios::out);
  streampos seekpos(streampos pos,
                    int mode =
                    ios::in|ios::out);
  virtual int sync();
};

The stdiostream.h header file declares class stdiobuf . stdiobufs are intended to be an interface to ANSI C style FILE *s on those systems that provide FILE *s. Calls to stdiobuf member functions are mapped directly to calls to ANSI C stdio functions.

Because stdiobuf objects provide no buffering other than that provided by the C stdio functions, any changes to file attributes or contents made via a stdiobuf are reflected immediately in the stdio data structures. This includes file positioning using seekoff() or seekpos() . For stdiobuf objects, the get and put pointers are tied together. That is, if you move one, you move the other.

Unless you are mixing streambuf and stdio access to the same file, you should use class filebuf instead of class stdiobuf . Use of filebuf objects may improve performance.

class stdiobuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

class stdiobuf defines one constructor:

stdiobuf::stdiobuf(FILE *file): creates a stdiobuf object associated with an open FILE *.

Here is the class stdiobuf destructor:

virtual stdiobuf::~stdiobuf(): closes the associated FILE *, if opened.

The following descriptions detail the nonvirtual member functions for class stdiobuf . The redefined virtual functions are described later in this section.

int stdiobuf::is_open(): returns a nonzero value if the stdiobuf is connected to an open file; returns 0 otherwise.
FILE* stdiofile(): returns the associated FILE *.

streampos stdiobuf::seekoff (streamoff offset, seek_dir place, int mode = ios::in|ios::out)

The following functions override their base class definitions (in class streambuf ).

moves the get and/or put pointers of the streambuf . place can be one of the following:

ios::beg: indicates the start of file.
ios::cur: indicates the current get and put position.
ios::end: indicates the end of file.

offset is a positive or negative integer position relative to place. mode can be one of the following:

ios::in: moves the get pointer.
ios::out: moves the put pointer.
ios::in|ios::out: moves both pointers.

Whether seekoff() and seekpos() work for an stdiobuf depends on the characteristics of the associated FILE* . See the SAS/C Library Reference, Volume 1 for more information on FILE* characteristics.

streampos stdiobuf::seekpos (streampos pos, int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . pos must be a value returned by a previous call to seekoff() . mode can be one of the following:

ios::in: moves the get pointer.
ios::out: moves the put pointer.
ios::in|ios::out: moves both pointers.

Some stream buffers do not support seeking. For those stream buffers, seekpos() returns streampos(EOF) to indicate an error occurred. See the documentation for particular stream buffer classes (such as filebuf ) for more information on what kinds of seeking are allowed.

virtual int stdiobuf::sync()

tries to force the state of the get or put pointer of the stdiobuf to be synchronized with the state of the associated file. This attempt at synchronization may result in the following:

buffered for output. Note that all characters may not be written immediately due to additional buffering performed by the operating system.
an attempt to seek the file, if characters have been read and buffered for input.

This function usually returns 0; if synchronization is not possible it returns EOF.

Provide Base Class for All Stream Buffers

class stdiostream

class streambuf

#include <iostream.h>

class streambuf
{
public:
   int in_avail();
   int out_waiting();

   int sbumpc();
   int sgetc();
   int sgetn(char *s, int n);
   int snextc();
   void stossc();

   int sputbackc(char c);
   int sputc(int c);
   int sputn(const char *s, int n);

   virtual int sync();
   virtual streampos seekoff(streamoff
            offset, seek_dir place,
            int mode = ios::in|ios::out);
   virtual streampos seekpos(streampos pos,
            int mode = ios::in|ios::out);
   virtual streambuf* setbuf(char *p,
                             int len);
};

CONSTRUCTORS AND DESTRUCTORS

class streambuf is declared in the iostream.h header file and is the base class for all stream buffers. Stream buffers manage the flow of characters between the program and the ultimate sources or consumers of characters, such as external files. The streambuf class defines behavior common to all stream buffers. More specialized classes can be derived from class streambuf to implement appropriate buffering strategies for particular stream types. For instance, filebufs implement buffering suitable for file input or output and strstreambufs implement buffering suitable for transfer of data from strings in memory. A streambuf is almost never used directly (classes derived from it are used instead) but more often acts as an interface specification for derived classes.

The functions defined by the streambuf interface are divided into two groups: nonvirtual functions and virtual functions. These sets of functions are described separately.

class streambuf defines two constructors and one destructor. All these functions are protected. This ensures that

class
streambuf

is used only as a base class for derived classes.

int streambuf::in_avail()

The following list describes the nonvirtual streambuf interface.

returns the number of characters that have been buffered for input, that is, the number of characters that have been read from the ultimate source of the input but have not been extracted from the streambuf . Generally, this information is useful only for classes derived from class streambuf .

int streambuf::out_waiting()

returns the number of characters that have been buffered for output, that is, the number of characters that have been inserted into the streambuf but have not been delivered to its ultimate destination. Generally, this information is useful only for classes derived from class streambuf .

int streambuf::sbumpc()

advances the get pointer one character and returns the character preceding the advanced pointer. If the get pointer is at the end of the stream, the get pointer is not moved and EOF is returned.

int streambuf::sgetc()

returns the character following the get pointer. This function does not move the get pointer. If the get pointer is at the end of the stream, this function returns EOF.

int streambuf::sgetn(char *s, int n)

extracts the next n characters from the stream into s and positions the get pointer after the last extracted character. If there are less than n characters between the get pointer and the end of the stream, those characters are extracted into s and the get pointer is moved to the end of the stream. This function returns the number of characters extracted into s .

int streambuf::snextc()

advances the get pointer one character and returns the character after the advanced pointer. If the get pointer is at the end of the stream, the get pointer is not moved and EOF is returned.

void streambuf::stossc()

advances the get pointer one character.

int streambuf::sputbackc(char c)

backs the get pointer up one character, returning c . c must be the character that the get pointer is moved over; if it is not, the effects of this function are undefined. For example, if the get pointer is at the start of the stream and you call this function, the effect is undefined.

Also, each class derived from streambuf may impose a limit on the number of characters that can be moved over by sputbackc() . If you exceed this limit, this function returns EOF. For some classes, you cannot back up over any characters.

int streambuf::sputc(int c)

stores c in the position following the put pointer, replacing any pre-existing character, and then advances the put pointer one position. This function returns c if the operation is successful, or EOF if an error occurs.

int streambuf::sputn(const char *s, int n)

stores after the put pointer the first n characters addressed by s , replacing any pre-existing characters in those positions, and then advances the put pointer past the last character stored. This function returns the number of characters successfully stored.

virtual int streambuf::sync()

The following virtual functions are members of class streambuf . These functions can be redefined in derived classes (both those supplied by the library and those you define yourself) to customize the behavior of streambuf objects.

tries to force the state of the get or put pointer of the streambuf to be synchronized with the state of the sink or source it is associated with. This function returns 0 if successful, or EOF if an error occurs.

virtual streampos streambuf::seekoff (streamoff offset, seek_dir place, int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . place can be one of the following:

ios::beg: indicates the start of file.
ios::cur: indicates the current get or put position.
ios::end: indicates the end of file.

offset is a positive or negative integer position relative to place. mode can be one of the following:

ios::in: moves the get pointer.
ios::out: moves the put pointer.
ios::in|ios::out: moves both pointers. This is the default value.

Some kinds of seeking are not supported for certain stream buffers. If a particular stream buffer does not support the seeking specified, this function returns streampos(EOF) to indicate an error occurred. See the documentation for particular stream buffer classes (such as filebuf ) for more information on what kinds of seeking are allowed.

virtual streampos streambuf::seekpos (streampos pos, int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . pos must be a value returned by a previous call to seekoff() . mode can be one of the following:

ios::in: moves the get pointer.
ios::out: moves the put pointer.
ios::in|ios::out: moves both pointers. This is the default value.

virtual streambuf* streambuf::setbuf (char *p, int len)

allocates a buffer area to be used for buffering within the streambuf .

class strstreambuf

Provide String I/O

#include <strstream.h>

class strstreambuf : public streambuf
{
public:
   strstreambuf( );
   strstreambuf(int len);
   strstreambuf(void* (*a) (long),
                void (*f) (void*));
   strstreambuf(char *b, int size,
                char *pstart = 0);

   ~strstreambuf( );

   void freeze(int n = 1);
   char* str( );

   virtual streambuf* setbuf(char *p,
                             int len);
   inc sync( );
   virtual streampos seekoff
           (streamoff offset,
            seek_dir place,
            int mode = ios::in|ios::out);

   virtual streampos seekpos 
            (streampos pos,
            int mode = ios::in|ios::out);
};

The header file strstream.h declares class strstreambuf , which specializes class streambuf to provide for I/O using arrays of char (strings).

For strstreambuf objects, the get and put pointers are separate. That is, if you move one of these pointers you do not necessarily move the other. strstreambuf objects are created in one of two different modes, dynamic mode or static (fixed) mode. Once a strstreambuf is created, it does not change modes. The following list explains the difference between fixed and dynamic mode:

dynamic mode: means the strstreambuf does not have a fixed size and grows as needed. When the array associated with a dynamic mode strstreambuf is filled, the strstreambuf automatically allocates a larger array, copies the old smaller array to the larger, and frees the smaller array. The functions used to handle allocating and freeing the arrays are determined by the constructor used to create the strstreambuf (see the description of constructors for class strstreambuf .
static mode: means the strstreambuf has a fixed size that does not change. If the array associated with a static mode strstreambuf is filled, further writes to the strstreambuf may corrupt memory. Be cautious when inserting into static mode strstreambuf s.

Note: Do not confuse static mode with the static storage class modifier. [cautionend]
class strstreambuf defines some member functions of its own and also redefines several virtual functions from the base class.

class strstreambuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

strstreambuf::strstreambuf()

class strstreambuf defines four constructors:

creates an empty strstreambuf object in dynamic mode.

strstreambuf::strstreambuf(int len)

creates an empty strstreambuf object in dynamic mode. The initial allocation uses at least len bytes.

strstreambuf::strstreambuf (void*(*a)(long), void (*f)(void*))

creates an empty strstreambuf object in dynamic mode. a is the allocation function to be used to do the dynamic allocation and takes as its argument a long , which specifies the number of bytes to allocate. If a is NULL , the operator new is used instead of a . f is the deallocation function, which frees the space allocated by a . f takes as its argument a pointer to an array allocated by a . If f is NULL , the operator delete is used instead of f .

strstreambuf::strstreambuf(char *b, int size, char *pstart = 0)

constructs a strstreambuf object in static mode; it does not grow dynamically. b specifies where to start the array and size specifies the size of the array, as explained in the following list.

If size is positive, the array is size bytes long.
If size is 0, the function assumes b points to the start of a null-terminated string. In this case, the string, not including the ' \0 ' character, is considered to be the strstreambuf .
If size is negative, the strstreambuf is assumed to be indefinitely long.

The get pointer receives the value of b and the put pointer receives the value of pstart . If pstart is NULL , then storing characters in the strstreambuf is not allowed and causes the function to return an error.

Here is the class strstreambuf destructor:

strstreambuf::~strstreambuf(): closes the strstreambuf object. The destructor causes any memory allocated for the strstreambuf to be freed.

void strstreambuf::freeze(int n = 1)

class strstreambuf defines two nonvirtual member functions.

controls the automatic deletion of the array. If n is nonzero, which is the default, the array is not deleted automatically. If n is 0, the array is unfrozen and is deleted automatically. The array is deleted whenever a dynamically created strstreambuf needs more space or when the destructor is called. This function only applies to dynamically created strstreambuf s; it has no effect on statically created strstreambuf s.

If you try to store characters in a frozen array, the effect is undefined.

char* strstreambuf::str()

returns a pointer to the first character in the current array and freezes the array. After str() has been called, the effect of storing characters in the array is undefined until the strstreambuf is unfrozen by calling freeze(0) .

virtual strstreambuf::streambuf* setbuf (char *p, int len)

class strstreambuf redefines several virtual functions from its base class ( class streambuf ).

tells the strstreambuf that the next time an array is dynamically allocated it should be at least len bytes long. p is ignored.

int strstreambuf::sync()

returns EOF.

virtual streampos strstreambuf::seekoff (streamoff offset, seek_dir place, int mode = ios::in|ios::out)

moves the get and/or put pointers of the strstreambuf . See the description of streambuf::seekoff for explanations of offset , place and mode .

If the strstreambuf is in dynamic mode, this function returns streampos(EOF) to indicate an error occurred.

If either the get or put pointer is moved to a position outside the strstreambuf , or if the put pointer is moved for a strstreambuf that does not allow output, then streampos(EOF) is returned and the pointers are not moved.

If place is ios::end , it refers to the end of the array.

virtual streampos strstreambuf::seekpos (streampos pos, int mode = *ios::in|ios::out)

moves the get and/or put pointers of the strstreambuf .

If the strstreambuf is in dynamic mode, this function returns streampos(EOF) to indicate an error occurred. pos must be a value returned by a previous call to seekoff() .

See the description of streambuf::seekpos() for an explanation of mode . If ios::out is specified for mode and output is not allowed for this strstreambuf , then streampos(EOF) is returned to indicate an error occurred and the put pointer is not moved.

class strstream

Manipulator Descriptions

This section describes contents of the iomanip.h header file, which provides predefined manipulators, as well as support functions and classes that enable you to create your own manipulators.

class IOMANIP

Provide Manipulators

#include <IOMANIP.h>

/* Macros for creating class names */
#define SMANIP(T)  ...
#define SAPP(T)    ...
#define IMANIP(T)  ...
#define IAPP(T)    ...
#define OMANIP(T)  ...
#define OAPP(T)    ...
#define IOMANIP(T) ...
#define IOAPP(T)   ...

// Start of IOMANIPdeclare macro

#define IOMANIPdeclare(T)

class SMANIP(T)
{
   public:
   SMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         SMANIP(T)& m);
   friend ostream& operator <<(ostream& o,
         SMANIP(T)& m);
};

class SAPP(T)
{
public:
   SAPP(T)(ios&(*f)(ios&, T));
   SMANIP(T)operator()(T d);
};

class IMANIP(T)
{
public:
   IMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         IMANIP(T)& m);
};

class IAPP(T)
{
public:
   IAPP(T)(ios&(*f)(ios&, T));
   IMANIP(T)operator()(T d);
};
class OMANIP(T)
{
public:
   OMANIP(T)(ios&(*f)(ios&, T), T d);
   friend ostream& operator <<(ostream& o,
         OMANIP(T)& m);
};
class OAPP(T)
{
public:
   OAPP(T)(ios&(*f)(ios&, T));
   OMANIP(T)operator()(T d);
};

class IOMANIP(T)
{
public:
   IOMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         IOMANIP(T)&m);
   friend ostream& operator <<(ostream& o,
         IOMANIP(T)&m);
};

class IOAPP(T)
{
public:
   IOAPP(T)(ios&(*f)(ios&, T));
   IOMANIP(T)operator()(T d);
};
// End of IOMANIPdeclare macro

IOMANIPdeclare(int);
IOMANIPdeclare(long);

SMANIP(int) setw(int width);
SMANIP(int) setbase(int base);
SMANIP(int) setfill(int fill_char);
SMANIP(int) setprecision(int precision);
SMANIP(long) setiosflags(long flags);
SMANIP(long) resetiosflags(long flags);