libg++.texinfo

早期freebsd实现

@{
  record r;
  SFile recfile("mydatafile", sizeof(record), ios::in|ios::out);
  recfile.raw();
  for (int i = 0; i < 10; ++i)  // ... write some out
  @{    
    r = something();
    recfile.put(&r);            // use '&r' for proper coercion
  @}
  for (i = 9; i >= 0; --i)      // now use them in reverse order
  @{
    recfile[i].get(&r);
    do_something_with(r);
  @}
@}
@end smallexample

@section The PlotFile Class

Class @code{PlotFile} is a simple derived class of @code{ofstream}
that may be used to produce files in Unix plot format.  Public
functions have names corresponding to those in the @code{plot(5)}
manual entry. 

@section C standard I/O

There is a complete implementation of the ANSI C stdio library
that is built on @emph{top} of the iostream facilities.
Specifically, the type @code{FILE} is the same as the @code{streambuf} class.
Also, the standard files are identical to the standard streams:
@code{stdin == cin.rdbuf()}.  This means that you don't have to
synchronize C++ output with C output.  It also means that C programs
can use some of the specialized sub-classes of streambuf.

The stdio library (@code{libstdio++})is not normally installed, because
of some difficulties when used with the C libraries version of stdio.
The stdio library provides binary compatibility with traditional
implementation.  Unfortunately, it takes a fair amount of care to avoid
duplicate definitions when linking with both @code{libstdio++}
and the C library.

@node Stream, Obstack, IOStream, Top
@chapter The old I/O library

WARNING: This chapter describes classes that are @emph{obsolete}.
These classes are normally not available when libg++
is installed normally.  The sources are currently included
in the distribution, and you can configure libg++ to use
these classes instead of the new iostream classes.
This is only a temporary measure; you should convert your
code to use iostreams as soon as possible.  The iostream
classes provide some compatibility support, but it is
very incomplete (there is no longer a @code{File} class).

@section File-based classes
   
The @code{File} class supports basic IO on Unix files.  Operations are
based on common C stdio library functions.

@code{File} serves as the base class for istreams, ostreams, and other
derived classes. It contains the interface between the Unix stdio file
library and these more structured classes.  Most operations are implemented
as simple calls to stdio functions. @code{File} class operations are also fully
compatible with raw system file reads and writes (like the system
@code{read} and @code{lseek} calls) when buffering is disabled (see below).
The @code{FILE*} stdio file pointer is, however maintained as protected.
Classes derived from File may only use the IO operations provided by File,
which encompass essentially all stdio capabilities.

The class contains four general kinds of functions: methods for binding
@code{File}s to physical Unix files, basic IO methods, file and buffer
control methods, and methods for maintaining logical and physical file
status.


Binding and related tasks are accomplished via @code{File} constructors and
destructors, and member functions @code{open, close, remove, filedesc,
name, setname}.

If a file name is provided in a constructor or open, it is
maintained as class variable @code{nm} and is accessible
via @code{name}.  If no name is provided, then @code{nm} remains
null, except that @code{Files} bound to the default files stdin,
stdout, and stderr are automatically given the names
@code{(stdin), (stdout), (stderr)} respectively.  
The function @code{setname} may be used to change the
internal name of the @code{File}. This does not change the name
of the physical file bound to the File.
      
The member function @code{close} closes a file.  The
@code{~File} destructor closes a file if it is open, except
that stdin, stdout, and stderr are flushed but left open for
the system to close on program exit since some systems may
require this, and on others it does not matter.  @code{remove}
closes the file, and then deletes it if possible by calling the
system function to delete the file with the name provided in
the @code{nm} field.

@section Basic IO

@itemize @bullet

@item 
@code{read} and @code{write} perform binary IO via stdio
@code{fread} and @code{fwrite}.

@item 
@code{get} and @code{put} for chars invoke stdio @code{getc}
and @code{putc} macros.

@item 
@code{put(const char* s)} outputs a null-terminated string via
stdio @code{fputs}.

@item 
@code{unget} and @code{putback} are synonyms.  Both call stdio
@code{ungetc}.

@end itemize

@section File Control

@code{flush}, @code{seek}, @code{tell}, and @code{tell} call the
corresponding stdio functions.

@code{flush(char)} and @code{fill()} call stdio @code{_flsbuf}
and @code{_filbuf} respectively.

@code{setbuf} is mainly useful to turn off buffering in cases
where nonsequential binary IO is being performed. @code{raw} is a
synonym for @code{setbuf(_IONBF)}.  After a @code{f.raw()}, using
the stdio functions instead of the system @code{read, write},
etc., calls entails very little overhead.  Moreover, these become
fully compatible with intermixed system calls (e.g.,
@code{lseek(f.filedesc(), 0, 0)}). While intermixing @code{File}
and system IO calls is not at all recommended, this technique
does allow the @code{File} class to be used in conjunction with
other functions and libraries already set up to operate on file
descriptors. @code{setbuf} should be called at most once after a
constructor or open, but before any IO.

@section File Status

File status is maintained in several ways. 

A @code{File} may be checked for accessibility via
@code{is_open()}, which returns true if the File is bound to a
usable physical file, @code{readable()}, which returns true if
the File can be read from (opened for reading, and not in a
_fail state), or @code{writable()}, which returns true if the
File can be written to.

@code{File} operations return their status via two means: failure and
success are represented via the logical state. Also, the
return values of invoked stdio and system functions that
return useful numeric values (not just failure/success flags)
are held in a class variable accessible via @code{iocount}.
(This is useful, for example, in determining the number of
items actually read by the @code{read} function.)

