1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html 3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5 6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 7<head> 8 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 9 <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> 10 <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" /> 11 <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." /> 12 <meta name="GENERATOR" content="vi and eight fingers" /> 13 <title>libstdc++-v3 HOWTO: Chapter 17: Library Introduction</title> 14<link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> 15<link rel="Start" href="../documentation.html" type="text/html" 16 title="GNU C++ Standard Library" /> 17<link rel="Next" href="../18_support/howto.html" type="text/html" 18 title="Library Support" /> 19<link rel="Copyright" href="license.html" type="text/html" /> 20<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." /> 21</head> 22<body> 23 24<h1 class="centered"><a name="top">Chapter 17: Library Introduction</a></h1> 25 26<p>Chapter 17 is actually a list of definitions and descriptions used 27 in the following chapters of the Standard when describing the actual 28 library. Here, we use "Introduction" as an introduction 29 to the <em>GNU implementation of</em> the ISO Standard C++ Library. 30</p> 31 32 33<!-- ####################################################### --> 34<hr /> 35<h1>Contents</h1> 36<ul> 37 <li><a href="#2">The Standard C++ header files</a></li> 38 <li><a href="#3">The Standard C++ library and multithreading</a></li> 39 <li><a href="#4"><code><foo></code> vs <code><foo.h></code></a></li> 40 <li><a href="porting-howto.html">Porting HOWTO</a></li> 41 <li><a href="#5">Behavior specific to libstdc++-v3</a></li> 42 <li><a href="#6">Preprocessor macros controlling the library</a></li> 43</ul> 44 45<hr /> 46 47<!-- ####################################################### --> 48 49<h2><a name="2">The Standard C++ header files</a></h2> 50 <p>The Standard C++ Library specifies 50 header files that must be 51 available to all hosted implementations. Actually, the word 52 "files" is a misnomer, since the contents of the headers 53 don't necessarily have to be in any kind of external file. The 54 only rule is that when you <code>#include</code> a certain header, the 55 contents of that header, as defined by the Standard, become 56 available to you, no matter how. 57 </p> 58 <p>The names of the headers can be easily seen in 59 <a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>, 60 which is a small testbed we use to make certain that the headers 61 all compile and run. 62 </p> 63 64<hr /> 65<h2><a name="3">The Standard C++ library and multithreading</a></h2> 66 <p>This section discusses issues surrounding the proper compilation 67 of multithreaded applications which use the Standard C++ 68 library. This information is GCC-specific since the C++ 69 standard does not address matters of multithreaded applications. 70 Unless explicitly prefaced, all information in this section is 71 current as of the GCC 3.0 release and all later point releases. 72 </p> 73 <p>Earlier GCC releases had a somewhat different approach to 74 threading configuration and proper compilation. Before GCC 3.0, 75 configuration of the threading model was dictated by compiler 76 command-line options and macros (both of which were somewhat 77 thread-implementation and port-specific). There were no 78 guarantees related to being able to link code compiled with one 79 set of options and macro setting with another set. For GCC 3.0, 80 configuration of the threading model used with libraries and 81 user-code is performed when GCC is configured and built using 82 the --enable-threads and --disable-threads options. The ABI is 83 stable for symbol name-mangling and limited functional 84 compatibility exists between code compiled under different 85 threading models. 86 </p> 87 <p>All normal disclaimers aside, multithreaded C++ application are 88 only supported when libstdc++ and all user code was built with 89 compilers which report (via <code> gcc/g++ -v </code>) the same thread 90 model and that model is not <em>single</em>. As long as your 91 final application is actually single-threaded, then it should be 92 safe to mix user code built with a thread model of 93 <em>single</em> with a libstdc++ and other C++ libraries built 94 with another thread model useful on the platform. Other mixes 95 may or may not work but are not considered supported. (Thus, if 96 you distribute a shared C++ library in binary form only, it may 97 be best to compile it with a GCC configured with 98 --enable-threads for maximal interchangeability and usefulness 99 with a user population that may have built GCC with either 100 --enable-threads or --disable-threads.) 101 </p> 102 <p>When you link a multithreaded application, you will probably 103 need to add a library or flag to g++. This is a very 104 non-standardized area of GCC across ports. Some ports support a 105 special flag (the spelling isn't even standardized yet) to add 106 all required macros to a compilation (if any such flags are 107 required then you must provide the flag for all compilations not 108 just linking) and link-library additions and/or replacements at 109 link time. The documentation is weak. Here is a quick summary 110 to display how ad hoc this is: On Solaris, both -pthreads and 111 -threads (with subtly different meanings) are honored. On OSF, 112 -pthread and -threads (with subtly different meanings) are 113 honored. On Linux/i386, -pthread is honored. On FreeBSD, 114 -pthread is honored. Some other ports use other switches. 115 AFAIK, none of this is properly documented anywhere other than 116 in ``gcc -dumpspecs'' (look at lib and cpp entries). 117 </p> 118 <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a 119 href="../23_containers/howto.html#3">23</a> (containers), and <a 120 href="../27_io/howto.html#9">27</a> (I/O) for more information. 121 </p> 122 <p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not 123 just the STL) has been designed so that multithreaded 124 applications using it may be written. The first problem is 125 finding a <em>fast</em> method of implementation portable to all 126 platforms. Due to historical reasons, some of the library is 127 written against per-CPU-architecture spinlocks and other parts 128 against the gthr.h abstraction layer which is provided by gcc. 129 A minor problem that pops up every so often is different 130 interpretations of what "thread-safe" means for a 131 library (not a general program). We currently use the <a 132 href="http://www.sgi.com/tech/stl/thread_safety.html">same 133 definition that SGI</a> uses for their STL subset. However, the 134 exception for read-only containers only applies to the STL 135 components. 136 </p> 137 <p>Here is a small link farm to threads (no pun) in the mail archives 138 that discuss the threading problem. Each link is to the first 139 relevant message in the thread; from there you can use 140 "Thread Next" to move down the thread. This farm is in 141 latest-to-oldest order. 142 </p> 143 <ul> 144 <li>Our threading expert Loren gives a breakdown of 145 <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the 146 six situations involving threads</a> for the 3.0 release series.</li> 147 <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> 148 This message</a> inspired a recent updating of issues with threading 149 and the SGI STL library. It also contains some example 150 POSIX-multithreaded STL code.</li> 151 </ul> 152 <p> (A large selection of links to older messages has been removed; many 153 of the messages from 1999 were lost in a disk crash, and the few 154 people with access to the backup tapes have been too swamped with work 155 to restore them. Many of the points have been superseded anyhow.) 156 </p> 157 <p>This section will be updated as new and interesting issues come 158 to light. 159 </p> 160 <p>Return <a href="#top">to top of page</a> or 161 <a href="../faq/index.html">to the FAQ</a>. 162 </p> 163 164<hr /> 165<h2><a name="4"><code><foo></code> vs <code><foo.h></code></a></h2> 166 <p>The new-style headers are fully supported in libstdc++-v3. The compiler 167 itself fully supports namespaces, including <code>std::</code>. 168 </p> 169 <p>For those of you new to ISO C++98, no, that isn't a typo, the headers 170 really have new names. Marshall Cline's C++ FAQ Lite has a good 171 explanation in 172<a href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item [27.4]</a>. 173 </p> 174 <p>Return <a href="#top">to top of page</a> or 175 <a href="../faq/index.html">to the FAQ</a>. 176 </p> 177 178<hr /> 179<h2><a name="5">Behavior specific to libstdc++-v3</a></h2> 180 <p>The ISO standard defines the following phrase: 181 </p> 182 <blockquote><dl> 183 <dt><code>[1.3.5] implementation-defined behavior</code></dt> 184 <dd>behavior, for a well-formed program construct and correct data, that 185 depends on the implementation <strong>and that each implementation 186 shall document</strong>. 187 </dd> 188 </dl></blockquote> 189 <p>We do so here, for the C++ library only. Behavior of the compiler, 190 linker, runtime loader, and other elements of "the 191 implementation" are documented elsewhere. Everything listed in 192 Annex B, Implementation Qualities, are also part of the compiler, not 193 the library. 194 </p> 195 <p>For each entry, we give the section number of the standard, when 196 applicable. This list is probably incomplet and inkorrekt. 197 </p> 198 <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then 199 interactive stream support is implied. 200 </p> 201 <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best 202 discussed in the various sections on multithreading (see above). 203 </p> 204 <!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec 205 can throw whatever we want; see also its footnote. Let's list those 206 in the sections where the function itself occurs. 207 --> 208 <p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described 209 <a href="../18_support/howto.html#1">here</a>. 210 </p> 211 <p><strong>[18.3]/8</strong> Even though it's listed in the library 212 sections, libstdc++-v3 has zero control over what the cleanup code hands 213 back to the runtime loader. Talk to the compiler people. :-) 214 </p> 215 <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br /> 216 <strong>[18.5.2]/5</strong> (bad_cast),<br /> 217 <strong>[18.5.3]/5</strong> (bad_typeid),<br /> 218 <strong>[18.6.1]/8</strong> (exception),<br /> 219 <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code> 220 member function of class <code>std::exception</code>, and these other 221 classes publicly derived from it, simply returns the name of the 222 class. But they are the <em>mangled</em> names; you will need to call 223 <code>c++filt</code> and pass the names as command-line parameters to 224 demangle them, or call a 225 <a href="../18_support/howto.html#5">runtime demangler function</a>. 226 (The classes in <code><stdexcept></code> have constructors which 227 require an argument to use later for <code>what()</code> calls, so the 228 problem of <code>what()</code>'s value does not arise in most 229 user-defined exceptions.) 230 </p> 231 <p><strong>[18.5.1]/7</strong> The return value of 232 <code>std::type_info::name()</code> is the mangled type name (see the 233 previous entry for more). 234 </p> 235 <p><strong>[20.1.5]/5</strong> <em>"Implementors are encouraged to 236 supply libraries that can accept allocators that encapsulate more 237 general memory models and that support non-equal instances. In such 238 implementations, any requirements imposed on allocators by containers 239 beyond those requirements that appear in Table 32, and the semantics 240 of containers and algorithms when allocator instances compare 241 non-equal, are implementation-defined."</em> As yet we don't 242 have any allocators which compare non-equal, so we can't describe how 243 they behave. 244 </p> 245 <p><strong>[21.1.3.1]/3,4</strong>,<br /> 246 <strong>[21.1.3.2]/2</strong>,<br /> 247 <strong>[23.*]'s foo::iterator</strong>,<br /> 248 <strong>[27.*]'s foo::*_type</strong>,<br /> 249 <strong>others...</strong> 250 Nope, these types are called implementation-defined because you 251 shouldn't be taking advantage of their underlying types. Listing them 252 here would defeat the purpose. :-) 253 </p> 254 <p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t 255 stuff... see the <a href="../22_locale/howto.html">chapter 22 notes</a> 256 for what does exist. 257 </p> 258 <p><strong>[22.*]</strong> Anything and everything we have on locale 259 implementation will be described 260 <a href="../22_locale/howto.html">over here</a>. 261 </p> 262 <p><strong>[26.2.8]/9</strong> I have no idea what 263 <code>complex<T></code>'s pow(0,0) returns. 264 </p> 265 <p><strong>[27.4.2.4]/2</strong> Calling 266 <code>std::ios_base::sync_with_stdio</code> after I/O has already been 267 performed on the standard stream objects will 268 flush the buffers, and <!-- this line might go away --> 269 destroy and recreate the underlying buffer instances. Whether or not 270 the previously-written I/O is destroyed in this process depends mostly 271 on the --enable-libio choice: for stdio, if the written data is 272 already in the stdio buffer, the data may be completely safe! 273 </p> 274 <p><strong>[27.6.1.1.2]</strong>,<br /> 275 <strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform 276 additional work than the minimum required. We are not currently taking 277 advantage of this yet. 278 </p> 279 <p><strong>[27.7.1.3]/16</strong>,<br /> 280 <strong>[27.8.1.4]/10</strong> 281 The effects of <code>pubsetbuf/setbuf</code> are described 282 <a href="../27_io/howto.html#2">in this chapter</a>. 283 </p> 284 <p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when 285 a get area exists will... whatever <code>fflush()</code> does, I think. 286 </p> 287 <p>Return <a href="#top">to top of page</a> or 288 <a href="../faq/index.html">to the FAQ</a>. 289 </p> 290 291<hr /> 292<h2><a name="6">Preprocessor macros controlling the library</a></h2> 293 <p>Some of the semantics of the libstdc++-v3 implementation are 294 controlled by preprocessor macros, both during build/installation and 295 during compilation of user code. Many of these choices are made when 296 the library is built and installed (actually, during 297 <a href="../configopts.html">the configuration step</a>, with the 298 various --enable/--disable choices being translated to #define/#undef). 299 </p> 300 <p>All library macros begin with <code>_GLIBCPP_</code> in earlier 301 versions, and <code>_GLIBCXX_</code> in later versions. The fact that 302 these symbols start with a leading underscore should give you a clue 303 that (by default) they aren't meant to be changed by the user. :-) 304 </p> 305 <p>These macros are all gathered in the file <code>c++config.h</code>, 306 which is generated during installation. <strong>You must assume that 307 these macros cannot be redefined by your own code</strong>, unless we 308 document otherwise here. Some of the choices control code which has 309 already been compiled (i.e., libstdc++.a/.so). If you explicitly 310 #define or #undef these macros, the <em>headers</em> may see different 311 code paths, but the <em>libraries</em> which you link against will not. 312 If you want to experiment with different values, you must change the 313 config headers before building/installing the library. 314 </p> 315 <p>Below are macros which, for 3.1 and later, you may change yourself, 316 in your own code with #define/#undef or with -D/-U compiler flags. 317 The default state of the symbol is listed. "Configurable" 318 (or "Not configurable") means that the symbol is initially 319 chosen (or not) based on --enable/--disable options at configure time. 320 For 3.1 through 3.3, the prefixes are <code>_GLIBCPP_</code>. 321 </p> 322 <dl> 323 <dt><code>_GLIBCXX_DEPRECATED</code></dt> 324 <dd>Undefined by default. Not configurable. Turning this on enables 325 older ARM-style iostreams code, and other anachronisms. This may be 326 useful in updating old C++ programs which no longer meet the 327 requirements of the language. 328 </dd> 329 <!-- 330 Can this actually be turned off and still produce a working lib? Must 331 check. -pme 332 No, it can't. Hmmm. -pme 333 <dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt> 334 <dd>Defined by default. Not configurable. The library follows 335 corrections and updates from the ISO committee, see 336 <a href="../faq/index.html#5_2">here</a> and 337 <a href="../ext/howto.html#5">here</a> for more on this feature. 338 If you have code which depends on the first version of the standard, 339 you might try undefining this macro. 340 </dd> 341 --> 342 <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> 343 <dd>Undefined by default. Configurable. When defined, performs 344 compile-time checking on certain template instantiations to detect 345 violations of the requirements of the standard. This is described 346 in more detail <a href="../19_diagnostics/howto.html#3">here</a>. 347 </dd> 348 <dt><code>_GLIBCXX_DEBUG</code></dt> 349 <dd>Undefined by default. Configurable. When defined, compiles 350 user code using the <a href="../debug.html#safe">libstdc++ debug 351 mode</a>. 352 </dd> 353 <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt> 354 <dd>Undefined by default. Configurable. When defined while 355 compiling with the <a href="../debug.html#safe">libstdc++ debug 356 mode</a>, makes the debug mode extremely picky by making the use 357 of libstdc++ extensions and libstdc++-specific behavior into 358 errors. 359 </dd> 360 <!-- 361 <dt><code></code></dt> 362 <dd> 363 </dd> 364 --> 365 </dl> 366 <p>Return <a href="#top">to top of page</a> or 367 <a href="../faq/index.html">to the FAQ</a>. 368 </p> 369 370 371 372<!-- ####################################################### --> 373 374<hr /> 375<p class="fineprint"><em> 376See <a href="license.html">license.html</a> for copying conditions. 377Comments and suggestions are welcome, and may be sent to 378<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. 379</em></p> 380 381 382</body> 383</html> 384 385 386