*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> c++/ios (3)              


IOS(3C++)							     IOS(3C++)

NAME    [Toc]    [Back]

     ios - input/output	formatting

SYNOPSIS    [Toc]    [Back]

     #include <iostream.h>

     class ios {
	       enum	 io_state { goodbit=0, eofbit, failbit,	badbit };
	       enum	 open_mode { in, out, ate, app,	trunc, nocreate, noreplace };
	       enum	 seek_dir { beg, cur, end };
	       /* flags	for controlling	format */
	       enum	 { skipws=01,
			   left=02,  right=04, internal=010,
			   dec=020, oct=040, hex=0100,
			   showbase=0200, showpoint=0400, uppercase=01000, showpos=02000,
			   scientific=04000, fixed=010000,
			   unitbuf=020000, stdio=040000	};
	       static const long basefield;
			 /* dec|oct|hex	*/
	       static const long adjustfield;
			 /* left|right|internal	*/
	       static const long floatfield;
			 /* scientific|fixed */

	       int	 bad();
	       static longbitalloc();
	       void	 clear(int state =0);
	       int	 eof();
	       int	 fail();
	       char	 fill();
	       char	 fill(char);
	       long	 flags();
	       long	 flags(long);
	       int	 good();
	       long&	 iword(int);
	       int	 operator!();
			 operator void*();
	       int	 precision();
	       int	 precision(int);
	       void* &	 pword(int);
	       int	 rdstate();
	       long	 setf(long setbits, long field);
	       long	 setf(long);
	       static voidsync_with_stdio();
	       ostream*	 tie();
	       ostream*	 tie(ostream*);
	       long	 unsetf(long);
	       int	 width();

									Page 1

IOS(3C++)							     IOS(3C++)

	      int	 width(int);
	       static intxalloc();
	       void	 operator=(ios&);

	       /* Manipulators */
     ios&      dec(ios&) ;
     ios&      hex(ios&) ;
     ios&      oct(ios&) ;
     ostream&  endl(ostream& i)	;
     ostream&  ends(ostream& i)	;
     ostream&  flush(ostream&) ;
     istream&  ws(istream&) ;

DESCRIPTION    [Toc]    [Back]

     The stream	classes	derived	from class ios provide a high level interface
     that supports transferring	formatted and unformatted information into and
     out of streambufs.	 This manual page describes the	operations common to
     both input	and output.

     Several enumerations are declared in class	ios, open_mode,	io_state,
     seek_dir, and format flags, to avoid polluting the	global name space.
     The io_states are described on this manual	page under ``Error States.''
     The format	fields are also	described on this page,	under ``Formatting.''
     The open_modes are	described in detail in fstream(3C++) under open().
     The seek_dirs are described in sbuf.pub(3C++) under seekoff().

     In	the following descriptions assume:
	  - s and s2 are ioss.
	  - sr is an ios&.
	  - sp is a ios*.
	  - i, oi, j, and n are	ints.
	  - l, f, and b	are longs.
	  - c and oc are chars.
	  - osp	and oosp are ostream*s.
	  - sb is a streambuf*.
	  - pos	is a streampos.
	  - off	is a streamoff.
	  - dir	is a seek_dir.
	  - mode is an int representing	an open_mode.
	  - fct	is a function with type	ios& (*)(ios&).
	  - vp is a void*&.

   Constructors	and assignment:
	       The streambuf denoted by	sb becomes the streambuf associated
	       with the	constructed ios.  If sb	is null, the effect is

									Page 2

IOS(3C++)							     IOS(3C++)


	       Copying of ioss is not well-defined in general, therefore the
	       constructor and assignment operators are	private	so that	the
	       compiler	will complain about attempts to	copy ios objects.
	       Copying pointers	to iostreams is	usually	what is	desired.

	       Because class ios is now	inherited as a virtual base class, a
	       constructor with	no arguments must be used.  This constructor
	       is declared protected.  Therefore ios::init(streambuf*) is
	       declared	protected and must be used for initialization of
	       derived classes.

   Error States    [Toc]    [Back]
     An	ios has	an internal error state	(which is a collection of the bits
     declared as io_states).  Members related to the error state are:

	       Returns the current error state.

	       Stores i	as the error state.  If	i is zero, this	clears all
	       bits.  To set a bit without clearing previously set bits
	       requires	something like s<b>.clear(ios::badbit|s.rdstate()).

	       Returns non-zero	if the error state has no bits set, zero

	       Returns non-zero	if eofbit is set in the	error state, zero
	       otherwise.  Normally this bit is	set when an end-of-file	has
	       been encountered	during an extraction.

	       Returns non-zero	if either badbit or failbit is set in the
	       error state, zero otherwise.  Normally this indicates that some
	       extraction or conversion	has failed, but	the stream is still
	       usable.	That is, once the failbit is cleared, I/O on s can
	       usually continue.

	       Returns non-zero	if badbit is set in the	error state, zero
	       otherwise.  This	usually	indicates that some operation on
	       s<b>.rdbuf() has failed, a severe error, from which	recovery is
	       probably	impossible.  That is, it will probably be impossible
	       to continue I/O operations on s.

									Page 3

IOS(3C++)							     IOS(3C++)

   Operators    [Toc]    [Back]
     Two operators are defined to allow	convenient checking of the error state
     of	an ios:	 operator!() and operator void*().  The	latter converts	an ios
     to	a pointer so that it can be compared to	zero.  The conversion will
     return 0 if failbit or badbit is set in the error state, and will return
     a pointer value otherwise.	 This pointer is not meant to be used.	This
     allows one	to write expressions such as:

	  if ( cin ) ...

	  if ( cin >> x	) ...

     The ! operator returns non-zero if	failbit	or badbit is set in the	error
     state, which allows expressions like the following	to be used:

	  if ( !cout ) ...

   Formatting    [Toc]    [Back]
     An	ios has	a format state that is used by input and output	operations to
     control the details of formatting operations.  For	other operations the
     format state has no particular effect and its components may be set and
     examined arbitrarily by user code.	 Most formatting details are
     controlled	by using the flags(), setf(), and unsetf() functions to	set
     the following flags, which	are declared in	an enumeration in class	ios.
     Three other components of the format state	are controlled separately with
     the functions fill(), width(), and	precision().

	       If skipws is set, whitespace will be skipped on input.  This
	       applies to scalar extractions.  When skipws is not set,
	       whitespace is not skipped before	the extractor begins
	       conversion.  If skipws is not set and a zero length field is
	       encountered, the	extractor will signal an error.	 Additionally,
	       the arithmetic extractors will signal an	error if skipws	is not
	       set and a whitespace is encountered.

	       These flags control the padding of a value.  When left is set,
	       the value is left-adjusted, that	is, the	fill character is
	       added after the value.  When right is set, the value is rightadjusted,
 that is, the fill character is	added before the
	       value.  When internal is	set, the fill character	is added after
	       any leading sign	or base	indication, but	before the value.
	       Right-adjustment	is the default if none of these	flags is set.
	       These fields are	collectively identified	by the static member,
	       ios::adjustfield.  The fill character is	controlled by the
	       fill() function,	and the	width of padding is controlled by the
	       width() function.

									Page 4

IOS(3C++)							     IOS(3C++)

	       These flags control the conversion base of a value.  The
	       conversion base is 10 (decimal) if dec is set, but if oct or
	       hex is set, conversions are done	in octal or hexadecimal,
	       respectively.  If none of these is set, insertions are in
	       decimal,	but extractions	are interpreted	according to the C++
	       lexical conventions for integral	constants.  These fields are
	       collectively identified by the static member, ios::basefield.
	       The manipulators	hex, dec, and oct can also be used to set the
	       conversion base;	see ``Built-in Manipulators'' below.

	       If showbase is set, insertions will be converted	to an external
	       form that can be	read according to the C++ lexical conventions
	       for integral constants.	showbase is unset by default.

	       If showpos is set, then a ``+'' will be inserted	into a decimal
	       conversion of a positive	integral value.

	       If uppercase is set, then an uppercase ``X`` will be used for
	       hexadecimal conversion when showbase is set, or an uppercase
	       ``E'' will be used to print floating point numbers in
	       scientific notation.

	       If showpoint is set, trailing zeros and decimal points appear
	       in the result of	a floating point conversion.

	       These flags control the format to which a floating point	value
	       is converted for	insertion into a stream.  If scientific	is
	       set, the	value is converted using scientific notation, where
	       there is	one digit before the decimal point and the number of
	       digits after it is equal	to the precision (see below), which is
	       six by default.	An uppercase ``E'' will	introduce the exponent
	       if uppercase is set, a lowercase	``e'' will appear otherwise.
	       If fixed	is set,	the value is converted to decimal notation
	       with precision digits after the decimal point, or six by
	       default.	 If neither scientific nor fixed is set, then the
	       value will be converted using either notation, depending	on the
	       value;  scientific notation will	be used	if the exponent
	       resulting from the conversion is	less than -4 or	greater	than
	       or equal	to precision digits.  Otherwise	the value will be
	       converted to decimal notation with precision digits total.  If
	       showpoint is not	set, trailing zeroes are removed from the
	       result and a decimal point appears only if it is	followed by a
	       digit.  scientific and fixed are	collectively identified	by the

									Page 5

IOS(3C++)							     IOS(3C++)

	       static member ios::floatfield.

	       When set, a flush is performed by ostream::osfx() after each
	       insertion.  Unit	buffering provides a compromise	between
	       buffered	output and unbuffered output.  Performance is better
	       under unit buffering than unbuffered output, which makes	a
	       system call for each character output.  Unit buffering makes a
	       system call for each insertion operation, and doesn't require
	       the user	to call	ostream::flush().

	       When set, stdout	and stderr are flushed by ostream::osfx()
	       after each insertion.

     The following functions use and set the format flags and variables.

	       Sets the	``fill character'' format state	variable to c and
	       returns the previous value.  c will be used as the padding
	       character, if one is necessary (see width(), below).  The
	       default fill or padding character is a space.  The positioning
	       of the fill character is	determined by the right, left, and
	       internal	flags; see above.  A parameterized manipulator,
	       setfill,	is also	available for setting the fill character; see

	       Returns the ``fill character'' format state variable.

	       Returns the current format flags.

	       Resets all the format flags to those specified in f and returns
	       the previous settings.

	       Sets the	precision format state variable	to i and returns the
	       previous	value.	This variable controls the number of
	       significant digits inserted by the floating point inserter.
	       The default is 6.  A parameterized manipulator, setprecision,
	       is also available for setting the precision; see	manip(3C++).

	       Returns the precision format state variable.

	       Turns on	in s the format	flags marked in	b and returns the
	       previous	settings.  A parameterized manipulator,	setiosflags,
	       performs	the same function; see manip(3C++).

									Page 6

IOS(3C++)							     IOS(3C++)

	       Resets in s only	the format flags specified by f	to the
	       settings	marked in b, and returns the previous settings.	 That
	       is, the format flags specified by f are cleared in s, then
	       reset to	be those marked	in b.  For example, to change the
	       conversion base in s to be hex, one could write:
	       s<b>.setf(ios::hex,ios::basefield).	 ios::basefield	specifies the
	       conversion base bits as candidates for change, and ios::hex
	       specifies the new value.	 s<b>.setf(0,f<b>) will clear	all the	bits
	       specified by f, as will a parameterized manipulator,
	       resetiosflags; see manip(3C++).

	       Unsets in s the bits set	in b and returns the previous

	       Sets the	field width format variable to i and returns the
	       previous	value.	When the field width is	zero (the default),
	       inserters will insert only as many characters as	necessary to
	       represent the value being inserted.  When the field width is
	       non-zero, the inserters will insert at least that many
	       characters, using the fill character to pad the value, if the
	       value being inserted requires fewer than	field-width characters
	       to be represented.  However, the	numeric	inserters never
	       truncate	values,	so if the value	being inserted will not	fit in
	       field-width characters, more than field-width characters	will
	       be output.  The field width is always interpreted as a mininum
	       number of characters; there is no direct	way to specify a
	       maximum number of characters.  The field-width format variable
	       is reset	to the default (zero) after each insertion or
	       extraction, and in this sense it	behaves	as a parameter for
	       insertions and extractions.  A parameterized manipulator, setw,
	       is also available for setting the width;	see manip(3C++).

	       Returns the field-width format variable.

   User-defined	Format Flags
     Class ios can be used as a	base class for derived classes that require
     additional	format flags or	variables.  The	iostream library provides
     several functions to do this.  The	two static member functions
     ios::xalloc and ios::bitalloc, allow several such classes to be used
     together without interference.

	       Returns a long with a single, previously	unallocated, bit set.
	       This allows users who need an additional	flag to	acquire	one,
	       and pass	it as an argument to ios::setf(), for example.

									Page 7

IOS(3C++)							     IOS(3C++)

	       Returns a previously unused index into an array of words
	       available for use as format state variables by derived classes.

	       When i is an index allocated by ios::xalloc, iword() returns a
	       reference to the	ith user-defined word.

	       When i is an index allocated by ios::xalloc, pword() returns a
	       reference to the	ith user-defined word.	pword()	is the same as
	       iword except that it is typed differently.

   Other members:
	       Returns a pointer to the	streambuf associated with s when s was

	       Solves problems that arise when mixing stdio and	iostreams.
	       The first time it is called it will reset the standard
	       iostreams (cin, cout, cerr, clog) to be streams using
	       stdiobufs.  After that, input and output	using these streams
	       may be mixed with input and output using	the corresponding
	       FILEs (stdin, stdout, and stderr) and will be properly
	       synchronized.  sync_with_stdio()	makes cout and cerr unit
	       buffered	(see ios::unitbuf and ios::stdio above).  Invoking
	       sync_with_stdio() degrades performance a	variable amount,
	       depending on the	length of the strings being inserted (shorter
	       strings incur a larger performance hit).

	       Sets the	tie variable to	osp, and returns its previous value.
	       This variable supports automatic	``flushing'' of	ioss.  If the
	       tie variable is non-null	and an ios needs more characters or
	       has characters to be consumed, the ios pointed at by the	tie
	       variable	is flushed.  By	default, cin is	tied initially to cout
	       so that attempts	to get more characters from standard input
	       result in flushing standard output.  Additionally, cerr and
	       clog are	tied to	cout by	default.  For other ioss, the tie
	       variable	is set to zero by default.

	       Returns the tie variable.

   Built-in Manipulators:
     Some convenient manipulators (functions that take an ios&,	an istream&,
     or	an ostream& and	return their argument; see manip(3C++))	are:
	  These	set the	conversion base	format flag to 10.

									Page 8

IOS(3C++)							     IOS(3C++)

	  These	set the	conversion base	format flag to 16.

	  These	set the	conversion base	format flag to 8.

	       Extracts	whitespace characters.	See istream(3C++).

	       Ends a line by inserting	a newline character and	flushing.  See

	       Ends a string by	inserting a null (0) character.	 See

	       Flushes outs.  See ostream(3C++).

     Several parameterized manipulators	that operate on	ios objects are
     described in manip(3C++):	setw, setfill, setprecision, setiosflags, and

     The streambuf associated with an ios may be manipulated by	other methods
     than through the ios.  For	example, characters may	be stored in a
     queuelike streambuf through an ostream while they are being fetched
     through an	istream.  Or for efficiency some part of a program may choose
     to	do streambuf operations	directly rather	than through the ios.  In most
     cases the program does not	have to	worry about this possibility, because
     an	ios never saves	information about the internal state of	a streambuf.
     For example, if the streambuf is repositioned between extraction
     operations	the extraction (input) will proceed normally.

CAVEATS    [Toc]    [Back]

     The need for sync_with_stdio is a wart.  The old stream package did this
     as	a default, but in the iostream package unbuffered stdiobufs are	too
     inefficient to be the default.

     The stream	package	had a constructor that took a FILE* argument.  This is
     now replaced by stdiostream.  It is not declared even as an obsolete form
     to	avoid having iostream.h	depend on stdio.h.

     The old stream package allowed copying of streams.	 This is disallowed by
     the iostream package.  However, objects of	type istream_withassign,
     ostream_withassign, and iostream_withassign

 Similar pages
Name OS Title
intro IRIX buffering, formatting and input/output
intro IRIX buffering, formatting and input/output
intro IRIX buffering, formatting and input/output
poll IRIX input/output multiplexing
fread IRIX binary input/output
fread_unlocked Tru64 Perform input/output operations
fread Tru64 Perform input/output operations
fread NetBSD binary stream input/output
ioperm Linux set port input/output permissions
fwrite OpenBSD binary stream input/output
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service