Like the AT&T i/o-stream classes, but unlike the description in
the Stroustrup book, p238, @code{rdstate()} returns the bitwise
OR of @code{_eof}, @code{_fail} and @code{_bad}, not necessarily
distinct values. The functions @code{eof()}, @code{fail()},
@code{bad()}, and @code{good()} can be used to test for each of
these conditions independently.

@code{_fail} becomes set for any input operation that could not
read in the desired data, and for other failed operations. As
with all Unix IO, @code{_eof} becomes true only when an input
operations fails because of an end of file. Therefore,
@code{_eof} is not immediately true after the last successful
read of a file, but only after one final read attempt. Thus, for
input operations, @code{_fail} and @code{_eof} almost always
become true at the same time.  @code{bad} is set for unbound
files, and may also be set by applications in order to communicate
input corruption. Conversely, @code{_good} is defined as 0 and
is returned by @code{rdstate()} if all is well.

The state may be modified via @code{clear(flag)}, which,
despite its name, sets the corresponding state_value flag.
@code{clear()} with no arguments resets the state to @code{_good}.
@code{failif(int cond)} sets the state to @code{_fail} only if
@code{cond} is true.  

Errors occuring during constructors and file opens also invoke the
function @code{error}.  @code{error} in turn calls a resetable error
handling function pointed to by the non-member global variable
@code{File_error_handler} only if a system error has been generated.
Since @code{error} cannot tell if the current system error is actually
responsible for a failure, it may at times print out spurious messages.
Three error handlers are provided. The default,
@code{verbose_File_error_handler} calls the system function
@code{perror} to print the corresponding error message on standard
error, and then returns to the caller.  @code{quiet_File_error_handler}
does nothing, and simply returns.  @code{fatal_File_error_handler}
prints the error and then aborts execution. These three handlers, or any
other user-defined error handlers can be selected via the non-member
function @code{set_File_error_handler}.

All read and write operations communicate either logical or
physical failure by setting the @code{_fail} flag.  All further
operations are blocked if the state is in a @code{_fail} or@code{_bad}
condition. Programmers must explicitly use @code{clear()} to
reset the state in order to continue IO processing after
either a logical or physical failure.  C programmers who are
unfamiliar with these conventions should note that, unlike
the stdio library, @code{File} functions indicate IO success,
status, or failure solely through the state, not via return values of
the functions.  The @code{void*} operator or @code{rdstate()}
may be used to test success.  In particular, according to c++
conversion rules, the @code{void*} coercion is automatically
applied whenever the @code{File&} return value of any @code{File}
function is tested in an @code{if} or @code{while}.  Thus,
for example, an easy way to copy all of stdin to stdout until
eof (at which point @code{get} fails) or some error is
@code{char c; while(cin.get(c) && cout.put(c));}.

@ignore
@section The istream and ostream classes

Some of these are supported by incorporating additional,
mainly virtual, functions into streambufs:

@table @code

@item streambuf::open([various args])
attaches the streambuf to a file, if applicable

@item streambuf::close()
detaches the streambuf from a file, if applicable.

@item streambuf::sputs(const char* s)
outputs null-terminated string s in a generally faster way
than repeated @code{sputcs}.

@item streambuf::sputsn(const char* s, int n)
outputs the first n characters of s in a generally faster way
than repeated @code{sputcs}.

@end table
@end ignore

The current version of istreams and ostreams differs significantly
from previous versions in order to obtain compatibility with
AT&T 1.2 streams. Most code using previous versions should still
work. However, the following features of @code{File} are not
incorporated in streams (they are still present in @code{File}):
@code{scan(const char* fmt...), remove(), read(), write(),
setbuf(), raw()}. Additionally, the feature of previous streams
that allowed free intermixing of stream and stdio input and output
is no longer guaranteed to always behave as desired.

@node Obstack, AllocRing, Stream, Top
@chapter The Obstack class


The @code{Obstack} class is a simple rewrite of the C obstack macros and
functions provided in the GNU CC compiler source distribution.  

Obstacks provide a simple method of creating and maintaining a string
table, optimized for the very frequent task of building strings
character-by-character, and sometimes keeping them, and sometimes
not. They seem especially useful in any parsing application. One of the
test files demonstrates usage.

A brief summary:
@table @code

@item grow   
places something on the obstack without committing to wrap 
it up as a single entity yet.

@item finish 
wraps up a constructed object as a single entity, 
and returns the pointer to its start address.

@item copy   
places things on the obstack, and @emph{does} wrap them up.
@code{copy} is always equivalent to first grow, then finish.

@item free   
deletes something, and anything else put on the obstack since its creation.
@end table

The other functions are less commonly needed:
@table @code
@item blank
is like grow, except it just grows the space by size units
without placing anything into this space
@item alloc
is like @code{blank}, but it wraps up the object and returns its starting
address. 
@item chunk_size, base, next_free, alignment_mask, size, room
returns the appropriate class variables.
@item grow_fast
places a character on the obstack without checking if there is enough room.
@item blank_fast
like @code{blank}, but without checking if there is enough room.
@item shrink(int n)
shrink the current chunk by n bytes.
@item contains(void* addr)
returns true if the Obstack holds the address addr.
@end table

Here is a lightly edited version of the original C documentation:

These functions operate a stack of objects.  Each object starts life
small, and may grow to maturity.  (Consider building a word syllable
by syllable.)  An object can move while it is growing.  Once it has
been ``finished'' it never changes address again.  So the ``top of the
stack'' is typically an immature growing object, while the rest of the
stack is of mature, fixed size and fixed address objects.

These routines grab large chunks of memory, using the GNU C++ @code{new}
operator.  On occasion, they free chunks, via @code{delete}.

Each independent stack is represented by a Obstack.

One motivation for this package is the problem of growing char strings
in symbol tables.  Unless you are a ``fascist pig with a read-only mind''
[Gosper's immortal quote from HAKMEM item 154, out of context] you
would not like to put a