Author: pme@gcc.gnu.org (Phil Edwards)
Description: Explanatory notes about libstdc++-v3.
Keywords: libstdc++, libstdc++-v3, GCC, g++

# Explanatory notes about libstdc++-v3 design

The latest version of this document is always available at http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html.

To the libstdc++-v3 homepage.

### "I/O packages", `--enable-cstdio`

In addition to all the nifty things which C++ can do for I/O, its library also includes all of the I/O capabilites of C. Making them work together can be a challenge, not only for the programmer but for the implementors as well.

There are two ways to do a C++ library: the cool way, and the easy way. More specifically, the cool-but-easy-to-get-wrong way, and the easy-to-guarantee-correct-behavior way. For 3.0, the easy way is used.

Choosing 'stdio' is the easy way. It builds a C++ library which forwards all operations to the C library. Many of the C++ I/O functions are specified in the standard 'as if' they called a certain C function; the easiest way to get it correct is to actually call that function. The disadvantage is that the C++ code will run slower (fortunately, the layer is thin).

Choosing 'libio' is the cool way; it allows C++ and C to share some buffers. It's disabled because of tricky synchronization issues. Other cool ways (various methods of sharing resources between C and C++ facilities, instead of layering) are possible. This approach can speed up I/O significantly.

Other packages are possible. For a new package, a header must be written to provide types like streamsize (usually just a typedef), as well as some internal types like`__c_file_type` and `__c_lock` (for the stdio case, these are FILE (as in "FILE*") and a simple POSIX mutex, respectively). An interface class called `__basic_file` must also be filled in; as an example, for the stdio case, these member functions are all inline calles to fread, fwrite, etc.

Return to the top of the page or to the homepage.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.