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