IOS.INTRO(3C++) IOS.INTRO(3C++)
iostream - buffering, formatting and input/output
#include <iostream.h>
class streambuf ;
class ios ;
class istream : virtual public ios ;
class ostream : virtual public ios ;
class iostream : public istream, public ostream ;
class istream_withassign : public istream ;
class ostream_withassign : public ostream ;
class iostream_withassign : public iostream ;
class Iostream_init ;
extern istream_withassign cin ;
extern ostream_withassign cout ;
extern ostream_withassign cerr ;
extern ostream_withassign clog ;
#include <fstream.h>
class filebuf : public streambuf ;
class fstream : public iostream ;
class ifstream : public istream ;
class ofstream : public ostream ;
#include <strstream.h>
class strstreambuf : public streambuf ;
class istrstream : public istream ;
class ostrstream : public ostream ;
#include <stdiostream.h>
class stdiobuf : public streambuf ;
class stdiostream : public ios ;
The C++ iostream package declared in iostream.h and other header files
consists primarily of a collection of classes. Although originally
intended only to support input/output, the package now supports related
activities such as incore formatting. This package is a mostly sourcecompatible
extension of the earlier stream I/O package, described in The
C++ Programming Language by Bjarne Stroustrup.
In the iostream man pages, character refers to a value that can be held
in either a char or unsigned char. When functions that return an int are
said to return a character, they return a positive value. Usually such
functions can also return EOF (-1) as an error indication. The piece of
memory that can hold a character is referred to as a byte. Thus, either
a char* or an unsigned char* can point to an array of bytes.
Page 1
IOS.INTRO(3C++) IOS.INTRO(3C++)
The iostream package consists of several core classes, which provide the
basic functionality for I/O conversion and buffering, and several
specialized classes derived from the core classes. Both groups of
classes are listed below.
Core Classes
The core of the iostream package comprises the following classes:
streambuf
This is the base class for buffers. It supports insertion
(also known as storing or putting) and extraction (also known
as fetching or getting) of characters. Most members are
inlined for efficiency. The public interface of class
streambuf is described in sbuf.pub(3C++) and the protected
interface (for derived classes) is described in
sbuf.prot(3C++).
ios This class contains state variables that are common to the
various stream classes, for example, error states and
formatting states. See ios(3C++).
istream
This class supports formatted and unformatted conversion from
sequences of characters fetched from streambufs. See
istream(3C++).
ostream
This class supports formatted and unformated conversion to
sequences of characters stored into streambufs. See
ostream(3C++).
iostream
This class combines istream and ostream. It is intended for
situations in which bidirectional operations (inserting into
and extracting from a single sequence of characters) are
desired. See ios(3C++).
istream_withassign
ostream_withassign
iostream_withassign
These classes add assignment operators and a constructor with
no operands to the corresponding class without assignment. The
predefined streams (see below) cin, cout, cerr, and clog, are
objects of these classes. See istream(3C++), ostream(3C++),
and ios(3C++).
Iostream_init
This class is present for technical reasons relating to
initialization. It has no public members. The Iostream_init
constructor initializes the predefined streams (listed below).
Because an object of this class is declared in the iostream.h
header file, the constructor is called once each time the
Page 2
IOS.INTRO(3C++) IOS.INTRO(3C++)
header is included (although the real initialization is only
done once), and therefore the predefined streams will be
initialized before they are used. In some cases, global
constructors may need to call the Iostream_init constructor
explicitly to ensure the standard streams are initialized
before they are used.
Predefined streams [Toc] [Back]
The following streams are predefined:
cin The standard input (file descriptor 0).
cout The standard output (file descriptor 1).
cerr Standard error (file descriptor 2). Output through this stream
is unit-buffered, which means that characters are flushed after
each inserter operation. (See ostream::osfx() in ostream(3C++)
and ios::unitbuf in ios(3C++).)
clog This stream is also directed to file descriptor 2, but unlike
cerr its output is buffered.
cin, cerr, and clog are tied to cout so that any use of these will
cause cout to be flushed.
In addition to the core classes enumerated above, the iostream package
contains additional classes derived from them and declared in other
headers. Programmers may use these, or may choose to define their own
classes derived from the core iostream classes.
Classes derived from streambuf
Classes derived from streambuf define the details of how characters are
produced or consumed. Derivation of a class from streambuf (the
protected interface) is discussed in sbuf.prot(3C++). The available
buffer classes are:
filebuf
This buffer class supports I/O through file descriptors.
Members support opening, closing, and seeking. Common uses do
not require the program to manipulate file descriptors. See
filebuf(3C++).
stdiobuf
This buffer class supports I/O through stdio FILE structs. It
is intended for use when mixing C and C++ code. New code
should prefer to use filebufs. See stdiobuf(3C++).
strstreambuf
This buffer class stores and fetches characters from arrays of
bytes in memory (i.e., strings). See ssbuf(3C++).
IOS.INTRO(3C++) IOS.INTRO(3C++)
Classes derived from istream, ostream, and iostream
Classes derived from istream, ostream, and iostream specialize the core
classes for use with particular kinds of streambufs. These classes are:
ifstream
ofstream
fstream
These classes support formatted I/O to and from files. They
use a filebuf to do the I/O. Common operations (such as
opening and closing) can be done directly on streams without
explicit mention of filebufs. See fstream(3C++).
istrstream
ostrstream
These classes support ``in core'' formatting. They use a
strstreambuf. See strstream(3C++).
stdiostream
This class specializes iostream for stdio FILEs. See
stdiostream.h.
Parts of the streambuf class of the old stream package that should have
been private were public. Most normal usage will compile properly, but
any code that depends on details, including classes that were derived
from streambufs, will have to be rewritten.
Performance of programs that copy from cin to cout may sometimes be
improved by breaking the tie between cin and cout and doing explicit
flushes of cout.
The header file stream.h exists for compatibility with the earlier stream
package. It includes iostream.h, stdio.h, and some other headers, and it
declares some obsolete functions, enumerations, and variables. Some
members of streambuf and ios (not discussed in these man pages) are
present only for backward compatibility with the stream package.
ios(3C++), sbuf.pub(3C++), sbuf.prot(3C++), filebuf(3C++),
stdiobuf(3C++), ssbuf(3C++), istream(3C++), ostream(3C++), fstream(3C++),
strstream(3C++), and manip(3C++)
Page 4
intro(3) intro(3)
intro - introduction to functions and libraries
This section describes functions found in various libraries, other than
those functions that directly invoke IRIX system primitives, which are
described in Section 2 of this volume. Function declarations can be
obtained from the #include files indicated on each page. Certain major
collections are identified by a letter after the section number.
In general, routines in these libraries are not MP or MT (multi-threaded)
safe, and therefore must be explicitly protected by one of the
synchronization primitives in the users code. Exceptions are noted in
the man pages. See section 3P below.
(3C) These functions, together with those of Section 2 and those marked
(3S), constitute the standard C library, libc, which is
automatically linked by the C compilation system. The standard C
library is implemented as a shared object, libc.so.1.
(3G) These functions constitute the IRIS Graphics Library which are
documented in the Graphics Library User's Guide. The -lgl and -lm
flags should be specified to access the graphics library.
Declarations for these functions may be obtained from the include
file <gl.h>. <device.h> and <get.h> define other constants used by
the Graphics Library.
(3M) These functions constitute the Math Library, libm. Use the -lm
option to cc(1) or ld(1) to have the link editor search this
library. Declarations for these functions may be obtained from the
include file <math.h>.
(3S) These functions constitute the ``standard I/O package'' (see
stdio(3S)). These functions are in the standard C library libc,
already mentioned. Declarations for these functions may be
obtained from the include file <stdio.h>.
(3G) These functions constitute the general-purpose library, libgen.
This library is implemented as a shared object and an archive, and
is not automatically linked by the C compilation system. Specify
-lgen on the cc command line to link with this library.
Declarations for these functions may be obtained from the include
file <libgen.h>.
(3B) IRIX supports many 4.3BSD system calls and library routines. To
get the maximum Berkeley compatibility, use the following compile
line:
cc -D_BSD_COMPAT -o prog prog.c -lbsd
-D_BSD_SIGNALS on the compile line specifically selects the
Berkeley signal routines and -D_BSD_TIME selects the Berkeley
Page 1
intro(3) intro(3)
time-of-day routines. Both are a subset of the compatibility
specified by -D_BSD_COMPAT.
The following 4.3BSD standard C Library routines in libbsd have
different arguments or conflicting semantics with the routines in
IRIX libc having the same names: dup2, getgroups, getpgrp,
setgroups, setpgrp. To compile and link a program that calls the
BSD version of any of these routines, use a command of the form:
cc prog.c -lbsd
See the "BSD Compatibility" section below for more details.
(3N) There are actually 3 types of networking in IRIX.
1) BSD sockets implemented in the kernel, along with SUN RPC and
NIS (YP). The functions that implement these calls are in libc
[see (3C) section above].
2) SVR4-style STREAMS/TLI networking (not sockets), along with
SVR4-style RPC. SVR4-style RPC doesn't work with sockets, only
with the TLI. Also, SVR4-style networking does not support NIS
[see intro(3N)]. The functions that implement these calls are in
libnsl, and to use them, the code must be compiled with :
cc -D_SVR4_TIRPC prog.c -lnsl
3) SVR4 emulation of sockets. This is an implementation of
sockets entirely in a library (libsocket) that sits on top of
libnsl. There are no header file differences for libsocket. The
MIPS ABI-compliant programs that use sockets must (in order to be
ABI-compliant) link with libsocket. There is no NIS support for
programs linked with libsocket [see intro(3N)]. To compile such a
program, use:
cc prog.c -lsocket
(3Y) Remote Procedure Call (RPC) and NIS support routines. These
functions are in the standard C library libc, already mentioned.
(3R) Remote Procedure Call services built on top of the Sun RPC protocol.
To compile and link a program that calls any of these routines, use
a command of the form:
cc prog.c -lrpcsvc
(3P) These functions constitute the parallel processing interfaces. They
comprise standard C library thread safe functions and POSIX threads
interfaces. IRIX supports two threading models: sproc(2), process
level threads (IRIX, proprietary) and pthreads(3P) (POSIX threads).
Page 2
intro(3) intro(3)
The models are quite different and cannot interact in the same
program; an sproc program cannot create pthreads and vice-versa.
Thread safe interfaces may be accessed by multiple threads or
processes simultaneously and are guaranteed to behave correctly.
In the sproc model no locking or single threading is done until the
program makes the first call to sproc(). The usconfig(3P) interface
can be used to alter the thread safe behavior of these routines.
Sproc programs wishing to do parallel processing should define the
feature test macros _SGI_MP_SOURCE and _SGI_REENTRANT_FUNCTIONS.
_SGI_MP_SOURCE changes the errno variable from a global to a per
thread private variable. It also makes certain macros and function
prototypes visible.
Pthread programs should enable the thread safe options including
reentrant functions and per thread errno by setting the POSIX
feature test macro, _POSIX_C_SOURCE to the value 199506L or greater;
the file <pthread.h> enables these options automatically.
The following calls have been single threaded so that multiple
shared processes accessing them simultaneously will function
correctly: getc, putc, fgetc, fputc, ungetc, getw, putw, gets,
fgets, puts, fputs, fopen, fdopen, freopen, ftell, rewind, feof,
clearerr, ferror, setbuf, setlinebuf, setbuffer, setvbuf, fclose,
fflush, fread, fwrite, fseek, fgetpos, fsetpos, flockfile,
funlockfile, tempnam, tmpnam, tmpfile, mktemp, mkstemp, popen,
pclose, atexit, printf, fprintf, vprintf, vfprintf, scanf, fscanf,
opendir, readdir, scandir, seekdir, closedir, telldir, dup2, srand,
rand, addsev, addseverity, fmtmsg, setcat, gettxt, lfmt, localeconv,
nl_langinfo, pfmt, setlabel, setlocale, strftime, strxfrm, strcoll,
vlfmt, vpfmt malloc, free, calloc, realloc, mallopt, memalign
acreate, amalloc, afree, acalloc, arealloc, amallopt.
_SGI_REENTRANT_FUNCTIONS enables prototypes and definitions for
reentrant versions of functions that are not thread safe by
definition (usually due to returning pointers to static data).
These alternatives are named func_r and are described on the same
manual page as the original, unsafe version.
Functions that return pointers to static data are not reentrant.
When there is no alternative interface threads must provide their
own synchronization. The following functions have non-obvious
side-effects with respect to reentrancy. setlocale modifies many
tables and static data. In particular, any strings returned by
strerror and gettxt will no longer be valid. setlocale also can
affect other tables such as character class, collating sequence and
numeric separator, which many routines access. To be safe, no
thread should be using any standard C library service when a change
to the locale must be made.
intro(3) intro(3)
(3T) These primitives implement a general terminal interface that
provides control over asynchronous communications ports. These are
all in the standard C library.
(3W) These functions constitute the wide-character library libw. The
functions are used to convert between multibyte and 32-bit wide
characters, respectively. This library is implemented as a shared
object and an archive and is not automatically linked by the C
compilation system. Specify -lw on the cc command line to link with
this library. Declarations for these functions may be obtained from
the include file <widec.h>.
(3X) Various specialized libraries. The files in which these libraries
are found are given on the appropriate pages.
As described in the discussion of Section 3B above,
cc -D_BSD_COMPAT -o prog prog.c -lbsd
selects maximum compatibility with BSD. The -lbsd directive specifies
that libbsd.a be searched before libc.a, which selects the BSD versions
of functions that reside in both libraries (duplicated because of
identical names yet differing semantics or arguments). The routines that
fall into this category are listed in the (3B) section above. The BSD
versions may also be selected on a case-by-case basis by prefixing the
function name with BSD when calling it in the program (e.g. BSDsetpgrp).
Specifying -D_BSD_COMPAT or -D_BSD_SIGNALS on the compile line links with
the BSD versions of the signal routines (kill, killpg, sigblock, signal,
sigpause, sigsetmask, and sigvec). The program must include <signal.h>
or <sys/signal.h>. Note that a "#define _BSD_COMPAT" or "#define
_BSD_SIGNALS" placed in the source program before the inclusion of the
signal header file has the same effect as specifying the corresponding -D
compile option.
Specifying -D_BSD_COMPAT or -D_BSD_TIME on the compile line links with
the BSD versions of the gettimeofday and gettimeofday routines. The
program must include <sys/time.h>. The "#define _BSD_COMPAT" or "#define
_BSD_TIME" must be placed in the source program before the inclusion the
time header file if the -D compile option is not specified.
Defining _BSD_COMPAT gives the following additional BSD compatibility
features over and above that given by _BSD_SIGNALSand _BSD_TIME: you get
the BSD version of setjmp(3) and including <sys/types.h> will cause
several additional macros and typedefs to be defined (e.g. major, minor,
makedev for dealing with device numbers). _BSD_COMPAT may affect more
things in future releases.
The System V and BSD versions of the directory routines (opendir,
seekdir, etc.) differ greatly; inclusion of <dirent.h> at the top of the
your program selects the System V routines, <sys/dir.h> selects the BSD
set. See also directory(3C) and directory_bsd(3B).
Page 4
intro(3) intro(3)
A character [except a multibyte character; see mbchar(3C)] is any bit
pattern able to fit into a byte on the machine. The null character is a
character with value 0, conventionally represented in the C language as
\0. A character array is a sequence of characters. A null-terminated
character array (a string) is a sequence of characters, the last of which
is the null character. A string is a designation for a null-terminated
character array. The null string is a character array containing only
the terminating null character. A NULL pointer is the value that is
obtained by casting 0 into a pointer. C guarantees that this value will
not match that of any legitimate pointer, so many functions that return
pointers return NULL to indicate an error. The macro NULL is defined in
stdio.h. Types of the form size_t are defined in the appropriate header
files.
INCDIR usually /usr/include
LIBDIR usually /usr/lib
LIBDIR<b>/libbsd.a BSD Compatibility library
LIBDIR<b>/libm.a Math library
LIBDIR<b>/libnsl.so Network Services library
LIBDIR<b>/libgen.{so,a} Miscellaneous routines
LIBDIR<b>/libgl.so GL library
LIBDIR<b>/librpcsvc.{so,a} RPC services library
LIBDIR<b>/libsocket.so Sockets Interface library
LIBDIR<b>/libpthread.so POSIX thread library
LIBDIR<b>/libw.{so,a} Wide character library
/usr/lib/libc.so.1 Runtime Linker/Standard C library
ar(1), cc(1), ld(1), nm(1), intro(2), usinit(3P), pthread(3P),
flockfile(3S), stdio(3S)
Graphics Library User's Guide
None of the functions, external variables, or macros should be redefined
in the user's programs. Any other name may be redefined without
affecting the behavior of other library functions, but such redefinition
may conflict with a declaration in an included header file.
The header files in INCDIR provide function prototypes (function
declarations including the types of arguments) for most of the functions
listed in this manual. Function prototypes allow the compiler to check
for correct usage of these functions in the user's program. The lint
program checker may also be used and will report discrepancies even if
the header files are not included with #include statements. Definitions
for Sections 2, 3C, and 3S are checked automatically. Other definitions
can be included by using the -l option to lint. (For example, -lm
includes definitions for libm.) Use of lint is highly recommended.
Users should carefully note the difference between STREAMS and stream.
STREAMS is a set of kernel mechanisms that support the development of
network services and data communication drivers. It is composed of
utility routines, kernel facilities, and a set of data structures. A
stream is a file with its associated buffering. It is declared to be a
Page 5
intro(3) intro(3)
pointer to a type FILE defined in stdio.h.
In detailed definitions of components, it is sometimes necessary to refer
to symbolic names that are implementation-specific, but which are not
necessarily expected to be accessible to an application program. Many of
these symbolic names describe boundary conditions and system limits.
In this section, for readability, these implementation-specific values
are given symbolic names. These names always appear enclosed in curly
brackets to distinguish them from symbolic names of other
implementation-specific constants that are accessible to application
programs by header files. These names are not necessarily accessible to
an application program through a header file, although they may be
defined in the documentation for a particular system.
In general, a portable application program should not refer to these
symbolic names in its code. For example, an application program would
not be expected to test the length of an argument list given to a routine
to determine if it was greater than {ARG_MAX}.
Page 6
intro(3N) intro(3N)
intro - introduction to SVR4 networking functions and libraries
This section describes functions found in the SVR4 networking library.
Function declarations can be obtained from the #include files indicated
on each page. Certain major collections are identified by a letter after
the section number:
The SVR4 networking functions are contained in a single libraries known
as the Network Services library, libnsl.
The following functions constitute the libnsl library:
netdir
Network Directory functions. This contains look-up functions
and the access point to network directory libraries for various
network transports.
netselect
Network Selection routines. These functions manipulate the
/etc/netconfig file and return entries.
nsl Transport Level Interface (TLI). These functions contain the
implementation of X/OPEN's Transport Level Interface.
rexec
REXEC library interface
rpc User-level Remote Procedure Call library
saf Service Access Facility library
yp Network Information Service functions. [The NIS functions have
been moved to libc.]
In the Network Services library, netbuf is a structure used in various
TLI functions to send and receive data and information. netbuf is
defined in sys/tiuser.h, and includes the following members:
struct netbuf {
unsigned int maxlen; /* The physical size of the buffer */
unsigned int len; /* The number of bytes in the buffer */
char *buf; /* Points to user input and/or output buffer */
};
If netbuf is used for output, the function will set the user value of len
on return. maxlen generally has significance only when buf is used to
receive output from the TLI function. In this case, it specifies the
maximum value of len that can be set by the function. If maxlen is not
Page 1
intro(3N) intro(3N)
large enough to hold the returned information, an TBUFOVFLW error will
generally result. However, certain functions may return part of the data
and not generate an error.
INCDIR usually /usr/include
LIBDIR usually /usr/ccs/lib
LIBDIR<b>/libsocket.so (normally unused, see below)
LIBDIR<b>/libnsl.so
intro(3)
None of the functions, external variables, or macros should be redefined
in the user's programs. Any other name may be redefined without
affecting the behavior of other library functions, but such redefinition
may conflict with a declaration in an included header file.
The header files in INCDIR provide function prototypes (function
declarations including the types of arguments) for most of the functions
listed in this manual. Function prototypes allow the compiler to check
for correct usage of these functions in the user's program. The lint
program checker may also be used and will report discrepancies even if
the header files are not included with #include statements. Use of lint
is highly recommended.
In detailed definitions of components, it is sometimes ne
|