Home

The GNU C++ Library

1. GLIBCXX_WRITE_MEM_BARRIER Which expand to the appropriate write and read barrier required by the host hardware and operating system 28 2 Implementation 28 2 1 Using Builtin Atomic Functions The functions for atomic operations described above are either implemented via compiler intrinsics 1f the underlying host is capable or by library fallbacks Compiler intrinsics builtins are always preferred However as the compiler builtins for atomics are not universally implemented using them directly is problematic and can result in undefined function calls An example of an undefined symbol from the use of __sync_fetch_and_add on an unsupported host is a missing reference to___ sync__fet ch_and_add_4 In addition on some hosts the compiler intrinsics are enabled conditionally via the march command line flag This makes usage vary depending on the target hardware and the flags used during compile If builtins are possible for bool sized integral types GLIBCXX_ATOMIC_BUILTINS_1 will be defined If builtins are possi ble for int sized integral types _GLIBCXX_ATOMIC_BUILTINS_4 will be defined For the following hosts intrinsics are enabled by default The GNU C Library 152 253 e alpha e 1264 e powerpc e 5390 For others some form of march may work On non ancient x86 hardware march nat ive usually does the trick For hosts without compiler intrinsics but with capable hardware h
2. include lt cassert gt include lt ccomplex gt include lt cctype gt include lt cerrno gt include lt cfenv gt include lt cfloat gt include lt cinttypes gt include lt ciso646 gt include lt climits gt include lt clocale gt include lt cmath gt include lt csetjmp gt include lt csignal gt include lt cstdarg gt include lt cstdbool gt include lt cstddef gt include lt cstdint gt include lt cstdio gt include lt cstdlib gt include lt cstring gt include lt ctgmath gt include lt ctime gt include lt cwchar gt 234 253 The GNU C Library 235 253 include lt cwctype gt include lt algorithm gt include lt array gt include lt bitset gt include lt complex gt include lt deque gt include lt exception gt include lt fstream gt include lt functional gt include lt iomanip gt include lt ios gt include lt iosfwd gt include lt iostream gt include lt istream gt include lt iterator gt include lt limits gt include lt list gt include lt locale gt include lt map gt include lt memory gt include lt new gt include lt numeric gt include lt ostream gt include lt queue gt include lt random gt include lt regex gt include lt set gt include lt sstream gt include lt stack gt include lt stdexcept gt include lt streambuf gt include lt string gt include lt tuple gt include lt typeinfo gt include lt type_tra
3. At this time there are a few libstdc specific macros which may be defined _GLIBCXX_USE_C99_CHECK may be defined to 1 to check C99 function declarations which are not covered by specialization below found in system headers against versions found in the library headers derived from the standard _GLIBCXX_USE_C99_DYNAMIC may be defined to an expression that yields 0 if and only if the system headers are exposing proper support for C99 functions which are not covered by specialization below If defined it must be O while bootstrapping the compiler rebuilding the library The GNU C Library 193 253 _GLIBCXX_USE_C99_LONG_LONG_CHECK may be defined to 1 to check the set of C99 long long function declarations found in system headers against versions found in the library headers derived from the standard T _GLIBCXX_USE_C99_LONG_LONG_DYNAMIC may be defined to an expression that yields 0 if and only if the system headers are exposing proper support for the set of C99 long long functions If defined it must be O while bootstrapping the compiler re building the library T _GLIBCXX_USE_C99_FP_MACROS_DYNAMIC may be defined to an expression that yields 0 if and only if the system headers are exposing proper support for the related set of macros If defined it must be 0 while bootstrapping the compiler rebuilding the library _GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK may be defined to to c
4. argument_error const std string amp s std runtime_error s The GNU C Library 41 253 y int main int argc std set_terminate __gnu_cxx __verbose_terminate_handler alice terce gt 6 throw argument_error argc is greater than 5 else throw argc With the verbose terminate handler active this gives B as OE terminate called after throwing a int Aborted ES ELE OMS dE Gh dE G2 at dE dE dE at af dE terminate called after throwing an instance of argument_error what argc is greater than 5 Aborted The Aborted line comes from the call to abort of course This is the default termination handler nothing need be done to use it To go back to the previous silent death method simply include exception and cstdlib and call std set_terminate std abort After this all calls to terminate will use abort as the terminate handler Note the verbose terminate handler will attempt to write to stderr If your application closes stderr or redirects it to an inappro priate location __ verbose_terminate_handler will behave in an unspecified manner The GNU C Library 42 253 Chapter 5 Diagnostics 5 1 Exceptions 5 1 1 API Reference All exception objects are defined in one of the standard header files exception stdexcept new and typeinfo The base exception object is exception located in exception This object has no st ring member
5. e The storage is obtained by calling operator new but it is unspecified when or how often this function is called The use of the hint is unspecified but intended as an aid to locality if an implementation so desires 20 4 1 1 6 Complete details can be found in the C standard look in 20 4 Memory 6 3 1 2 Design Issues The easiest way of fulfilling the requirements is to call operator new each time a container needs memory and to call operator delete each time the container releases memory This method may be slower than caching the allocations and re using previously allocated memory but has the advantage of working correctly across a wide variety of hardware and operating systems including large clusters The __gnu_cxx new_allocator implements the simple operator new and operator delete semantics while __ gnu_cxx malloc_allocator implements much the same thing only with the C language functions std malloc and free Another approach is to use intelligence within the allocator class to cache allocations This extra machinery can take a variety of forms a bitmap index an index into an exponentially increasing power of two sized buckets or simpler fixed size pooling cache The cache is shared among all the containers in the program when your program s std vector lt int gt gets cut in half and frees a bunch of its storage that memory can be reused by the private std 1ist lt WonkyWidget gt brought in from a KDE libra
6. with gxx include dir lt include files dir gt Adds support for named libstdc include directory For in stance the following puts all the libstdc headers into a directory called 4 4 20090404 instead of the usual c version with gxx include dir foo0 H x86 gcc 3 c gxx inc include 4 4 20090404 enable cstdio This is an abbreviated form of enable cstdio stdio described next enable cstdio OPTION Select a target specific I O package At the moment the only choice is to use stdio a generic C abstraction The default is stdio This option can change the library ABI enable clocale This is an abbreviated form of enable clocale generic described next enable clocale OPTION Select a target specific underlying locale package The choices are ieee_1003 1 2001 to specify an X Open Standard Unix IEEE Std 1003 1 2001 model based on langinfo iconv catgets gnu to specify a model based on functionality from the GNU C library langinfo iconv gettext from glibc the GNU C library or generic to use a generic C abstraction which consists of C locale info If not explicitly specified the configure proccess tries to guess the most suitable package from the choices above The default is generic On glibc based systems of sufficient vintage 2 2 5 and newer and capability with installed DE and FR locale data gnu is automatically selected This option can change
7. 13 Bjarne Stroustrup The C Programming Language Copyright O 2000 19 4 Allocators Addison Wesley 14 Felix Yen Yalloc A Recycling C Allocator isoct _1998 ISO IEC 14882 1998 Programming languages C 20 4 Memory 6 3 2 auto_ptr 6 3 2 1 Limitations Explaining all of the fun and delicious things that can happen with misuse of the auto_ptr class template called AP here would take some time Suffice it to say that the use of AP safely in the presence of copying has some subtleties The AP class is a really nifty idea for a smart pointer but it is one of the dumbest of all the smart pointers and that s fine AP is not meant to be a supersmart solution to all resource leaks everywhere Neither is it meant to be an effective form of garbage collection although it can help a little bit And it can notbe used for arrays AP is meant to prevent nasty leaks in the presence of exceptions That s all This code is AP friendly The GNU C Library 49 253 Not a recommend naming scheme but good for web based FAQs typedef std auto_ptr lt MyClass gt APMC extern function_taking_MyClass_pointer MyClassx extern some_throwable_function wola func int data APMC ap new MyClass data some_throwable_function this will throw an exception function_taking_MyClass_pointer ap get When an exception gets thrown the instance of MyClass that s been created on the heap will be del
8. Like so std sort v begin v end __gnu_parallel sequential_tag Some parallel algorithm variants can be excluded from compilation by preprocessor defines See the doxygen documentation on compiletime_settings hand features h for details For some algorithms the desired variant can be chosen at compile time by appending a tag object The available options are specific to the particular algorithm class For the embarrassingly parallel algorithms there is only one tag object type the enum _Parallelism It takes one of the following values __gnu_parallel parallel_tag gnu_parallel balanced_tag gnu_parallel unbalanced_tag gnu_parallel omp_loop_tag gnu_parallel omp_loop_static_tag This means that the actual parallelization strategy is chosen at run time Choosing the variants at compile time will come soon For the following algorithms in general we have __gnu_parallel parallel_tagand__gnu_parallel defa ult_parallel_tag in addition to __gnu_parallel seguential_tag __gnu_parallel default_par allel_tag chooses the default algorithm at compiletime as does omitting the tag __gnu_parallel parallel_tag postpones the decision to runtime see next section For all tags the number of threads desired for this call can optionally be passed to the respective tag s constructor The multiway_merge algorithm comes with the additional choices __gnu_parallel exact_tag
9. The GNU C Library de_AT utf 8 de_AT utf8 euro de_BE de_BE euro de_BE utf 8 de BI de_C de_C de_D de DI de_DI de DI de_L de_LU euro de_LU ut 8 euro AUS 5 e A o a cs c a Ie a Ln foe E de_LU ut 8 euro el_GR el_GR utf8 en_AU en_AU utf8 en_BW en_BW ut 8 en_CA en_CA utf8 en_DK en_DK utf 8 en_GB en_GB iso885915 en_GB utf8 en_HK en_HK ut 8 en_I en_I en_I en_T en_I en_NZ en_NZ utf8 en_PH en_PH utf8 en_SG en_SG utf8 en_US euro tf8 AoA Z E U 4 en_US iso885915 en_US utf8 en_ZA en_ZA ut 8 en_Zw en_ZW ut 8 es_AR es_AR ut 8 es_BO es_BO utf8 es_CL es_CL utf8 es_CO es_CO ut 8 es_CR es_CR utf8 es_DO es_DO utf8 es_EC utf 8 euro utf 8 euro tf8 euro 62 253 The GNU C E G C D a aves Mea e a S a ea ea Ea nn 0 n E QQ H H oO un ja Z es_HN u 9 Fl El 0 oe sal Eal C 9p uu tE SE aa at Fh ir H Dw dal JP IE fi_FI e Ie NIL UL e 19 TL 0 fo_FO Hh iv TS O C _BE e jes deal eal eal sill Eu Fh 5 EST MES all OE O Q w w w w Hh P j JTT a fr_FR e Iie JO ie ING Ul Er IU fr_LU e ice IU 501 Ee 1070 701 ga_IE ga_IE e SS ih o Ul a Ja bl Library ES uro t 8 t 8 euro EES t 8 t 8 t 8 t 8 t 8 t 8 t 8 t 8 t 8 t 8 t 8 t 8 uro
10. The GNU C Library 240 253 Finally every program is threatened constantly by software patents States should not allow patents to restrict development and use of software on general purpose computers but in those that do we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary To prevent this the GPL assures that patents cannot be used to render the program non free The precise terms and conditions for copying distribution and modification follow TERMS AND CONDITIONS 0 Definitions This License refers to version 3 of the GNU General Public License Copyright also means copyright like laws that apply to other kinds of works such as semiconductor masks The Program refers to any copyrightable work licensed under this License Each licensee is addressed as you Licensees and recipients may be individuals or organizations To modify a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission other than the making of an exact copy The resulting work is called a modified version of the earlier work or a work based on the earlier work A covered work means either the unmodified Program or a work based on the Program To propagate a work means to do anything with it that without permission would make you directly or secondarily liable for infringement under applica
11. Start with a capital letter end with a period inline void public_member const char _ arg const In class function definitions should be restricted to one liners int one_line return 0 int two_lines const char arg return strchr arg a inline int three_lines inline but defined below Note indentation template lt typename _Formal_argument gt void public_template const throw template lt typename _Iterator gt void other_template private The GNU C Library 167 253 class _Helper int _M private Jata int _M more_stuff _Helperx _M helper int _M private_function enum _Enum _S_one _S_two static void _S_initialize_library More or less standard language features described by lack not presence ifndef _G_NO_LONGLONG extern long long _G_global_with_a_good_long_name avoid globals L endif Avoid in class inline definitions define separately likewise for member class definitions inline int gribble public_member const int _ local 0 return _ local class gribble _Helper INE aM stuff friend class gribble L Names beginning with __ only for arguments and Ed local variables never use __ in a type name or within any name never use __ 0 9 endif _HEADER_ x namespace std template lt typename T gt notic
12. The primary author of the checking code Jeremy Siek had already started work on a replacement implementation The new code has been formally reviewed and accepted into the Boost libraries and we are pleased to incorporate it into the GNU C library The new version imposes a much smaller space overhead on the generated object file The checks are also cleaner and easier to read and understand They are off by default for all versions of GCC They can be enabled at configure time with enable concept checks You can enable them on a per translation unit basis with D_GLIBCXX_CONCEPT_CH ECKS Please note that the upcoming C standard has first class support for template parameter constraints based on concepts in the core language This will obviate the need for the library simulated concept checking described above The GNU C Library 44 253 Chapter 6 Utilities 6 1 Functors If you don t know what functors are you re not alone Many people get slightly the wrong idea In the interest of not rein venting the wheel we will refer you to the introduction to the functor concept written by SGI as chapter of their STL in their http www sgi com tech stl functors html 6 2 Pairs The pair lt T1 T2 gt is a simple and handy way to carry around a pair of objects One is of type T1 and another of type T2 they may be the same type but you don t get anything extra if they are The two members can be access
13. but there is no standard vfscanf to use to implement std fscanf It appears that v scanf but be re implemented in C for targets where no vfscanf extension has been defined This is interesting in that it seems to be the only significant case in the C library where this kind of rewriting is necessary Of course Glibc provides the vfscanf extension The functions related to exit must be rewritten for other reasons Annex D Headers lt strstream gt Annex D defines many non library features and many minor modifications to various headers and a complete header It is mostly done except that the libstdc 2 lt strstream gt header has not been adopted into the library or checked to verify that it matches the draft in those details that were clarified by the committee Certainly it must at least be moved into the std namespace We still need to wrap all the deprecated features in if guards so that pedantic compile modes can detect their us The GNU C Library 188 253 Nonstandard Extensions Headers lt iostream h gt lt strstream h gt lt hash gt lt rbtree gt lt pthread_alloc gt lt stdiobuf gt etc User code has come to depend on a variety of nonstandard components that we must not omit Much of this code can be adopted from libstdc v2 or from the SGI STL This particularly includes lt iostream h gt lt strstream h gt and various SGI extensions such as
14. AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS SCXXFLAGS CXXFLAGS SCXXFLAGS std gnu 0x AC_TRY_COMPILE include lt unordered_set gt using std unordered_set ac_cv_cxx_unordered_set yes ac_cv_cxx_unordered_set no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE 1 if test Sac_cv_cxx_unordered_set yes then AC_DEFINE HAVE_UNORDERED_SET Define if unordered_set is present Ed B 6 3 8 Container iterator_type is not necessarily Container value_type This is a change in behavior from the previous version Now most iterator_type typedefs in container classes are POD objects not value_type pointers B 6 4 Bibliography 65 Dan Kegel uri Migrating to GCC 4 1 66 Martin Michlmayr uri Building the Whole Debian Archive with GCC 4 1 A Summary 67 uri Migration guide for GCC 3 2 The GNU C Library 237 253 Appendix C Free Software Needs Free Documentation Appendix Documentation The biggest deficiency in free operating systems is not in the software it is the lack of good free manuals that we can include in these systems Many of our most important programs do not come with full manuals Documentation is an essential part of any software package when an important free software package does not come with a free manual that is a major gap We have many such gaps today
15. The GNU C Library B 5 B 6 xv B42 Checking ActtVew s pe serao ead he eee ea RE ee RAR E Oe 213 B43 Allowed Changes te a tt A Dt ARE Es RR og 214 B 44 Prohibited Changes c e S coca a a a A eee 214 B 4 5 Implementation 2 2 444 4 0446 ew EE Oe ea A A a ee 214 B46 Testa 2453222 542 306 bo ede o ew eee A ASAE SRS tA 215 B461 Single ABTTESIDS s r eroen Pid Bee eee KER A O RRR E E E oS 213 B 4 6 2 Multiple ABILTeSnng 216 B 4 7 Outstanding ISSUES oo ms Seka aaa A RG a a a 217 B 4 8 Bibliography lt s sorea kpe ee a a A bee 217 API Evolution and Deprecation History oaoa aaa ee 217 BSL A A we Dae era ek aa hae a E e a 218 B32 3b enspe ori e a e oe de ee AA 218 BOS a r rs iaa Be SE Sie aa a O e A A Ei Ao a e E 218 BOA Bis air e AA Beebe A A a ee ee Lane bes 218 A A h G45 bb td needa ee ee oth eh bbe SSE aed bea bd eo 218 B356 420 R we Sa RR A a EES BES BR e a ed e Beh a eh oe Ge N 219 Bod Aelia a 4 Se AA AA A Be es HS eee SS 220 BESO Ai e rd gk Ric ah tes a Geta Beene nents de Bias A ee ent pd e 220 BIO A Se RSS ERE E R EARS PERE S Ree ES GRE RS be ee eee T 220 B310 AU ira a a ba ea ee di A a SPER GE Gd 221 E A RAR 222 Backwards Compatbility lt iia a E A A E Ae e 222 B 6 1 Fitsf een m ore ta a Ba ee A A ARA R ee oe See a 222 B611 Noios base seten RE RO eR a e E A RR ela ee E we e 222 B 6 1 2 No cout inostream h nocininistream h 222 B62 Second 25432 24 storek be tbe B
16. To compute the code paths that throw test instruments are used that throw on allocation events __gnu_cxx throw_allo cator_randomand__gnu_cxx throw_allocator_limit and copy assignment comparison increment swap and various operators __gnu_cxx throw_type_random and __gnu_cxx throw_type_limit Looping through a given test sequence and conditionally throwing in all instrumented places Then when the test sequence completes without an exception being thrown assume all potential error paths have been exercised in a sequential manner B 3 5 1 2 Existing tests s Ad Hoc For example testsuite 23_containers list modifiers 3 cc The GNU C Library 205 253 e Policy Based Data Structures For example take the test functor rand_reg_test inintestsuite ext pb_ds regression tree_no_data_ map_rand cc This uses container_rand_regression_test intestsuite util regression rand assoc container_rand_regression_test h Which has several tests for container member functions Includes control and test container objects Configuration includes random seed iterations number of distinct values and the probability that an exception will be thrown Assumes instantiating container uses an extension allocator ___gnu_cxx throw_allocator_randon as the allocator type e C 0x Container Requirements Coverage is currently limited to testing container requirements for exception safety although __gnu_cxx throw_type meets the additional t
17. Use the style of commands not the style Please be careful about whitespace in your markup comments Most of the time it doesn t matter doxygen absorbs most whitespace and both HTML and roff are agnostic about whitespace However in lt pre gt blocks and code endcode sections spacing can have interesting effects Use either kind of grouping as appropriate doxygroups cc exists for this purpose See st 1_iterator h for a good example of the other kind of grouping Please use markup tags like p and a when referring to things such as the names of function parameters Use e for emphasis when necessary Use c to refer to other standard names Examples of all these abound in the present code Complicated math functions should use the multi line format An example from random h xx x brief A model of a linear congruential random number generator L x Qf x_ it l leftarrow ax_ i c bmod m Qf Be careful about using certain special characters when writing Doxygen comments Single and double quotes and separators in filenames are two common trouble spots When in doubt consult the following table HTML Doxygen n y S N lt i gt a word lt b gt b word lt code gt Oc word lt em gt a word lt em gt lt em gt two words or more lt em gt Table A 1 HTML to Doxygen Markup Comparison The GNU C Library 170 253 A 4 2 Docbo
18. accumulate ar ar 50 1 std multiplies lt int gt The first call adds all the members of the array using zero as an initial value for sum The second does the same but uses so meval as the starting value thus sum_stuff sum someval The final call uses the second of the two signatures and multiplies all the members of the array here we must obviously use as a starting value instead of 0 The other three functions have similar dual signature forms The GNU C Library 86 253 12 3 Interacting with C 12 3 1 Numerics vs Arrays One of the major reasons why FORTRAN can chew through numbers so well is that it is defined to be free of pointer aliasing an assumption that C89 is not allowed to make and neither is C 98 C99 adds a new keyword restrict to apply to individual pointers The C solution is contained in the library rather than the language although many vendors can be expected to add this to their compilers as an extension That library solution is a set of two classes five template classes and a whole bunch of functions The classes are required to be free of pointer aliasing so compilers can optimize the daylights out of them the same way that they have been for FORTRAN They are collectively called valarray although strictly speaking this is only one of the five template classes and they are designed to be familiar to people who have worked with the BLAS libraries before 12 3 2 C99 In additi
19. front end The following is a partial list of solutions with justifications for our rejection of each e Completely separate debug release libraries This is by far the simplest implementation option where we do not allow any coexistence of debug and release compiled translation units in a program This solution has an extreme negative affect on usability because it is quite likely that some libraries an application depends on cannot be recompiled easily This would not meet our usability or minimize recompilation criteria well e Add a Debug boolean template parameter Partial specialization could be used to select the debug implementation when De bug true and the state of _GLIBCXX_DEBUG could decide whether the default Debug argument is true or false This option would break conformance with the C standard in both debug and release modes This would not meet our correctness criteria e Packaging a debug flag in the allocators We could reuse the Allocator template parameter of containers by adding a sentinel wrapper debug lt gt that signals the user s intention to use debugging and pick up the debug lt gt allocator wrapper in a partial specialization However this has two drawbacks first there is a conformance issue because the default allocator would not be the standard specified std allocator lt T gt Secondly and more importantly users that specify allocators instead of implicitly using the default allocator would not g
20. trat size strlen e_lit int_type i_lit_base 24 25088 27648 24832 25344 27392 8192 28672 25856 24832 29184 27648 8192 27136 24832 29440 27904 26880 28160 25856 8192 29696 25856 24832 2560 hi const int_type lts a lat base const ext_typex efrom_next const int_typex ifrom_next ext_typex _arr new ext_typelsize 1 ext_typex eto_next int_typex i_arr new int_typelsize 1 int_typex TEO eres construct a locale object with the specialized facet locale loc locale classic new unicode_codecvt sanity check the constructed locale has the specialized facet VERIFY has_facet lt unicode_codecvt gt loc const unicode_codecvt amp cvt use_facet lt unicode_codecvt gt loc convert between const char and unicode strings unicode_codecvt state_type state0l UNICODE ISO_8859 1 initialize _state state0l result rl cvt in state01l e_lit e_lit size efrom_next 1 Jer SEE Size 10 nexb gt ERIFY rl codecvt_base ok BRAT EB Ya Uae E lulls Sires COMP aah 1 sera al loe Sie NP ERIFY efrom_next e_lit size ERIFY ito_next i_arr size V V v V 8 2 2 5 Future e a things that are sketchy or remain unimplemented do_encoding max_length and length member functions are only weakly implemented I have no idea how to do this correctly and in a generic manner Nathan e b conversions involving std string
21. 1 32 x c x 100 where k is the constant overhead per node e g for list it is 8 bytes and for map it is 12 bytes and c is the size of the base type on which the map list is instantiated Thus suppose the typel is int and type2 is double they are related by the relation sizeof double 2 sizeof int Thus all types must have this double size relation for this formula to work properly Plugging in For List k 8 and c 4 int and double we get 33 376 For map multimap k 12 and c 4 int and double we get 37 524 Thus knowing these values and based on the sizeof value_type we may create a function that returns the Max_Wastage_Percentage for us to use 20 2 2 5 allocate The allocate function is specialized for single object allocation ONLY Thus ONLY if n 1 will the bitmap_allocator s specialized algorithm be used Otherwise the request is satisfied directly by calling operator new Suppose n 1 then the allocator does the following 1 Checks to see whether a free block exists somewhere in a region of memory close to the last satisfied request If so then that block is marked as allocated in the bit map and given to the user If not then 2 is executed 2 Is there a free block anywhere after the current block right up to the end of the memory that we have If so that block is found and the same procedure is applied as above and returned to the user If not then 3 is executed 3 Is there any
22. 13 5 Interacting with C 13 5 1 Using FILE and file descriptors See the extensions for using FILE and file descriptors with of streamand ifstream The GNU C Library 93 253 13 5 2 Performance Pathetic Performance Ditch C It sounds like a flame on C but it isn t Really Calm down I m just saying it to get your attention Because the C library includes the C library both C style and C style I O have to work at the same time For example include lt iostream gt include lt cstdio gt Sola e COUE lt lt Wisin artes aportas Mo Oz sele sema lt lt Voli Nine This must do what you think it does Alert members of the audience will immediately notice that buffering is going to make a hash of the output unless special steps are taken The special steps taken by libstdc at least for version 3 0 involve doing very little buffering for the standard streams leaving most of the buffering to the underlying C library This kind of thing is tricky to get right The upside is that correctness is ensured The downside is that writing through cout can quite easily lead to awful performance when the C I O library is layered on top of the C I O library as it is for 3 0 by default Some patches have been applied which improve the situation for 3 1 However the C and C standard streams only need to be kept in sync when both libraries facilities are in use If your program only uses C I O then there s n
23. 8 2 1 1 Implementation 8 2 1 1 1 Specializations For the required specialization codecvt lt wchar_t char mbstate_t gt conversions are made between the internal character set always UCS4 on GNU Linux and whatever the currently selected locale for the LC_CTYPE category implements The two required specializations are implemented as follows ctype lt char gt This is simple specialization Implementing this was a piece of cake ctype lt wchar_t gt This specialization by specifying all the template parameters pretty much ties the hands of implementors As such the imple mentation is straightforward involving mcsrtombs for the conversions between char to wchar_t and wesrtombs for conversions between wchar_t and char Neither of these two required specializations deals with Unicode characters 8 2 1 2 Future How to deal with the global locale issue How to deal with different types than char wchar_t Overlap between codecvt ctype narrow widen Mask typedef in codecvt_base argument types in codecvt what is know about this type Why mask argument in codecvt Can this be made more generic is there a simple way to straighten out the configure time mess that is a by product of this class Get the ctype lt wchar_t gt mask stuff under control Need to make some kind of static table and not do lookup every time somebody hits the do_is functions Too bad we can t just redefine mask for ctype lt wchar_t gt Rename ab
24. 85 253 Chapter 12 Numerics 12 1 Complex 12 1 1 complex Processing Using complex lt gt becomes even more comple er sorry complicated with the not quite gratuitously incompatible addition of complex types to the C language David Tribble has compiled a list of C 98 and C99 conflict points his description of C s new type versus those of C and how to get them playing together nicely is here complex lt gt is intended to be instantiated with a floating point type As long as you meet that and some other basic requirements then the resulting instantiation has all of the usual math operators defined as well as definitions of op lt lt and op gt gt that work with iostreams op lt lt prints u v and op gt gt can read u u and u v 12 2 Generalized Operations There are four generalized functions in the lt numeric gt header that follow the same conventions as those in lt algorithm gt Each of them is overloaded one signature for common default operations and a second for fully general operations Their names are self explanatory to anyone who works with numerics on a regular basis accumulate inner_product e chapterial_sum adjacent_difference Here is a simple example of the two forms of accumulate Lac ar 50 LE someval somefunction initialize members of ar to something ine Sum std accumulate ar ar 50 0 int sum_stuff std accumulate ar ar 50 someval ote Jalil std
25. Addison Wesley The GNU C Library 76 253 49 Angelika LangerKlaus Kreft Standard C IOStreams and Locales Advanced Programmer s Guide and Reference Copyright 2000 Addison Wesley Longman Inc Addison Wesley Longman 50 uri API Specifications Java Platform java util Properties java text MessageFormat java util Locale java util ResourceBundle 51 uri GNU gettext tools version 0 10 38 Native Language Support Library and Tools The GNU C Library 77 253 Chapter 9 Containers 9 1 Sequences 9 1 1 list 9 1 1 1 list size is O n Yes it is and that s okay This is a decision that we preserved when we imported SGI s STL implementation The following is quoted from their FAQ The size member function for list and slist takes time proportional to the number of elements in the list This was a deliberate tradeoff The only way to get a constant time size for linked lists would be to maintain an extra member variable containing the list s size This would require taking extra time to update that variable it would make splice a linear time operation for example and it would also make the list larger Many list algorithms don t require that extra word algorithms that do require it might do better with vectors than with lists and when it is necessary to maintain an explicit size count it s something that users can do themselves This choice is permitted by the C stan
26. By default libstdc is built with efficiency in mind and therefore performs little or no error checking that is not required by the C standard This means that programs that incorrectly use the C standard library will exhibit behavior that is not portable and may not even be predictable because they tread into implementation specific or undefined behavior To detect some of these errors before they can become problematic libstdc offers a debug mode that provides additional checking of library facilities and will report errors in the use of libstdc as soon as they can be detected by emitting a description of the problem to standard error and aborting the program This debug mode is available with GCC 3 4 0 and later versions The libstdc debug mode performs checking for many areas of the C standard but the focus is on checking interactions among standard iterators containers and algorithms including e Safe iterators Iterators keep track of the container whose elements they reference so errors such as incrementing a past the end iterator or dereferencing an iterator that points to a container that has been destructed are diagnosed immediately e Algorithm preconditions Algorithms attempt to validate their input parameters to detect errors as early as possible For instance the set_intersection algorithm requires that its iterator parameters first1 and last1 form a valid iterator range and that the sequence first1 last 1 is sort
27. CONTAINERS HASHTABLE_TODISMALL 1 10 HASHTABLE_TOOSLARGE 1 10 INEFFICIENT_HASH 3 10 VECTOR_TOO_SM amp LL 1 10 VECTOR_TOO_LARGE 1 10 VECTOR_TO_HASHTABLE 7 10 HASHTABLE_TO VECTOR 7 10 VECTOR_TO_LIST8 5 10 LIST_TO_VECTOR10 5 10 ORDERED_TO_UNORDERED 5 10 ALGORITHMS SORT 7 8 7 LOCALITY SOFTWARE_PREFBTCH 8 5 RBTREE_LOCALTPY 8 5 FALSE_SHARING 8 10 10 Table 19 2 Profile Diagnostics 19 7 1 Diagnostic Template Switch _GLIBCXX_PROFILE_ lt diagnostic gt Goal What problem will it diagnose Fundamentals What is the fundamental reason why this is a problem Sample runtime reduction Percentage reduction in execution time When reduction is more than a constant factor describe the reduction rate formula Recommendation What would the advise look like To instrument What stdlibc components need to be instrumented Analysis How do we decide when to issue the advice Cost model How do we measure benefits Math goes here Example program code advice sample The GNU C Library 122 253 19 7 2 Containers Switch _GLIBCXX_PROFILE_CONTAINERS T 19 7 2 1 Hashtable Too Small e Switch _GLIBCXX_PROFILE_HASHTABLE_TOO_SMALL e Goal Detect hashtables with many rehash operations small construction size and large destruction size e Fundamentals Rehash is very expensive Read content follow chains within bucket evaluate hash function place at new location in differen
28. I ve decided to keep these bitmaps close to the actual blocks This will help in 2 ways 1 Constant time access for the bitmap themselves since no kind of look up will be needed to find the correct bitmap list or it s equivalent 2 And also this would preserve the cache as far as possible So in effect this kind of an allocator might prove beneficial from a purely cache point of view But this allocator has been made to try and roll out the defects of the node_allocator wherein the nodes get skewed about in memory if they are not returned in the exact reverse order or in the same order in which they were allocated Also the new_allocator s book keeping overhead is too much for small objects and single object allocations though it preserves the locality of blocks very well when they are returned back to the allocator 20 2 2 9 Overhead and Grow Policy Expected overhead per block would be 1 bit in memory Also once the address of the free list has been found the cost for allocation deallocation would be negligible and is supposed to be constant time For these very reasons it is very important to minimize the linear time costs which include finding a free list with a free block while allocating and finding the corresponding free list for a block while deallocating Therefore I have decided that the growth of the internal pool for this allocator will be exponential as compared to linear for node_allocator There linear time works
29. Once upon a time many years ago I thought I would learn Perl I got a copy of a free manual but I found it hard to read When I asked Perl users about alternatives they told me that there were better introductory manuals but those were not free Why was this The authors of the good manuals had written them for O Reilly Associates which published them with restrictive terms no copying no modification source files not available which exclude them from the free software community That wasn t the first time this sort of thing has happened and to our community s great loss it was far from the last Proprietary manual publishers have enticed a great many authors to restrict their manuals since then Many times I have heard a GNU user eagerly tell me about a manual that he is writing with which he expects to help the GNU project and then had my hopes dashed as he proceeded to explain that he had signed a contract with a publisher that would restrict it so that we cannot use it Given that writing good English is a rare skill among programmers we can ill afford to lose manuals this way Free documentation like free software is a matter of freedom not price The problem with these manuals was not that O Reilly Associates charged a price for printed copies that in itself is fine The Free Software Foundation sells printed copies of free GNU manuals too But GNU manuals are available in source code form while these manuals are availa
30. Probably the most frequently asked question about code conversion is So dudes what s the deal with Unicode strings The dude part is optional but apparently the usefulness of Unicode strings is pretty widely appreciated Sadly this specific encoding And other useful encodings like UTF8 UCS4 ISO 8859 10 etc etc etc are not mentioned in the C standard A couple of comments The thought that all one needs to convert between two arbitrary codesets is two types and some kind of state argument is unfortunate In particular encodings may be stateless The naming of the third parameter as stateT is unfortunate as what is really needed is some kind of generalized type that accounts for the issues that abstract encodings will need The minimum information that is required includes e Identifiers for each of the codesets involved in the conversion For example using the iconv family of functions from the Single Unix Specification what used to be called X Open hosted on the GNU Linux operating system allows bi directional mapping between far more than the following tantalizing possibilities An edited list taken from iconv list ona Red Hat 6 2 Intel system 8859 1 8859_9 10646 1 1993 10646 1 1993 UCS4 ARABIC ARABIC7 ASCII EUC CN EUC JP EUC KR EUC TW GREEK CCIcode GREEK GREEK7 OLD GREEK7 GREEK8 HEBREW ISO 8859 1 ISO 8859 2 ISO 8859 3 SOS DOS ES SES OS SO ES DIS LES OI TOS SIS IES OS OE SOS RS O SES O O O IZ 1S0 88
31. The GNU C Library 204 253 try_named_locale try_mkfifo func_callback counter copy_tracker copy_constructor assignment_operator destructor pod_char pod_int and associated char_traits specializations testsuite_io h Error exception and constraint checking for std streambuf std basic_stringbuf std basic_file buf testsuite_iterators h Wrappers for various iterators testsuite_performance h A number of class abstractions for performance counters and reporting functions including time counter resource_counter report_performance B 3 5 Special Topics B 3 5 1 Qualifying Exception Safety Guarantees B 3 5 1 1 Overview Testing is composed of running a particular test sequence and looking at what happens to the surrounding code when exceptions are thrown Each test is composed of measuring initial state executing a particular sequence of code under some instrumented conditions measuring a final state and then examining the differences between the two states Test sequences are composed of constructed code sequences that exercise a particular function or member function and either confirm no exceptions were generated or confirm the consistency coherency of the test subject in the event of a thrown exception Random code paths can be constructed using the basic test sequences and instrumentation as above only combined in a random or pseudo random way
32. URRU TUNE S UTF 8 se_NO UTF 8 UTF 8 ec UEG zh_TW BIG5 Failure to have the underlying C library locale information installed will mean that C named locales for the above regions will not work because of this the libstdc testsuite will skip the named locale tests If this isn t an issue don t worry about it If named locales are needed the underlying locale information must be installed Note that rebuilding libstdc after the C locales are installed is not necessary To install support for locales do only one of the following e install all locales with RedHat Linux export LC_ALL C rpm e glibc common nodeps rpm i define _install_langs all glibc common 2 2 5 34 i386 rpm Instructions for other operating systems solicited e install just the necessary locales with Debian Linux Add the above list as shown to the file etc locale gen run usr sbin locale gen on most Unix like operating systems localedef i de DR f ISO 8859 1 de D repeat for each entry in the above list Gl Instructions for other operating systems solicited 2 2 Configure When configuring libstdc you ll have to configure the entire gccsrcdir directory Consider using the toplevel gcc configuration option enable languages c which saves time by only building the C toolchain Here are all of the configure options specific to libstdc Keep in mind that they all have opposite forms as well
33. an argument to affect subsequent include directory options additively so that if one said pedantic iprefix prefix idirafter ino pedantic ino extern c iwithprefix I g v3 iwithprefix I g v3 ext the compiler would search prefix gt v3 and not report pedantic warnings for files found there but treat files in prefix g v3 ext pedantically The undocumented semantics of isystem in g stink Can they be rescinded If not it must be replaced with something more rationally behaved All the C headers need the treatment above in the standard these headers are mentioned in various chapters Below I have only mentioned those that present interesting implementation issues The components identified as mostly complete below have not been audited for conformance In many cases where the library passes conformance tests we have non conforming extensions that must be wrapped in if guards for pedantic use and in some cases renamed in a conforming way for continued use in the implementation regardless of conformance flags he STL portion of the library still depends on a header stl bits stl_config h full of ifdef clauses This apparatus hould be replaced with autoconf automake machinery LD The SGI STL defines a type_traits lt gt template specialized for many types in their code including the built in numeric and pointer types and some library typ
34. disable foo yes no The enable_FEATURE variable is guaranteed to equal either yes or no after the macro If the user tries to pass something else an explanatory error message will be given and configure will halt The GNU C Library 192 253 The second signature takes a fifth argument permit a b c This allows a or b or after the equals sign in the option and enable_FEATURE is guaranteed to equal one of them after the macro Note that if you want to allow plain enable disable with no whatever you must include yes and no in the list of permitted values Also note that whatever you passed as DEFAULT must be in the list If the user tries to pass something not on the list a semi explanatory error message will be given and configure will halt Example permit generic gnulieee_1003 1 2001 yes nolauto The third signature takes a fifth argument It is arbitrary shell code to execute if the user actually passes the enable dis able option If the user does not the default is used Duh No argument checking at all is done in this signature See GLIBCXX_ENABLE_CXX_FLAGS for an example of handling and an error message B 2 Porting to New Hardware or Operating Systems This document explains how to port libstdc the GNU C library to a new target In order to make the GNU C library libstdc work with a new target you must edit some configuration files and provide some new header files Unle
35. endl The proper thing to do in this case to just write the data out and let the libraries and the system worry about the buffering If you need a newline just write a newline STR SITE e lt HS LES E ter me lt one TE T The GNU C Library 90 253 lt lt Wan tene lina o era yaa I have also joined the output statements into a single statement You could make the code prettier by moving the single newline to the start of the quoted text on the last line for example If you do need to flush the buffer above you can send an endl if you also need a newline or just flush the buffer yourself QUEUE lt lt ELUSA can use std flush manipulator output flush I or SEL E meder in On the other hand there are times when writing to a file should be like writing to standard error no buffering should be done because the data needs to appear quickly a prime example is a log file for security related information The way to do this is just to turn off the buffering before any I O operations at all have been done note that opening counts as an I O operation std ofstream os std ifstream Les int IGA os rdbuf gt pubsetbuf 0 0 is rdbuf gt pubsetbuf 0 0 os open foo bar baz is open qux quux quuux os lt lt this data is written immediately n LS SS ale and this will probably cause a disk read Since all aspects of buffering are handled by a streambuf derived member it is necessary
36. example ifdef _ EXCEPTIONS void __throw_bad_exception void throw bad_exception else void __throw_bad_exception void abort endif The last language feature needing to be transformed by fno except ions is treatment of exception specifications on member functions Fortunately the compiler deals with this by ignoring exception specifications and so no alternate source markup is needed By using this combination of language re specification by the compiler and the pre processor tricks and the functional indirection layer for thrown exception objects by the library libstdc files can be compiled with fno exceptions User code that uses C keywords like throw t ry and catch will produce errors even if the user code has included libstdc headers and is using constructs like basic_iostream Even though the standard library has been transformed user code may need modification User code that attempts or expects to do error checking on standard library components compiled with exception handling disabled should be evaluated and potentially made conditional Some issues remain with this approach see bugzilla entry 25191 Code paths are not equivalent in particular catch blocks are not evaluated Also problematic are throw expressions expecting a user defined throw handler Known problem areas in the standard library include using an instance of basic_istream with exceptions set to specific ios_base iostate c
37. is called This means that there will be bins of the following sizes in bytes 1 2 4 8 16 32 64 128 Create the _S_binmap array All requests are rounded up to the next large enough bin Le a request for 29 bytes will cause a block from the 32 byte bin to be returned to the application The purpose of _S_binmap is to speed up the process of finding out which bin to use I e the value of _S_binmap 29 is initialized to 5 bin 5 32 bytes Create the _S_bin array This array consists of bin_records There will be as many bin_records in this array as the number of bins that we calculated earlier I e if _S_max_bytes 128 there will be 8 entries Each bin_record is then initialized bin_record gt first An array of pointers to block_records There will be as many block_records pointers as there are maximum number of threads in a ST application there is only 1 thread in a MT application there are _S_max_threads This holds the pointer to the first free block for each thread in this bin Le if we would like to know where the first free block of size 32 for thread number 3 is we would look this up by _S_bin 5 first 3 The above created block record pointers members are now initialized to their initial values Le _S_bin n first n NULL Additionally a MT application will Create a list of free thread id s The pointer to the first entry is stored in _S_thread_freelist_first The reason for this approach is
38. modification and use would permit combination with GCC in accord with the license of GCC Target Code refers to output from any compiler for a real or virtual target processor architecture in executable form or suitable for input to an assembler loader linker and or execution phase Notwithstanding that Target Code does not include data in any format that is used as a compiler intermediate representation or used for producing a compiler intermediate representation The Compilation Process transforms cod ntirely represented in non intermediate languages designed for human written code and or in Java Virtual Machine byte code into Target Code Thus for example use of source code generators and preprocessors need not be considered part of the Compilation Process since the Compilation Process can be understood as starting with the output of the generators or preprocessors The GNU C Library 9 253 A Compilation Process is Eligible if it is done using GCC alone or with other GPL compatible software or if it is done without using any work based on GCC For example using non GPL compatible Software to optimize any GCC intermediate representations would not qualify as an Eligible Compilation Process 1 Grant of Additional Permission You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules even if such propagation
39. redhat com if you are confused about the assignment or have general licensing questions When requesting an assignment form from mailto assign gnu org please cc the libstdc maintainer above so that progress can be monitored The GNU C Library 156 253 A 1 3 Getting Sources Getting write access look for Write after approval A 1 4 Submitting Patches Every patch must have several pieces of information before it can be properly evaluated Ideally and to ensure the fastest possible response from the maintainers it would have all of these pieces e A description of the bug and how your patch fixes this bug For new features a description of the feature and your implemen tation e A ChangeLog entry as plain text see the various ChangeLog files for format and content If you are using emacs as your editor simply position the insertion point at the beginning of your change and hit CX 4a to bring up the appropriate ChangeLog entry See magic Similar functionality also exists for vi e A testsuite submission or sample program that will easily and simply show the existing error or test new functionality e The patch itself If you are accessing the SVN repository use svn update svn diff NEW else use diff cp OLD NEW If your version of diff does not support these options then get the latest version of GNU diff The SVN Tricks wiki page has information on customising the output of svn diff e When you have all these piec
40. t include everything and so a lot of those obvious classes didn t get included Known Issues include many of the limitations of its immediate ancestor Portability notes and known implementation limitations are as follows B 6 1 1 No ios base At least some older implementations don t have std ios_base so you should use std ios badbit std ios failbit and std ios eofbit and std ios goodbit B 6 1 2 No cout in ostream h no cin in istream h In earlier versions of the standard stream h ostream h and istream h used to define cout cin and so on ISO C specifies that one needs to include iost ream explicitly to get the required definitions Some include adjustment may be required This project is no longer maintained or supported and the sources archived For the desperate the GCC extensions page describes where to find the last libg source The code is considered replaced and rewritten The GNU C Library 223 253 B 6 2 Second The second generation GNU C library was called libstdc or libstdc v2 It spans the time between libg and pre ISO C standardization and is usually associated with the following GCC releases egcs 1 x gcc 2 95 and gcc 2 96 The STL portions of this library are based on SGI HP STL release 3 11 This project is no longer maintained or supported and the sources archived The code is considered replaced and rewritten Portability notes and known implementation li
41. the thread id is set to the current one What s the use Well when a deallocation occurs we can now look at the thread id and find out if it was allocated by another thread id and decrease the used counter of that thread instead thus keeping the free and used counters correct And keeping the free and used counters corrects is very important since the relationship between these two variables decides if memory should be returned to the global pool or not when a deallocation occurs When the application requests memory calling allocate we first look at the requested size and if this is gt _S_max_bytes we call new directly and return If the requested size is within limits we start by finding out from which bin we should serve this request by looking in _S_binmap A call to _S_ get_thread_id returns the thread id for the calling thread and if no value has been set in _S_thread_key a new id 1s assigned and returned A quick look at _S_bin bin first thread_id tells us if there are any blocks of this size on the current threads freelist If this is not NULL fine just remove the block that _S_bin bin first thread_id points to from the list update _S_bin bin first thread_id update the free and used counters and return a pointer to that blocks data If the freelist is empty the pointer is NULL we start by looking at the global freelist 0 If there are blocks available on the global freelist we lock this bins mutex
42. the title page itself plus such following pages as are needed to hold legibly the material this License requires to appear in the title page For works in formats which do not have any title page as such Title Page means the text near the most prominent appearance of the work s title preceding the beginning of the body of the text A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language Here XYZ stands for a specific section name mentioned below such as Acknowledgements Dedications Endorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Disclaimers are considered to be included by reference in this License but only as regards disclaiming warranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License 2 VERBATIM COPYING You may copy and distribute the Document in any medium either commercially or noncommercially provided that this License the copyright notices and the license notice saying this License applies to the Document are reproduced in all copies and that you add no other c
43. ush_front push_back insert and rehash The container in question is instantiated with two instrumented template arguments with ___ gnu_cxx throw_allocator_limit as the allocator type and with __gnu_cxx throw_ty pe_limit as the value type This allows the test to loop through conditional throw points The general form demonstrated in test suite 23_containers list requirements exception propagation_ coherent cc The instantiating test objectis__gnu_test propagation_coherent andis detailed in testsuite util exception safety h The GNU C Library 206 253 B 4 ABI Policy and Guidelines B 4 1 The C Interface C applications often dependent on specific language support routines say for throwing exceptions or catching exceptions and perhaps also dependent on features in the C Standard Library The C Standard Library has many include files types defined in those include files specific named functions and other behavior The text of these behaviors as written in source include files is called the Application Programing Interface or API Furthermore C source that is compiled into object files is transformed by the compiler it arranges objects with specific alignment and in a particular layout mangling names according to a well defined algorithm has specific arrangements for the support of virtual functions etc These details are defined as the compiler Application Binary Interface or ABI The GNU C compiler
44. 31 March 2009 Copyright C 2009 Free Software Foundation Inc Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed This GCC Runtime Library Exception Exception is an additional permission under section 7 of the GNU General Public License version 3 GPLv3 It applies to a given file the Runtime Library that bears a notice placed by the copyright holder of the file stating that the file is governed by GPLv3 along with this Exception When you use GCC to compile a program GCC may combine portions of certain GCC header files and runtime libraries with the compiled program The purpose of this Exception is to allow compilation of non GPL including proprietary programs to use in this way the header files and runtime libraries covered by this Exception 0 Definitions A file is an Independent Module if it either requires the Runtime Library for execution after a Compilation Process or makes use of an interface provided by the Runtime Library but is not otherwise based on the Runtime Library GCC means a version of the GNU Compiler Collection with or without modifications governed by version 3 or a specified later version of the GNU General Public License GPL with the option of using any subsequent versions published by the FSF GPL compatible Software is software whose conditions of propagation
45. At runtime set LD_LIBRARY_PATH in your environment correctly so that the shared library for libstdc can be found and loaded Be certain that you understand all of the other implications and behavior of LD_LIBRARY_PATH first e Compile the path to find the library at runtime into the program This can be done by passing certain options to g which will in turn pass them on to the linker The exact format of the options is dependent on which linker you use GNU ld default on Linux W1 rpath destdir lib IRIX ld W1 rpath destdir lib Solaris ld W1 Rdestdir lib Use the Idd utility on the linked executable to show which libstdc so library the system will get at runtime A libstdc la file is also installed for use with Libtool If you use Libtool to create your executables these details are taken care of for you 3 6 Concurrency This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C library This information is GCC specific since the C standard does not address matters of multithreaded applications 3 6 1 Prerequisites All normal disclaimers aside multithreaded C application are only supported when libstdc and all user code was built with compilers which report via gcc g v the same thread model and that model is not single As long as your final application is actually single threaded then it should be safe to mix user code built with
46. Bie hye EBS eld See SS Ae he eS SS 197 B 3 1 2 Naming Conventions s y e riore eR RR ERR ee Re ee ee 198 B 3 2 Running the Testsuite 2 ee 199 B321 Basic uses bh tPA baa Bee hee SPE A da ew SS 199 B322 Vanlations a cameos me See Oe ER ee E Oe eee eS Ge ee L 199 B 3 2 3 Permutations a ee ee PE ERA Ea we eee bea ee 9 201 B 3 3 Witnga new test case nk A eR a A Se Ree ee E 201 B 3 4 Test Harness and Utilities 2 000000 0 0000000000000 00 203 B 3 4 1 Dejagnu Harness Details 0 02000 0 00000000000 203 B 34 2 Utilities s a essri bac bot a a ben dest ke thie be ea Be ee ee wo 203 B 3 3 Special Topics s sode e we ak eae Re De Sa eee ee ae ae ee a E 204 B 3 5 1 Qualifying Exception Safety Guarantees e 204 B351 OVERVIEW goes ee ee ERR OR AR PO as ee ee ee ee does a 204 B 3 3 1 2 S lt T TT tests 24 4 5 04 bb bebe EE ERA ee GA ae e A 204 B 3 5 1 3 C 0x Requirements Test Sequence Descriptions 205 B 4 ABI Policy and Guidelines lt aR R R E R RRR aa ek Re ee Oo ee a ER Ee E N 206 BAI TheC klntertace cdta bee ete te woe weed ABBA PALA amp 4 206 B 4 2 Versioning 4 seis aos K eka Rae ao AO oS o e wa BO T 206 BAZI Goals cp ace ei dat ean bie bbaee bea shee a bane bea ee bane 206 BA22 DistOly 2224446546 2444 6405 68 DS E 5455 46 eR HEE HE SEES 206 B423 Prerequisites oec e pe eee BEER ARE see ew Ae oa oS SR eee ee 6 213 B424 Configurms evocar ddr ad a a ee 213
47. CO So what was happening with OUT lt lt IN Undefined behavior since that chaptericular lt lt isn t defined by the Standard I have seen instances where it is implemented but the character extraction process removes all the whitespace leaving you with no blank lines and only Thequickbrownfox With libraries that do not define that operator IN or one of IN s member pointers sometimes gets converted to a void and the output file then contains a perfect text representation of a hexadecimal address quite a big surprise Others don t compile at all Also note that none of this is specific to o f streams The operators shown above are all defined in the parent basic_ostream class and are therefore available with all possible descendants 13 4 2 Binary Input and Output The first and most important thing to remember about binary I O is that opening a file with ios binary is not repeat not the only thing you have to do It is not a silver bullet and will not allow you to use the lt lt gt gt operators of the normal fstreams to do binary I O Sorry Them s the breaks This isn t going to try and be a complete tutorial on reading and writing binary files because binary covers a lot of ground but we will try and clear up a couple of misconceptions and common errors First ios binary has exactly one defined effect no more and no less Normal text mode has to be concerned with the newline characters and the run
48. Foo size t m std bitset lt n gt bits because n must be known at compile time Your compiler is correct it is not a bug That s the way templates work Yes it is a feature There are a couple of ways to handle this kind of thing Please consider all of them before passing judgement They include in no chaptericular order e A very large N in bitset lt N gt e A container lt bool gt s Extremely weird solutions A very large Nin bitset lt N gt It has been pointed out a few times in newsgroups that N bits only takes up N 8 bytes on most systems and division by a factor of eight is pretty impressive when speaking of memory Half a megabyte given over to a bitset recall that there is zero space overhead for housekeeping info it is known at compile time exactly how large the set is will hold over four million bits If you re using those bits as status flags e g changed unchanged flags that s a lot of state You can then keep track of the maximum bit used during some testing runs on representative data make note of how many of those bits really need to be there and then reduce N to a smaller number Leave some extra space of course If you plan to write code like the incorrect example above where the bitset is a local variable then you may have to talk your compiler into allowing that much stack space there may be zero space overhead but it s all allocated inside the object A container lt
49. GCC_3 4 2 GCC_3 4 4 GCC_4 0 0 GCC_4 1 0 GCC_4 2 0 GCC_4 3 0 GCC_4 4 0 3 Release versioning on the libstdc so binary implemented in the same was as the libgcc_s so binary above Listed is the filename DT_SONAMI For example filename libs equivalent DT_SONAM explicitly noted It is versioned as follows E can be deduced from the filename by removing the last two period delimited numbers E of libstdc so 5 Binaries with tdct t so 5 0 4 corresponds to a DT_SONAMI Es are forward compatibile in the table below releases incompatible with the previous one are The GNU C Library gec 3 0 0 gec 3 0 1 gec 3 0 2 gcec 3 0 3 gcec 3 0 4 gcec 3 1 0 gcc 3 1 1 gcec 3 2 0 gcec 3 2 1 gec 3 2 2 gcec 3 2 3 gec 3 3 0 gec 3 3 1 gec 3 3 2 gcec 3 3 3 gcec 3 4 0 gcc 3 4 1 gcc 3 4 2 gcec 3 4 3 gcec 3 4 4 gcc 3 4 5 gcc 3 4 6 gcc 4 0 0 gcec 4 0 1 gcec 4 0 2 gcec 4 0 3 gcec 4 1 0 gcc 4 1 1 gcc 4 1 2 gec 4 2 0 gcc 4 2 1 gcc 4 2 2 gcec 4 2 3 gcec 4 2 4 gcec 4 3 0 gcec 4 3 1 gec 4 3 2 gcc 4 3 3 gcec 4 3 4 gcec 4 4 0 gcc 4 4 1 gcc 4 4 2 gcec 4 5 0 libstdc so 3 0 0 libstdc s0 3 0 1 libstdc s0 3 0 2 libstdc so 3 0 2 See Note 1 libstdc s0 3 0 4 libstdc s0 4 0 0 Incompatible with previous libstdc s0 4 0 1 libstdc so 5 0 0 Incompatible with previous libstdc so 5 0 1 libstdc s0 5 0 2 libstdc so 5 0 3 See Note 2
50. GNU Coding Standard which can be referenced in full here http www gnu org prep standards standards html Formatting The rest of this is also interesting reading but skip the Design Advice part The GCC coding conventions are here and are also useful http gcec gnu org codingconventions html In addition because it doesn t seem to be stated explicitly anywhere else there is an 80 column source limit ChangeLog entries for member functions should use the classname member function name syntax as follows 1999 04 15 Dennis Ritchie lt dr att com gt x src basic_file cc __basic_file open Fix thinko in G_HAVE_IO_FILE_OPEN bits Notable areas of divergence from what may be previous local practice particularly for GNU C include 01 Pointers and references 161 253 The GNU C Library 162 253 charx p flop char amp c xp NOT char p flop wrong char c XD wrong Reason In C definitions are mixed with executable code Here p is being initialized not p This is near universal practice among C programmers it is normal for C hackers to switch spontaneously as they gain experience 02 Operator names and parentheses operator type NOT operator type wrong Reason The is part of the function name Separating it makes the declaration look like an expression 03 Function names and parentheses void ma
51. MESES Yo reos sei SA ETNen AC_DEF ELL 1 INE STDCXX_TR1_HEADERS Define if ISO C TR1 header files ar ac_cv_cxx_stdcxx_trl no 1 PRESSE An alternative is to check just for specific TR1 includes such as lt unordered_map gt and lt unordered_set gt AC_HEADER_TR1_UNORDERED_MAP AC_DEFUN AC_HEADER_TR1_UNORDERED_MAP AC_CACHE_CHECK for trl unordered_map ac_cv_cxx_trl_unordered_map AC_LANG_SAVE LANG_CPLUSPLUS AC_TRY_CO INE acu ACH EVE ZE AANG_RESTORE PILE include lt tr1 unordered_map gt _trl_unordered_map yes 1 SR Sac_cv_cxx_trl_unordered_map yes AC_DEF EL Ip AC_HEAD AC_DEFUN AC_CACH AC OV ORA ETL AC_LANG_SAVE LANG_CPLUSPLUS ACE ER_TR1_U AC_HEADER_T ORDERED_SET R1_UNORDERED_SET CHECK for trl unordered_set _unordered_set INE HAVE_TR1_UNORDERED_MAP Define if trl unordered_map is present using std trl unordered_map ac_cv_cxx_trl_unordered_map no then 1 using std trl unordered_set ac_cv_cxx_trl_unordered_set no AC_TRY_COMPILE finclude lt tr1 unordered_set gt ac_cv_cxx_trl_unordered_set yes AC_LANG_RESTORE 1 if test Sac_cv_cxx_trl_unordered_set yes the
52. Modified Source Versions You may convey a work based on the Program or the modifications to produce it from the Program in the form of source code under the terms of section 4 provided that you also meet all of these conditions a The work must carry prominent notices stating that you modified it and giving a relevant date b The work must carry prominent notices stating that it is released under this License and any conditions added under section 7 This requirement modifies the requirement in section 4 to keep intact all notices The GNU C Library 242 253 c You must license the entire work as a whole under this License to anyone who comes into possession of a copy This License will therefore apply along with any applicable section 7 additional terms to the whole of the work and all its parts regardless of how they are packaged This License gives no permission to license the work in any other way but it does not invalidate such permission if you have separately received it d If the work has interactive user interfaces each must display Appropriate Legal Notices however if the Program has interactive interfaces that do not display Appropriate Legal Notices your work need not make them do so A compilation of a covered work with other separate and independent works which are not by their nature extensions of the covered work and which are not combined with it such as to form a larger program in or on a volume o
53. Past the End This starts off sounding complicated but is actually very easy especially towards the end Trust me Beginners usually have a little trouble understand the whole past the end thing until they remember their early algebra classes see they told you that stuff would come in handy and the concept of half open ranges First some history and a reminder of some of the funkier rules in C and C for builtin arrays The following rules have always been true for both languages 1 You can point anywhere in the array or to the first element past the end of the array A pointer that points to one past the end of the array is guaranteed to be as unique as a pointer to somewhere inside the array so that you can compare such pointers safely 2 You can only dereference a pointer that points into an array If your array pointer points outside the array even to just one past the end and you dereference it Bad Things happen The GNU C Library 83 253 3 Strictly speaking simply pointing anywhere else invokes undefined behavior Most programs won t puke until such a pointer is actually dereferenced but the standards leave that up to the platform The reason this past the end addressing was allowed is to make it easy to write a loop to go over an entire array e g while d s So when you think of two pointers delimiting an array don t think of them as indexing 0 through n 1 Think of them as boundar
54. STL Though it inspired much work in this area it has not been kept up to date for use with modern compilers or C standard library implementations STLport STLport is a free implementation of the C standard library derived from the SGI implementation and ported to many other platforms It includes a debug mode that uses a wrapper model that in some ways inspired the libstdc debug mode design although at the time of this writing the debug mode is somewhat incomplete and meets only the Full user recompilation 2 recompilation guarantee by requiring the user to link against a different library in debug mode vs release mode Metrowerks CodeWarrior The C standard library that ships with Metrowerks CodeWarrior includes a debug mode It is a full debug mode implementation including debugging for CodeWarrior extensions and is easy to use although it meets only the Full recompilation 1 recompilation guarantee The GNU C Library 108 253 Chapter 18 Parallel Mode The libstdc parallel mode is an experimental parallel implementation of many algorithms the C Standard Library Several of the standard algorithms for instance std sort are made parallel using OpenMP annotations These parallel mode constructs and can be invoked by explicit source declaration or by compiling existing sources with a specific compiler flag 18 1 Intro The following library components in the include numeric are included in the parallel m
55. This guarantee minimizes the recompilation that users are required to perform shortening the detect compile debug bug hunting cycle and making the debug mode easier to incorporate into development environments by minimizing dependencies Achieving link and run time coexistence is not a trivial implementation task To achieve this goal we required a small extension to the GNU C compiler since incorporated into the C 0x language specification described in the GCC Manual for the C language as namespace association and a complex organization of debug and release modes The end result is that we have achieved per use recompilation but have had to give up some checking of the std basic_string class template namely safe iterators 17 4 2 3 1 Compile time coexistence of release and debug mode components Both the release mode components and the debug mode components need to exist within a single translation unit so that the debug versions can wrap the release versions However only one of these components should be user visible at any particular time with the standard name e g std list In release mode we define only the release mode version of the component with its standard name and do not include the debugging component at all The release mode version is defined within the namespace std Minus the namespace associations this method leaves the behavior of release mode completely unchanged from its behavior prior to the introduction o
56. _GLIBCXX_DEPRECATED Defined by default Not configurable ABI changing Turning this off removes older ARM style iostreams code and other anachronisms from the API This macro is dependent on the version of the standard being tracked and as a result may give different results for std c 98 and std c 0x This may be useful in updating old C code which no longer meet the requirements of the language or for checking current code against new language standards _GLIBCXX_FORCE_NEW Undefined by default When defined memory allocation and allocators controlled by libstdc call operator new delete without caching and pooling Configurable via enable libstdcxx allocator ABI changing The GNU C Library 24 253 _GLIBCXX CONCEPT_CHECKS Undefined by default Configurable via nable concept checks When defined performs compile time checking on certain template instantiations to detect violations of the requirements of the standard This is described in more detail here _GLIBCXX_DEBUG Undefined by default When defined compiles user code using the debug mode _GLIBCXX_DEBUG_PEDANTIC Undefined by default When defined while compiling with the debug mode makes the debug mode extremely picky by making the use of libstdc extensions and libstdc specific behavior into errors _GLIBCXX_PARALLEL Undefined by default When defined compiles user code using the parallel mode _GLIBCXX_PROFILE Undefined by default When defined comp
57. a few are listed here Derive your own fstream type classes and write your own lt lt gt gt operators to do binary I O on whatever data types you re using This is a Bad Thing because while the compiler would probably be just fine with it other humans are going to be confused The overloaded bitshift operators have a well defined meaning formatting and this breaks it 5 Build the file structure in memory then mmap the file and copy the structure Well this is easy to make work and easy to break and is pretty equivalent to using read 1 and write directly and makes no use of the iostream library at all Use streambufs that s what they re there for While not trivial for the beginner this is the best of all solutions The streambuf filebuf layer is the layer that is responsible for actual I O If you want to use the C library for binary I O this is where you start How to go about using streambufs is a bit beyond the scope of this document at least for now but while streambufs go a long way they still leave a couple of things up to you the programmer As an example byte ordering is completely between you and the operating system and you have to handle it yourself Deriving a streambuf or filebuf class from the standard ones one that is specific to your data types or an abstraction thereof is probably a good idea and lots of examples exist in journals and on Usenet Using the stand
58. a key less than that of h and greater than that of the item preceding h The new item will be inserted between h and h s predecessor For multimap and multiset the restrictions are slightly looser greater than should be replaced by not less than and less than should be replaced by not greater than Why not replace greater with greater than or equal to You probably could in your head but the mathematicians will tell you that it isn t the same thing If the conditions are not met then the hint is not used and the insertion proceeds as if you had called a insert t instead Note that GCC releases prior to 3 0 2 had a bug in the case with hint begin for the map and set classes You should not use a hint argument in those releases This behavior goes well with other containers insert functions which take an iterator if used the new item will be inserted before the iterator passed as an argument same as the other containers Note also that the hint in this implementation is a one shot The older insertion with hint routines check the immediately surrounding entries to ensure that the new item would in fact belong there If the hint does not point to the correct place then no further local searching is done the search begins from scratch in logarithmic time 9 2 2 bitset 9 2 2 1 Size Variable No you cannot write code of the form The GNU C Library 79 253 include lt bitset gt word
59. abstracted via the GNU Dejagnu package This is similar to the rest of GCC This is information for those looking at making changes to the testsuite structure and or needing to trace dejagnu s actions with verbose This will not be useful to people who are merely adding new tests to the existing structure The first key point when working with dejagnu is the idea of a tool Files directories and functions are all implicitly used when they are named after the tool in use Here the tool will always be libstdc The lib subdir contains support routines The 1i1b 1libstdc exp file support library is loaded automagically and must explicitly load the others For example files can be copied from the core compiler s support directory into Lib Some routines in Lib libstdc exp are callbacks some are our own Callbacks must be prefixed with the name of the tool To easily distinguish the others by convention our own routines are named v3 The next key point when working with dejagnu is test files Any directory whose name starts with the tool name will be searched for test files We have only one In those directories any exp file is considered a test file and will be run in turn Our main test file is called normal exp it runs all the tests in testsuite_files using the callbacks loaded from the support library The config directory is searched for any particular target board information unique to this library This
60. all take pairs of iterators describing a range of values on which to operate All of these ranges are half open ranges so you pass the beginning iterator as the starting parameter and the one past the end iterator as the finishing parameter This generalizes very well You can operate on sub ranges quite easily this way functions accepting a first last range don t know or care whether they are the boundaries of an entire array sequence container whatever or whether they only enclose a few elements from the center This approach also makes zero length sequences very simple to recognize if the two endpoints compare equal then the array sequence container whatever is empty Just don t dereference end The GNU C Library 84 253 Chapter 11 Algorithms The neatest accomplishment of the algorithms sect is that all the work is done via iterators not containers directly This means two important things 1 Anything that behaves like an iterator can be used in one of these algorithms Raw pointers make great candidates thus built in arrays are fine containers as well as your own iterators 2 The algorithms do not and cannot affect the container as a whole only the things between the two iterator endpoints If you pass a range of iterators only enclosing the middle third of a container then anything outside that range is inviolate Even strings can be fed through the algorithms here although the string class h
61. allow to be wrapped into an inline function Probably this header will demand attention whenever a new target is chosen The functions atexit exit and abort in cstdlib have different semantics in C so must be re implemented for C Chapter 19 Diagnostics Headers lt stdexcept gt C headers lt cassert gt lt cerrno gt This defines the standard exception objects which are mostly complete Cygnus has a version and now SGI provides a slightly different one It makes little difference which we use The C global name errno which C allows to be a variable or a macro is required in C to be a macro For MT it must typically result in a function call Chapter 20 Utilities Headers lt utility gt lt functional gt lt memory gt C header lt ctime gt also in 18 SGI STL provides mostly complete versions of all the components The GNU C Library 182 253 defined in this chapter However the auto_ptr lt gt implementation is known to be wrong Furthermore the standard definition of it is known to be unimplementable as written A minor change to the standard would fix it and auto_ptr lt gt should be adjusted to match Multi threading affects the allocator implementation and there must be configuration installation choices for different users MT requirements Anyway users will want to tune allocator options to support different target conditions MT or no The primitive
62. also permit a debug mode in which range ownership and validity are rigorously checked The current use of pointers for iterators is evil As mentioned for chapter 24 the deque iterator is a good example of an opportunity to implement a Staged iterator that would benefit from specializations of some algorithms Chapter 24 Iterators Headers lt iterator gt Standard iterators are mostly complete with the exception of the stream iterators which are not yet templatized on the stream type Also the base class template iterator lt gt appears to be wrong so everything derived from it must also be wrong currently The streambuf iterators currently located in stl bits std_iterator h but should be under bits can be rewritten to take advantage of friendship with the streambuf implementation Matt Austern has identified opportunities where certain iterator types particularly including streambuf iterators and deque iterators have a two stage quality such that an intermediate limit can be checked much more quickly than the true limit on range operations If identified with a member of iterator_traits algorithms may be specialized for this case Of course the iterators that have this quality can be identified by specializing a traits class Many of the algorithms must be specialized for the streambuf iterators to take advantage of block mode operations in order to allow iostream locale operations perform
63. any simple C file and link it to the shared libstdc library include lt iostream gt int main f eweh seoti lt 4 Vielloy xs gwrek erent recoin ie 75 Sgt hello cc o hello out Sldd hello out libstdct so 5 gt usr lib libstdc so 5 0x00764000 libm so 6 gt lib tls libm so 6 0x004a8000 libgcc_s so 1 gt mnt hd bld gcc gcc libgcc_s so 1 0x40016000 libc so 6 gt lib tls libc so 6 0x0036d000 The GNU C Library 214 253 lib ld linux so 2 gt lib ld linux so 2 0x00355000 nm hello out If you see symbols in the resulting output with GLIBCXX_3 as part of the name then the executable is versioned Here s an example U _ZNSt8ios_base4InitClEv GLIBCXx_3 4 B 4 3 Allowed Changes The following will cause the library minor version number to increase say from libstdc so 3 0 4 to libstdc s0 3 0 5 1 Adding an exported global or static data member 2 Adding an exported function static or non virtual member function 3 Adding an exported symbol or symbols by additional instantiations Other allowed changes are possible B 4 4 Prohibited Changes The following non exhaustive list will cause the library major version number to increase say from libstdc so 3 0 4 to l bstdc s0 4 0 0 1 Changes in the gcc g compiler ABI N Changing size of an exported symbol Changing alignment of an exported symbol Changing the layout of an exported symbol Changin
64. as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsements provided it contains nothing but endorsements of your Modified Version by various parties for example statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard You may add a passage of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through arrangements made by any one entity If the Document already includes a cover text for the same cover previously added by you or by arrangement made by the same entity you are acting on behalf of you may not add another but you may replace the old one on explicit permission from the previous publisher that added the old one The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version 5 COMBINING DOCUMENTS You may combine the Document with other documents released under thi
65. ciso646 climits clocale cmath cset jmp csignal cstdarg cstddef cstdio cstdlib cstring ctime cwchar cwctype Table 3 3 C 1998 Library Headers for C Library Facilities algorithm array bitset chrono complex o donz deque exception forward_list fstream variable f initalizer_ l functional future i iomanip ios list iosfwd iostream istream iterator limits list locale map memory mutex new numeric ostream queue random ratio regex set sstream stack stdexcept streambuf string system_error thread tuple type_traits typeinfo unordered_map unordered_set utility valarray vector Table 3 4 C 200x Library Headers cassert ccomplex cctype cerrno cfenv cfloat cinttypes ciso646 climits clocale cmath cset jmp csignal cstdarg cstdbool cstddef ecstdint cstdlib cstdio cstring ctgmath ctime cuchar cwchar cwctype stdatomic h Table 3 5 C 200x Library Headers for C Library Facilities trl array tr1 complex trl memory trl functional tr1l random cejas Dl pa o tr1 unordered_ trl unordered_ traits map set tr1 utility Table 3 6 C TR 1 Library Headers trl ccomplex tr1 cfenv tr1 cfloat tr1 cmath tr1 cinttypes tr1 climits trl cstdarg trl cstdbool trl cstdint trl cstdio trl cstdlib trl ctgmath tr1 ctime tr1 cwchar trl cwctype Table 3 7 C TR 1 Library Headers for C Library Facilities The GNU C Library 21 253 In addition TR1 includes as Decimal floating point
66. data members I e a fr_FR locale that doesn t have numpunct truename does it use true Or is it a blank string What s the convention Explain how locale aliasing happens When does de_DE use de information What is the rule for locales composed of just an ISO language code say de and locales with both an ISO language code and ISO country code say de_DE What should non required facet instantiations do If the generic implementation is provided then how to end users provide specializations 8 1 1 5 Bibliography 19 Roland McGrathUlrich Drepper The GNU C Library Copyright O 2007 FSF Chapters 6 Character Set Handling and 7 Locales and Internationalization 20 Ulrich Drepper Correspondence Copyright O 2002 21 ISO IEC 14882 1998 Programming languages C Copyright 1998 ISO 22 ISO IEC 9899 1999 Programming languages C Copyright O 1999 ISO 23 uri System Interface Definitions Issue 7 IEEE Std 1003 1 2008 Copyright 2008 The Open Group The Institute of Electrical and Electronics Engineers Inc 24 Bjarne Stroustrup The C Programming Language Special Edition Copyright 2000 Addison Wesley Inc Appendix D Addison Wesley 25 Angelika LangerKlaus Kreft Standard C IOStreams and Locales Advanced Programmer s Guide and Reference Copyright O 2000 Addison Wesley Longman Inc Addison Wesley Longman The GNU C Library 67 253 8 2 Facets 8 2 1 ctype
67. enable disable and with without The defaults are for the current development sources which may be different than those for released versions The canonical way to find out the configure options that are available for a given set of libstdc sources is to go to the source directory and then type configure help enable multilib default This is part of the generic multilib support for building cross compilers As such targets like powerpc elf will have libstdc built many different ways msoft float and not etc A different libstdc will be built for each of the different multilib versions This option is on by default The GNU C Library 16 253 enable sjlj exceptions Forces old set jump long jump exception handling model If at all possible the new frame unwinding exception handling routines should be used instead as they significantly reduce both runtime memory usage and executable size This option can change the library ABI enable version specific runtime libs Specify that run time libraries should be installed in the compiler specific subdirectory 1 e Libdir gcec lib target_alias gcc_version instead of 1ibd ir This option is useful if you intend to use several versions of gcc in parallel In addition libstdc s include files will be installed in libdir gcc lib S target_alias gcc_version include g unless you also specify with gxx include dir dirname during configuration
68. estimation The idea is to estimate or measure the cost of all operations in the original scenario versus the scenario we advise to switch to For instance when advising to change a vector to a list an occurrence of the insert method will generally count as a benefit Its magnitude depends on 1 the number of elements that get shifted and 2 whether it triggers a reallocation e Synthetic measurements We will measure the relative difference between similar operations on different containers We plan to write a battery of small tests that compare the times of the executions of similar methods on different containers The idea is to run these tests on the target machine If this training phase is very quick we may decide to perform it at library initialization time The results can be cached on disk and reused across runs e Timers We plan to use timers for operations of larger granularity such as sort For instance we can switch between different sort methods on the fly and report the one that performs best for each call context e Show stoppers We may decide that the presence of an operation nullifies the advice For instance when considering switching from set to unordered_set if we detect use of operator we will simply not issue the advice since this could signal that the use care require a sorted container 19 2 6 Reports There are two types of reports First if we recognize a pattern for which we have a substitute that is likely
69. exceptional symbols are allowed to be visible namespace __gnu_cxx Defaults to not exporting any symbols in label GLIBCXX select items are allowed to be visible namespace __gnu_internal Defaults to not exported no items are allowed to be visible namespace __cxxabivl aliased to namespace abi Defaults to not exporting any symbols in label CXXABI select items are allowed to be visible 3 Freezing the API Disallowed changes as above are not made on a stable release branch Enforcement tends to be less strict with GNU extensions that standard includes B 4 6 Testing B 4 6 1 Single ABI Testing Testing for GNU C ABI changes is composed of two distinct areas testing the C compiler g for compiler changes and testing the C library libstdc for library changes Testing the C compiler ABI can be done various ways One Intel ABI checker Two The second is yet unreleased but has been announced on the gcc mailing list It is yet unspecified if these tools will be freely available and able to be included in a GNU project Please contact Mark Mitchell mark codesourcery com for more details and current status Three Involves using the vlad consistency test framework This has also been discussed on the gcc mailing lists Testing the C library ABI can also be done various ways One Brendan Kehoe Jeff Law suggestion to run make check c two ways one with a new compiler and an old library and the other w
70. expected on this line Uche test edla iE it Oesa t oce Linenum 0 for general tool messages eg V arg missing The GNU C Library 202 253 means the current lin dg warning regexp comment target xfail selector 0 linenum indicate a warning message lt regexp gt is expected on this line ias tesi canles alae slic close OCELE dg bogus regexp comment target xfail selector 0 linenum indicate a bogus error message lt regexp gt use to occur here the test fails if it does occur dg build regexp comment target xfail selector indicate the build use to fail for some reason errors covered here include bad assembler generated tool crashes and link failures the test fails if it does occur dg excess errors comment target xfail selector indicate excess errors are expected any line this should only be used sparingly and temporarily dg output regexp target selector indicate the expected output of the program is lt regexp gt there may be multiple occurrences of this they are concatenated Ckejaicaligiel mte escle y add some tcl code to be run at the end there may be multiple occurrences of this they are concatenated unbalanced braces must be escaped target selector is a list of expressions that determine whether th test succeeds or fails for a particular target or in some cases whether th option applies for a particular target If
71. fer 2 T A e locale displays environmental variables that impact how locale will be deduced gb18030 gbk utf 8 ES Suctw utf8 LANG en_US 65 253 The GNU C Library 66 253 LC_CTYPE en_US LC_NUMERIC en_US LC_TIME en_US LC_COLLATE en_US LC_MONETARY en_US LC_MESSAGES en_US LC_PAPER en_US LC_NAME en_US LC_ADDRESS en_US LC_TELEPHONE en_US LC_MEASUREMENT en_US LC_IDENTIFICATION en_US iC OL From Josuttis p 697 698 which says that there is only one relation of the C locale mechanism to the C locale mecha nism the global C locale is modified if a named C locale object is set as the global locale emphasis Paolo that is stds locale oloba istor locale Matar affects the C functions as if the following call was made stedi S ce hoc alles 110 Miib 041 0 On the other hand there is no vice versa that is calling setlocale has no whatsoever on the C locale mechanism in particular on the working of locale which constructs the locale object from the environment of the running program that is in practice the set of LC_ALL LANG etc variable of the shell 8 1 1 4 Future Locale initialization at what point does _S_classic _S_global get initialized Can named locales assume this initialization has already taken place Document how named locales error check when filling
72. files Yes this can be and has been done This would be the approach of either a visionary genius or a raving lunatic depending on your programming and management style Probably the latter Which of the above techniques you use if any are up to you and your intended application Some time space profiling is indicated if it really matters don t just guess And if you manage to do anything along the lines of the third category the author would love to hear from you Also note that the implementation of bitset used in libstdc has some extensions 9 2 2 2 Type String Bitmasks do not take char nor const char arguments in their constructors This is something of an accident but you can read about the problem follow the library s Links from the homepage and from the C information defect reflector link select the library issues list Issue number 116 describes the problem For now you can simply make a temporary string object using the constructor expression The GNU C Library 80 253 suele lies lt os le 1 eTe serra LALO e instead of stek sbicser lt 5 gt o 10110 J invalid 9 3 Interacting with C 9 3 1 Containers vs Arrays You re writing some code and can t decide whether to use builtin arrays or some kind of container There are compelling reasons to use one of the container classes but you re afraid that you ll eventually run into difficulties change everything back to array
73. for writing and managing this information Actually the number of bytes allocated in this case would be 4 4 4x2 64x4 272 bytes but the first 4 bytes are an addition by the Free List Store so the Bitmap Allocator sees only 268 bytes These first 4 bytes about which the bitmapped allocator is not aware hold the value 268 What do the remaining values represent The 2nd 4 in the expression is the sizeof size_t because the Bitmapped Allocator maintains a used count for each Super Block which is initially set to 0 as indicated in the diagram This is incremented every time a block is removed from this super block allocated and decremented whenever it is given back So when the used count falls to 0 the whole super block will be given back to the Free List Store The value 4294967295 represents the integer corresponding to the bit representation of all bits set 1111111111111111111111111111111 The 3rd 4x2 is size of the bitmap itself which is the size of 32 bits x 2 which is 8 bytes or 2 x sizeof size_t The GNU C Library 138 253 20 2 2 4 Maximum Wasted Percentage This has nothing to do with the algorithm per se only with some vales that must be chosen correctly to ensure that the allocator performs well in a real word scenario and maintains a good balance between the memory consumption and the allocation deal location speed The formula for calculating the maximum wastage as a percentage 32x k 1 2x 32x k
74. free system resources becomes most important The function _S_should_i_give decides the policy that determines whether the current block of memory should be given to the allocator for the request that it has made That s because we may not always have exact fits for the memory size that the allocator requests We do this mainly to prevent external fragmentation at the cost of a little internal fragmentation Now the value of this internal fragmentation has to be decided by this function I can see 3 possibilities right now Please add more as and when you find better strategies 1 Equal size check Return true only when the 2 blocks are of equal size 2 Difference Threshold Return true only when the _block_size is greater than or equal to the _required_size and if the _BS is gt _RS by a difference of less than some THRESHOLD value then return true else return false 3 Percentage Threshold Return true only when the _block_size is greater than or equal to the _required_size and if the _BS is gt RS by a percentage of less than some THRESHOLD value then return true else return false Currently 3 is being used with a value of 36 Maximum wastage per Super Block 20 2 2 2 Super Block A super block is the block of memory acquired from the FLS from which the bitmap allocator carves out memory for sin gle objects and satisfies the user s requests These super blocks come in sizes that are powers of 2 and multiples of 32 _Bits_Per_B
75. gt usr lib libstdct so 6 0x40016000 libm so 6 gt lib tls libm so 6 0x400fa000 lore 8 5071 gt Maz Ae lees c s je cms Sor lm O4 Ohne REED libc so 6 gt lib tls libc so 6 0x40125000 lib ld linux so 2 gt lib ld linux so 2 0x00355000 Sldd libtwo so 1 0 0 libstdct so 5 gt usr lib libstdc so 5 0x40027000 libm so 6 gt lib tls libm so 6 0x400e1000 IgE c ESSE mie abla Ce ie c s ge ESSE ORO S O10I0 The GNU C Library 217 253 Loc s09 gt Jia aT uo s06 IHE Her CHE HD A MS Oma gt A MS OZ Osc0 OSS 01010 Then the C compiler is used to compile a source file that uses functions from each library gce test c g 02 L lon ltwo usr lib libstdct so 5 usr lib libstde so 6 Which gives the expected Sldd a out libstdc so 5 gt usr lib libstdc so 5 0x00764000 libstdc so 6 gt usr lib libstdc t so 6 0x40015000 libc so 6 gt lib tls libc so 6 0x0036d000 libm so 6 gt lib tls libm so 6 0x004a8000 libgcc_s so 1 gt mnt hd bld gcc gcec libgcc_s so 1 0x400e5000 dla s02 gt Jaib ld lhinux so 2 0x0038550 0 0 This resulting binary when executed will be able to safely use code from both liba and the dependent libstdc so 6 and libb with the dependent libstdc so 5 B 4 7 Outstanding Issues Some features in the C language make versioning especially difficult In particular compiler generated constructs such as implicit instantia
76. host file to ensure that your new directory is activated Look for the switch statement that sets os_include_dir and add a pattern to handle your operating system if the default will not suffice The switch statement switches on only the OS portion of the standard target triplet e g the solaris2 8 in sparc sun sola ris2 8 Ifthe new directory is named after the OS portion of the triplet the default then nothing needs to be changed The first file to create in this directory should be called os_defines h This file contains basic macro definitions that are required to allow the C library to work with your C library Several libstdc source files unconditionally define the macro _POSIX_SOURCE On many systems defining this macro causes large portions of the C library header files to be eliminated at preprocessing time Therefore you may have to undef this macro or define other macros like _LARGEFILE_SOURCE or __EXTENSIONS__ You won t know what macros to define or undefine at this point you ll have to try compiling the library and seeing what goes wrong If you see errors about calling functions that have not been declared look in your C library headers to see if the functions are declared there and then figure out what macros you need to define You will need to add them to the CPLUSPLUS_CPP_SPEC macro in the GCC configuration file for your target It will not work to simply define these macros in os_defines h
77. how should operators and work for string of different same encoding The GNU C Library 72 253 what is equal A byte by byte comparison or an encoding then byte comparison conversions between narrow wide and unicode strings e c conversions involving std filebuf and std ostream how to initialize the state object in a standards conformant manner how to synchronize the C and C conversion information wchar_t char internal buffers and conversions between internal external buffers 8 2 2 6 Bibliography 33 Roland McGrathUlrich Drepper The GNU C Library Copyright 2007 FSF Chapters 6 Character Set Handling and 7 Locales and Internationalization 34 Ulrich Drepper Correspondence Copyright 2002 35 ISO IEC 14882 1998 Programming languages C Copyright 1998 ISO 36 ISO IEC 9899 1999 Programming languages C Copyright 1999 ISO 37 uri System Interface Definitions Issue 7 IEEE Std 1003 1 2008 Copyright 2008 The Open Group The Institute of Electrical and Electronics Engineers Inc 38 Bjarne Stroustrup The C Programming Language Special Edition Copyright 2000 Addison Wesley Inc Appendix D Addison Wesley 39 Angelika LangerKlaus Kreft Standard C IOStreams and Locales Advanced Programmer s Guide and Reference Copyright 2000 Addison Wesley Longman Inc Addison Wesley Longman 40 Clive Feather uri A brief description
78. include anything other than the work as a whole that a is included in the normal form of packaging a Major Component but which is not part of that Major Component and b serves only to enable use of the work with that Major Component or to implement a Standard Interface for which an implementation is available to the public in source code form A Major Component in this context means a major essential component kernel window system and so on of the specific operating system if any on which the executable work runs or a compiler used to produce the work or an object code interpreter used to run it The Corresponding Source for a work in object code form means all the source code needed to generate install and for an executable work run the object code and to modify the work including scripts to control those activities However it does not include the work s System Libraries or general purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work For example Corresponding Source includes interface definition files associated with source files for the work and the source code for shared libraries and dynamically linked subprograms that The GNU C Library 241 253 the work is specifically designed to require such as by intimate data communication or control flow between those subprograms and other parts of the work The Correspo
79. is C you have an open ifstream call it IN and an open ofstream call it OUT include lt fstream gt std ifstream IN input_file std ofstream OUT output_file Here s the easiest way to get it completely wrong OVT N For those of you who don t already know why this doesn t work probably from having done it before I invite you to quickly create a simple text file called input_file containing the sentence The quick brown fox jumped over the lazy dog surrounded by blank lines Code it up and try it The contents of output_file may surprise you Seriously go do it Get surprised then come back It s worth it The thing to remember is that the basic_ io stream classes handle formatting nothing else In chaptericular they break up on whitespace The actual reading writing and storing of data is handled by the basic_streambuf family Fortunately the operator lt lt is overloaded to take an ostream and a pointer to streambuf in order to help with just this kind of dump the data verbatim situation Why a pointer to streambuf and not just a streambuf Well the io streams hold pointers or references depending on the implementation to their buffers not the actual buffers This allows polymorphic behavior on the chapter of the buffers as well as the streams themselves The pointer is easily retrieved using the rdbuf member function Therefore the easiest way to copy the file is QUE lt lt UN
80. is correct The GNU C Library 229 253 B 6 3 2 Extension headers hash_map hash_set moved to ext or backwards At this time most of the features of the SGI STL extension have been replaced by standardized libraries In particular the unordered_map and unordered_set containers of TR1 are suitable replacement for the non standard hash_map and hash_set containers in the SGI STL Header files hash map and hash_set moved to ext hash_map and ext hash_set respectively At the same time all types in these files are enclosed in namespace __gnu_cxx Later versions move deprecate these files and suggest using TRI s unordered_map and unordered_set instead The extensions are no longer in the global or std namespaces instead they are declared in the __gnu_cxx namespace For maximum portability consider defining a namespace alias to use to talk about extensions e g ifdef _ GNUC__ E NU CAES include lt hash_map h gt namespace extension using hash_map inherit globals telse include lt backward hash_map gt if _GNUC__ 3 KK GNUC_MINOR 0 namespac xtension std i CEC 30 else namespac xtension __gnu_cxx PASAS Di aia dere endif endif else there are other compilers right namespac xtension std endif extension hash_map lt int int gt my_map This is a bit cleaner than defining typedefs for all the instantiations you might need The following autoconf tests check for workin
81. is currently unused and sets only default variables B 3 4 2 Utilities The testsuite directory also contains some files that implement functionality that is intended to make writing test cases easier or to avoid duplication or to provide error checking in a way that is consistent across platforms and test harnesses A stand alone executable called abi check and a static library called libtestc are constructed Both of these items are not installed and only used during testing These files include the following functionality s testsuite_abi h testsuite_abi cc testsuite_abi_check cc Creates the executable abi_check Used to check correctness of symbol versioning visibility of exported symbols and com patibility on symbols in the shared library for hosts that support this feature More information can be found in the ABI documentation here s testsuite_allocator h testsuite_allocator cc Contains specialized allocators that keep track of construction and destruction Also support for overriding global new and delete operators including verification that new and delete are called during execution and that allocation over max_size fails s testsuite_character h Contains std char_traits and std codecvt specializations for a user defined POD s testsuite_hooks h testsuite_hooks cc A large number of utilities including VERIFY set_memory_limits verify_demangle run_tests_wrapped_locale run_tests_wrapped_env
82. length s argument types Change the first parameter to st ateT amp and implement the new effects paragraph 83 string npos vs string max_size Safety checks on the size of the string should test against max_size rather than npos 90 Incorrect description of operator gt gt for strings The effect contain isspace c getloc which must be replaced by isspace c is getloc 91 Description of operator gt gt and getline for string lt gt might cause endless loop They behave as a formatted input function and as an unformatted input function respectively except that get line is not required to set gcount 103 set iterator is required to be modifiable but this allows modification of keys For associative containers where the value type is the same as the key type both iterator and const_iterator are constant iterators 109 Missing binders for non const sequence elements The binder1st and binder2nd didn t have an operator taking a non const parameter 110 istreambuf_iterator equal not const This was not a const member function Note that the DR says to replace the function with a const one we have instead provided an overloaded version with identical contents 117 basic_ostream uses nonexistent num_put member functions num_put put was overloaded on the wrong types 118 basic_istream uses nonexistent num_get member functions Same as 117 but for num_get get 129 Need error indication from seekp and
83. link code compiled with parallel mode and code compiled without parallel mode if no instantiation of a container is passed between the two translation units Parallel mode functionality has distinct linkage and cannot be confused with normal mode symbols 18 3 3 Using Specific Parallel Components When it is not feasible to recompile your entire application or only specific algorithms need to be parallel aware individual parallel algorithms can be made available explicitly These parallel algorithms are functionally equivalent to the standard drop in algorithms used in parallel mode but they are available in a separate namespace as GNU extensions and may be used in programs compiled with either release mode or with parallel mode An example of using a parallel version of std sort but no other parallel algorithms is include lt vector gt include lt parallel algorithm gt int main Sidi vector si nts wELuUCTs Ji laca rores a Call to parallel Sort __gnu_parallel sort v begin v end return 0 Then compile this code with the prerequisite compiler flags fopenmp and any necessary architecture specific flags for atomic operations The following table provides the names and headers of all the parallel algorithms that can be used in a similar manner 18 4 Design 18 4 1 Interface Basics All parallel algorithms are intended to have signatures that are equivalent to the ISO C algorithms replaced For in
84. message string in the open member function for instance Quite murky and unclear on reflection Lastly it seems odd that messages which explicitly require code conversion don t use the codecvt facet Because the messages facet has only one template parameter it is assumed that ctype and not codecvt is to be used to convert between character sets It is implicitly assumed that the locale for the default message string in get is in the C locale Thus all source code is assumed to be written in English so translations are always from en_US to other explicitly named locales 8 2 3 3 Implementation 8 2 3 3 1 Models This is a relatively simple class on the face of it The standard specifies very little in concrete terms so generic implementations that are conforming yet do very little are the norm Adding functionality that would be useful to programmers and comparable to Java s java text MessageFormat takes a bit of work and is highly dependent on the capabilities of the underlying operating system Three different mechanisms have been provided selectable via configure flags e generic This model does very little and is what is used by default e gnu The gnu model is complete and fully tested It s based on the GNU gettext package which is part of glibc It uses the functions textdomain bindtextdomain gettext to implement full functionality Creating message catalogs is a relatively straight forward proces
85. not for C or C definitions which have not been kept up to date The C run time library contains initialization code that needs to be run as the library is loaded Often that requires linking in special object files when the C library is built as a shared library or taking other system specific actions The libstdc library is linked with the C version of libtool even though it is a C library Therefore the C version of libtool needs to ensure that the run time library initializers are run The usual way to do this is to build the library using gcc shared If you need to change how the library is linked look at 1t cf c sh in the top level directory Find the switch statement that sets archive_cmds Here adjust the setting for your operating system B 3 Test The libstdc testsuite includes testing for standard conformance regressions ABI and performance B 3 1 Organization B 3 1 1 Directory Layout The directory libsrcdir testsuite contains the individual test cases organized in sub directories corresponding to chapters of the C standard detailed below the dejagnu test harness support files and sources to various testsuite utilities that are packaged in a separate testing library All test cases for functionality required by the runtime components of the C standard ISO 14882 are files within the following directories no 18_support 19 diagnostics 210 pre a IL Al ST LNS 22_locale 23_containers 25_a
86. of the gcc 3 0 release and all later point releases Although earlier gcc releases had a different approach to threading configuration and proper compilation the basic code design rules presented here were similar For information on all other aspects of multithreading as it relates to libstdc including details on the proper compilation of threaded code and compatibility between threaded and non threaded code see Chapter 17 Two excellent pages to read when working with the Standard C containers and threads are SGI s http www sgi com tech stl thread_safety html and SGI s http www sgi com tech stl Allocators html The GNU C Library 29 253 However please ignore all discussions about the user level configuration of the lock implementation inside the STL container memory allocator on those pages For the sake of this discussion libstdc configures the SGI STL implementation not you This is quite different from how gcc pre 3 0 worked In particular past advice was for people using g to explicitly define _PTHREADS or other macros or port specific compilation options on the command line to get a thread safe STL This is no longer required for any port and should no longer be done unless you really know what you are doing and assume all responsi bility Since the container implementation of libstdc uses the SGI code we use the same definition of thread safety as SGI when discussing design A key point that beginners may m
87. or padding to avoid false sharing in multithreaded access at foo cc 4 Detected N shared cache lines 19 7 6 Statistics Switch _GLIBCXX_PROFILE_STATISTICS In some cases the cost model may not tell us anything because the costs appear to offset the benefits Consider the choice between a vector and a list When there are both inserts and iteration an automatic advice may not be issued However the programmer may still be able to make use of this information in a different way This diagnostic will not issue any advice but it will print statistics for each container construction site The statistics will contain the cost of each operation actually performed on the container 19 8 Bibliography 54 Lixia LiuSilvius Rus Perflint A Context Sensitive Performance Advisor for C Programs Copyright 2009 Proceedings of the 2009 International Symposium on Code Generation and Optimization The GNU C Library 131 253 Chapter 20 Allocators 20 1 mt_allocator 20 1 1 Intro The mt allocator hereinafter referred to simply as the allocator is a fixed size power of two allocator that was initially developed specifically to suit the needs of multi threaded applications hereinafter referred to as an MT application Over time the allocator has evolved and been improved in many ways in particular it now also does a good job in single threaded applications hereinafter referred to as a ST application Note In this do
88. rehash The GNU C Library 30 253 3 7 2 Exception Neutrality Simply put once thrown an exception object should continue in flight unless handled explicitly In practice this means propagat ing exceptions should not be swallowed in gratuitous catch blocks Instead matching try and catch blocks should have specific catch handlers and allow un handed exception objects to propagate If a terminating catch blocks exist then it should end with a t hrow to re throw the current exception Why do this By allowing exception objects to propagate a more flexible approach to error handling is made possible although not required Instead of dealing with an error immediately one can allow the exception to propagate up until sufficient context is available and the choice of exiting or retrying can be made in an informed manner Unfortunately this tends to be more of a guideline than a strict rule as applied to the standard library As such the following is a list of known problem areas where exceptions are not propagated e Input Output The destructor ios_base Init Init swallows all exceptions from flush called on all open streams at termina tion All formatted input in basic_istream or formatted output in basic_ostream can be configured to swallow exceptions when exceptions is set to ignore ios_base badbit Functions that have been registered with ios_base register_callback swallow all exceptions when called as
89. s Example oe Aero O 2 vector lt intx gt v 10000000 amp zero S cor ime k 08 k lt 10000000 maki 4 4 v random 10000000 new int k S tor int 5 OF a lt 10000000 ro 4 7 Covme MES H 2 OLE 8 LO c advice se rt prekereh instructions 19 7 4 2 Linked Structure Locality T e Switch GLIBCXX_PROFILE_RBTREE_LOCALITY Goal Give measure of locality of objects stored in linked structures lists red black trees and hashtables with respect to their actual traversal patterns e Fundamentals Allocation can be tuned to a specific traversal pattern to result in better data locality See paper Custom Memory Allocation for Free e Sample runtime reduction 30 e Recommendation High scatter score N for container built at site S Consider changing allocation sequence or choosing a structure conscious allocator e To instrument Methods of all containers using linked structures e Analysis First get cache line size and page size from system Then record the number of successive elements that are on different line or page for each traversal method such as find Give advice only if the ratio between this number and the number of total node hops is above a threshold e Cost model Sum same_cache_line this previous The GNU C Library 129 253 s Example set lt int gt s moje ae al WP 1 lt TOOMOOOWPS ra 4 Shaimse mite ne SceSsime gt Gil 2p moje Siam a O
90. secondary and in fact will be worse than the release mode Usability the libstdc debug mode should be easy to use It should be easily incorporated into the user s development environment e g by requiring only a single new compiler switch and should produce reasonable diagnostics when it detects a problem with the user program Usability also involves detection of errors when using the debug mode incorrectly e g by linking a release compiled object against a debug compiled object if in fact the resulting program will not run correctly Minimize recompilation While it is expected that users recompile at least part of their program to use debug mode the amount of recompilation affects the detect compile debug turnaround time This indirectly affects the usefulness of the debug mode because debugging some applications may require rebuilding a large amount of code which may not be feasible when the suspect code may be very localized There are several levels of conformance to this requirement each with its own usability and implementation characteristics In general the higher numbered conformance levels are more usable i e require less recompilation but are more complicated to implement than the lower numbered conformance levels 1 Full recompilation The user must recompile his or her entire application and all C libraries it depends on including the C standard library that ships with the compiler This must be done even if onl
91. seekg These functions set failbit on error now The GNU C Library 130 136 167 169 171 181 195 211 214 231 233 235 241 243 251 253 265 266 271 275 280 292 300 303 305 11 253 Return type of container erase iterator differs for associative containers Make member erase return iterator for s et multiset map multimap seekp seekg setting wrong streams seekp should only set the output stream and seekg should only set the input stream Improper use of traits_type length op lt lt witha const char was calculating an incorrect number of characters to write Bad efficiency of overflow mandated Grow efficiently the internal array object Strange seekpos semantics due to joint position Quite complex to summarize make_pair unintended behavior This function used to take its arguments as reference to const now it copies them pass by value Should basic_istream sentry s constructor ever set eofbit Yes it can specifically if EOF is reached while skipping whitespace operator gt gt istream amp string amp doesn t set failbit If nothing is extracted into the string op gt gt now sets failbit which can cause an exception etc etc set find missing const overload Both set and multiset were missing overloaded find lower_bound upper_bound and equal_range functions for const instances Precision in iostream For con
92. sepa i e Sg E a Bs Sw ON we Re a we Re He ok A we 6 3 2 2 Use Contamers s s sa cs be me ea ae Pa eae Ewe ee ae RR 6 3 3 shared Pis sos aks Bec ws ee SE A Se Ge AR Ea SERS Ga Soe RGR eee ee 8 6 3 3 Requirement coo p44 40654 Pe bie be bee ee ee ee ae h 6 3 3 2 Desipnilssies soi asar bk BSS eS RMR ERS ee a eH A ee 6 3 3 3 Implementation v ssd esteen d 2 0 00 0200000000000 0000000 vi 36 37 37 37 38 38 39 40 40 40 42 42 42 42 42 The GNU C Library 6333 1 Class Hierarchy Vic e A a a 6 33 3 2 Thread Safety users a aa A a e A a e 6 3 3 3 3 Selecting Lock Policy o o e 6 3 3 3 4 Dual C 0x and TRI Implementation o e 6 3 3 3 5 Related functions and Classes a 63d MSGS 24 4624 peda o A oe eee SO 63341 Examples i225 cose Yad Res wee ee ee ee wy eRe eee oS 6 3 3 4 2 Unresolved Issues e g R RR A E N 6 3 3 5 Acknowledgments p sc es ag R T e RR TR R RRR RR ee 6 3 3 6 Bibliography T OA Wraats e sxeckhs eo GAG Sa E A RO SE BA Rae A RAG ome Bec es Bek 7 Strings Tel String Classes epa ape ap debe BE we AS ADA wR As xe ae dee Be Se 7 1 1 Simple Transformations oaoa 741 2 Case Sensitivity 234 sume p s YA eee eS are oY Bee ee od YE ee ee eS 7 1 3 Arbitrary Character Types esop Sy t4ida owe Ewes di ES Seeds AA es 7 1 4 Tokenizing ss 20 45h bt ae opie bi wea ew bas bea dee ead se bP Gae hae E Rls Shrink toFit 4 4 droee os HB eee e
93. siria ada a A La a ee 94 15 Concurrency 95 15 1 API Referente sucre a gah a AS a o a ia a e 95 TI Extensions 96 16 Compile Time Checks 98 17 Debug Mode 99 UT cy AA AAN 99 17 2 Semantics ira ea a A A A 99 17 3 WSUS a A Sie dee abe A ee ce ER A Ate a So AA e e 100 17 3 1 Using the Debug Mode K RR ee ee sos ee 100 17 3 2 Using a Specific Debug Container ee 100 17 4 DeSIPD 6 5 sa a a Be he a ae Re eee SS be Se ee we es 102 LAA e c 4 355 os 2 ha eee oS AERP ERE RA A he eee e 102 The GNU C Library x 117 4 2 1 The Wrapper Model lt ss ara ae R Ra Se ee ek ee a EE oS 103 WADIA SafeSteratots sca Ga ek Ra RE AAG Raa be RA wha ek 103 17 4 2 1 2 Safe Sequences Containers a 103 17 4 2 2 Precondition Checking lt a coo esee RR R ee Se ee eee RO ee oO 104 17 4 2 3 Release and debug mode coexistence 0000000 eee eee eee 104 17 4 2 3 1 Compile time coexistence of release and debug mode components o 104 17 4 2 3 2 Link and run time coexistence of release and debug mode components 105 17 4 2 3 3 Alternatives for Coexistence 2 2 2 ee ee ee ee 106 17 4 3 Other Implementations 2 2 2 00000 a 107 18 Parallel Mode 108 WS Intro c ce ee da A a A a A a a baw e 108 8 2 Semantics ius ace Ve ees A o Ae E oe E Eee ales da 109 t83 USINE e eto Di A E e A AA AE AS AA e K 109 18 3 1 Prerequisite Compiler Flags ee 109 18 3 2 Using Parallel Mo
94. some platforms that covered up implementation errors Now the test suite has a policy of one file one test case which solves the above issues and gives finer grained results and more manageable error debugging As an example the test case quoted above becomes 2i strings siesta enal e ies nos stes ult nO ca AC 21_strings basic_string find char 3 cc 21l SS ase Siervas y Enea 10 1 ES ZAS ic nOs pasais alta o Timey Eh EA CE 21_strings basic_string find wchar_t 3 cc All new tests should be written with the policy of one test case one file in mind B 3 1 2 Naming Conventions In addition there are some special names and suffixes that are used within the testsuite to designate particular kinds of tests e _xin cc This test case expects some kind of interactive input in order to finish or pass At the moment the interactive tests are not run by default Instead they are run by hand like g 27_i0 objects char 3_xin ce Caetano Obs CCS char duna ce Outs ein This file contains the expected input for the corresponding _xin cc test case e _neg cc This test case is expected to fail it s a negative test At the moment these are almost always compile time errors s char This can either be a directory name or part of a longer file name and indicates that this file or the files within this directory are testing the char instantiation of a template The GNU C Library 199 253 s wchar_t This can either be a director
95. sort_algorithmcan have any values of enum __gnu_parallel _SortAlgorithn MWMS QS or QS_BALANCED Likewise for setting the minimal threshold for algorithm parallelization Parallelism always incurs some overhead Thus it is not helpful to parallelize operations on very small sets of data Because of this measures are taken to avoid parallelizing below a certain pre determined threshold For each algorithm a minimum problem size is encoded as a variable in the active __gnu_parallel _Settings object This threshold variable follows the following naming scheme __ gnu_parall el _Settings algorithm _minimal_n So for fill the threshold variable is__gnu_parallel _Sett ings fi11_minimal_n Finally hardware details like L1 L2 cache size can be hardwired via__ gnu_parallel _Settings Ll1_cache_size and friends All these configuration variables can be changed by the user if desired There exists one global instance of the class_Settings i e it is a singleton It can be read and written by calling __gnu_parallel _Settings get and__gnu_parall el _Settings set respectively Please note that the first call return a const object so direct manipulation is forbidden See settings h for complete details The GNU C Library 114 253 A small example of tuning the default include lt parallel algorithm gt include lt parallel settings h gt int main __gnu_parallel _Settings s s algorithm_strategy __gnu_paralle
96. tf8 tf 8 euro uro tf8 tf8feuro tf8 uro tf8 tf8feuro tf8 ES uro tf8 tf 8 euro uro tf8 tf8leuro O tf8feuro 63 253 The GNU C Library 64 253 gl_ES utf8 euro gv_GB utf8 he_IL utf8 lowes Joliet Whe atte U DUMAS whesets D DUES Le INS he Ee e Cial Cl teste IT it_IT euro ae ICI y Whe Elo it_IT utf8 euro iw_IL Wee ble S ja_JP eucjp Jan PA ka_GE k1_GL k1_GL utf8 ko_KR euckr ko_KR utf8 kw_GB kw_GB utf8 T ET AS ALAS iy rS mk mk tf8 E lt a utf8 ines JE mos ms_ Weed men n EAS ERES euro AUS utf 8 euro n n w w w w E i MAAK KAR ARN nd nl_NL nl_NL euro AN TUS utf 8 euro O nn_NO utf8 O O SUS Sd IP bys Wiese The GNU C Library PESBR BEZBES EPT utf8 pt_PT euro PESEN PETE OERO FO RO ru_RU He JNU 5 UM 2 ru_UA ru_UA se_NO sk_SK SE 5K SL GI sl Sis sq_AL SEGEN SIA utf8 utf8 euro ut T B KOMO utf8 utf8 utf8 utf8 utf8 Sad eya rie Sa SA SVENE utf8 utf 8 cyrillic sv_FlI euro SWI I n lt n lea ea eal p utf8 utf 8 euro so885915 ESE ETS edb IP isl bie WR Ere TR uk_UA uk_UA We JL uz_UZ A EEN wa_BE ES SUERO utf8 tcvn wa_BE euro Ke H n 06 6 E N NN NN NNNN er i er fey fer fer
97. that the __gthread_self call will not return a value that corresponds to the maximum number of threads allowed but rather a process id number or something else So what we do is that we create a list of thread_records This list is _S_max_threads long and each entry holds a size_t thread_id which is initialized to 1 2 3 4 5 and so on up to _S_max_threads Each time a thread calls allocate or deallocate we call _S_get_thread_id which looks at the value of _S_thread_key which is a thread local storage pointer If this is NULL we know that this is a newly created thread and we pop the first entry from this list and saves the pointer to this record in the _S_thread_key variable The next time we will get the pointer to the thread_record back and we use the thread_record gt thread_id as identification I e the first thread that calls allocate will get the first record in this list and thus be thread number 1 and will then find the pointer to its first free 32 byte block in _S_bin 5 first 1 When we create the _S_thread_key we also define a destructor _S_thread_key_destr which means that when the thread dies this thread_record is returned to the front of this list and the thread id can then be reused if a new thread is created This list is protected by a mutex _S_thread_freelist_mutex which is only locked when records are removed or added to the list Initialize the free and used counters of each bin_record bin_record gt free An a
98. the C ABI one must use a corresponding GNU C toolchain i e g and libstdc that implements the C ABI in question B 4 2 Versioning The C interface has evolved throughout the history of the GNU C toolchain With each release various details have been changed so as to give distinct versions to the C interface B 4 2 1 Goals Extending existing stable ABIs Versioning gives subsequent releases of library binaries the ability to add new symbols and add functionality all the while retaining compatibility with the previous releases in the series Thus program binaries linked with the initial release of a library binary will still link correctly if the library binary is replaced by carefully managed subsequent library binaries This is called forward compatibility The reverse backwards compatibility is not true It is not possible to take program binaries linked with the latest version of a library binary in a release series with additional symbols added substitute in the initial release of the library binary and remain link compatible Allows multiple incompatible ABIs to coexist at the same time B 4 2 2 History How can this complexity be managed What does C versioning mean Because library and compiler changes often make binaries compiled with one version of the GNU tools incompatible with binaries compiled with other either newer or older versions of the same GNU tools specific techniques are used to make mana
99. the Document or a portion of it either copied verbatim or with modifications and or translated into another language A Secondary Section is a named appendix or a front matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document s overall subject or to related matters and contains nothing that could fall directly within that overall subject Thus if the Document is in part a textbook of mathematics a Secondary Section may not explain any mathematics The relationship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regarding them The Invariant Sections are certain Secondary Sections whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not identify any Invariant Sections then there are none The GNU C Library 249 253 The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 wor
100. the library cannot track what you do on your own with a file descriptor so if you perform any I O directly don t expect the library to be aware of it Beginning with 3 1 the extra filebuf constructor and the fd function were removed from the standard filebuf Instead lt ext stdio_filebuf h gt contains a derived class called __gnu_cxx stdio_filebuf This class can be constructed from a CFILEx or a file descriptor and provides the fd function If you want to access a filebuf s file descriptor to implement file locking e g using the fcnt1 system call then you might be interested in Henry Suter s RWLock class The GNU C Library Chapter 27 Demangling 148 253 Transforming C ABI identifiers like RTTI symbols into the original C source identifiers is called demangling If you have read the source documentation for namespace abi then you are aware of the cross vendor C ABI in use by GCC One of the exposed functions is used for demangling abi __cxa_demangle In programs like c filt the linker and other tools have the ability to decode C ABI names and now so can you The function itself might use different demanglers but that s the whole point of abstract interfaces If we change the implemen tation you won t notice Probably the only times you ll be interested in demangling at runtime are when you re seeing t ypeid strings in RTTL or when you re handling the runtime suppo
101. to as FLS for the remaining part of this document is the Global memory pool that is shared by all instances of the bitmapped allocator instantiated for any type This maintains a sorted order of all free memory blocks given back to it by the bitmapped allocator and is also responsible for giving memory to the bitmapped allocator when it asks for more Internally there is a Free List threshold which indicates the Maximum number of free lists that the FLS can hold internally cache Currently this value is set at 64 So 1f there are more than 64 free lists coming in then some of them will be given back to the OS using operator delete so that at any given time the Free List s size does not exceed 64 entries This is done because a Binary Search is used to locate an entry in a free list when a request for memory comes along Thus the run time complexity of the search would go up given an increasing size for 64 entries however 1g 64 6 comparisons are enough to locate the correct free list if it exists Suppose the free list size has reached it s threshold then the largest block from among those in the list and the new block will be selected and given back to the OS This is done because it reduces external fragmentation and allows the OS to use the larger The GNU C Library 137 253 blocks later in an orderly fashion possibly merging them later Also on some systems large blocks are obtained via calls to mmap so giving them back to
102. uses an industry standard C ABI starting with version 3 Details can be found in the ABI specification The GNU C compiler g has a compiler command line option to switch between various different C ABIs This explicit version switch is the flag fabi version In addition some g command line options may change the ABI as a side effect of use Such flags include fpack struct and fno exceptions but include others see the complete list in the GCC manual under the heading Options for Code Generation Conventions The configure options used when building a specific libstdc version may also impact the resulting library ABI The available configure options and their impact on the library ABI are documented here Putting all of these ideas together results in the C Standard library ABI which is the compilation of a given library API by a given compiler ABI In a nutshell library API compiler ABI library ABI The library ABI is mostly of interest for end users who have unresolved symbols and are linking dynamically to the C Standard library and who thus must be careful to compile their application with a compiler that is compatible with the available C Standard library binary In this case compatible is defined with the equation above given an application compiled with a given compiler ABI and library API it will work correctly with a Standard C Library created with the same constraints To use a specific version of
103. when unexpectedly killed via exceptional circumstances Two general topics of discussion follow exception neutrality and exception safety 3 7 1 Exception Safety What is exception safe code Will define this as reasonable and well defined behavior by classes and functions from the standard library when used by user defined classes and functions that are themselves exception safe Please note that using exceptions in combination with templates imposes an additional requirement for exception safety Instan tiating types are required to have destructors that do no throw Using the layered approach from Abrahams can classify library components as providing set levels of safety These will be called exception guarantees and can be divided into three categories e One Don t throw As specified in 23 2 1 general container requirements Applicable to container and string classes Member functions erase pop_back pop_front swap clear And iterator copy constructor and assignment operator e Two Don t leak resources when exceptions are thrown This is also referred to as the basic exception safety guarantee This applicable throughout the standard library e Three Commit or rollback semantics This is referred to as strong exception safety guarantee As specified in 23 2 1 general container requirements Applicable to container and string classes Member functions insert of a single element push_back push_front and
104. which implies the C 0x functionality and deprecations in lt functional gt will be present Second the other headers can be included with either dialect of the standard headers although features and types specific to C 0x are still only enabled when in C 0x compilation mode So to use rvalue references with __gnu_cxx vstri ng or to use the debug mode versions of std unordered_map one must use the std gnu 0x compiler flag Or std c 0x of course A special case of the second rule is the mixing of TR1 and C 0x facilities It is possible although not especially prudent to include both the TR1 version and the C 0x version of header in the same translation unit include lt trl type_traits gt include lt type_traits gt Several parts of C 0x diverge quite substantially from TR1 predecessors The GNU C Library 22 253 debug bitset debug deque debug list debug map debug set debug debug E PETRER unordered_map unordered_set AR ieee Or Table 3 11 Extension Debug Headers profile bitset profile deque profile list profile map fil fil S Sek a ile unordered_ ile unordered_ orot rie yectot Table 3 12 Extension Profile Headers 3 2 3 The C Headers and namespace std The standard specifies that if one includes the C style header lt math h gt in this case the symbols will be available in the global namespace and perhaps in namespace std but this is
105. which will evaluate to std string or string ie in the global namespace on systems that do not put string in std dnl synopsis AC_CXX_NAMESPACE_STD Se dnl If the compiler supports namespace std define dnl HAVE_NAMESPACE_STD dnl dnl category Cxx dnl author Todd Veldhuizen dnl author Luc Maisonobe lt luc spaceroots org gt dnl version 2004 02 04 dnl license AllPermissive AC_DEFUN AC_CXX_NAMESPACE_STD AC CACHE CHECK if g supports namespace std ac_cv_cxx_have_std_namespace AC_LANG_SAVE AC_LANG_CPLUSPLUS AC_TRY_COMPILE include lt iostream gt secs Sastre als Sola reas ll ay ac_cv_cxx_have_std_namespace yes ac_cv_cxx_have_std_namespace no AC_LANG_RESTORE 1 if test Sac_cv_cxx_have_std_namespace yes then AC_DEFINE HAVE_NAMESPACE_STD Define if g supports namespace std SEa The GNU C Library 224 253 B 6 2 2 Illegal iterator usage The following illustrate implementation allowed illegal iterator use and then correct use e you cannot do ostream operator lt lt iterator to print the address of the iterator gt use operator lt lt xite rator instead e you cannot clear an iterator s reference iterator 0 gt use iterator iterator_type e if iterator won t work any more gt use if iterator iterator_type B 6 2 3 isspace from cctype is a macro Glibc 2 0 x a
106. would otherwise violate the terms of GPLv3 provided that all Target Code was generated by Eligible Compilation Processes You may then convey such a combination under terms of your choice consistent with the licensing of the Independent Modules 2 No Weakening of GCC Copyleft The availability of this Exception does not imply any general presumption that third party software is unaffected by the copyleft requirements of the license of GCC Hopefully that text is self explanatory If it isn t you need to speak to your lawyer or the Free Software Foundation 1 2 2 The Documentation GPL FDL The documentation shipped with the library and made available over the web excluding the pages generated from source com ments are copyrighted by the Free Software Foundation and placed under the GNU Free Documentation License version 1 2 There are no Front Cover Texts no Back Cover Texts and no Invariant Sections For documentation generated by doxygen or other automated tools via processing source code comments and markup the original source code license applies to the generated files Thus the doxygen documents are licensed GPL If you plan on making copies of the documentation please let us know We can probably offer suggestions 1 3 Bugs 1 3 1 Implementation Bugs Information on known bugs details on efforts to fix them and fixed bugs are all available as part of the GCC bug tracking system with the category set to libst
107. writing such a definition to fit all possible CharT s cannot be done The C standard also requires that char_traits be specialized for instantiations of char and wchar_t and it is these template specializations that permit entities like basic_string lt char char_traits lt char gt gt to work If you want to use character types other than char and wchar_t such as unsigned char and int you will need suitable specializations for them For a time in earlier versions of GCC there was a mostly correct implementation that let programmers be lazy but it broke under many situations so it was removed GCC 3 4 introduced a new implementation that mostly works and can be specialized even for int and other built in types If you want to use your own special character class then you have a lot of work to do especially if you with to use i18n features facets require traits information but don t have a traits argument Another example of how to specialize char_traits was given on the mailing list and at a later date was put into the file inclu de ext pod_char_traits h We agree that the way it s used with basic_string scroll down to main doesn t look nice but that s because the nice looking first attempt turned out to not be conforming C due to the rule that CharT must be a POD See how tricky this is 7 1 4 Tokenizing The Standard C and C function st rtok leaves a lot to be desired in terms of user friendliness It s uni
108. 22 253 B 5 11 4 5 C 0X features e Added functional future random e Updated and improved atomic system_error type_traits e Add support for explicit operators and standard layout types Profile mode first appears Support for decimal floating point arithmetic including decimal32 decimal64 and decimal128 Python pretty printers are added for use with appropriately advanced versions of gdb Audit for application of function attributes notrow const pure and noreturn The default behavior for comparing typeinfo names changed so in typeinfo __GXX_MERGED_TYPEINFO_NAMES now defaults to zero Extensions modified ext throw_allocator h B 6 Backwards Compatibility B 6 1 First The first generation GNU C library was called libg It was a separate GNU project although reliably paired with GCC Rumors imply that it had a working relationship with at least two kinds of dinosaur Some background libg was designed and created when there was no ISO standard to provide guidance Classes like linked lists are now provided for by 1ist lt T gt and do not need to be created by genclass For that matter templates exist now and are well supported whereas genclass mostly predates them There are other classes in libg that are not specified in the ISO Standard e g statistical analysis While there are a lot of really useful things that are used by a lot of people the Standards Committee couldn
109. 3 Third The third generation GNU C library is called libstdc or libstdc v3 The subset commonly known as the Standard Template Library chapters 23 through 25 mostly is adapted from the final release of the SGI STL version 3 3 with extensive changes A more formal description of the V3 goals can be found in the official design document Portability notes and known implementation limitations are as follows B 6 3 1 Pre ISO headers moved to backwards or removed The pre ISO C headers iostream h defalloc h etc are available unlike previous libstdc versions but inclusion generates a warning that you are using deprecated headers This compatibility layer is constructed by including the standard C headers and injecting any items in std into the global namespace For those of you new to ISO C welcome time travelers no that isn t a typo Yes the headers really have new names Marshall Cline s C FAQ Lite has a good explanation in item 27 4 Some include adjustment may be required What follows is an autoconf test that defines PRE_STDCXX_HEADERS when they exist The GNU C Library 228 253 AC_HEADER_PRE_STDCXX AC_DEFUN AC_HEADER_PRE_STDCXX ACREACHEMCHE CK EE OLAP rel TT TET ac_Cv_cxx_pre_stdcxx AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS CXXFLAGS SCXXFLAGS Wno deprecated Omit defalloc h as compilation with
110. 344 e a Behe a ew RG aed sb ewe oR ads ew wae Eee e 20 222 Super Block ir e bop adh othe A a edie Ss 20 2 2 3 Super Block DataLayout Bam rE are u ar 20 2 2 4 Maximum Wasted Percentage 2 ee 202235 aTLGGate E soe ook onde a aoe Sao ee o ER See Ee 4 202 216 dedllocate yi i246 6 44 84 b 6 Gb ewe Sew beh bee wi w kh Oba ew eS 20 2 2 7 QUESTIONS 2 eed bb eRe eA AE A Re ee eS ZOD 20M Ah AA S Be oh ok Be ey E A DE owe Be oe be ee e EE Pw DOBLA Vir Goa EM hoe A Re ee a Re eo ER ES SS 20 27 28 Locality 4 22 4844 44805 bees Bae oe ORAS R EEE Sow ea ee Sea eee 20 2 2 9 Overhead and Grow Policy 0 a Containers 21 1 Policy Based Data Structures e e R KR R RRR R RRR RRR RRR RRR RRR RRR 21 2 HP SG cc cms 8 ta RE R RE A a a eae bee 2 21 3 Deprecated HP SOL 2254225 o e a E E E EE S Utilities Algorithms Numerics Iterators Input and Output 26 1 Derived filebufs ra dor e A A A A A ee A A A 9 xii 131 131 131 131 131 132 132 133 133 134 135 136 136 136 136 137 137 138 138 139 139 139 139 139 140 140 141 141 141 142 143 144 145 146 147 The GNU C Library xiii 27 Demangling 148 28 Concurrency 150 28 1 Desin g ora eS e a de E A A KR RR R H le 150 28 1 1 Interface to Locks and Mutexes e etae ctra rr 150 28 1 2 Interface to Atomic Functions ee 150 28 2 Implementation s soc pa eoa Re ee eR eae a 151 28 2 1 Using Builtin Atomi
111. 44 253 8 Termination You may not propagate or modify a covered work except as expressly provided under this License Any attempt otherwise to propagate or modify it is void and will automatically terminate your rights under this License including any patent licenses granted under the third paragraph of section 11 However if you cease all violation of this License then your license from a particular copyright holder is reinstated a provi sionally unless and until the copyright holder explicitly and finally terminates your license and b permanently if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation Moreover your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means this is the first time you have received notice of violation of this License for any work from that copyright holder and you cure the violation prior to 30 days after your receipt of the notice Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License If your rights have been terminated and not permanently reinstated you do not qualify to receive new licenses for the same material under section 10 9 Acceptance Not Required for Having Copies You are not required to accept this License in order to receive
112. 59 15 ISO 10646 ISO 10646 UCS2 ISO 10646 UCS4 TSO 10646 UTF 8 ISO 10646 UTF8 SHIFT JIS SHIFT_JIS UCS 2 UCS 4 VES UCS4 UNICODE UNTCODER LG UNLCODELLEodeLE US ASC IL US ULE 3 UAB IG WW WTI For iconv based implementations string literals for each of the encodings i e UCS 2 and UTF 8 are necessary although for other non iconv implementations a table of enumerated values or some other mechanism may be required e Maximum length of the identifying string literal e Some encodings require explicit endian ness As such some kind of endian marker or other byte order marker will be neces sary See Footnotes for C C developers in Haible for more information on UCS 2 Unicode endian issues Summary big endian seems most likely however implementations most notably Microsoft vary e Types representing the conversion state for conversions involving the machinery in the C library or the conversion descriptor for conversions using iconv such as the type iconv_t Note that the conversion descriptor encodes more information than a simple encoding state type e Conversion descriptors for both directions of encoding i e both UCS 2 to UTF 8 and UTF 8 to UCS 2 e Something to indicate if the conversion requested if valid e Something to represent if the conversion descriptors are valid e Some way to enforce stri
113. COR RECTION 16 Limitation of Liability IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MODIFIES AND OR CONVEYS THE PROGRAM AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES INCLUDING ANY GENERAL SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES 17 Interpretation of Sections 15 and 16 If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program and you want it to be of the greatest possible use to the public the best way to achieve this is to make it free software which everyone can redistribute and change under these terms To do so attach the following notices to the program It is safest to attach them to the start of each source
114. Class std ifstream input_file y extern std ostreamg operator lt lt std ostreams MyClass amp lt ios gt declares the base classes for the entire I O stream hierarchy std ios_base and std basic_ios lt charT gt the counting types std streamoff and std streamsize the file positioning type std fpos and the various manipulators like std hex std fixed std noshowbase and so forth The ios_base class is what holds the format flags the state flags and the functions which change them setf widthQ precision etc You can also store extra data and register callback functions through ios_base but that has been historically underused Anything which doesn t depend on the type of characters stored is consolidated here The template class basic_ios is the highest template class in the hierarchy it is the first one depending on the character type and holds all general state associated with that type the pointer to the polymorphic stream buffer the facet information etc lt streambuf gt declares the template class basic_streambuf and two standard instantiations streambuf and wstreambuf If you need to work with the vastly useful and capable stream buffer classes e g to create a new form of storage transport this header is the one to include lt istream gt lt ostream gt are the headers to include when you are using the gt gt lt lt interface or any of the other abstract stream formatting funct
115. DAS COMDINCS 21h ve le ed Ee BR ee Dare Be aes oe Ae Bees eee A Ghee gs amp amp 173 A 4 3 1 Generating Combines and Assemblages e 173 AS Desis NOTES venias 4 ar e a a A a a ie de 173 The GNU C Library xiv B Porting and Maintenance AppendixPorting and Maintenance 189 B 1 Configure and Build Hacking RRR RRR R ENR R RL 189 B 1 1 PrereqUisiles cocoa sor a Aa A A a AG wal god oa 189 B 1 2 Overview What Comes from Where ee 189 B 1 3 Storing Information in non AC files like configure host o o o 189 B 1 4 Coding and Commenting Conventions 2 2 2 0 0 00 0 00 ee ee 189 B 1 5 The acinclude m4 layout poder ee ee ea eee ee a ee 190 B 1 6 GLIBCXX_ENABLE the enable maker 0 0 00 000 eee ee 191 B 2 Porting to New Hardware or Operating Systems 2 2 ee ee 192 B21 Operating System 56 244 4222 bob bee A oe ThE SESS ES 192 B 22 CRU cue E ib es eG GR ds ie we ed e Ph oe Bie ete bw 6 ek oe eZ 193 B 2 3 Character Types i cine a ea de bee dee Ae E de ene he E ee 193 B24 Thread Safety o nck save A eae yt A eee Ae wees Cede BE SR AS SS we 196 B 2 5 Numerico Limits 205 ke pe ee be REP BR RE a ee Lee ee 197 B 2 6 Libt ol s s pb eben eign rd A ede bbe bd eS 197 Bi Test s mir ete ae a Ge e Spe ES eS ER Ge Bie odd a Seth be te 197 B31 Ofganization vu ari e A ae Ye eee Be AS EG Oe Re Ee SS 197 B 3 1 1 Directory Layout 6 46 2 dr
116. Derived from this are several classes that may have a st ring member a full hierarchy can be found in the source documentation Full API details 5 1 2 Adding Data to exception The standard exception classes carry with them a single string as data usually describing what went wrong or where the throw took place It s good to remember that you can add your own data to these exceptions when extending the hierarchy struct My_Exception public std runtime_error p ber My_Exception const string amp whatarg std runtime_error whatarg e errno id GetDataBaseID int errno_at_time of throw const return e DBID Le O thangs thatsehrew const return kely protected lke aie e DBID id some user defined typ y 5 2 Concept Checking In 1999 SGI added concept checkers to their implementation of the STL code which checked the template parameters of instantiated pieces of the STL in order to insure that the parameters being used met the requirements of the standard For example the Standard requires that types passed as template parameters to vector be Assignable which means what you think it means The checking was done during compilation and none of the code was executed at runtime Unfortunately the size of the compiler files grew significantly as a result The checking code itself was cumbersome And bugs were found in it on more than one occasion The GNU C Library 43 253
117. EADERS Define if ISO C Ed B 6 3 6 Support for C TR1 dialect Check for library coverage of the TR1 standard AC_HEADER_STDCXX_TR1 AC_DEFUN AC_HEADER_STDCXX_TR1 AC_CACHE ACC VACAS SieCescxant Gailey AC_LANG_SAVE AC_LANG_CPLUSPLUS AC_TRY_COMPILE include lt trl array gt include lt tr1 ccomplex gt include lt trl1 cctype gt include lt tr1 cfenv gt include lt tr1 cfloat gt include lt trl1 cinttypes gt include lt tr1 climits gt CMHC S LEI SO Coros INR LG Reer males 1998 header files ar present 1 231 253 The GNU C Library vr imel RACA Ei incl Toed AE bae dl FNCA are Je Imek tmel Pacl CA Haed tmel amel Taek ENKA Haei ie ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ude ac_cv_cxx_stdcxx_trl yes cmath gt complex gt cstdarg gt cstdbool gt cstdint gt cstdio gt cstdlib gt ctgmath gt ctime gt cwchar gt cwctype gt functional gt memory gt random gt regex gt tuple gt type_traits gt unordered_set gt unordered_map gt AE Sy BEK ORL E16 Ib Ce 1k EJE Je Ele Je Gre de Ce de EJE Jl E16 Ib Cae Ab Gael Ere Je EXE AL Ele Je ae IL EJE 516 de Giese te TE OS IS IS IK IR IN IN IS IS OR DIR PIN IS IN TR EAS E16 Je AC_LANG_RESTORE if test
118. FC libraries Note It looks like the CString shipped with VC 6 0 has fixed this although it may in fact have been one of the VC SPs that did it e string operations like this have O n complexity if the implementors do it correctly The libstdc implementors did it correctly Other vendors might not e While chapters of the SGI STL are used in libstdc their string class is not The SGI st ring is essentially vector lt cha r gt and does not do any reference counting like libstdc s does It is O n though So if you re thinking about SGI s string or rope classes you re now looking at four possibilities CString the libstdc string the SGI string and the SGI rope and this is all before any allocator or traits customizations More choices than you can shake a stick at want fries with that The GNU C Library 60 253 Chapter 8 Localization 8 1 Locales 8 1 1 locale Describes the basic locale object including nested classes id facet and the reference counted implementation object class _Impl 8 1 1 1 Requirements Class locale is non templatized and has two distinct types nested inside of it class facet 22 1 1 1 2 Class locale facet Facets actually implement locale functionality For instance a facet called numpunct is the data object that can be used to query for the thousands separator in the locale Literally a facet is strictly defined e Containing the following public data member s
119. FIGURE_TESTSUITE Feature tests which only get used in one place Here things used only in the testsuite plus a couple bits used in the guts of I O GLIBCXX_EXPORT_INCLUDES GLIBCXX_EXPORT_FLAGS GLIBCXX_EXPORT_INSTALL_INFO Installation variables multilibs working with the rest of the compiler Many of the critical variables used in the makefiles are set here IBGCC_ENABLE IBCXX_ENABLE_C99 IBCXX_ENABLE_CHEADERS IBCXX_ENABLE_CLOCALE IBCXX_ENABLE_CONCEPT_CHECKS IBCXX_ENABLE_CSTDIO IBCXX_ENABLE_CXX_FLAGS IBCXX_ENABLE_C_MBCHAR IBCXX_ENABLE_DEBUG IBCXX_ENABLE_DEBUG_FLAGS IBCXX_ENABLE_LONG_LONG IBCXX_ENABLE_PCH IBCXX_ENABLE_SJLJ_EXCEPTIONS IBCXX_ENABLE_SYMVERS IBCXX_ENABLE_THREADS GI GY GI ES GI GE G GF Oro SONORO iG The GNU C Library 191 253 All the features which can be controlled with enable disable configure options Note how they re alphabetized now Keep them like that AC_LC_MESSAGES Luto bits Things which we don t seem to use directly but just has to be present otherwise stuff magically goes wonky B 1 6 GLIBCXX ENABLE the enable maker All the GLIBCXX_ENABLE_FOO macros use a common helper GLIBCXX_ENABLE You don t have to use it but it s easy The helper does two things for us 1 Builds the c
120. FLAGS target_board powerpc sim target calmrisc32 libgloss sid make check target libstdc v3 RUNTESTFLAGS target_board calmrisc32 sid target xscal lf newlib sim make check target libstdc v3 RUNTESTFLAGS target_board arm sim Also here is an example of how to run the libstdc testsuite for a multilibed build directory with different ABI settings make check target libstdc v3 RUNTESTFLAGS target_board unix mabi 32 mabi 64 You can run the tests with a compiler and library that have already been installed Make sure that the compiler e g g is in your PATH If you are using shared libraries then you must also ensure that the directory containing the shared version of libstdc is in your LD_LIBRARY_PATH or equivalent If your GCC source tree is at path to gcc then you can run the tests as follows runtest tool libstdc sredir path to gcc libstdc v3 testsuite The testsuite will create a number of files in the directory in which you run this command Some of those files might use the same name as files created by other testsuites like the ones for GCC and G so you should not try to run all the testsuites in parallel from the same directory In addition there are some testing options that are mostly of interest to library maintainers and system integrators As such these tests may not work on all cpu and host combinations a
121. Files The C standard specifies the entire set of header files that must be available to all hosted implementations Actually the word files is a misnomer since the contents of the headers don t necessarily have to be in any kind of external file The only rule is that when one include s a header the contents of that header become available no matter how That said in practice files are used There are two main types of include files header files related to a specific version of the ISO C standard called Standard Headers and all others TR1 C ABI and Extensions Two dialects of standard headers are supported corresponding to the 1998 standard as updated for 2003 and the draft of the upcoming 200x standard C 98 03 include files These are available in the default compilation mode i e std c 98 or std gnu 98 C 0x include files These are only available in C 0x compilation mode i e std c 0x or std gnu 0x The GNU C Library 20 253 algorithm bitset complex deque exception fstream functional iomanip ios iosfwd iostream istream iterator limits list locale map memory new numeric ostream queue set sstream stack stdexcept streambuf string utility typeinfo valarray vector Table 3 2 C 1998 Library Headers cassert cerrno cctype cfloat
122. HP eh Sheets ee Se ae eS 4s 223 B 6 2 1 Namespace std not supported 0 0 0 0 20000 223 B 6 2 2 Illegal iterator usage ee 224 B 6 2 3 isspacefromcctypeisamacro asao ee 224 B 6 2 4 Novector at deque at string at sspe sa pp esar Ea eip ap 224 B 6 2 5 Nostd char_traits lt char gt eof e RRR RR N 225 B626 N ostring cleat so oreki a eek e ee BORA Oy E RE ew a 225 B 6 2 7 Removal of ostream formand istream scanextensions 223 B 6 2 8 Nobasic_stringbuf basic st ringST rean 0000000008 229 B 6 2 9 Little or no wide character support 2 2 0 0 0 0 0 000000000007 226 B 6 2 10 Notemplatizediostreams 1 2 ee 227 B 6 2 11 Thread safety issues ee 227 Bi6 3 TA co e e 6 Oe TE a A EA AE A oS 221 The GNU C Library xvi B 6 3 2 Extension headers hash map hash_set moved to ext or backwards 229 B 6 3 3 Noios nocreate ilos nmoreplace e e 230 B 6 3 4 Nostream attach int fd e 230 B 6 3 5 Support for C 98 dialect ee 230 B 6 3 6 Support for C TR1 dialect gt s sses cerere ee 291 B 6 3 7 Support for C 0x dialect ee 233 B 6 3 8 Container iterator_type is not necessarily Container value_type oo 236 B 6 4 Bibliography osc stack a a a e RE a A a E 236 Free Software Needs Free Documentation AppendixFree Documentation 237 GNU General Public License version 3 239 G
123. In the USA this national standards organization is ANSI and their web site is right here And if you ve already registered with them clicking this link will take you to directly to the place where you can buy the standard on line The library working group bugs and known defects can be obtained here http www open std org jtc 1 sc22 wg21 The newsgroup dedicated to standardization issues is comp std c this FAQ for this group is quite useful and can be found here Peruse the GNU Coding Standards and chuckle when you hit the part about Using Languages Other Than C Be familiar with the extensions that preceded these general GNU rules These style issues for libstdc can be found here And last but certainly not least read the library specific information found here A 1 2 Assignment Small changes can be accepted without a copyright assignment form on file New code and additions to the library need completed copyright assignment form on file at the FSF Note your employer may be required to fill out appropriate disclaimer forms as well Historically the libstdc assignment form added the following question Which Belgian comic book character is better Tintin or Asterix and why While not strictly necessary humoring the maintainers and answering this question would be appreciated For more information about getting a copyright assignment please see Legal Matters Please contact Benjamin Kosnik at bkoz assign
124. Library Active Issues List N2456 17 uri Working Draft Standard for Programming Language C N2461 18 uri shared_ptr Boost C Libraries documentation shared_ptr N2461 6 4 Traits The GNU C Library Chapter 7 Strings 7 1 String Classes 7 1 1 Simple Transformations 54 253 Here are Standard simple and portable ways to perform common transformations on a st ring instance such as convert to all upper case The word transformations is especially apt because the standard template function trans form lt gt is used This code will go through some iterations Here s a simple version include lt string gt include lt algorithm gt include lt cctype gt old lt ctype h gt struct ToLower char operator char c const y Sipe Cah OURO ers char operator char c const y int main SECIS SERN E Change everything into upper case std transform s begin s end Change everything into lower case std transform s begin s end Change everything back into upper case result in a different string arok gereng Ganitel S capital_s resize s size std transform s begin s end s begin s begin capital_s begin return std tolower c l pertica Siecle suas a 7 Some Kind Of Initial Input Goes Here oUpper ToLower but store the ToUpper Note that these calls all invol
125. NU C Library 33 253 3 8 2 Debug Versions of Library Binary Files If you would like debug symbols in libstdc there are two ways to build libstdc with debug flags The first is to run make from the toplevel in a freshly configured tree with enable 1libstdcxx debug and perhaps enable libstdcxx debug flags to create a separate debug build Both the normal build and the debug build will persist without having to specify CXXFLAGS and the debug library will be installed in a separate directory tree in prefix 1ib debug For more information look at the configuration section A second approach is to use the configuration flags make CXXFLAGS g3 fno inlin O04 ul This quick and dirty approach is often sufficient for quick debugging tasks when you cannot or don t want to recompile your application to use the debug mode 3 8 3 Memory Leak Hunting There are various third party memory tracing and debug utilities that can be used to provide detailed memory allocation infor mation about C code An exhaustive list of tools is not going to be attempted but includes mtrace valgrind mudf lap and the non free commercial product purify In addition 1ilbcwd has a replacement for the global new and delete operators that can track memory allocation and deallocation and provide useful memory statistics Regardless of the memory debugging tool being used there is one thing of great importance to keep in mind wh
126. NU Free Documentation License 248 Index 253 The GNU C Library xvii 1 1 C 1998 2003 Implementation Status ooa 3 1 2 C 200x Implementation Status K 1 3 Ctr TRI Implementation Status 6 1 4 C TR 24733 Implementation Status ooa 7 3 1 CF Command Options s scios ssas A A a a E Ba aS 19 3 2 Cah DOS Library Headers ss anean os el ET R a eee ee 3 20 3 3 C 1998 Library Headers for C Library Facilities o aoaaa e e 20 3 4 C 200x Library Headers seves sser vre kerre crre 20 3 5 C 200x Library Headers for C Library Facilities oaoa o e e 20 3 0 C TR L Library Headers o s coios C R A A A AG A A Blase 20 3 7 C TR Library Headers for C Library Facilities o e e 20 3 8 C TR 24733 Decimal Floating Point Header e 21 3 9 Ch ABI Headers so e co e e e ERR eR A A dd 21 3 10 Extensi n Headers sec cesta e EEE A e SE eee A See e 21 3 11 Extension Debug Headertg lt e se a eG OR ee we RS Bee we a N 22 3 12 Extension Profile Headers eee RRR ee 22 3 13 Extension Parallel Headers osso eeo pa E RRR TE Bee ESE EG EO SP Re TR eee L TRR 22 17 1 Debugging Containers ooa oaa a 101 17 2 Debugging Containers CHOX soseo pa ra mapt ed Bee ee GES R BA eR Eee ER ew ES bes 101 18 1 Parallel Algorithms 2 0000 ee e RR RRR RRR RRR RR RRR 111 19 1 Profile Cod Location s e ios sicpi e ek a AR RE are A e A OE e 117 19 2 Pro
127. P 1 lt LOOWOOOOS dei 4 sl insert 1 SZ alanis Grater Ele ge 0 e 30 Oo fF WNE Ii Past better locality 10 for set lt int gt iterator it s begin it s end it LI sum 1t 12 Slow elements are further apart T3 for set lt int gt iterator it sl begin it sl end 1t 14 sum xit 15 foo cc 5 advice High scatter score NNN for set built here Consider changing the allocation sequence or switching to a structure conscious allocator 19 7 5 Multithreaded Data Access The diagnostics in this group are not meant to be implemented short term They require compiler support to know when container elements are written to Instrumentation can only tell us when elements are referenced Switch _GLIBCXX_PROFILE_ MULTITHREADED 19 7 5 1 Data Dependence Violations at Container Level s Switch _GLIBCXX_PROFILE_DDTEST e Goal Detect container elements that are referenced from multiple threads in the parallel region or across parallel regions e Fundamentals Sharing data between threads requires communication and perhaps locking which may be expensive e Sample runtime reduction e Recommendation Change data distribution or parallel algorithm e To instrument Container access methods and iterators e Analysis Keep a shadow for each container Record iterator dereferences and container member accesses Issue advice for elements referenced by multiple thread
128. Performance Analysis The Profile based Performance Analysis Extension has performance checks for many algorithms The GNU C Library 36 253 Part II Standard Contents The GNU C Library 37 253 Chapter 4 Support This part deals with the functions called and objects created automatically during the course of a program s existence While we can t reproduce the contents of the Standard here you need to get your own copy from your nation s member body see our homepage for help we can mention a couple of changes in what kind of support a C program gets from the Standard Library 4 1 Types 4 1 1 Fundamental Types C has the following builtin types char signed char unsigned char signed short signed int signed long unsigned short unsigned int unsigned long bool wchar_t float double long double These fundamental types are always available without having to include a header file These types are exactly the same in either C or in C Specializing parts of the library on these types is prohibited instead use a POD The GNU C Library 38 253 4 1 2 Numeric Properties The header 1imits defines traits classes to give access to various implementation defined aspects of the fundamental types The traits classes fourteen in total are all specializations of the template class numeric_limits documented here and defined as follows template lt typename
129. SS i Aka NUEL diee E oo eo ek oe ee be 8 a 4 2 DynamicMemory es e e cam eetere k e RKR RRR RRR RRR AS Termination sx ee fe ee ewe a eae ee e bea ae Eee ae SR See A eae Rae ae eS 43 1 Termination Handlers s oir Re OS RS A SR RS Go el RR ele be we Oe 4 3 2 Verbose Terminate Handler ooa 5 Diagnostics JA Exceptions gico aie ao GD a ea ge a ee oO ee ae Boa Boer GS algo a 31 1 API Reference norris ir RG R OEE EEE A A ewe eee e i a 5 1 2 Adding Data to exception ee 5 2 Concept Checking s u ee Se ee a a a bea e A e a ea ea E 6 Utilities OL FUNCIONS e ae e Bes be A Reh e Gee AL EAR es Bh a a o aa Ee da aE ae SR SEO we Gi a 62 Pals egus e o a ad A A AR E E A R A a S A 63 Memory is ie Slog ai ao a il aa ARE A eS A A ia 630 Allocat 0tS wo pitt a AA A A eee 6 3 1 1 Requirements s S se opos koog ra e A e a A ee N 6 3 1 2 Desigmissies se datat Be PR re a ES oe a ee 6 3 1 3 Implementation sis e S S R RR RR a eA RR ka ee EE Ae a we eo 6 3 1 3 1 Interface Design 2 56 4284048054 24 Eee ES eee EEE SSS 6 3 1 3 2 Selecting Default Allocation Policy o a 6 3 1 3 3 Disabling Memory Caching a 6 3 1 4 Using a Specific Allocator RR RRR RRR RR RRR KR e 6 3 1 5 Custom Allocators ee 63 16 Extension AllOCAtorS s s posee pae A ER E e R Y 63 1 7 Bibhosraphy a a 4 4 eae ts e AS o a Bee eh ee E O32 AMOD 1 44 3 2 9 Sen o Se Ok oo BS ee Eb wee do Stee Qe Fo a 6 3 2 1 LIMITADOS
130. Sections being LIST THEIR TITLES with the Front Cover Texts being LIST and with the Back Cover Texts being LIST If you have Invariant Sections without Cover Texts or some other combination of the three merge those two alternatives to suit the situation If your document contains nontrivial examples of program code we recommend releasing these examples in parallel under your choice of free software license such as the GNU General Public License to permit their use in free software The GNU C Library Appendix F Index T algorithm 84 Test atomic 94 Exception Safety 204 C 99 108 115 condition variable 95 U debug 99 Utilities 44 future 95 ISO C 2 37 42 44 54 60 77 82 84 85 87 94 95 97 150 library 2 37 42 44 54 60 77 82 84 85 87 94 95 97 99 108 115 150 mutex 95 parallel 108 profile 115 thread 95 A Algorithms 84 Atomics 94 C Concurrency 95 Containers 77 D Diagnostics 42 E Extensions 96 I Input and Output 87 Introduction 1 Iterators 82 L Localization 60 N Numerics 85 S Strings 54 Support 37 253 253
131. T gt struct class a tatic const bool is_specialized racie 1 maxi Chro Op TAEL min throw n n TACLE come me CAGES ESS CCiNsic ime Glaicaliesiles tatic const bool is_signed tatic const bool is_integer carie icons OOolmmtsmexact carie Const Hoe cli tatic T epsilon throw Ear round_error throw LR as Cs L 2 L S T tatic const int min _exponent tatic const int min _exponent10 tatic const int max exponent tatic const int max_exponent10 nun Wn W calco comas Isa las oca tatic const bool has_quiet_NaN tatic const bool has_signaling_NaN tatic const float_denorm_style has_denorm tatic const bool has_denorm_loss cara E ara o carow Us tatic T quiet_NaN throw tatic T denorm_min throw 0 0 0 00000 DN Pattee comete Jon as icono cratie const bool ts bounded batie const bool Ls modulos nn Wn Siva Billete on sio ita psi static const bool tinyness before static const float_round_style round_style y 4 1 3 NULL The only change that might affect people is the type of NULL while it is required to be a macro the definition of that macro is not allowed to be void 0 which is often used in C For g NULL is define d to be __nu11 a magic keyword extension of g The biggest problem of defining NULL to be something like OL is that the compiler will view that as a long integer before it views it as a pointer so overloading won t do w
132. TCH e Goal Discover sequences of indirect memory accesses that are not regular thus cannot be predicted by hardware prefetchers e Fundamentals Indirect references are hard to predict and are very expensive when they miss in caches e Sample runtime reduction 25 e Recommendation Insert prefetch instruction e To instrument Vector iterator and access operator e Analysis First get cache line size and page size from system Then record iterator dereference sequences for which the value is a pointer For each sequence within a container issue a warning if successive pointer addresses are not within cache lines and do not form a linear pattern otherwise they may be prefetched by hardware If they also step across page boundaries make the warning stronger The same analysis applies to containers other than vector However we cannot give the same advice for linked structures such as list as there is no random access to the n th element The user may still be able to benefit from this information for instance by employing frays user level light weight threads to hide the latency of chasing pointers This analysis is a little oversimplified A better cost model could be created by understanding the capability of the hardware prefetcher This model could be trained automatically by running a set of synthetic cases e Cost model Total distance between pointer values of successive elements in vectors of pointers
133. The GNU C Library The GNU C Library The GNU C Library Copyright O 2009 2010 FSF License The GNU C Library COLLABORATORS TITLE The GNU C Library ACTION NAME DATE SIGNATURE WRITTEN BY March 12 2010 REVISION HISTORY NUMBER DATE DESCRIPTION NAME The GNU C Library iv Contents I Introduction 1 1 Status 2 1 1 Implementation Stat s gt p ce pe SR RA EGR SO ORE EERE SE Ee RE ES 2 1 1 1 CHR T998 2008 5 ceo eed Be kOe eB a a Bs hos Pe es we Boe eR ee we we 2 1 1 1 1 Implementation Status 2 0 0 0 0 2 020000 00 00 0000 000 2 1 1 1 2 Implementation Specific Behavior aoaaa a 2 A CEF 200K aa do Se a eS e e de bilis a 4 L3 ICFETR ir be eee Ee be BAe a ga aai gr aaie haa eae PRA ee SSS 4 114 Cre TR 24733 cae td baw eb ee ee oa eA ee be eae eS 4 1 2 e 4 3 0 bh gk he Bad Bek Seok he Ate eh e a See hk oe oe A OE te SG ek de me e da 4 1 21 The Code GPL ciar ss eee Ee be BAe ae he Reloads BRAY Ged OEE 8 1 2 2 The Documentation GPL FDL 0 0 0 0 00 00 00000 eee ee 9 1 3 BUSS on ee oe eed be Bee ee ee ee ee et hp ee ke Be os 5 1 3 1 Implementation BUES lt s Z S E A Be a eda SSS 9 13 2 Standard Bugs s sr reend erta bas SoA ea A ae eae a eo 9 2 Setup 14 Zl sPIETEQuisites cta Soak ak ne be eS ee oe a ee Eg eo ee ee be ee Soe ms Ge 14 2 2 Conf Bure 0 3 S05 Bb Sa Be Oe ee Re we ee we Be Se he Be ew Se w
134. VE AC_LANG_CPLUSPLUS AC_ TRY_COMPILE include lt cassert gt include lt cctype gt include lt cerrno gt include lt cfloat gt include lt ciso646 gt include lt climits gt include lt clocale gt include lt cmath gt include lt cset jmp gt include lt csignal gt include lt cstdarg gt include lt cstddef gt include lt cstdio gt include lt cstdlib gt include lt cstring gt include lt ctime gt The GNU C Library include lt algorithm gt include lt bitset gt include lt complex gt include lt deque gt include lt exception gt include lt fstream gt include lt functional gt include lt iomanip gt include lt ios gt include lt iosfwd gt include lt iostream gt include lt istream gt include lt iterator gt include lt limits gt include lt list gt include lt locale gt include lt map gt include lt memory gt include lt new gt include lt numeric gt include lt ostream gt include lt queue gt include lt set gt include lt sstream gt include lt stack gt include lt stdexcept gt include lt streambuf gt include lt string gt include lt typeinfo gt include lt utility gt include lt valarray gt include lt vector gt lee ac_cv_cxx_stdcxx_98 yes ac_cv_cxx_stdcxx_98 no AC LANG RESTORE lp 1 test Sas ow exe erez OE yes then AC_DEFINE STDCXX_98_H
135. _Inputlterl lastl HEGDE TL S E HESE EDHE EE EST E lesit which does what The GNU C Library 145 253 Chapter 24 Numerics 26 4 the generalized numeric operations such as accumulate are extended with the following functions power x n power x n moniod_operation Returns in FORTRAN syntax x n where n gt 0 In the case of n 0 returns the identity element for the monoid operation The two argument signature uses multiplication for a true power implementation but addition is supported as well The operation functor must be associative The iota function wins the award for Extension With the Coolest Name It assigns sequentially increasing values to a range That is it assigns value to first value 1 to first 1 and so on Quoted from SGI documentation void iota _Forwardlter first _Forwardlter last _Tp value The GNU C Library 146 253 Chapter 25 lterators 24 3 2 describes struct iterator which didn t exist in the original HP STL implementation the language wasn t rich enough at the time For backwards compatibility base classes are provided which declare the same nested typedefs e input_iterator e output_iterator s forward_iterator s bidirectional_iterator e random_access_iterator 24 3 4 describes iterator operation distance which takes two iterators and returns a result It is extended by another signature which takes two iterators and a reference to a
136. a used can probably be improved to further reduce the risk of blocks being bounced back and forth between freelists 20 2 bitmap_allocator 20 2 1 Design As this name suggests this allocator uses a bit map to keep track of the used and unused memory locations for it s book keeping purposes This allocator will make use of 1 single bit to keep track of whether it has been allocated or not A bit indicates free while 0 indicates allocated This has been done so that you can easily check a collection of bits for a free block This kind of Bitmapped strategy works best for single object allocations and with the STL type parameterized allocators we do not need to choose any size for the block which will be represented by a single bit This will be the size of the parameter around which the allocator has been parameterized Thus close to optimal performance will result Hence this should be used for node based containers which call the allocate function with an argument of 1 The bitmapped allocator s internal pool is exponentially growing Meaning that internally the blocks acquired from the Free List Store will double every time the bitmapped allocator runs out of memory The macro __ GTHREADS decides whether to use Mutex Protection around every allocation deallocation The state of the macro 1s picked up automatically from the gthr abstraction layer 20 2 2 Implementation 20 2 2 1 Free List Store The Free List Store referred
137. a ole sabias Guo 33 Woo seua Voc wel 5 void do_something int main extern void __dso_handle __attribute__ __weak__ __cxa_atexit void x void x __libc_freeres NULL amp dso_handle __dso_handle NULL do_test return 0 Suggested valgrind flags given the suggestions above about setting up the runtime environment library and test file might be valgrind v num callers 20 leak check yes leak resolution high show reachable ves elo TWT 3 8 4 Using gdb Many options are available for gdb itself please see GDB features for C in the gdb documentation Also recommended the other parts of this manual These settings can either be switched on in at the gdb command line or put into a gdbint file to establish default debugging characteristics like so set print pretty on set print object on set print static members on sel Joa Wasi o set print demangle on set demangle style gnu v3 Starting with version 7 0 GDB includes support for writing pretty printers in Python Pretty printers for STL classes are dis tributed with GCC from version 4 5 0 The most recent version of these printers are always found in libstdc svn repository To enable these printers check out the latest printers to a local directory svn co svn gcc gnu org svn gcc trunk libstdc v3 python Next add the following section to your gdbinit The path must match the location where the Pyth
138. a deprecated warning is added that notifies on inclusion Wno deprecated deactivates the warn ing Deprecated include backward strstream added Removal of include builtinbuf h indstream h parsestream h PlotFile h SFile h stdiostream h and stream h B 5 2 3 1 Extensions from SGI HP moved from namespace std to namespace __gnu_cxx As part of this the following new includes are added ext algorithm ext functional ext iterator ext memory and ext numeric Extensions to basic_filebuf introduced __ gnu_cxx enc_filebuf and__gnu_cxx stdio_filebuf Extensions to tree data structures added in ext rb_tree Removal of ext tree moved to backward tree h B 5 3 3 2 Symbol versioning introduced for shared library Removal of include backward strstream h Allocator changes Change __malloc_alloctomalloc_allocatorand__new_alloctonew_allocator For GCC releases from 2 95 through the 3 1 series defining__ USE_MALLOC on the gcc command line would change the default allocation strategy to instead use malloc and free This same functionality is now spelled _GLIBCXX_FORCE_NEW see this page for details Error handling in iostreams cleaned up made consistent B 5 4 3 3 B 5 5 3 4 Large file support Extensions for generic characters and char_traits added in ext pod_char_traits h Support for wchar_t specializations of basic_filebuf enhanced to support UTF 8 and Unicode depending on host More hosts suppor
139. a minimal configuration with only partial support for the standard library Assume only the following header files can be used cstdarg cstddef cstdlib e exception e limits e new exception typeinfo In addition throw in R cxxabi h In the C 0x dialect add e initializer _list e type_traits There exists a library that offers runtime support for just these headers and it is called libsupct a To use it compile with gcc instead of g like so gcc foo cc Isupc No attempt is made to verify that only the minimal subset identified above is actually used at compile time Violations are diagnosed as undefined symbols at link time The GNU C Library 26 253 3 5 2 Finding Dynamic or Shared Libraries If the only library built is the static library 1ibstdc a or if specifying static linking this section is can be skipped But if building or using a shared library libstdc so then additional location information will need to be provided But how A quick read of the relevant part of the GCC manual Compiling C Programs specifies linking against a C library More details from the GCC FAQ which states GCC does not by default specify a location so that the dynamic linker can find dynamic libraries at runtime Users will have to provide this information Methods vary for different platforms and different styles and are printed to the screen during installation To summarize e
140. a thread model of single with a libstdc and other C libraries built with another thread model useful on the platform Other mixes may or may not work but are not considered supported Thus if you distribute a shared C library in binary form only it may be best to compile it with a GCC configured with enable threads for maximal interchangeability and usefulness with a user population that may have built GCC with either enable threads or disable threads When you link a multithreaded application you will probably need to add a library or flag to g This is a very non standardized area of GCC across ports Some ports support a special flag the spelling isn t even standardized yet to add all required macros to a compilation if any such flags are required then you must provide the flag for all compilations not just linking and link library additions and or replacements at link time The documentation is weak Here is a quick summary to display how ad hoc this is On Solaris both pthreads and threads with subtly different meanings are honored On OSF pthread and threads with subtly different meanings are honored On Linux i386 pthread is honored On FreeBSD pthread is honored Some other ports use other switches AFAIK none of this is properly documented anywhere other than in gcc dumpspecs look at lib and cpp entries The GNU C Library 27 253 3 6 2 Thread Safety We currently use the SGI STL definition
141. achinery to do that on your system const charx ctype lt char gt do_toupper charx __low const charx __ high const while __low lt __high x_ low do_toupper __low ow return _ high const char ctype lt char gt do_tolower charx __low const charx __high const while __low lt __high x_ low do_tolower x__low A RA RSU ALENE You must also provide the ct ype_inline h file which contains a few more functions On most systems you can just copy config os generic ctype_inline h and use it on your system In detail the functions provided test characters for particular properties they are analogous to the functions like isalpha and islower provided by the C library The first function is implemented like this on IRIX bool ctype lt char gt ielmask mM Char 0 const throw i return _M_table unsigned char __c amp _m The _M table is the table passed in above in the constructor This is the table that contains the bitmasks for each character The implementation here should work on all systems The next function is const Chans ctype lt char gt is const char __low const charx __high maskx __vec const throw while __low lt __high x__vect _M table unsigned char x __low t return _ high This function is similar it copies the masks for all the characters from __ 1ow up until __ high into the vector given by__ vec The last two functions a
142. all to the AC_ARG_ENABLE macro with help text properly quoted and aligned Death to changequote 2 Checks the result against a list of allowed possibilities and signals a fatal error if there s no match This means that the rest of the GLIBCXX_ENABLE_FOO macro doesn t need to test for strange arguments nor do we need to protect against empty whitespace strings with the xS foo xbar idiom Doing these things correctly takes some extra autoconf autom4te code which made our macros nearly illegible So all the ugliness is factored out into this one helper macro Many of the macros take an argument passed from when they are expanded in configure ac The argument controls the default value of the enable disable switch Previously the arguments themselves had defaults Now they don t because that s extra complexity with zero gain for us There are three overloaded signatures When reading the descriptions below keep in mind that the brackets are autoconf s quotation characters and that they will be stripped Examples of just about everything occur in acinclude m4 if you want to look GLIBCXX_ENABLE FEATURE DEFAULT HELP ARG HELP STRING GLIBCXX_ENABLE FEATURE DEFAULT HELP ARG HELP STRING permit albl c GLIBCXX_ENABLE FEATURE DEFAULT HELP ARG HELP STRING SHELL CODE HANDLER FEATURE is the string that follows enable The resul
143. als Resizing can be expensive Copying large amounts of data takes time Resizing many small vectors may have allocation overhead and affect locality Sample runtime reduction Recommendation Set initial size to N at construction site S To instrument vector Analysis For each dynamic instance of vector record initial size and call context of the constructor Record size increase if any after each relevant operation such as push_back Record the estimated resize cost Cost model Total number of words copied time to copy a word 1 vector lt int gt v 2 for int k 0 k lt 1000000 k 3 v push_back k 4 foo cc 1 advice Changing initial vector size from 10 to 1000000 saves copying 4000000 bytes and 20 memory allocations and deallocations The GNU C Library 124 253 19 7 2 5 Vector Too Large e Switch _GLIBCXX_PROFILE_VECTOR_TOO_LARGE e Goal Detect vectors which are never filled up because fewer elements than reserved are ever inserted e Fundamentals Save memory which is good in itself and may also improve memory reference performance through fewer cache and TLB misses e Sample runtime reduction s Recommendation Set initial size to N at construction site S s To instrument vector e Analysis For each dynamic instance of vector record initial size and call context of the constructor and correlate it with its size at destruction time e Cost model Total amount of memory save
144. ance not to suffer It may be that they could be treated as staged iterators and take advantage of those optimizations Chapter 25 Algorithms Headers lt algorithm gt C headers lt cstdlib gt also in 18 21 26 The algorithms are mostly complete As mentioned above they are optimized for speed at the expense of code and data size Specializations of many of the algorithms for non STL types would give performance improvements but we must use great care not to interfere with fragile template overloading semantics for the standard interfaces Conventionally the standard function template interface is an inline which delegates to a non standard function which is then overloaded this is already done in many places in the library Particularly appealing opportunities for the sake of EE Si t ostream performance are for copy and find applied to streambuf terators or as noted elsewhere for staged iterators of which he streambuf iterators are a good example The GNU C Library 186 253 The bsearch and qsort functions cannot be overloaded properly as required by the standard because gcc does not yet allow overloading on th xtern C ness of a function pointer Chapter 26 Numerics Headers lt complex gt lt valarray gt lt numeric gt C headers lt cmath gt lt cstdlib gt also 18 21 25 Numeric components Gabriel dos Reis s valarray Drepper s complex and the few algorit
145. ance test cases and collects information for performance analysis and can be used to spot performance regressions Various timing information is collected as well as number of hard page faults and memory used This is not run by default and the implementation is in flux We are interested in any strange failures of the testsuite please email the main libstdc mailing list if you see something odd or have questions B 3 2 3 Permutations To run the libstdc test suite under the debug mode edit libstdct v3 scripts testsuite_flags to add the compile time flag D_GLIBCXX_DEBUG to the result printed by the build cxx option Additionally add the D_GLIB CXX_DEBUG_PEDANTIC flag to turn on pedantic checking The libstdc test suite should produce precisely the same results under debug mode that it does under release mode any deviation indicates an error in either the library or the test suite The parallel mode can be tested in much the same manner substituting D_GLIBCXX_PARALLEL for D_GLIBCXX_DEBUG in the previous paragraph Or just run the testsuites with CXXFLAGS set to D_GLIBCXX_DEBUG or D_GLIBCXX_PARALLEL B 3 3 Writing a new test case The first step in making a new test case is to choose the correct directory and file name given the organization as previously described All files are copyright the FSF and GPL d this is very important The first copyright year should correspond to the date the fi
146. and crafted assembly is selected This is the case for the following hosts e cris e hppa 1386 1486 m48k e mips sparc And for the rest a simulated atomic lock via pthreads Detailed information about compiler intrinsics for atomic operations can be found in the GCC documentation More details on the library fallbacks from the porting section 28 2 2 Thread Abstraction A thin layer above IEEE 1003 1 i e pthreads is used to abstract the thread interface for GCC This layer is called gthread and is comprised of one header file that wraps the host s default thread layer with a POSIX like interface The file lt gthr default h gt points to the deduced wrapper for the current host In libstdc implementation files lt bits gthr h gt is used to select the proper gthreads file Within libstdc sources all calls to underlying thread functionality use this layer More detail as to the specific interface can be found in the source documentation By design the gthread layer is interoperable with the types functions and usage found in the usual lt pthread h gt file including pthread_t pthread_once_t pthread_create etc 28 3 Use Typical usage of the last two constructs is demonstrated as follows include lt ext concurrence h gt namespace gnu_cxx __mutex safe _base_mutex anonymous namespace namespace other void The GNU C Library 153 253 foo gnu_cxx __scoped_lock sentr
147. and move up to block_count the number of blocks of this bins size that will fit into a _S_chunk_ size or until end of list whatever comes first to the current threads freelist and at the same time change the thread_id ownership and update the counters and pointers When the bins mutex has been unlocked we remove the block that _S_bin bin first thread_id points to from the list update _S_bin bin first thread_id update the free and used counters and return a pointer to that blocks data The reason that the number of blocks moved to the current threads freelist is limited to block_count is to minimize the chance that a subsequent deallocate call will return the excess blocks to the global freelist based on the _S_freelist_headroom calculation see below However if there isn t any memory on the global pool we need to get memory from the system this is done in exactly the same way as in a single threaded application with one major difference the list built in the newly allocated memory of _S_chunk_size size is added to the current threads freelist instead of to the global The GNU C Library 136 253 The basic process of a deallocation call is simple always add the block to the front of the current threads freelist and update the counters and pointers as described earlier with the specific check of ownership that causes the used counter of the thread that originally allocated the block to be decreased instead of the cur
148. and__gnu_pa rallel sampling_tag Exact and sampling are the two available splitting strategies For the sort and stable_sort algorithms there are several additional choices namely __gnu_parallel multi way_mergesort_tag __gnu_parallel multiway_mergesort_exact_tag gnu_parallel multi way_mergesort_sampling_tag __gnu_parallel quicksort_tag and__gnu_parallel balanced_ quicksort_tag Multiway mergesort comes with the two splitting strategies for multi way merging The quicksort options cannot be used for stable_sort 18 4 2 3 Run Time Settings and Defaults The default parallelization strategy the choice of specific algorithm strategy the minimum threshold limits for individual parallel algorithms and aspects of the underlying hardware can be specified as desired via manipulation of__gnu_parallel _S ettings member data First off the choice of parallelization strategy serial parallel or heuristically deduced This corresponds to __ gnu_para llel _Settings algorithm_strategy and is a value of enum __gnu_parallel _AlgorithmStrategy type Choices include heuristic force_sequential and force_parallel The default is heuristic Next the sub choices for algorithm variant if not fixed at compile time Specific algorithms like find or sort can be imple mented in multiple ways when this is the case a__ gnu_parallel _Settings member exists to pick the default strategy For example gnu_parallel _Settings
149. anuals acceptable for the same reason so many people consider proprietary software accept able they judge in purely practical terms not using freedom as a criterion These people are entitled to their opinions but since those opinions spring from values which do not include freedom they are no guide for those of us who do value freedom Please spread the word about this issue We continue to lose manuals to proprietary publishing If we spread the word that proprietary manuals are not sufficient perhaps the next person who wants to help GNU by writing documentation will realize before it is too late that he must above all make it free We can also encourage commercial publishers to sell free copylefted manuals instead of proprietary ones One way you can help this is to check the distribution terms of a manual before you buy it and prefer copylefted manuals to non copylefted ones Note We now maintain a web page that lists free books available from other publishers Copyright O 2004 2005 2006 2007 Free Software Foundation Inc 51 Franklin Street Fifth Floor Boston MA 02110 1301 USA Verbatim copying and distribution of this entire article are permitted worldwide without royalty in any medium provided this notice is preserved Report any problems or suggestions to webmaster fsf org The GNU C Library 239 253 Appendix D GNU General Public License version 3 Version 3 29 June 2007 Copyright O 2007 Free Softwa
150. arallel algorithm o E ind_if G CG c gnu_parallel f z z E l Sl T el f f 1 T ili t ind_first_o algorithm ma Ler et parallel algorithm 3 nu_parallel f y a std for_each algorithm SE parallel algorithm or_each gnu_parallel g S c std generate algorithm arallel algorithm g 7 enerate p see nu_parallel g a p S E std generate_n algorithm gnu p g parallel algorithm enerate_n l f nu_parallel 1 std lexicographi g zE y a algorithm exicographical_co parallel algorithm cal_compare mpare S Z gnu_parallel m 2 a std mismatch algorithm arallel algorithm g ismatch p pers nu_parallel s E a A std search algorithm gnu p parallel algorithm earch nu_parallel s a l std search_n algorithm aes parallel algorithm earch_n nu_parallel t a a std transform algorithm gnu p parallel algorithm ransform nu_parallel r p y std replace algorithm gnu p parallel algorithm eplace E gnu_parallel r 3 A y std replace_if algorithm 5 arallel algorithm E 5 S eplace_if P alg nu_parallel m A 4 std max_element algorithm gnu p parallel algorithm ax_element i nu_parallel m x S std merge algorithm gnu_p parallel algorithm erge n arallel m a E 4 l std min_element algorithm S gnu p parallel algorithm in_element gnu_parallel n 3 4 A std nth_element algorithm arallel algorithm E 3 th_element p fats y y gnu_parallel p a E s a std partial sort algorithm
151. ard filebufs directly either by declaring your own or by using the pointer returned from an fstream s rdbuf is certainly feasible as well One area that causes problems is trying to do bit by bit operations with filebufs C is no different from C in this respect I O must be done at the byte level If you re trying to read or write a few bits at a time you re going about it the wrong way You must read write an integral number of bytes and then process the bytes For example the streambuf functions take and return variables of type int_type Another area of problems is opening text files in binary mode Generally binary mode is intended for binary files and opening text files in binary mode means that you now have to deal with all of those end of line and end of file problems that we mentioned before An instructive thread from comp lang c moderated delved off into this topic starting more or less at this post and continuing to the end of the thread The subject heading is binary iostreams on both comp std c and comp lang c moderated Take special note of the replies by James Kanze and Dietmar Kiihl Briefly the problems of byte ordering and type sizes mean that the unformatted functions like ostream put and istr eam get cannot safely be used to communicate between arbitrary programs or across a network or from one invocation of a program to another invocation of the same program on a different platform etc
152. are not used in this library include ext Headers that define extensions to the standard library No standard header refers to any of them scripts Scripts that are used during the configure build make or test process src Files that are used in constructing the library but are not installed testsuites backward demangle ext performance thread 17_ to 27_x Test programs are here and may be used to begin to exercise the library Support for make check and make check install is complete and runs through all the subdirectories here when this command is issued from the build directory Please note that make check requires DejaGNU 1 4 or later to be installed Please note that make check script calls the script mkcheck which requires bash and which may need the paths to bash adjusted to work properly as bin bash is assumed Other subdirectories contain variant versions of certain files that are meant to be copied or linked by the configure script Currently these are config abi config cpu config io config locale config os In addition a subdirectory holds the convenience library libsupc libsupc Contains the runtime library for C including exception handling and memory allocation and deallocation RTTI terminate handlers etc Note that glibc also has a bits subdirectory We will either need to be careful not to collide with names in its bits directory or rename bits t
153. are two licenses affecting GNU libstdc one for the code and one for the documentation There is a license section in the FAQ regarding common questions If you have more questions ask the FSF or the gcc mailing list The GNU C Library 5 253 Section Description Status Comments 18 Language support 18 1 General Y 18 2 Types Partial Sss OEE max_align_t nullptr_t 18 3 Implementation properties 18 3 1 Numeric Limits 18 3 1 1 G Y numeric_limits 18 3 1 2 Dene Ee as Partial Missing constexpr members 18 3 1 3 float_round_style N 18 3 1 4 float_denorm_style N 18 3 1 5 eee Y specializations 18 3 2 C Library Y 18 4 Integer types 18 4 1 Header lt cstdint gt y synopsis May use 18 4 2 The header lt stdint h gt Partial ee eee ues GCC_HEADER_STDINT 18 5 Start and termination Partial Misang quick exit at_quick_exit 18 6 Dynamic memory Y management 18 7 Type identification 18 7 1 Class type_info Y 18 7 2 Class type_index N 18 7 3 Class bad_cast Y 18 7 4 Class bad_typeid Y 18 8 Exception handling 18 8 1 Class exception Y 18 8 2 ROT e Y exception specifications 18 8 3 Abnormal termination Y 18 8 4 uncaught_exception Y 18 8 5 Propagation Y 18 8 6 a Y nested_exception 18 9 Initializer lists 18 9 1 Initializer list constructors Y 18 9 2 Initializer list access Y 18 9 3 Initializer l
154. ared_count constructors taking a custom deleter but no allocator are technically redundant and could be removed The GNU C Library 53 253 changing callers to always specify an allocator If a separate pointer deleter class was added the __shared_count constructor would be needed so it has been kept for now The hack used to get the address of the managed object from _Sp_counted_ptr_inplace _M get_deleter is accessible to users This could be prevented if get_deleter lt _Sp_make_shared_tag gt always returned NULL since the hack only needs to work at a lower level not in the public API This wouldn t be difficult but hasn t been done since there is no danger of accidental misuse users already know they are relying on unsupported features if they refer to implementation details such as _Sp_make_shared_tag tr1 _Sp_deleter could be a private member of tr1 __shared_count but it would alter the ABI Exposing the alias constructor in TR1 mode could simplify the _pointer_cast functions Constructor could be private in TR1 mode with the cast functions as friends 6 3 3 5 Acknowledgments The original authors of the Boost shared_ptr which is really nice code to work with Peter Dimov in particular for his help and invaluable advice on thread safety Phillip Jordan and Paolo Carlini for the lock policy implementation 6 3 3 6 Bibliography 15 uri Improving shared_ptr for C 0x Revision 2 N2351 16 uri C Standard
155. arithmetic is available if the C compiler supports scalar decimal floating point types defined via ___a ttribute__ mode SD DD LD decimal decimal Table 3 8 C TR 24733 Decimal Floating Point Header Also included are files for the C ABI interface cxxabi h cxxabi_forced h Table 3 9 C ABI Headers And a large variety of extensions f ext atomicity ext array_ ext bitmap_ t al th US t Es oh G OETAN h allocator h allocator h S ext codecvt ae es ext ext debug_ ext enc_ ext extptr_ a concurrence h allocator h filebuf h allocator h ext malloc ext mt GAE E 1 t it t ys E t E ext functiona ext iterator ccoo ext memory aa Neher in k t pb_d t pb_d ext new_ E ext numeric_ a EE d ext numeric assoc_ priority_ allocator h traits h S container h queue h ext pod_char_ ext pool_ ext rb_tree ext rope ext slist traits h allocator h x j p ext stdio ext stdio ext throw f ext type s gt on Ia e EL list h l filebuf h sync_filebuf h allocator h exec yEnc tts traits h ext vstring h Table 3 10 Extension Headers 3 2 2 Mixing Headers A few simple rules First mixing different dialects of the standard headers is not possible It s an all or nothing affair Thus code like include lt array gt include lt functional gt Implies C 0x mode To use the entities in lt array gt the C 0x compilation mode must be used
156. articularly embedded applications The alternative demands Care in construction and some compiler support but there is no need for library subsets What are the sources of this overhead There are four main causes The library is specified almost entirely as templates which with current compilers must be included in line resulting in very slow builds as tens or hundreds of thousands of lines of function definitions are read for each user source file Indeed th ntire SGI STL as well as the dos Reis valarray are provided purely as header files largely for simplicity in porting lostream locale is or will be as large again The library is very flexible specifying a multitude of hooks where users can insert their own code in place of defaults When these hooks are not used any time and code expended to support that flexibility is wasted Templates are often described as causing to code bloat In practice this refers when it refers to anything real to several The GNU C Library 174 253 independent processes First when a class template is manually instantiated in its entirely current compilers place the definitions for all members in a single object file so that a program linking to one member gets definitions of all Second template functions WwW hich do not actually depend on the template argument are under urrent compilers generated anew for each instantiation rathe
157. artup time Only include the header files you need to in general your compile times will go down when there s less parsing work to do 13 2 Stream Buffers 13 2 1 Derived streambuf Classes Creating your own stream buffers for I O can be remarkably easy If you are interested in doing so we highly recommend two very excellent books Standard C IOStreams and Locales by Langer and Kreft ISBN 0 201 18395 1 and The C Standard Library by Nicolai Josuttis ISBN 0 201 37926 0 Both are published by Addison Wesley who isn t paying us a cent for saying that honest Here is a simple example io outbuf1 from the Josuttis text It transforms everything sent through it to uppercase This version assumes many things about the nature of the character type being used for more information read the books or the newsgroups include lt iostream gt include lt streambuf gt The GNU C Library 89 253 include lt locale gt include lt cstdio gt class outbuf public std streambuf protected x central output function x print characters in uppercase mode ey virtual int_type overflow int_type c alge AL ais 4 convert lowercase to uppercase c std toupper static_cast lt char gt c getloc and write the character to the standard output PUE CANA e PE OE 21 return EOF RECURS y int main create special output buffer outbut ob initialize output stream with tha
158. as specialized versions of many of these functions for example string find Most of the examples on this page will use simple arrays of integers as a playground for algorithms just to keep things simple The use of N as a size in the examples is to keep things easy to read but probably won t be valid code You can use wrappers such as those described in the containers sect1 to keep real code readable The single thing that trips people up the most is the definition of range used with iterators the famous past the end rule that everybody loves to hate The iterators sect1 of this document has a complete explanation of this simple rule that seems to cause so much confusion Once you get range into your head it s not that hard honest then the algorithms are a cakewalk 11 1 Mutating 11 1 1 swap 11 1 1 1 Specializations If you call std swap x y Where x and y are standard containers then the call will automatically be replaced by a call to x swap y instead This allows member functions of each container class to take over and containers swap functions should have O 1 complexity according to the standard And while should allows implementations to behave otherwise and remain compliant this imple mentation does in fact use constant time swaps This should not be surprising since for two containers of the same type to swap contents only some internal pointers to storage need to be exchanged The GNU C Library
159. ass template __gnu_debug _Safe_iterator which takes two template parameters e Iterator The underlying iterator type which must be either the iterator or const_iterator typedef from the sequence type this iterator can reference Sequence The type of sequence that this iterator references This sequence must be a safe sequence discussed below whose iterator or const_iterator typedef is the type of the safe iterator 17 4 2 1 2 Safe Sequences Containers Container wrappers provide a debugging layer over a particular container type Because containers vary greatly in the member functions they support and the semantics of those member functions especially in the area of iterator invalidation container wrappers are tailored to the container they reference e g the debugging version of std list duplicates the entire interface of std list adding additional semantic checks and then forwarding operations to the real std list a public base class of the debugging version as appropriate However all safe containers inherit from the class template __gnu_debug _Safe_sequence instantiated with the type of the safe container itself an instance of the curiously recurring template pattern The iterators of a container wrapper will be safe iterators that reference sequences of this type and wrap the iterators provided by the release mode base class The debugging container will use only the safe iterators within its own interface therefor
160. ast_dealloc_index point to valid locations within the vector 20 2 2 7 Questions 20 2 2 7 1 1 Q1 The Data Layout section is cryptic I have no idea of what you are trying to say Layout of what The free list Each bitmap The Super Block The layout of a Super Block of a given size In the example a super block of size 32 x 1 is taken The general formula for calculating the size of a super block is 32 x sizeof value_type x 2 n where n ranges from 0 to 32 for 32 bit systems 20 2 2 7 2 2 And since I just mentioned the term each bitmap what in the world is meant by it What does each bitmap manage How does 1t relate to the super block Is the Super Block a bitmap as well Each bitmap is part of a Super Block which is made up of 3 parts as I have mentioned earlier Re iterating 1 The use count 2 The bit map for that Super Block 3 The actual memory that will be eventually given to the user Each bitmap is a multiple of 32 in size If there are 32 x 2 3 blocks of single objects to be given there will be 32 x 2 3 bits present Each 32 bits managing the allocated free status for 32 blocks Since each size_t contains 32 bits one size_t can manage up to 32 blocks status Each bit map is made up of a number of size_t whose exact number for a super block of a given size I have just mentioned 20 2 2 7 3 3 How do the allocate and deallocate functions work in regard to bitmaps The allocate and deallocate functio
161. ata or functionality in a sanely named unique namespace whenever possible This is considered an advantage over dumping everything in the global namespace as then name look up can be explicitly enabled or disabled as above symbols are consistently mangled without repetitive naming prefixes or macros etc For instance consider a project that defines most of its classes in namespace gtk Itis possible to adapt namespace gtk to namespace std by using a C feature called namespace composition This is what happens if a using declaration is put into a namespace definition the imported symbol s gets imported into the currently active namespace s For example The GNU C Library 25 253 namespace gtk using Steels sil Oj usimg Gregal sanra class Window In this example std string gets imported into namespace gtk The result is that use of std string inside names pace gtk can just use st ring without the explicit qualification As an added bonus std string does not get imported into the global namespace Additionally a more elaborate arrangement can be made for backwards compatibility and porta bility whereby the using declarations can wrapped in macros that are set based on autoconf tests to either or i e using std string depending on whether the system has libstdc in std or not ideas from Llewelly and Karl Nelson 3 5 Linking 3 5 1 Almost Nothing Or as close as it gets freestanding This is
162. ate implementations of items in tuple and functional Default what implementations give more elaborate exception strings for bad_cast bad_typeid bad_exception and bad_alloc PCH binary files no longer installed Instead the source files are installed Namespace pb_ds moved to __gnu_pb_ds B 5 10 4 4 C 0X features e Added atomic chrono condition_variable forward_list initializer_list mutex ratio thread e Updated and improved algorithm system_error type_traits e Use of the GNU extension namespace association converted to inline namespaces e Preliminary support for initializer_list and defaulted and deleted constructors in container classes unique_ptr e Support for new character types char16_t and char32_t added to char_traits basic_string numeric_limits and assorted compile time type traits e Support for string conversions to_st ring and to_wstring e Member functions taking string arguments were added to iostreams including basic_filebuf basic_ofstream and basic_ifstream e Exception propagation support including exception_ptr current_exception copy_exception and rethr ow_exception Uglification of try to__try and catch to__catch Audit of internal mutex usage conversion to functions returning static local mutex Extensions added ext pointer h and ext extptr_allocator h Support for non standard pointer types has been added to vector and forward_list The GNU C Library 2
163. b deeded 24 4 E4456 eee eRe eo bbe S ES 28 36 44 Alternatives bebe R oe Eee EER E ee ae Gea ee 28 3 6 5 Containers ses gah a Re PO SRE RR EY eR RR EY ORR A Gwe RE ES a 28 EXcepuonS s uba e 556 556 44 25 4 69844255 4445 6 is a GR 29 3 1 1 Exception Safety ee eu phe dead be ee eA eb e baa ee Ee ae a ee 29 3 7 2 Exception Neutrality osas ERR EY ORR EGR SES Ewe RE ESS 30 37 3 Domp without 22854655244 245 64644285 64445425556 6454 oe Pht betes 30 3 74 Compatibility secs e Bede ae Ree SA eae Ea a ea Eh ewe Ue ae Gea E 31 STAN WD esponsor eS we Se he bee 31 3 7 4 2 With POSIX thread cancellation 20 0 020 000 0020 00 0000 31 3 7 Bibliography sese GA a e e he ea ea e a ew y E a 32 Debugging SUpport p sso redana pe bes ew ee a a ee we a Ea EE 38 1 USING BHF TT 32 3 8 2 Debug Versions of Library Binary Files oaaae 33 3 8 3 Memory Leak Hunting 65 5 pels nee oras ca eS Ee RE ESS 33 3 84 Using sdh es ee ke Bae eS SR RERES SO e Eh De a e De ee Ee N 34 3 8 5 Tracking uncaught exceptions aee a E R p RR E RR RRR RR RRR R T 39 3 8 0 Debug Mode s core ce pe ROE RE A a ER a RE ESS 39 3 8 7 Compile Time Checking 0 0 0 0 0000002 e R RRR RRR R 35 3 8 8 Profile based Performance Analysis a 35 The GNU C Library II Standard Contents 4 Support 4 1 Types eset RR NN 4 1 1 Fundamental Types ea cece ea gee e A A ee ee Re 4 1 2 JNumeric Properties lt ces s 2 eae a Re REE a DLR BES SA
164. bably because the author thought it would be more correct to specify nocreate explicitly So it can be left out for input streams For output streams nocreate is probably the default unless you specify std ios trunc To be safe you can open the file for reading check if 1t has been opened and then decide whether you want to create replace or not To my knowledge even older implementations support app ate and t runc except for app B 6 3 4 No stream attach int fd Phil Edwards writes It was considered and rejected for the ISO standard Not all environments use file descriptors Of those that do not all of them use integers to represent them For a portable solution among systems which use file descriptors you need to implement a subclass of std streambuf or std basic_streambuf lt gt which opens a file given a descriptor and then pass an instance of this to the stream constructor An extension is available that implements this ext stdio_filebuf h contains a derived class called__gnu_cxx stdio_filebuf This class can be constructed from a C FILE or a file descriptor and provides the fd function For another example of this refer to fdstream example by Nicolai Josuttis B 6 3 5 Support for C 98 dialect Check for complete library coverage of the C 1998 2003 standard AC_HEADER_STDCXX_98 AC_DEFUN AC_HEADER_STDCXX_98 AGmCACHEMCHE CKa hoOm ei CONC a O Cde les I Sis AC_LANG_SA
165. beginof vector lt T gt amp v return v begin template lt typename T unsigned int sz gt inline Tx beginof T amp array sz return array endof template lt typename T gt inline typename vector lt T gt iterator endof vector lt T gt amp v return v end template lt typename T unsigned int sz gt inline Tx endof T amp array sz return array sz lengthof template lt typename T gt inline typename vector lt T gt size_type lengthof vector lt T gt v return v size The GNU C Library 81 253 template lt typename T unsigned int sz gt inline unsigned int lengthof T 8 sz return sz Astute readers will notice two things at once first that the container class is still a vector lt T gt instead of a more general Container lt T gt This would mean that three functions for deque would have to be added another three for 1ist and so on This is due to problems with getting template resolution correct I find it easier just to give the extra three lines and avoid confusion Second the line inline unsigned int lengthof T 8 sz return sz looks just weird Hint unused parameters can be left nameless The GNU C Library 82 253 Chapter 10 lterators 10 1 Predefined 10 1 1 Iterators vs Pointers The following FAQ entry points out that iterators are not implemented as pointers They are a generalization of point
166. ble copyright law except executing it on a computer or modifying a private copy Propagation includes copying distribution with or without modification making available to the public and in some countries other activities as well To convey a work means any kind of propagation that enables other parties to make or receive copies Mere interaction with a user through a computer network with no transfer of a copy is not conveying An interactive user interface displays Appropriate Legal Notices to the extent that it includes a convenient and prominently visible feature that 1 displays an appropriate copyright notice and 2 tells the user that there is no warranty for the work except to the extent that warranties are provided that licensees may convey the work under this License and how to view a copy of this License If the interface presents a list of user commands or options such as a menu a prominent item in the list meets this criterion 1 Source Code The source code for a work means the preferred form of the work for making modifications to 1t Object code means any non source form of a work A Standard Interface means an interface that either is an official standard defined by a recognized standards body or in the case of interfaces specified for a particular programming language one that is widely used among developers working in that language The System Libraries of an executable work
167. ble only on paper GNU manuals come with permission to copy and modify the Perl manuals do not These restrictions are the problems The criterion for a free manual is pretty much the same as for free software it is a matter of giving all users certain freedoms Redistribution including commercial redistribution must be permitted so that the manual can accompany every copy of the program on line or on paper Permission for modification is crucial too As a general rule I don t believe that it is essential for people to have permission to modify all sorts of articles and books The issues for writings are not necessarily the same as those for software For example I don t think you or I are obliged to give permission to modify articles like this one which describe our actions and our views But there is a particular reason why the freedom to modify is crucial for documentation for free software When people exercise their right to modify the software and add or change its features if they are conscientious they will change the manual too so they can provide accurate and usable documentation with the modified program A manual which forbids programmers to be conscientious and finish the job or more precisely requires them to write a new manual from scratch if they change the program does not fill our community s needs While a blanket prohibition on modification is unacceptable some kinds of limits on the method of modification pose no pr
168. block in whatever region of memory that we own free This is done by checking s The use count for each super block and if that fails then e The individual bit maps for each super block Note Here we are never touching any of the memory that the user will be given and we are confining all memory accesses to a small region of memory This helps reduce cache misses If this succeeds then we apply the same procedure on that bit map as 1 and return that block of memory to the user However if this process fails then we resort to 4 4 This process involves Refilling the internal exponentially growing memory pool The said effect is achieved by calling _S_refill_pool which does the following e Gets more memory from the Global Free List of the Required size e Adjusts the size for the next call to itself e Writes the appropriate headers in the bit maps e Sets the use count for that super block just allocated to O zero e All of the above accounts to maintaining the basic invariant for the allocator If the invariant is maintained we are sure that all is well Now the same process is applied on the newly acquired free blocks which are dispatched accordingly Thus you can clearly see that the allocate function is nothing but a combination of the next fit and first fit algorithm optimized ONLY for single object allocations The GNU C Library 139 253 20 2 2 6 deallocate The deallocate function again is specialized for si
169. bool gt The Committee made provision for the space savings possible with that N 8 usage previously mentioned so that you don t have to do wasteful things like Container lt char gt or Container lt short int gt Specifically vecto r lt bool1 gt is required to be specialized for that space savings The problem is that vector lt bool gt doesn t behave like a normal vector anymore There have been journal articles which discuss the problems the ones by Herb Sutter in the May and July August 1999 issues of C Report cover it well Future revisions of the ISO C Standard will change the requirement for vect or lt boo1 gt specialization In the meantime deque lt bool gt is recommended although its behavior is sane you probably will not get the space savings but the allocation scheme is different than that of vector Extremely weird solutions If you have access to the compiler and linker at runtime you can do something insane like figuring out just how many bits you need then writing a temporary source code file That file contains an instantiation of bit set for the required number of bits inside some wrapper functions with unchanging signatures Have your program then call the compiler on that file using Position Independent Code then open the newly created object file and load those wrapper functions You ll have an instantiation of bit set lt N gt for the exact N that you need at the time Don t forget to delete the temporary
170. c Functions 151 28 2 2 Thread Abstraction s s 2 os p ke ad A E ee 152 28 3 USE s isa a RR e a E e ee e RR ia Bae dod A aiii See 152 IV Appendices 154 A Contributing AppendixContributing 155 Asl Contubutor Checklist lt s 22i 52844058 da 4454 2555 Seed sored eden ch 155 AIl Reading see be ae eae a lt A ee 155 AN 2 Assignment ese 4 255 485 sale eb baa abe eee baer eee sb hanes 2 bee ee hes e s 155 Ail 3 Getting Sources 252 bib kee ee ERS ee BS ee A a a a 156 A 1 4 Submitting Patches cs es sest teree deteee tte ke NR R RRR RR RRR 156 A 2 Directory Layout and Source Conventions 2 2 ee 156 AS Coding Style cues eee ba hee RE ER Se eee he eS Ee A Bee is 158 A3 1 Bad Identifiers 65 4045044 bebe Soa ee ERA ERS ee eae be a ee 158 A 3 2 By Examples 55 485 elo eb been he Gee dawn a tee ee 161 A 4 Documentation Style o c es ED ee RS ee Ee A ee ee 168 AAA eA gare ie Ae ees Bete ie ai ede Gee o He OS Shedd es we 168 ALT Prerequisites cos a scaricare eee he wR ERAS REE ESR eR OY E a 168 A 4 1 2 Generating the Doxygen Files ee ee 168 A413 Markup ness oe de Bede de BS ee Se ele Ged ERAS GES se amp x 169 AA2 Docbook 245 petae euge 03 e 08 bois Sha ee eae tba awe bs Poe Ae ee ae HO 170 A421 Prerequisites so 50095 a bw ee a OS a ee RO a RA e we 170 A 4 2 2 Generating the DocBook Files 0 a 170 A 4 2 3 File Organization and Basics ee 170 A 4 2 4 Markup By Example o oo a 171
171. cal reasons the instrumentation library processes the trace partially rather than dumping it to disk in raw form Each event is processed when it occurs It is usually attached a cost and it is aggregated into the database of a specific diagnostic class The cost model is based largely on the standard performance guarantees but in some cases we use knowledge about GCC s standard library implementation Information is indexed by 1 call stack and 2 instance id or address to be able to understand and summarize precise creation use destruction dynamic chains Although the analysis is sensitive to dynamic instances the reports are only sensitive to call context Whenever a dynamic instance is destroyed we accumulate its effect to the corresponding entry for the call stack of its constructor location For details see paper presented at CGO 2009 19 2 4 Analysis and Diagnostics Final analysis takes place offline and it is based entirely on the generated trace and debugging info in the application binary See section Diagnostics for a list of analysis types that we plan to support The GNU C Library 118 253 The input to the analysis is a table indexed by profile type and call stack The data type for each entry depends on the profile type 19 2 5 Cost Model While it is likely that cost models become complex as we get into more sophisticated analysis we will try to follow a simple set of rules at the beginning e Relative benefit
172. certain numbered version of the GNU General Public License or any later version applies to it you have the option of following the terms and conditions either of that The GNU C Library 246 253 numbered version or of any later version published by the Free Software Foundation If the Program does not specify a version number of the GNU General Public License you may choose any version ever published by the Free Software Foundation If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used that proxy s public statement of acceptance of a version permanently authorizes you to choose that version for the Program Later license versions may give you additional or different permissions However no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version 15 Disclaimer of Warranty THERE IS NO WARRANTY FOR THE PROGRAM TO THE EXTENT PERMITTED BY APPLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR POSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFECTIVE YOU ASSUME THE COST OF ALL NECESSARY SERVICING REPAIR OR
173. cets and gathering data from them for each call operator lt lt would be prohibitively slow To cache forma 184 253 ng to data for use by num_put lt gt and num_get lt gt we have a _Format_cache lt gt This is construc It object stored in the ios_base pword array and initialized lazily and is organized purely for utility is discarded when a new locale with different facets is imbued Using only the public interfaces o facet functions would character operations The streambu described under chapter 24 iterators via expl streambufs and us streambuf internal under chapter 27 for input parsing f the iterator arguments to f iterator optimizations are xtended inter buffer arrays faces to get direct access to ted the limit performance by forbidding vector style but facets can also bypass the streambuf licit specializations and operate directly on the the These extensions are mentioned These optimizations are particularly important Unused virtual members of locale facets can be omitted as mentioned above by a smart linker Chapter 23 Containers Headers lt deque gt lt list gt lt queue gt lt stack gt lt vector gt lt map gt lt set gt lt bitset gt All the components in chapter 23 are implemented in the SGI STL They are mostly complete they include a large number of nonconforming extensions which must be wrapped Some of these are us
174. ch 3 8 Debugging Support There are numerous things that can be done to improve the ease with which C binaries are debugged when using the GNU tool chain Here are some of them 3 8 1 Using g Compiler flags determine how debug information is transmitted between compilation and debug or analysis tools The default optimizations and debug flags for a libstdc build are g 02 However both debug and optimization flags can be varied to change debugging characteristics For instance turning off all optimization via the g 00 fno inlin flags will disable inlining and optimizations and add debugging information so that stepping through all functions including inlined constructors and destructors is possible In addition fno eliminate unused debug types can be used when additional debug information such as nested class info is desired Or the debug format that the compiler and debugger use to communicate information about source constructs can be changed via gdwarf 2 or gstabs flags some debugging formats permit more expressive type and scope information to be shown in gdb Expressiveness can be enhanced by flags like g3 The default debug information for a particular platform can be identified via the value set by the PREFERRED_DEBUGGING_TYPE macro in the gcc sources Many other options are available please see Options for Debugging Your Program in Using the GNU Compiler Collection GCC for a complete list The G
175. ct type checking on the internal and external types As part of this the size of the internal and external types will need to be known 8 2 2 2 3 Other Issues In addition multi threaded and multi locale environments also impact the design and requirements for code conversions In particular they affect the required specialization codecvt lt wchar_t char mbstate_t gt when implemented using standard C functions Three problems arise one big one of medium importance and one small First the small mesrtombs and wcsrtombs may not be multithread safe on all systems required by the GNU tools For GNU Linux and glibc this is not an issue The GNU C Library 70 253 Of medium concern in the grand scope of things is that the functions used to implement this specialization work on null terminated strings Buffers especially file buffers may not be null terminated thus giving conversions that end prematurely or are otherwise incorrect Yikes The last and fundamental problem is the assumption of a global locale for all the C functions referenced above For something like C iostreams where codecvt is explicitly used the notion of multiple locales is fundamental In practice most users may not run into this limitation However as a quality of implementation issue the GNU C library would like to offer a solution that allows multiple locales and or simultaneous usage with computationally correct results In short libstdc i
176. cument when referring to single threaded applications this also includes applications that are compiled with gcc without thread support enabled This is accomplished using ifdef s on __GTHREADS This allocator is tunable very flexible and capable of high performance The aim of this document is to describe from an application point of view the inner workings of the allocator 20 1 2 Design Issues 20 1 2 1 Overview There are three general components to the allocator a datum describing the characteristics of the memory pool a policy class containing this pool that links instantiation types to common or individual pools and a class inheriting from the policy class that is the actual allocator The datum describing pools characteristics is template lt bool _Thread gt class __pool This class is parametrized on thread support and is explicitly specialized for both multiple threads with bool t rue and single threads via bool false It is possible to use a custom pool datum instead of the default class that is provided There are two distinct policy classes each of which can be used with either type of underlying pool datum template lt bool _Thread gt Sere wong common_pool_policy template lt typename _Tp bool _Thread gt SIE REE per_type_pool_policy The first policy __common_pool_ policy implements a common pool This means that allocators that are instantiated with different types say char and long w
177. d Ll vwector lt vector lt into gt vw 100000 vector lt ant gt 00 3 2 for ant k 07 kK lt LO0000 F k 3 to int y OF 3 lt Ue e 4 4 vado ias e are 30 5 6 foo cc 1 advice Changing initial vector size from 100 to 10 saves N bytes of memory and may reduce the number of cache and TLB misses 19 7 2 6 Vector to Hashtable e Switch _GLIBCXX_PROFILE_VECTOR_TO_HASHTABL E s Goal Detect uses of vector that can be substituted with unordered_set to reduce execution time e Fundamentals Linear search in a vector is very expensive whereas searching in a hashtable is very quick e Sample runtime reduction factor up to container size e Recommendation Replace vector with unordered_set at site S e To instrument vector operations and access methods e Analysis For each dynamic instance of vector record call context of the constructor Issue the advice only if the only methods called on this vector are push_back insert and find e Cost model Cost vector push_back cost vector insert cost find vector cost unordered_set insert cost unordered_set find e Example INES O LAE V7 2 aoe A AS A SL Con eases 7 3 find v begin v end i a foo cc 1 advice Changing vector to unordered_set will save about 500 000 comparisons The GNU C Library 125 253 19 7 2 7 Hashtable to Vector e Switch _GLIBCXX_PROFILE_HASHTABLE_TO_VECTOR s Goal Detect us
178. d instantiations the GNU extension syntax extern template can be used to control where template definitions reside By marking required instantiations as extern template in include files and providing explicit instantiations in the appro priate instantiation files non inlined template functions can be versioned This technique is mostly used on parts of the standard that require char and wchar_t instantiations and includes basic_string the locale facets and the typesin iostreams In addition these techniques have the additional benefit that they reduce binary size which can increase runtime perfor mance 2 Namespaces linking symbol definitions to export mapfiles All symbols in the shared library binary are processed by a linker script at build time that either allows or disallows external linkage Because of this some symbols regardless of normal C C linkage are not visible Symbols that are internal have several appealing characteristics by not exporting the symbols there are no relocations when the shared library is started and thus this makes for faster runtime loading performance by the underlying dynamic loading mechanism In addition they have the possibility of changing without impacting ABI compatibility The following namespaces are transformed by the mapfile namespace std Defaults to exporting all symbols in label GLIBCXX that do not begin with an underscore i e __t est_func would not be exported by default Select
179. d or affirmed under this License For example you may not impose a license fee royalty or other charge for exercise of rights granted under this License and you may not initiate litigation including a cross claim or counterclaim in a lawsuit alleging that any patent claim is infringed by making using selling offering for sale or importing the Program or any portion of it 11 Patents A contributor is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based The work thus licensed is called the contributor s contributor version A contributor s essential patent claims are all patent claims owned or controlled by the contributor whether already acquired or hereafter acquired that would be infringed by some manner permitted by this License of making using or selling its contributor version but do not include claims that would be infringed only as a consequence of further modification of the contributor version For purposes of this definition control includes the right to grant patent sublicenses in a manner consistent with the requirements of this License The GNU C Library 245 253 Each contributor grants you a non exclusive worldwide royalty free patent license under the contributor s essential patent claims to make use sell offer for sale import and otherwise run modify and propagate the contents of its contributor version In the
180. d they do for std string what their siblings do for files All that work you put into writing lt lt and gt gt functions for your classes now pays off again Need to format a string before passing the string to a function Send your stuff via lt lt to an ostringstream You ve read a string as input and need to parse it Initialize an istringstream with that string and then pull pieces out of it with gt gt Have a stringstream and need to get a copy of the string inside Just call the str member function This only works if you ve written your lt lt gt gt functions correctly though and correctly means that they take istreams and ostreams as parameters not ifstreams and ofstreams If they take the latter then your I O operators will work fine with file streams but with nothing else including stringstreams If you are a user of the strstream classes you need to update your code You don t have to explicitly append ends to terminate the C style character array you don t have to mess with freezing functions and you don t have to manage the memory yourself The strstreams have been officially deprecated which means that 1 future revisions of the C Standard won t support them and 2 if you use them people will laugh at you The GNU C Library 91 253 13 4 File Based Streams 13 4 1 Copying a File So you want to copy a file quickly and easily and most important completely portably And since this
181. dard The standard says that size should be constant time and should does not mean the same thing as shall This is the officially recommended ISO wording for saying that an imple mentation is supposed to do something unless there is a good reason not to One implication of linear time size you should never write if L size 0 Instead you should write if L empty 9 1 2 vector 9 1 2 1 Space Overhead Management In this message to the list Daniel Kostecky announced work on an alternate form of std vector that would support hints on the number of elements to be over allocated The design was also described along with possible implementation choices The first two alpha releases were announced here and here The GNU C Library 78 253 9 2 Associative 9 2 1 Insertion Hints Section 23 1 2 Table 69 of the C standard lists this function for all of the associative containers map set etc a insert p t where p is an iterator into the container a and Y is the item to insert The standard says that t is inserted as close as possible to the position just prior to p Library DR 233 addresses this topic referring to N1780 Since version 4 2 GCC implements the resolution to DR 233 so that insertions happen as close as possible to the hint For earlier releases the hint was only used as described below Here we ll describe how the hinting works in the libstdc impl
182. dc 1 3 2 Standard Bugs Everybody s got issues Even the C Standard Library The Library Working Group or LWG is the ISO subcommittee responsible for making changes to the library They periodically publish an Issues List containing problems and possible solutions As they reach a consensus on proposed solutions we often incorporate the solution Here are the issues which have resulted in code changes to the library The links are to the specific defect reports from a partial copy of the Issues List You can read the full version online at the ISO C Committee homepage linked to on the GCC Readings page If you spend a lot of time reading the issues we recommend downloading the ZIP file and reading them locally The GNU C Library 10 253 NB partial copy means that not all links within the lwg html pages will work Specifically links to defect reports that have not been accorded full DR status will probably break Rather than trying to mirror the entire issues list on our overworked web server we recommend you go to the LWG homepage instead If a DR is not listed here we may simply not have gotten to it yet feel free to submit a patch Search the include bits and src directories for appearances of _GLIBCXX_RESOLVE_LIB_DEFECTS for examples of style Note that we usually do not make changes to the code until an issue has reached DR status 5 string compare specification questionable This should be two
183. de crre pem boob e ee oy A ee Bee eR od YB ae ee oe 110 18 3 3 Using Specific Parallel Components 000 0002 00 e eee 110 18 4 Design 2 eeen 6 bob GA eh A hae do ed ae ORAM Ea e 110 184 1 Interface Basics lt 6s Sas He REA ee ES ce ee ok eee Bee e 110 18 4 2 Configuration and Tuning 2 a 112 18 4 2 1 Setting up the OpenMP Environment 112 18 4 2 2 Compile Time Switches ee 113 18 4 2 3 Run Time Settings and Defaults 2 ee 113 18 4 3 Implementation Namespaces 2 2 a 114 A Fe BA OR Re ee FOr eels Be Y Dee ee 5 114 18 6 Bibliography sa sa ok ma R R a A Ra eS a Gee A Re eee 114 19 Profile Mode 115 TO AMO is a ae E A H Ghee ADA a Mes Gig ARAS ee 115 19 1 1 Using the Profile Mode 2 2 2 2 0 0 a 115 19 1 2 Tuning the Profile Mode 0 0 000000020002 eee ee 116 192 Desie NE es ee eee E ee MES A Boeke A ets Bay A AS AS ee 117 19 2 1 Wrapper M del i og 2 5 oc bo a A ae ee 117 19 2 2 Instrumentation s ooro os aor DR RR RR Re ee we a 117 19 23 Run Time Behavior ht e dt e i Sede ARA x 117 19 2 4 Analysis and Diagnostics 2 ee 117 19 23 Cost Model posar e e BAe A A Pod YB ae ee 9 118 19 20 REPOMS a ide ice Ste eek as he ei A A AS AAA ee 118 192 7 Testing 2 eae bP eae bee be hae OR ee a ba ee Bede Gow eb te ee 118 The GNU C Library xi 19 3 Extensions for Custom Containers oaoa 118 19 4 Empirical Cost Model s mas ojos a A A OO a be AA a e 119 19 5 Impl
184. dition the policy based containers have their own visualizations which have additional software dependencies than the usual bare boned text file and can be generated by using the make doc performance rule in the testsuite s Makefile 18 6 Bibliography 52 Johannes SinglerLeonor Frias Parallelization of Bulk Operations for STL Dictionaries Copyright 2007 Workshop on Highly Parallel Processing on a Chip HPPC 2007 LNCS 53 Johannes SinglerPeter SandersFelix Putze The Multi Core Standard Template Library Copyright 2007 Euro Par 2007 Parallel Processing LNCS 4641 The GNU C Library 115 253 Chapter 19 Profile Mode 19 1 Intro Goal Give performance improvement advice based on recognition of suboptimal usage patterns of the standard library Method Wrap the standard library code Insert calls to an instrumentation library to record the internal state of various compo nents at interesting entry exit points to from the standard library Process trace recognize suboptimal patterns give advice For details see paper presented at CGO 2009 Strengths e Unintrusive solution The application code does not require any modification e The advice is call context sensitive thus capable of identifying precisely interesting dynamic performance behavior e The overhead model is pay per view When you turn off a diagnostic class at compile time its overhead disappears Drawbacks e You must recompile the app
185. ds A Transparent copy of the Document means a machine readable copy represented in a format whose specification is available to the general public that is suitable for revising the document straightforwardly with generic text editors or for images composed of pixels generic paint programs or for drawings some widely available drawing editor and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters A copy made in an otherwise Transparent file format whose markup or absence of markup has been arranged to thwart or discourage subsequent modification by readers is not Transparent An image format is not Transparent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Texinfo input format LaTeX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScript or PDF designed for human modification Examples of transparent image formats include PNG XCF and JPG Opaque formats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or PDF produced by some word processors for output purposes only The Title Page means for a printed book
186. e typename not class no space long_return_value_type lt with_many args gt function_name charx pointer char pointer is wrong char argument const References ref int a_local wrong see below if test nested code The GNU C Library 168 253 int a_local 0 declare variable at first use char a b p wrong char a a char b a 1 char c abc each variable goes on its own line always except maybe here for unsigned i 0 mask 1 mask i mask lt lt 1 gribble gribble _M private_data 0 _M_more_stuff 0 _M_helper 0 inline int gribble three_lines doesn t fit in one line namespace std A 4 Documentation Style A 4 1 Doxygen A 4 1 1 Prerequisites Prerequisite tools are Bash 2 x Doxygen and the GNU coreutils GNU versions of find xargs and possibly sed and grep are used just because the GNU versions make things very easy To generate the pretty pictures and hierarchy graphs the Graphviz package will need to be installed For PDF output pdflatex is required A 4 1 2 Generating the Doxygen Files The following Makefile rules run Doxygen to generate HTML docs XML docs PDF docs and the man pages make doc html doxygen make doc xml doxygen make doc pdf doxygen make doc man doxygen Careful observers will see that the Makefile rules simply call a script from
187. e Tell us the libstdc mailing list if you discover more enable c99 The long long type was introduced in C99 along with many other functions for wide characters and math classification macros etc If enabled all C99 functions not specified by the C standard will be put into namespace ___gnu_cxx and then all these names will be injected into namespace std so that C99 functions can be used as if they were in the C standard as they will eventually be in some future revision of the standard without a doubt By default C99 support is on assuming the configure probes find all the necessary functions and bits necessary This option can change the library ABI enable wchar_t default Template specializations for the wchar_t type are required for wide character conversion support Disabling wide character specializations may be expedient for initial porting efforts but builds only a subset of what is required by ISO and is not recommended By default this option is on This option can change the library ABI enable long long The long long type was introduced in C99 It is provided as a GNU extension to C 98 in g This flag builds support for long long into the library specialized templates and the like for iostreams This option is on by default if enabled users will have to either use the new style C headers by default i e lt cmath gt not lt math h gt or add appropriate compile time flags to all compile lines
188. e gribble _M private_data 0 _M more_stuff 0 _M helper 0 NOT gribble gribble _M private_data 0 _M_more_stuff 0 _M helper 0 L 08 Try Catch blocks try Gatien ese NOT try catch 09 Member functions declarations and definitions Keywords such as extern static export explicit inline etc go on the line above the function name Thus virtual int foo L NOT virtual int foo Reason GNU coding conventions dictate return types for functions are on a separate line than the function name and parameter list for definitions For C where we have member functions that can The GNU C Library 164 253 be either inline definitions or declarations keeping to this standard allows all member function names for a given class to be aligned to the same margin increasing readability 10 Invocation of member functions with this gt For non uglified names use this gt name to call the function this gt sync NOT sync Reason Koenig lookup 11 Namespaces namespace std blah blah blah namespace std NOT namespace std blah blah blah namespace std 12 Spacing under protected and private in class declarations space above none below i e public int foo NOT public int foo 13 Spacing WRT return statements no extra spacing before returns no parenthesis i e retur
189. e the __basic_file type is basically derived from FILE The real situation is more complex than that it s derived from an internal type used to implement FILE See libio libioP h to see scary things done with vtbls The result is that there is no layer of C stdio to go through the filebuf makes calls directly into the same functions used to implement fread fwrite and so forth using internal data structures And when I say makes calls directly I mean the function is literally replaced by a jump into an internal function Fast but frightening grin Also the libio internal locks are used This requires pulling in large chunks of glibc such as a pthreads implementation and is one of the issues preventing widespread use of libio as the libstdc cstdio implementation But we plan to make this work at least as an option if not a future default Platforms running a copy of glibc with a recent enough version will see calls from libstdc directly into the glibc already installed For other platforms a copy of the libio subsection will be built and included in libstdc 3 6 4 4 Alternatives Don t forget that other cstdio implementations are possible You could easily write one to perform your own forms of locking to solve your interesting problems 3 6 5 Containers This section discusses issues surrounding the design of multithreaded applications which use Standard C containers All information in this section is current as
190. e A struct X extern C global or maybe just extern C struct Y EE y void A X mangles to tL _FPO21A1X void f A Yx mangles to f__FP1Y It may be that this is really the appropriate semantics for regular extern C and extern C global as an extension would not be necessary This would allow functions declared in non standard C headers and thus fixable by neither us nor users to link properly with functions declared using C types defined in properly namespaced headers The problem this solves is that C headers which C programmers do persist in using frequently forward declare C struct tags without including the header where the type is defined as in struct tm void munge tm Without some compiler accommodation munge cannot be called by correct C code using a pointer to a correctly scoped tm value The current C headers use the preprocessor extension include_next which the compiler complains about when run pedantic Incidentally it appears that fpedantic is currently ignored probably a bug The solution in the C compiler is to use The GNU C Library 180 253 isystem rather than I but unfortunately in g this seems also to wrap the whole header in an extern C block so it s unusable for C headers The correct solution appears to be to allow the various special include directory options if not given
191. e A Hore eee dE Be ee 8 eS TLG CSting MFC soi e a eoon a Ba NS SEG ee eG RRS oe a A eee a 8 Localization Sal Localest awe a the Bee ee A eee ee DU e a ee be Sl locale donee e POY OR ke ewe SNe beet Ee daa 8 1 1 1 Requirements c ssc spa 6b bo eR ERR RR ee ee ee ee ee SLZ DESEN q oi ayant ee BEE ee Bad ah oe ev ee eS See te AE Se 8 1 1 3 Implementation s q esre 644084 bee A bee ee wR EAR YS 8 1 1 3 1 Interacting with C locales ee SA FUE ce ai Eten se Be eed Hk A aed weve eS Sa ee A ee 8 1 1 Bibliostaphy oc mest a Se ha Ga Phd eee 8 2 Facets sip so ghee Be e Be Be eS we GS Behe ee A hw a ea ee OZ CLV Per Eta le kim dere A ME eh OS A eee AS AS ee ee eS 4 8 2 1 1 Implementation ss se sp mest taa et nu a a e e G E e 0002 22 2 ee 8 2 1 1 1 Specializations tetepan kea dea deao ie S2 L2 FUE seein e A AE AS A 8 2 1 3 Biblhography lt ci respet Ea A RE ea R ea eae ee 82 2 COdECVE 284 64 dae eres Ya RAO Ro Ae ee Pog YB ae es 8S 82 21 Requirements seos e Se ei At ee ES eS ee pe pod Se 8 2 2 2 K T 625 0 eae Oe Ra OA be ed AA dee vii 50 51 51 52 32 52 52 32 53 53 53 54 54 54 55 56 56 57 58 The GNU C Library 8 2 2 2 1 WEM SIZES 2 acu cae oe a BRE ae 82 222 Supporttor Unicode 23 244 268 6he 84 4495 Seeds He wn eee he S 4 8 2 2 2 3 Other 8 2 2 3 Implementation 8 2 2 4 Use 8 2 2 5 Future 8 2 2 6 Bibliography 8 2 3 messages 8 2 3 1 Requirements ISSUES me ei di
192. e c 3 3 2 gec 3 3 3 include c 3 3 3 gec 3 4 0 include c 3 4 0 gcc 3 4 1 include c 3 4 1 gcc 3 4 2 include c 3 4 2 gec 3 4 3 include c 3 4 3 gcc 3 4 4 include c 3 4 4 gec 3 4 5 include c 3 4 5 gec 3 4 6 include c 3 4 6 gcc 4 0 0 include c 4 0 0 gcec 4 0 1 include c 4 0 1 gcec 4 0 2 include c 4 0 2 gcec 4 0 3 include c 4 0 3 gcc 4 1 0 include c 4 1 0 gcec 4 1 1 include c 4 1 1 gcec 4 1 2 include c 4 1 2 gcec 4 2 0 include c 4 2 0 gcc 4 2 1 include c 4 2 1 gcec 4 2 2 include c 4 2 2 gcec 4 2 3 include c 4 2 3 gcc 4 2 4 include c 4 2 4 gcc 4 3 0 include c 4 3 0 gec 4 3 1 include c 4 3 1 gec 4 3 3 include c 4 3 3 gcc 4 3 4 include c 4 3 4 The GNU C Library 213 253 e gcc 4 4 0 include c 4 4 0 e gcc 4 4 1 include c 4 4 1 e gcc 4 4 2 include c 4 4 2 e gcc 4 5 0 include c 4 5 0 Taken together these techniques can accurately specify interface and implementation changes in the GNU C tools them selves Used properly they allow both the GNU C tools implementation and programs using them an evolving yet controlled development that maintains backward compatibility B 4 2 3 Prerequisites Minimum environment that supports a versioned ABI A supported dynamic linker a GNU linker of sufficient vintage to un derstand demangled C name globbing Id a shared executable compiled with g and shared libraries libgcc_s libstdc compiled by a co
193. e primitives sentry objects or char_traits members All these templates should be manually instantiated for char and wchar_t in a way that links only used members into user programs Streambuf is fertile ground for optimization extensions An extended interface giving iterator access to its internal buffer would be very useful for other library components Tostream operations primarily operators lt lt and gt gt can take advantage of the case where user code has not specified a locale and bypass locale operations entirely The current implementation of op lt lt num_put lt gt put for the integer types demonstrates how they can cache encoding details from the locale on each operation There is lots more room for optimization in this area The definition of the relationship between the standard streams cout et al and stdout et al requires something like a stdiobuf The SGI solution of using double indirection to actually use a The GNU C Library 187 253 stdio FILE object for buffering is unsatisfactory because it interferes with peephole loop optimizations The lt sstream gt header work has begun stringbuf can benefit from friendship with basic_string lt gt and basic_string lt gt _Rep to use those objects directly as buffers and avoid allocating and making G The basic_filebuf lt gt template is a complex beast It is specified to use the locale facet codecvt lt gt to tran
194. e requiring the user to use safe iterators although this does not change correct user code and will communicate with the release mode base class with only the underlying unsafe release mode iterators that the base class exports The debugging version of std 1ist will have the following basic structure template lt typename _Tp typename _Allocator allocator lt _Tp gt class debug list public release list lt _Tp _Allocator gt public __gnu_debug _Safe_sequence lt debug list lt _Tp _Allocator gt gt typedef release list lt _Tp _Allocator gt _Base typedef debug list lt _Tp _Allocator gt _Self public The GNU C Library 104 253 typedef __gnu_debug _Safe_iterator lt typename _Base iterator _Self gt iterator typedef __gnu_debug _Safe_iterator lt typename _Base const_iterator _Self gt const_iterator duplicate std list interface with debugging semantics y 17 4 2 2 Precondition Checking The debug mode operates primarily by checking the preconditions of all standard library operations that it supports Preconditions that are always checked regardless of whether or not we are in debug mode are checked via the __ check __xxx macros defined and documented in the source file include debug debug h Preconditions that may or may not be checked depending on the debug mode macro _GLIBCXX_DEBUG are checked via the __requires_xxx macros defined and documented in the same source file Preconditions ar
195. e validated using any additional information available at run time e g the containers that are associated with a particular iterator the position of the iterator within those containers the distance between two iterators that may form a valid range etc In the absence of suitable information e g an input iterator that is not a safe iterator these precondition checks will silently succeed The majority of precondition checks use the aforementioned macros which have the secondary benefit of having prewritten debug messages that use information about the current status of the objects involved e g whether an iterator is singular or what sequence it is attached to along with some static information e g the names of the function parameters corresponding to the objects involved When not using these macros the debug mode uses either the debug mode assertion macro _GLIBCXX _DEBUG_ASSERT its pedantic cousin _GLIBCXX_DEBUG_PEDASSERT or the assertion check macro that supports more advance formulation of error messages _GLIBCXX_DEBUG_VERIFY These macros are documented more thoroughly in the debug mode source code 17 4 2 3 Release and debug mode coexistence The libstdc debug mode is the first debug mode we know of that is able to provide the Per use recompilation 4 guarantee that allows release compiled and debug compiled code to be linked and executed together without causing unpredictable behav ior
196. e ws 15 2 3 Make 00 pia ea 5004 ESE Ra RS ea Re a ee Re ea eo a SOR 18 3 Using 19 3 1 Command Opuons lt lt s z desee es eRe ee RAK eM Ra Se Kew ee ee Oe dG Be eee eG 19 e AE A OR Ra Se A She we Ek 19 32 1 Header Piles vs 54 2084 404 rd 54 644454 e8b 5 2 tHe eee hb bade 19 3 22 Mixing Header lt c caraca e 4 ea Ee Re ee RL Oe E YR a oS pa 3 2 3 The C Headers and namespace std pis ore gR pa RRR R RRR R R R KR RRR a 22 3 2 4 Precompiled Headers 2 e a E E RRR RRR RR EAE 22 ES E ae ee a ee ks Be oe A a we A ee Be Ge eS e 23 The GNU C Library 3 4 3 5 3 6 3 7 3 8 v Namespaces auena ad e Nedan E e TT A a A e e a ea a 24 341 Available Namespaces ego eae a Ra RAS RR e R a 24 342 namespacerstd odos e di a y 24 3 4 3 Using Namespace Composition o ooa ee 24 LORDS i ee ek oe ea ea oe A SS a areas Ake Sa de A ohare e 25 3 54 Almost Nothing 22 e carane ie di tee hein di Pe ee big a ee en a sa 25 3 5 2 Finding Dynamic or Shared Libraries 0 0 0 0 0000000000 000004 26 CODCUITENGYs 5s ae A hale aS A AS ROR Bae ee AGE Ra be ORG eee eo 26 S641 Prerequisites 2244 54 56 425 bo 4h4245 64644 44 R052 oO 2 oe E SR 26 3 6 2 Thread Satety no edeu GA ae ee ROA ea baa Pa a eee Ge Eee oe ae a 27 SI A bk Ga a AE ES Rae AG GOR E oe RG a ee S 27 3604 TOn e gaa e e a a e A AN 27 36 41 SCTE 25 a a Ee A A a Be 28 3 60 42 WelaultS oia a RR Eee EAS a eG a 28 364 3 PUE 2324556 24 2 t
197. ect dynamic type is known This is an application of the technique known as type erasure 6 3 3 3 Implementation 6 3 3 3 1 Class Hierarchy A shared_ptr lt T gt contains a pointer of type T and an object of type __shared_count The shared_count contains a pointer of type _Sp_counted_base which points to the object that maintains the reference counts and destroys the managed resource _Sp_counted_base lt Lp gt The base of the hierarchy is parameterized on the lock policy alone _Sp_counted_base doesn t depend on the type of pointer being managed it only maintains the reference counts and calls virtual functions when the counts drop to zero The managed object is destroyed when the last strong reference is dropped but the _Sp_counted_base itself must exist until the last weak reference is dropped _Sp _counted_base_impl lt Ptr Deleter Lp gt Inherits from _Sp_counted_base and stores a pointer of type Ptr and a deleter of type Deleter _Sp_deleter is used when the user doesn t supply a custom deleter Unlike Boost s this default deleter is not checked because GCC already issues a warning if delete is used with an incomplete type This is the only derived type used by shared_ptr lt Ptr gt and it is never used by shared_ptr which uses one of the following types depending on how the shared_ptr is constructed _Sp_counted_ptr lt Ptr Lp gt Inherits from _Sp_counted_base and stores a pointer of type Ptr which is passed to d elete when
198. ection gt lt sec t1 gt lt sect1 gt lt sec lt sec lt sec lt sec t1 gt t2 gt t2 gt t1 gt lt chapter gt lt chap ter gt lt chapter gt lt par lt boo t gt K gt lt set gt A 4 2 4 Markup By Example Complete details on Docbook markup can be found in the DocBook Element Reference online An incomplete reference for HTML to Docbook conversion is detailed in the table below And examples of detailed markup for which there are no real HTML equivalents are listed in the table below The GNU C Library 172 253 HTML Docbook lt p gt lt para gt lt pre gt lt computeroutput gt lt programlisting gt lt literallayout gt lt ul gt lt itemizedlist gt lt ol gt lt orderedlist gt lt il gt lt listitem gt lt dl gt lt variablelist gt lt dt gt lt term gt lt dd gt lt listitem gt lt a href gt lt ulink url gt lt code gt lt literal gt lt programlisting gt lt strong gt lt emphasis gt lt em gt lt emphasis gt K lt quote gt Table A 2 HTML to Docbook XML Markup Comparison Element Use lt structname gt lt structname gt char_traits lt structname gt lt classname gt lt classname gt string lt classname gt lt function gt clear lt function gt lt function gt 3 lt function gt fs clear lt function gt lt type gt lt type g
199. ed according to the same predicate that was passed to set_inters ection the libstdc debug mode will detect an error if the sequence is not sorted or was sorted by a different predicate 17 2 Semantics A program that uses the C standard library correctly will maintain the same semantics under debug mode as it had with the normal release library All functional and exception handling guarantees made by the normal library also hold for the debug mode library with one exception performance guarantees made by the normal library may not hold in the debug mode library For instance erasing an element in a std list is a constant time operation in normal library but in debug mode it is linear in the number of iterators that reference that particular list So while your correct program won t change its results it is likely to execute more slowly libstdc includes many extensions to the C standard library In some cases the extensions are obvious such as the hashed associative containers whereas other extensions give predictable results to behavior that would otherwise be undefined such as throwing an exception when a std basic_string is constructed from a NULL character pointer This latter category also includes implementation defined and unspecified semantics such as the growth rate of a vector Use of these extensions is not considered incorrect so code that relies on them will not be rejected by debug mode However use of these ext
200. ed data structures revised New includes types namespace moved to__pb_ds Extensions for debug mode modified now nested in namespace std __debug and extensions in namespace _ gnu _cxx __debug Extensions added ext typelist h and ext throw_allocator h B 5 9 4 3 C 0X features first appear TR1 regex and cmath s mathematical special function added Backward include edit s Removed algobase halgo halloc hbvector hcomplex hdefalloc hdeque h fstream h function hhash_ map hhash_set hhashtable hheap hiomanip hiostream histream hiterator hlist hmap h multimap hmultiset hnew hostream hpair hqueue hrope hset hslist hstack hstreambuf h stream h tempbuf htree hvector h e Added hash_map and hash_set e Added in C 0x auto_ptr handbinders h Header dependency streamlining e algorithm no longer includes climits cstring or iosfwd e bitset no longer includes ist ream or ostream adds iosfwd e functional no longer includes cstddef e iomanip no longer includes istream istream or functional adds ioswd numeric no longer includes iterator The GNU C Library 221 253 e string no longer includes algorithm or memory e valarray no longer includes numeric or cstdlib e tr1 hashtable no longer includes memory or functional e tr1 memory no longer includes algorithm e tr1 randon no longer includes algorithmor fstream Debug mode for unordered_map and unordered_set Parallel mode first appears Variadic templ
201. ed directly as first and second Construction is simple The default ctor initializes each member with its respective default ctor The other simple ctor peii eomer Wilks ox Comsit WAG we does what you think it does first getting x and second getting y There is a copy constructor but it requires that your compiler handle member function templates template lt class U class V gt pair const pair lt U V gt amp p The compiler will convert as necessary from U to T1 and from V to T2 in order to perform the respective initializations The comparison operators are done for you Equality of two pair lt T1 T2 gt s is defined as both first members compar ing equal and both second members comparing equal this simply delegates responsibility to the respective operator functions for types like MyClass or builtin comparisons for types like int char etc The less than operator is a bit odd the first time you see it It is defined as evaluating to IS Woitiiesic AS IN EEE KK x second lt y second The other operators are not defined using the rel_ops functions above but their semantics are the same Finally there is a template function called make_pair that takes two references to const objects and returns an instance of a pair instantiated on their respective types pair lt int MyClass gt p make_pair 4 myobject The GNU C Library 45 253 6 3 Memory Memory contains three general areas First func
202. ed internally and must be renamed or duplicated The SGI components are optimized for large memory environments embedded targets different criteria might be more appropriate will want to be able to tune this behavior We should provide For Users ways for users to compile the library with different memory usage characteristics A lot more work is needed on factoring out common code from different specializations to reduce code size here and in chapter 25 The easiest fix for this would be a compiler ABI improvement that allows the compiler to recognize when a specialization depends only on the size or other gross quality of a template argument and allow the linker to share the code with similar specializations In its absence many of the algorithms and containers can be partial specialized at least for the case of pointers but this only solves a small part of the problem Use of a type_traits style templat allows a few more optimization opportunities more if the compiler can generate the specializations automatically As an optimization containers can specialize on the default allocator and bypass it or take advantage of details of its after it has been improved upon Replacing the vector iterators implementation which currently are simple element The GNU C Library 185 253 pointers with class objects would greatly increase the safety of the client interface and
203. ed__ atomic_add _Atomic_wordx mem int _ val x_ mem val The GNU C Library 197 253 B 2 5 Numeric Limits The C library requires information about the fundamental data types such as the minimum and maximum representable values of each type You can define each of these values individually but it is usually easiest just to indicate how many bits are used in each of the data types and let the library do the rest For information about the macros to define see the top of include bits std_limits h If you need to define any macros you can do so in os_defines h However if all operating systems for your CPU are likely to use the same values you can provide a CPU specific file instead so that you do not have to provide the same definitions for each operating system To take that approach create a new file called cpu_limits h in your CPU configuration directory see CPU B 2 6 Libtool The C library is compiled archived and linked with libtool Explaining the full workings of libtool is beyond the scope of this document but there are a few particular bits that are necessary for porting Some parts of the libstdc library are compiled with the libtool tags CXX option the C definitions for libtool There fore lt cf cxx sh in the top level directory needs to have the correct logic to compile and archive objects equivalent to the C version of libtool 1t cf c sh Some libtool targets have definitions for C but
204. efault constructor value mbstate_t must be the base or ground sequence stat According to the likely resolution of a recently raised Core issue this may become unnecessary However there are other reasons to use a state type not as limited as whatever the C library provides If we might want to provide conversions from e g internally represented EUC wide to externally represented Unicode or vice versa the mbstate_t we choose will need to be more accommodating than what might be provided by an underlying C library There remain some basic_string template member functions which do not overload properly with their non template brethren The infamous hack akin to what was done in vector lt gt is needed to conform to 23 1 1 para 10 The CHECKLIST items for basic_string marked X or incomplete are so marked for this reason Replacing the string iterators which currently are simple character pointers with class objects would greatly increase the safety of the The GNU C Library 183 253 client interface and also permit a debug mode in which range ownership and validity are rigorously checked The current use of raw pointers as string iterators is evil vector lt gt iterators need the same treatment Note that the current implementation freely mixes pointers and iterators and that must be fixed before safer iterators can be introduced Some of the fu
205. ementation and what you need to do in order to take advantage of it Insertions can change from logarithmic complexity to amortized constant time if the hint is properly used Also since the current implementation is based on the SGI STL one these points may hold true for other library implementations also since the HP SGI code is used in a lot of places In the following text the phrases greater than and less than refer to the results of the strict weak ordering imposed on the container by its comparison object which defaults to basically lt Using those phrases is semantically sloppy but I didn t want to get bogged down in syntax I assume that if you are intelligent enough to use your own comparison objects you are also intelligent enough to assign greater and lesser their new meanings in the next paragraph grin If the hint parameter p above is equivalent to begin then the item being inserted should have a key less than all the other keys in the container The item will be inserted at the beginning of the container becoming the new entry at begin e end then the item being inserted should have a key greater than all the other keys in the container The item will be inserted at the end of the container becoming the new entry before end e neither begin nor end then Let h be the entry in the container pointed to by hint that is h hint Then the item being inserted should have
206. ementation Issues ya moona Eye e Ea RRR RRR RRR RRR NR 119 19 51 Stack Traces e ata E A a A ees oe ea ds 119 19 5 2 Symbolization of Instruction Addresses ee 119 195 3 Concurrency 2227446504 4458 2 eras A bee eee E ee bb ete be 119 19 5 4 Using the Standard Library in the Instrumentation Implementation 119 19 5 5 Malloc Hooks s 54 rs aa a E a a A ai RG eee aa 119 19 5 6 Construction and Destruction of Global Objects oaao ee 119 19 6 Developer Information oaoa oaa a 120 19 6 1 Big Picture y aos mos aa A aca a a BRE RS E A ee a 120 19 6 2 How To Add A Diagnostic 2 ee 120 19 7 DiaBNOSucs o e a A A e al eae Ge AE ee Oe ae ee 121 19 7 1 Diagnostic Template lt cisma ia RRS aa ERG GEE a RRS ee eo 121 19 7 2 Containers 24 2 2a GA BS RDO EE ee SRSA SE a e ee eS Ge 122 19 7 2 1 Hashtable Too Small 2 ee ee 122 19 7 2 2 Hashtable Too Large lt s 5 aa X N ee EE eR Re RR KK a 122 19 7 2 3 Inefficient Hashi s x coea g ake e ee RR e ee ee 123 19 7 2 4 Vector Too Small s s s eos ee ea ewe e R Ee ee e R a ee 123 197 25 Vector Too Lars 0 ees keh REE ER ee a a Ya 124 19 7 2 6 Vector to Hashtable 2 0 ee 124 19 7 2 7 Hashtable to Vector 2 ee 125 19 BZ NECIOS ere o GA en eee he Pe a a Bee be 125 19 7 2 9 List to Vector seps ts ek be Ee ee a Te a eS ee wm wo 126 19 7 2 10 List to Forward List Slist ee 126 19 7 2 11 Ordered to Unordered Associat
207. ementation deals with the conversion between wide and narrow characters and also presents a framework for dealing with the huge number of other encodings that iconv can convert including Unicode and UTF8 Design issues and requirements are addressed and examples of correct usage for both the required specializations for wide and narrow characters and the implementation provided extended functionality are given 8 2 2 1 Requirements Around page 425 of the C Standard this charming heading comes into view 22 2 1 5 Template class codecvt The text around the codecvt definition gives some clues 1 The class codecvt lt internT externT stateT gt is for use when converting from one codeset to another such as from wide characters to multibyte characters between wide character encodings such as Unicode and EUC Hmm So in some unspecified way Unicode encodings and translations between other character sets should be handled by this class 2 The stateT argument selects the pair of codesets being mapped between Ah ha Another clue 3 The instantiations required in the Table lib locale category namely codecvt lt wchar_t char mbstate_t gt and codecvt lt char char mbstate_t gt convert the implementation defined native character set codecvt lt char char mbstate_t gt implements a degenerate conversion it does not convert at all codecvt lt wchar_t char mbstate_t gt converts between the native character sets for tiny and wide cha
208. en create a precompiled header file with the same flags that will be used to compile other projects parallel algorithm parallel numeric Table 3 13 Extension Parallel Headers The GNU C Library 23 253 g Winvalid pch x c header g 02 stdc h gch mnt share bld H x86 gcc 20071201 include c 4 3 0 x86_64 unknown 1inux gnu bits stdc h The resulting file will be quite large the current size is around thirty megabytes How to use the resulting file ce imeluds suclesa la ll 8 0 liGllo cs Verification that the PCH file is being used is easy Gare T T E T imelues suce la k 23 0 2 hello ce 9 SS Exe stde b gch a mnt share bld H x86 gcc 20071201 include c 4 3 0 iostream mnt share bld H x86 gcc 20071201include c 4 3 0 string The exclamation point to the left of the st dc h gch listing means that the generated PCH file was used and thus the Detailed information about creating precompiled header files can be found in the GCC documentation 3 3 Macros All library macros begin with _GLIBCXX_ Furthermore all pre processor macros switches and configuration options are gathered in the file c config h which is generated during the libstdc configuration and build process This file is then included when needed by files part of the public libstdc API like lt ios gt Most of these macros should not be used by consumers of libstdc and are reserved for i
209. en debugging C code that uses new and delete there are different kinds of allocation schemes that can be used by std allocator For implementation details see the mt allocator documentation and look specifically for GLIBCXX_FORCE_NEW In a nutshell the default allocator used by std allocator is a high performance pool allocator and can give the mistaken impression that in a suspect executable memory is being leaked when in reality the memory leak is a pool being used by the library s allocator and is reclaimed after program termination For valgrind there are some specific items to keep in mind First of all use a version of valgrind that will work with current GNU C tools the first that can do this is valgrind 1 0 4 but later versions should work at least as well Second of all use a completely unoptimized build to avoid confusing valgrind Third use GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from cluttering debug information Fourth it may be necessary to force deallocation in other libraries as well namely the C library On linux this can be accomplished with the appropriate use of the __cxa_atexit or atexit functions include lt cstdlib gt extern C void __libc_freeres void void do_something int main atexit __libc_freeres do_something return 0 or using___cxa_atexit The GNU C Library 34 253 extern C void _ libc freeres void extern WOW ow ric
210. ensions may affect the portability of code to other implementations of the C standard library and is therefore somewhat hazardous For this reason the libstdc debug mode offers a pedantic mode similar to GCC s pedantic compiler flag that attempts to emulate the semantics guaranteed by the C standard For instance constructing a std basic_string with a NULL character pointer would result in an exception under normal mode or non pedantic debug mode this is a libstdc extension whereas under pedantic debug mode libstdc would signal an error To enable the pedantic debug mode compile your program The GNU C Library 100 253 with both D_GLIBCXX_DEBUG and D_GLIBCXX_DEBUG_PEDANTIC N B In GCC 3 4 x and 4 0 0 due to a bug D _GLIBXX_DEBUG_PEDANTIC was also needed The problem has been fixed in GCC 4 0 1 and later versions The following library components provide extra debugging capabilities in debug mode e std basic_string no safe iterators and see note below e std bitset e std deque eistdisslist e std map e std multimap e std multiset e std set std vector e std unordered_map e std unordered_multimap e std unordered_set e std unordered_multiset N B although there are precondition checks for some string operations e g operator they will not always be run when using the char and wchar_t specialisations std string and std w
211. ent The standard library may use some of these functions to implement parts of the ISO C standard or depend on them for extensions The GNU C Library 32 253 Of note nanosleep read write open close and wait The parts of libstdc that use C library functions marked as cancellation points should take pains to be exception neutral Failing this catch blocks have been augmented to show that the POSIX cancellation object is in flight This augmentation adds a catch block for__cxxabivl __forced_unwind which is the object representing the POSIX cancellation object Like so catch const __cxxabivl __forced_unwind amp this gt _M_setstate ios_base badbit throw y Caren eao this gt _M_setstate ios_base badbit 3 7 5 Bibliography 1 uri System Interface Definitions Issue 7 IEEE Std 1003 1 2008 2 9 5 Thread Cancellation Copyright 2008 The Open Group The Institute of Electrical and Electronics Engineers Inc 2 David Abrahams uri Error and Exception Handling Boost 3 David Abrahams uri Exception Safety in Generic Components Boost 4 Matt Austern uri Standard Library Exception Policy WG21 N1077 5 Richard Henderson uri ia64 c abi exception handling GNU 6 Bjarne Stroustrup uri Appendix E Standard Library Exception Safety 7 Herb Sutter Exceptional C Exception Safety Issues and Techniques 8 uri GCC Bug 25191 exception_defines h defines try cat
212. ere are two drawbacks to this approach One it s very verbose relying on macro renaming at compile time and several levels of include ordering Two ODR issues remained with container member functions taking no arguments in mixed mode settings resulting in equivalent link names vector push_back being one example See link name Other options may exist for implementing the debug mode many of which have probably been considered and others that may still be lurking This list may be expanded over time to include other options that we could have implemented but in all cases the full ramifications of the approach as measured against the design goals for a libstdc debug mode should be considered first The DejaGNU testsuite includes some testcases that check for known problems with some solutions e g the using declaration solution that breaks user specialization and additional testcases will be added as we are able to identify other typical problem cases These test cases will serve as a benchmark by which we can compare debug mode implementations 17 4 3 Other Implementations There are several existing implementations of debug modes for C standard library implementations although none of them directly supports debugging for programs using libstdc The existing implementations include SafeSTL SafeSTL was the original debugging version of the Standard Template Library STL implemented by Cay S Horstmann on top of the Hewlett Packard
213. erence shared_ptr template assignment and void Add an auto_ptr lt void gt specialization valarray slice default constructor Follow the straightforward proposed resolution What should the return type of pow float int be In C 0x mode remove the pow float int etc signatures string inserter not a formatted function Change it to be a formatted output function i e catch exceptions 27 8 1 3 Table 112 omits a and a b modes Add the missing modes to fopen_mode arrays of valarray Implement the simple resolution Missing bitwise operations Add the missing operations const_local_iterator cbegin cend missing from TRI Tn C 0x mode add cbegin size_type and cend size_type to the unordered containers std bitset all missing Add it consistently with the discussion ctype lt char gt classic_table not accessible Make the member functions table and classic table public istream operator gt gt int amp broken Implement the straightforward resolution The GNU C Library 761 FIS 776 781 809 844 853 865 13 253 unordered_map needs an at member function In C 0x mode add at and at const Tuple indexing should be unsigned Implement the int gt size_t replacements Undescribed assign function of std array Tn C 0x mode remove assign add fill std complex should add missing C99 functions In C 0x mode add std proj std swap should be overloaded for array types Add the overload comple
214. eric_limits 182 12 numeric_limits Y members 18 2 1 3 float_round_style Y 18 2 1 4 float_denorm_style Y 18 2 1 5 Reb tier pass Y specializations 18 2 2 C Library Y 18 3 Start and termination Y 18 4 Dynamic memory Y management 18 5 Type identification 18 5 1 Class type_info Y 18 5 2 Class bad_cast Y 18 5 3 Class bad_typeid Y 18 6 Exception handling 18 6 1 Class exception Y 18 6 2 L a Y exception specifications 18 6 3 Abnormal termination Y 18 6 4 uncaught_exception Y 18 7 Other runtime support Y 19 Diagnostics 19 1 Exception classes Y 19 2 Assertions Y 19 3 Error numbers Y 20 General utilities 20 1 Requirements Y 20 2 Utility components 20 2 1 Operators Y 20 2 2 pair Y 20 3 Function objects 20 3 1 Base Y 20 3 2 Arithmetic operation Y 20 3 3 Comparisons Y 20 3 4 Logical operations Y 20 3 5 Negators Y 20 3 6 Binders Y 203 7 Adaptors for pointers to Y functions 20 3 8 Adaptors for pointers to Y members 20 4 Memory 20 4 1 The default allocator Y 20 4 2 Raw storage iterator Y 20 4 3 Temporary buffers Y 20 4 4 Specialized algorithms Y 20 4 4 1 uninitialized_copy Y 20 4 4 2 uninitialized_fill Y 204 43 uninitialized_fil Y Ln 20 4 5 Class template auto_ptr Y 20 4 6 C library Y 21 Strings 21 1 Character traits 21 1 1 Character traits Y requirements The GNU C Library 4 253 20 1 5 5 Implementors are encouraged to supply libraries that can accept allocators that encap
215. ers but they are implemented in libstdc as separate classes Keeping that simple fact in mind as you design your code will prevent a whole lot of difficult to understand bugs You can think of it the other way round even Since iterators are a generalization that means that pointers are iterators and that pointers can be used whenever an iterator would be All those functions in the Algorithms sect of the Standard will work just as well on plain arrays and their pointers That doesn t mean that when you pass in a pointer it gets wrapped into some special delegating iterator to pointer class with a layer of overhead If you think that s the case anywhere you don t understand templates to begin with Oh no if you pass in a pointer then the compiler will instantiate that template using T as a type and good old high speed pointer arithmetic as its operations so the resulting code will be doing exactly the same things as it would be doing if you had hand coded it yourself for the 273rd time How much overhead is there when using an iterator class Very little Most of the layering classes contain nothing but typedefs and typedefs are meta information that simply tell the compiler some nicknames they don t create code That information gets passed down through inheritance so while the compiler has to do work looking up all the names your runtime code does not This has been a prime concern from the beginning 10 1 2 One
216. ers need checking debugging containers are available as GNU extensions These debugging containers are functionally equivalent to the standard drop in containers used in debug mode but they are available in a separate namespace as GNU extensions and may be used in programs compiled with either release mode or with debug mode The following table provides the names and headers of the debugging containers In addition when compiling in C 0x mode these additional containers have additional debug capability The GNU C Library 101 253 Container Header Debug container Debug header std bitset bitset IIA bitset std deque deque __gnu_debug deque deque std list list __gnu_debug list list std map map __gnu_debug map map std multima ma gnu debug anaes ma SENN P p imap p std multiset set 9nu_debug mult set iset std set set __gnu_debug set set l __gnu_debug stri std string string a string __gnu_debug wstr std wstring string S string ing std basic_string string gnu_debug basi string c_string std vector vector m vector Table 17 1 Debugging Containers Container Header Debug container Debug header std unordered_map unordered_map _gnu_debug unor dered_map unordered_map LD td unordered_mu H timap unordered_map gnu_debug unor dered_multimap unordered_map std unordered_
217. es bundle them up in a mail message and send it to libstde gcc gnu org All patches and related discussion should be sent to the libstdc mailing list A 2 Directory Layout and Source Conventions The unpacked source directory of libstdc contains the files needed to create the GNU C Library It has subdirectories doc Files in HTML and text format that document usage quirks of the implementation and contributor checklists include All header files for the C library are within this directory modulo specific runtime related files that are in the libsupc directory include std Files meant to be found by include lt name gt directives in standard conforming user programs include c Headers intended to directly include standard C headers NB this can be enabled via nable cheaders c include c_global Headers intended to include standard C headers in the global namespace and put select names into the std namespace NB this is the default and is the same as nable cheaders c_global include c_std The GNU C Library 157 253 Headers intended to include standard C headers already in namespace std and put select names into the std namespace NB this is the same as nable cheaders c_std include bits Files included by standard headers and by other files in the bits directory include backward Headers provided for backward compatibility such as lt iostream h gt They
218. es to direct optimizations of standard functions The SGI compiler has been extended to generate specializations of this template automatically for user types so that use of STL templates on user types Can take advantage of these optimizations Specializations for other non STL types would make more optimizations possible but extending the gcc compiler in the same way would be much better Probably the next round of standardization will ratify this but probably with changes so it probably should be renamed to place it in the implementation namespace The SGI STL also defines a large number of extensions visible in standard headers Other extensions that appear in separate headers have been sequestered in subdirectories ext and backward All t a 1 hese extensions should be moved to other headers where possible nd in any case wrapped in a namespace not std and where kept n a standard header girded about with macro guards Some cannot be moved out of standard headers because they are used to implement standard features The canonical method for accommodating these is to use a protected name aliased in macro guards to a user space name Unfortunately C offers no satisfactory template typedef mechanism so very ad hoc and unsatisfactory aliasing must be used instead The GNU C Library 181 253 Implementation of a template typedef mechanism should have the highest priorit
219. es of licensors or authors of the material or e Declining to grant rights under trademark law for use of some trade names trademarks or service marks or f Requiring indemnification of licensors and authors of that material by anyone who conveys the material or modified versions of it with contractual assumptions of liability to the recipient for any liability that these contractual assumptions directly impose on those licensors and authors All other non permissive additional terms are considered further restrictions within the meaning of section 10 If the Program as you received it or any part of it contains a notice stating that it is governed by this License along with a term that is a further restriction you may remove that term If a license document contains a further restriction but permits relicensing or conveying under this License you may add to a covered work material governed by the terms of that license document provided that the further restriction does not survive such relicensing or conveying If you add terms to a covered work in accord with this section you must place in the relevant source files a statement of the additional terms that apply to those files or a notice indicating where to find the applicable terms Additional terms permissive or non permissive may be stated in the form of a separately written license or stated as exceptions the above requirements apply either way The GNU C Library 2
220. es of unordered_set that can be substituted with vector to reduce execution time e Fundamentals Hashtable iterator is slower than vector iterator e Sample runtime reduction 95 e Recommendation Replace unordered_set with vector at site S e To instrument unordered_set operations and access methods e Analysis For each dynamic instance of unordered_set record call context of the constructor Issue the advice only if the number of find insert and operations on this unordered_set are small relative to the number of elements and methods begin or end are invoked suggesting iteration s Cost model Number of e Example 1 unordered_set lt int gt us TADOS S107 for unordered_set lt int gt iterator it us begin it us end it s it foo cc 1 advice Changing unordered_set to vector will save about N indirections and may achieve better data locality 19 7 2 8 Vector to List e Switch _GLIBCXX_PROFILE_VECTOR_TO_LIST e Goal Detect cases where vector could be substituted with 1ist for better performance e Fundamentals Inserting in the middle of a vector is expensive compared to inserting in a list e Sample runtime reduction factor up to container size e Recommendation Replace vector with list at site S e To instrument vector operations and access methods e Analysis For each dynamic instance of vector record the call context of the constructor Record the overhead of each insert o
221. et debugging containers Thus this solution fails the correctness criteria s Define debug containers in another namespace and employ a using declaration or directive This is an enticing option because it would eliminate the need for the 1 ink_name extension by aliasing the templates However there is no true template aliasing mechanism in C because both using directives and using declarations disallow specialization This method fails the correctness criteria e Use implementation specific properties of anonymous namespaces See this post This method fails the correctness criteria The GNU C Library 107 253 e Extension allow reopening on namespaces This would allow the debug mode to effectively alias the namespace std to an internal namespace such as ___ gnu_std_debug so that it is completely separate from the release mode std namespace While this will solve some renaming problems and ensure that debug and release compiled code cannot be mixed unsafely it ensures that debug and release compiled code cannot be mixed at all For instance the program would have two std cout objects This solution would fails the minimize recompilation requirement because we would only be able to support option 1 or 2 e Extension use link name This option involves complicated re naming between debug mode and release mode components at compile time and then a g extension called link name to recover the original names at link time Th
222. et ee code vette ty kei R R Ue ened tay ao Ste aa te deni ey So ee 8 2 3 2 DESIR a4 ace SES RA RE ERR Bee SEES BRE Ree Pewee as 8 2 3 3 Implementation 0 R RR R RRR E RE ee 82331 Models TTT 8 23 32 The GNU Model 32 22 24 cee added seer a dedbe eh 9204 MUSE ane hay bee a oe A ek ok we ee en ee OE ce Hoe ee a 8 23 93 FULUTE i ss aaea 414 4 te OY HY Se Sea Gb Rae SH Ge Eww eee et 2 8 23 60 Bibliography coss e o Soe ee eee See bie eee See SS EROS e oS 9 Containers 9 T Sequences 3 5 2484 ba Dee SA a A ES OA A ge es Ate Ge een eee Reet eee 91 11 listsize is O n yaa e a ea ew RR Ee Ree EE See ba ewe eee he Gs OZ VECINA ae we Ee eee R Oe ey Ge 9 1 2 1 Space Overhead Management 2 0 0 0 000000000000 OD ASSOCIALIVES slats amp AE es a BR ee E EA aoe E Re ee BER es ee 9 92 1 Insertion Hints lt lt arias a gE a A RS A AGS a Re So amp Gh aL Se we O22 BISEN e oci we eto tae PGA ORES EEA OES A eae ews bebe ew eee 8 9 2 2 1 Size Varlable oca a we eK we se e Se eA e a 92 22 Typ Sting ses datet Se Pee BUR oe CRA EE Ree Ea bea ee 9 3 Interacts WIDE ce gk R R RR EER REE REE Rae RRR ae GR wep ce E 9 3 1 Containers VS ArrayS lt cce ne ee ee be ee ea eae wee 10 Iterators 10 51 Predefined 3 5 5 age a Se GP ALG de GOS A a ae A E e E io A ae a Gale ee 10 1 1 Iterators vs Pointers ee 10 12 One Past the Edd sio Af e Sg he a eke we Beale Sb RO Se Se aa 11 Algorithms 11 1 Mutatin
223. ete d as the stack is unwound past func Changing that code as follows is not AP friendly APMC ap new MyClass 22 You will get the same problems as you would without the use of AP charx array new char 10 Pf array ENT oc delete array IT SOME single oby ect delet AP cannot tell whether the pointer you ve passed at creation points to one or many things If it points to many things you are about to die AP is trivial to write however so you could write your own auto_array_ ptr for that situation in fact this has been done many times check the mailing lists Usenet Boost etc 6 3 2 2 Use in Containers All of the containers described in the standard library require their contained types to have among other things a copy constructor like this Struct My type My_Type My_Type const amp y Note the const keyword the object being copied shouldn t change The template class auto_ptr called AP here does not meet this requirement Creating a new AP by copying an existing one transfers ownership of the pointed to object which means that the AP being copied must change which in turn means that the copy ctors of AP do not take const objects The resulting rule is simple Never ever use a container of auto_ptr objects The standard says that undefined behavior is the result but it is guaranteed to be messy To prevent you from doing this to yourself the concept checks built in to this implementa
224. evel constructs for playing with threads In contrast to the atomics layer the concurrence layer consists largely of types All types are defined within namespace __gnu_cxx These types can be used in a portable manner regardless of the specific environment They are carefully designed to provide optimum efficiency and speed abstracting out underlying thread calls and accesses when compiling for single threaded situations even on hosts that support multiple threads The enumerated type _Lock_pol i cy details the set of available locking policies _S_single _S_mutex and _S_atom ic e _S_single Indicates single threaded code that does not need locking e __S_mutex Indicates multi threaded code using thread layer abstractions e _S_ atomic Indicates multi threaded code using atomic operations The compile time constant __default_lock_policy is set to one of the three values above depending on characteristics of the host environment and the current compilation flags Two more datatypes make up the rest of the interface __ mutex and__ scoped_lock The scoped lock idiom is well discussed within the C community This version takes a__ mut ex reference and locks it during construction of __scoped_locke and unlocks it during destruction This is an efficient way of locking critical sections while retaining exception safety 28 1 2 Interface to Atomic Functions Two functions and one type form the base of atomic support The type _A
225. example basic _iostream lt T gt traits_type is ambiguous Wrong type in num_get get overloads Similar to 118 Comparison of reverse_iterator to const reverse_iterator Add global functions with two template parameters NB not added for now a templated assignment operator Effects of a copyfmt a If this rhs do nothing List merge specification incomplete If this amp x do nothing Bitset input operator underspecified Basically compare the input character to is widen 0 and is widen 1 Default behavior of codecvt lt wchar_t char mbstate_t gt length Do not specify what codecvt lt wchar_t char mbstate_t gt do_length must return The GNU C Library 328 365 387 389 396 402 408 409 431 432 434 438 453 455 464 508 512 526 538 539 541 543 550 586 596 630 660 691 693 695 696 12 253 Bad sprintf format modifier in money_put lt gt do_put Change the format string to OLf Lack of const qualification in clause 27 Add const overloads of is_open std complex over encapsulated Add the real T and imag T members in C 0x mode also adjust the existing real and imag members and free functions Const overload of valarray operator returns by value Change it to return a const T what are characters zero and one Implement the proposed resolution Wrong new expression in some_Jallocator construct Replace new with ne
226. f a storage or distribution medium is called an aggregate 1f the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation s users beyond what the individual works permit Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate 6 Conveying Non Source Forms You may convey a covered work in object code form under the terms of sections 4 and 5 provided that you also convey the machine readable Corresponding Source under the terms of this License in one of these ways a Convey the object code in or embodied in a physical product including a physical distribution medium accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange b Convey the object code in or embodied in a physical product including a physical distribution medium accompanied by a written offer valid for at least three years and valid for as long as you offer spare parts or customer support for that product model to give anyone who possesses the object code either 1 a copy of the Corresponding Source for all the software in the product that is covered by this License on a durable physical medium customarily used for software interchange for a price no more than your reasonable cost of physically performing this conveying of source or 2 access to copy the Corresponding Source from a network ser
227. f the libstdc debug mode Here s an example of what this ends up looking like in C namespace std template lt typename _Tp typename _Alloc allocator lt _Tp gt gt class list namespace std The GNU C Library 105 253 In debug mode we include the release mode container which is now defined in the namespace __norm and also the debug mode container The debug mode container is defined within the namespace __ debug which is associated with namespace std via the C 0x namespace association language feature This method allows the debug and release versions of the same component to coexist at compile time and link time without causing an unreasonable maintenance burden while minimizing confusion Again this boils down to C code as follows namespace std namespace __norm template lt typename _Tp typename _Alloc allocator lt _Tp gt gt ISS Gist IE hee y namespace __gnu_norm namespace _ debug template lt typename _Tp typename _Alloc allocator lt _Tp gt gt class list Stole O ans E Ao gt public __gnu_debug _Safe_sequence lt list lt _Tp _Alloc gt gt Lele ison y namespace __norm namespace __debug __attribute__ strong inline namespace __debug 17 4 2 3 2 Link and run time coexistence of release and debug mode components Because each component has a distinct and separate release and debug implementation there is no issue w
228. file Diagnostics o oc se e R e RE RR De Aw ka OD ee A ee 121 20 1 Bitmap Allocator Memory Map 2 aaa 137 A 1 HTML to Doxygen Markup Comparison oaoa 169 A 2 HTML to Docbook XML Markup Comparison 172 A 3 Docbook XML Element Use 0 000022 ee 172 B l Extension Allocators lt o opa a 5 peenaa Yee Ee Aa a A A 219 B 2 Extension Allocators Continued 219 The GNU C Library 1 253 Part I Introduction The GNU C Library 2 253 Chapter 1 Status 1 1 Implementation Status 1 1 1 C 1998 2003 1 1 1 1 Implementation Status This status table is based on the table of contents of ISO IEC 14882 2003 This page describes the C support in mainline GCC SVN not in any particular release 1 1 1 2 Implementation Specific Behavior The ISO standard defines the following phrase 1 3 5 implementation defined behavior Behavior for a well formed program construct and cor rect data that depends on the implementation and that each implementation shall document We do so here for the C library only Behavior of the compiler linker runtime loader and other elements of the implemen tation are documented elsewhere Everything listed in Annex B Implementation Qualities are also part of the compiler not the library For each entry we give the section number of the standard when applicable This list is probably incomplet and inkorrekt 1 9 11 3 If isatty 3 is true then interactive stream su
229. file to most effectivel y state the exclusion of warranty and each file should have at least the copyright line and a pointer to where the full notice is found one line to give the program s name and a brief idea of what it does Copyright C year name of author This program is free software you can redistribute it and or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 3 of the License or The GNU C Library 247 253 at your option any later version This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU General Public License for more details You should have received a copy of the GNU General Public License along with this program If not see http www gnu org licenses Also add information on how to contact you by electronic and paper mail If the program does terminal interaction make it output a short notice like this when it starts in an interactive mode program Copyright C year name of author This program comes with ABSOLUTELY NO WARRANTY for details type show w This is free software and you are welcome to redistribute it under certain conditions type show c for details The hypothetical commands show w and show c should show the appropriate part
230. following three paragraphs a patent license is any express agreement or commitment however denominated not to enforce a patent such as an express permission to practice a patent or covenant not to sue for patent infringement To grant such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party If you convey a covered work knowingly relying on a patent license and the Corresponding Source of the work is not available for anyone to copy free of charge and under the terms of this License through a publicly available network server or other readily accessible means then you must either 1 cause the Corresponding Source to be so available or 2 arrange to deprive yourself of the benefit of the patent license for this particular work or 3 arrange in a manner consistent with the requirements of this License to extend the patent license to downstream recipients Knowingly relying means you have actual knowledge that but for the patent license your conveying the covered work in a country or your recipient s use of the covered work in a country would infringe one or more identifiable patents in that country that you have reason to believe are valid If pursuant to or in connection with a single transaction or arrangement you convey or propagate by procuring conveyance of a covered work and grant a patent license to some of the parties receiving the covered work au
231. for an example e Make initial catalog see 4 Making the PO Template File from the gettext docs xgettext c debug string_literals cc o libstdc pot e Make language and country specific locale catalogs cp libstdc pot fr_FR po cp libstdc pot de_DE po e Edit localized catalogs in emacs so that strings are translated emacs fr_FR po e Make the binary mo files msgfmt fr_FR po o fr_FR mo T msgfmt de_DE po o de_DE mo e Copy the binary files into the correct directory structure cp fr_FR mo dir fr_FR LC_MESSAGES libstdc mo cp de_DE mo dir de_DE LC_MESSAGES libstdc mo e Use the new message catalogs locale loc_de de_DE use_facet lt messages lt char gt gt loc_de open libstdc locale dir 8 2 3 4 Use A simple example using the GNU model of message conversion include lt iostream gt include lt locale gt using namespace std void test01 typedef messages lt char gt catalog catalog The GNU C Library 75 253 const charx dir mnt egcs build i686 pc linux gnu libstdct po share locale const locale Wockde denbE const messages lt char gt amp mssg_de use_facet lt messages lt char gt gt loc_de catalog cat_de mssg_de open libstdc loc_de dir string s01l mssg_de get cat_de 0 0 please string s02 mssg_de get cat_de 0 0 thank you cout l
232. for symbols that were introduced in the gcc 3 2 0 release If a particular release is not listed it has the same version labels as the preceding release gcc 3 0 0 Error not versioned gcc 3 0 1 Error not versioned gcc 3 0 2 Error not versioned gcc 3 0 3 Error not versioned gcc 3 0 4 Error not versioned gcc 3 1 0 GLIBCPP_3 1 CXXABI_1 gcc 3 1 1 GLIBCPP_3 1 CXXABI_1 gcc 3 2 0 GLIBCPP_3 2 CXXABI_1 2 gcc 3 2 1 GLIBCPP_3 2 1 CXXABI_1 2 gcc 3 2 2 GLIBCPP_3 2 2 CXXABI_1 2 gcc 3 2 3 GLIBCPP_3 2 2 CKXABI_1 2 gcc 3 3 0 GLIBCPP_3 2 2 CXXABI_1 2 1 gcc 3 3 1 GLIBCPP_3 2 3 CXXABI_1 2 1 gcc 3 3 2 GLIBCPP_3 2 3 CXXABI_1 2 1 gcc 3 3 3 GLIBCPP_3 2 3 CXXABI_1 2 1 gcc 3 4 0 GLIBCXX_3 4 CXXABI_1 3 gcc 3 4 1 GLIBCXX_3 4 1 CXXABI_1 3 gcc 3 4 2 GLIBCXX_3 4 2 gcc 3 4 3 GLIBCXX_3 4 3 gcc 4 0 0 GLIBCXX_3 4 4 CXXABI_1 3 1 gcc 4 0 1 GLIBCXX_3 4 5 gcc 4 0 2 GLIBCXX_3 4 6 gcc 4 0 3 GLIBCXX_3 4 7 gcc 4 1 1 GLIBCXX_3 4 8 gcc 4 2 0 GLIBCXX_3 4 9 gcc 4 3 0 GLIBCXX_3 4 10 CKXABI_1 3 2 gcc 4 4 0 GLIBCXX_3 4 11 CXXABI_1 3 3 gcc 4 4 1 GLIBCXX_3 4 12 CKXABI_1 3 3 gec 4 4 2 GLIBCXX_3 4 13 CKXABI_1 3 3 gcc 4 5 0 GLIBCXX_3 4 14 CKXABI_1 3 4 5 Incremental bumping of a compiler pre defined macro _GXX_ABI_VERSION This macro is defined as the version of the compiler v3 ABI with g 3 0 x being version 100 This macro will be automatically defined whenever g is used the curious can test this by invok
233. g 11 1 1 swap 11 1 1 1 Specializations viii 68 69 69 70 71 71 72 T2 172 FES T3 73 74 74 T3 75 qe FS TI 77 T a 78 78 78 78 79 80 80 82 82 82 82 The GNU C Library ix 12 Numerics 85 12 1 Complexes R kw he ew a ek a ee ye a eS ee ee wa ee ee oo 85 12 1 1 complex Processg corps cocos tas o ER ERG Bae Swe Ad e 85 12 2 Generalized Operations poe ee ee RR EY ERR ERE ORES ERE Ee a Le RE Ee 85 12 3 Interacting with gt o e ee Re A Ee ee eR a a i 86 12 3 1 Numerics YS TTAYS ke RR e ee ee eo 86 E OOD ccc eee a eb ee Se Roe et ee ES eae ona a Se bse ee ne eevee e 86 13 Input and Output 87 13 1 Tostreant ODJEC S is ee a a SE ER Oa we eS RR eS ee ES oe 87 13 2 Stream Buffers sec e perne seid e ae Oe Ee EEA Eee HERA ee ee GA ee ae ee 88 13 2 1 Derived streambuf Classes lt e ss ee 88 13 22 Buffering ype 6 shades e oR eee ee Bw eee EY Bee cee as GP eS 89 13 3 Memory Based Streams o ces e ee 90 13 3 1 Compatibility With strstream 2 2 ee 90 13 4 File Based Streams o eo cc feb pe Sek A ERE eRe EERE ee ee SG RE bos 91 13 4 1 Copying ar File ocios o Oe eA eA ee ee ea ba A A R R e 91 13 4 2 Binary Input and Output 2 2 2 2 ee 91 13 5 Interacting with Cisco gr k e Re RA OE EG De ew AS Ge ke e 92 13 5 1 Using FILE and file descriptors a 92 13 32 Performance e rt REA AA UA Bw oe Eo E be 93 14 Atomics 94 14 1 API Reference ose
234. g HP SGI hash containers AC HEADER _EXT_HASH MAP AC_DEFUN AC_HEADER_EXT_HASH MAP AC_CACHE_CHECK for ext hash_map ac_cv_cxx_ext_hash_map AC_LANG_SAV AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS CXXFLAGS S CXXFLAGS Werror AC_TRY_COMPILE include lt ext hash_map gt using __gnu_cxx hash_map ac_cv_cxx_ext_hash_map yes ac_cv_cxx_ext_hash_map no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE 19 if test Sac_cv_cxx_ext_hash_map yes then AC_DEFINE HAVE_EXT_HASH_MAP Define if ext hash_map is present Pak 1 Hct AC _HEADER_EXT_HASH_ SET AC_DEFUN AC_HEADER_EXT_HASH_ SET AC_CACHE_CHECK for ext hash_set ac_cv_cxx_ext_hash_set AC_LANG_SAV AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS CXXFLAGS S CXXFLAGS Werror AC_TRY_COMPILE include lt ext hash_set gt using __gnu_cxx hash_set Ha ct The GNU C Library 230 253 ac_cv_cxx_ext_hash_set yes ac_cv_cxx_ext_hash_set no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE lp if test Sac_cv_cxx_ext_hash_set yes then AC_DEFINE HAVE_EXT_HASH_SET Define if ext hash_set is present Ed B 6 3 3 Noios nocreate ios noreplace The existence of ios nocreate being used for input streams has been confirmed most pro
235. g auto_ptr parameters are deprecated in C 0x mode The Thread Safety section of the Boost shared_ptr documentation says shared_ptr objects offer the same level of thread safety as built in types The implementation must ensure that concurrent updates to separate shared_ptr instances are correct even when those instances share a reference count e g shared_ptr lt A gt a new A shared_ptr lt A gt b a Thread 1 Thread 2 a reset b reset The dynamically allocated object must be destroyed by exactly one of the threads Weak references make things even more interesting The shared state used to implement shared_ptr must be transparent to the user and invariants must be preserved at all times The key pieces of shared state are the strong and weak reference counts Updates to these need to be atomic and visible to all threads to ensure correct cleanup of the managed resource which is after all shared_ptr s job On multi processor systems memory synchronisation may be needed so that reference count updates and the destruction of the managed resource are race free The function _Sp_counted_base _M add_ref_lock called when obtaining a shared_ptr from a weak_ptr has to test if the managed resource still exists and either increment the reference count or throw bad_weak_pt r In a multi threaded program there is a potential race condition if the last reference is dropped and the managed resource destroyed between testing the refere
236. g mangling on an exported symbol Deleting an exported symbol YN DA Un HE Ww Changing the inheritance properties of a type by adding or removing base classes 8 Changing the size alignment or layout of types specified in the C standard These may not necessarily be in stantiated or otherwise exported in the library binary and include all the required locale facets as well as things like std basic_streambuf et al 9 Adding an explicit copy constructor or destructor to a class that would otherwise have implicit versions This will change the way the compiler deals with this class in by value return statements or parameters instead of being passing instances of this class in registers the compiler will be forced to use memory See this part of the C ABI documentation for further details B 4 5 Implementation 1 Separation of interface and implementation This is accomplished by two techniques that separate the API from the ABI forcing undefined references to link against a library binary for definitions Include files have declarations source files have defines For non templatized types such as much of class local e the appropriate standard C include say locale can contain full declarations while various source files say locale cc locale_init cc localename cc contain definitions The GNU C Library 215 253 Extern template on required types For parts of the standard that have an explicit list of require
237. gain see the link under Structure We do no locking ourselves but simply pass through to calls to fopen fwrite and so forth So for 3 0 the question of is multithreading safe for I O must be answered with is your platform s C library threadsafe for 1 0 Some are by default some are not many offer multiple implementations of the C library with varying tradeoffs of threadsafety and efficiency You the programmer are always required to take care with multiple threads As an example the POSIX standard requires that C stdio FILE operations are atomic POSIX conforming C libraries e g on Solaris and GNU Linux have an internal mutex to serialize operations on FILE s However you still need to not do stupid things like calling fclose fs in one thread followed by an access of fs in another So if your platform s C library is threadsafe then your fst ream I O operations will be threadsafe at the lowest level For higher level operations such as manipulating the data contained in the stream formatting classes e g setting up callbacks inside an std ofstream you need to guard such accesses like any other critical shared resource 3 6 4 3 Future A second choice may be available for I O implementations libio This is disabled by default and in fact will not currently work due to other issues It will be revisited however The libio code is a subset of the guts of the GNU libc glibc I O implementation When libio is in us
238. gain are entirely generic const charx ctype lt char gt scan_is mask __m const charx __low const charx __high const throw while low lt high ss this gt is _ im m L oer TE return __low The GNU C Library 196 253 CONSTE Ote ctype lt char gt scan_not mask m const ehar __low const charx __high const throw while __low lt __high amp amp this gt is __m __low low return _ low B 2 4 Thread Safety The C library string functionality requires a couple of atomic operations to provide thread safety If you don t take any special action the library will use stub versions of these functions that are not thread safe They will work fine unless your applications are multi threaded If you want to provide custom safe versions of these functions there are two distinct approaches One is to provide a version for your CPU using assembly language constructs The other is to use the thread safety primitives in your operating system In either case you make a file called atomicity h and the variable ATOMICITYH must point to this file If you are using the assembly language approach put this code in config cpu lt chip gt atomicity h where chip is the name of your processor see CPU No additional changes are necessary to locate the file in this case ATOMICITYH will be set by default If you are using the operating system thread safety primitives approach you can also put thi
239. ging this complexity easier The following techniques are used The GNU C Library 1 Release versioning on the libgcc_s so binary This is implemented via file names and the ELF DT_SONAM follows gcec 3 0 0 gcec 3 0 1 gec 3 0 2 gec 3 0 3 gcec 3 0 4 gcc 3 1 0 gcc 3 1 1 gcec 3 2 0 gcec 3 2 1 gcec 3 2 2 gcec 3 2 3 gcec 3 3 0 gec 3 3 1 gec 3 3 2 gec 3 3 3 libgcc_s so 1 libgec_s so 1 libgcc_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgcc_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 libgec_s so 1 207 253 E mechanism at least on ELF systems It is versioned as gcc 3 4 x gcc 4 0 5 x on m68k linux and hppa linux this is either libgec_s so 1 when configuring with s313 exceptions or libgcc_s so 2 For all others this is libgcec_s so 1 2 Symbol versioning on the libgec_s so binary It is versioned with the following labels and version definitions where the version definition is the maximum for a particular release Labels are cumulative If a particular release is not listed it has the same version labels as the preceding release This corresponds to the mapfile gcc libgce std ver gec 3 0 0 gec 3 3 0 gec 3 3 1 gec 3 3 2 gcec 3 3 4 gec 3 4 0 gcc 3 4 2 gcc 3 4 4 gec 4 0 0 gcec 4 1 0 gcec 4 2 0 gcec 4 3 0 gcec 4 4 0 GCC_3 0 GCC_3 3 GCC_3 3 1 GCC_3 3 2 GCC_3 3 4 GCC_3 4
240. hat you expect This is why g has a magic extension so that NULL is always a pointer The GNU C Library 39 253 In his book Effective C Scott Meyers points out that the best way to solve this problem is to not overload on pointer vs integer types to begin with He also offers a way to make your own magic NULL that will match pointers before it matches integers See the Effective C CD example 4 2 Dynamic Memory There are six flavors each of new and delete so make certain that you re using the right ones Here are quickie descriptions of new e single object form throwing a bad_alloc on errors this is what most people are used to using e Single object nothrow form returning NULL on errors e Array new throwing bad_alloc on errors e Array nothrow new returning NULL on errors e Placement new which does nothing like it s supposed to e Placement array new which also does nothing They are distinguished by the parameters that you pass to them like any other overloaded function The six flavors of delete are distinguished the same way but none of them are allowed to throw an exception under any circumstances anyhow They match up for completeness sake Remember that it is perfectly okay to call delete on a NULL pointer Nothing happens by definition That is not the same thing as deleting a pointer twice By default if one of the throwing news can t allocate the memory requested it tosses an insta
241. he address of the new A object embedded in the _Sp_count ed_ptr_inplace but it has no way to access it This implementation uses a covert channel to return the address of the embedded object when get_deleter lt _Sp_make_shared_tag gt is called Users should not try to use this As well as the extra constructors this implementation also needs some members of _Sp_counted_deleter to be protected where they could otherwise be private 6 3 3 4 Use 6 3 3 4 1 Examples Examples of use can be found in the testsuite under test suite tr1 2_general_utilities shared_ptr 6 3 3 4 2 Unresolved Issues The resolution to C Standard Library issue 674 shared_ptr interface changes for consistency with N1856 will need to be implemented after it is accepted into the working paper Issue 743 might also require changes The _S_single policy uses atomics when used in MT code because it uses the same dispatcher functions that check ___ gt hre ad_active_p This could be addressed by providing template specialisations for some members of _Sp_counted_ba se lt _S_single gt Unlike Boost this implementation does not use separate classes for the pointer deleter and pointer deleter allocator cases in C 0x mode combining both into _Sp_counted_deleter and using al locator when the user doesn t specify an allocator If it was found to be beneficial an additional class could easily be added With the current implementation the _Sp_counted_deleter and __sh
242. he compiler seems capable of passing the simple sanity checks thrown at it adjusts items in namespace std namespace std trl and namespace __gnu_cxx so that fvisibility options work enable libstdcxx pch In 3 4 and later tries to turn on the generation of stdc h gch a pre compiled file including all the standard C includes If enabled as by default and the compiler seems capable of passing the simple sanity checks thrown at it try to build stdc h gch as part of the make process In addition this generated file is used later on by appending include bits stdc h to CXXFLAGS when running the testsuite disable hosted libstdcxx By default a complete hosted C library is built The C Standard also describes a freestanding environment in which only a minimal set of headers are provided This option builds such an environment The GNU C Library 18 253 enable clock gettime This is an abbreviated form of nable clock gettime yes described next enable libstdcxx time OPTION Enables link type checks for the availability of the clock_gettime clocks used in the implementation of time clock and of the nanosleep and sched_yield functions used in the implementation of thread thread this of the current C 0x draft The choice OPTION yes checks for the availability of the facilities in libc and libposix4 In case of need the latter is also linked to libstdc as part of the build process OPTION rt also searche
243. heck the related set of function decla rations found in system headers against versions found in the library headers derived from the standard _GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC may be defined to an expression that yields 0 if and only if the system headers are exposing proper support for the related set of functions If defined it must be 0 while bootstrapping the compiler rebuilding the library Finally you should bracket the entire file in an include guard like this ifndef _GLIBCXX_OS_DEFINES define _GLIBCXX_OS_DEFINES endif We recommend copying an existing os_defines h to use as a starting point B 2 2 CPU If you are porting to a new chip as opposed to a new operating system running on an existing chip you will need to create a new directory in the config cpu hierarchy Much like the Operating system setup there are no strict rules on how to organize the CPU configuration directory but careful naming choices will allow the configury to find your setup files without explicit help We recommend that for a target triplet lt CPU gt lt vendor gt lt 0S gt you name your configuration directory config cpu lt CPU gt If you do this the configury will find the directory by itself Otherwise you will need to edit the configure host file and in the switch statement that sets cou_include_dir add a pattern to handle your chip Note that some chip families
244. his is guaranteed by the standard Like any other global object they must be initialized once and only once This is typically done with a construct like the one above and the nested class ios_base Init is specified in the standard for just this reason How does it work Because the header is included before any of your code the __foo object is constructed before any of your objects Global objects are built in the order in which they are declared and destroyed in reverse order The first time the constructor runs the eight stream objects are set up The static keyword means that each object file compiled from a source file containing lt iostream gt will have its own private copy of __foo There is no specified order of construction across object files it s one of those pesky NP problems that make life so interesting so one copy in each object file means that the stream objects are guaranteed to be set up before any of your code which uses them could run thereby meeting the requirements of the standard The penalty of course is that after the first copy of __foo is constructed all the others are just wasted processor time The time spent is merely for an increment and test inside a function call but over several dozen or hundreds of object files that time can add up It s not in a tight loop either The lesson Only include lt iostream gt when you need to use one of the standard objects in that source file you ll pay less st
245. hms from the STL are mostly done Of course optimization opportunities abound for the numerically literate It is not clear whether the valarray implementation really conforms fully in the assumptions it makes about aliasing and lack thereof in its arguments The C div and ldiv functions are interesting because they are th only case where a C library function returns a class object by value Since the C type div_t must be different from the underlying C type which is in the wrong namespace the underlying functions div and ldiv cannot be re used efficiently Fortunately they are trivial to re implement Chapter 27 Iostreams Headers lt iosfwd gt lt streambuf gt lt ios gt lt ostream gt lt istream gt lt iostream gt lt iomanip gt lt sstream gt lt fstream gt C headers lt cstdio gt lt cwchar gt also in 21 Tostream is currently in a very incomplete state lt iosfwd gt lt iomanip gt los_base and basic_ios lt gt are mostly complete basic_streambuf lt gt and basic_ostream lt gt are well along but basic_istream lt gt has had little work done The standard stream objects lt sstream gt and lt fstream gt have been started basic_filebuf lt gt write functions have been implemented just enough to do hello world Most of the istream and ostream operators lt lt and gt gt with the exception of the op lt lt integer ones have not been changed to use local
246. i arallel algorithm p a 7 artial_sort p raug 2 gnu_parallel p g 9 std partition algorithm eg arallel algorithm p cake artition p Lagoni std random_shuff gnu_parallel r i x 7 algorithm S arallel algorithm le g andom_shuffle P 219 nu_parallel s g gt l std set_union algorithm 3 P parallel algorithm et_union std set_intersec A nu_parallel s E S gt E algorithm gr P parallel algorithm tion et_intersection __gnu_parallel s st set_symmetri ART oe A ibe Eaa a As id eee r d e an PARA e E AA API es A The GNU C Library 112 253 namespace std namespace _ parallel template lt typename _Flter gt MES adjacent_find _Flter _Flter But why the ellipses The ellipses in the example above represent additional overloads required for the parallel version of the function These additional overloads are used to dispatch calls from the ISO C function signature to the appropriate parallel function or sequential function if no parallel functions are deemed worthy based on either compile time or run time conditions The available signature options are specific for the different algorithms algorithm classes The general view of overloads for the parallel algorithms look like this e ISO C signature e ISO C signature sequential_tag argument e ISO C signature algorithm specific tag type several signatures Please note that the implementatio
247. iating test objectis__ gnu_test basic_safety and is detailed in testsuite util exception safety h e Generation Prohibited Exception generation tests For each container an object of that container is constructed and all member functions required to not throw exceptions are exercised Included in these tests are member functions are iterator and const_iterator operations er ase pop_front pop_back swap and clear The container in question is instantiated with two instrumented template arguments with __ gnu_cxx throw_allocator_random as the allocator type and with __ gnu_cxx throw_t ype_random as the value type This test does not loop an instead is sudden death first error fails The general form is demonstrated in test suite 23_containers list requirements exception generation_ prohibited cc The instantiating test objectis__gnu_test generation_prohibited and is detailed in testsuite util exception safety h e Propagation Consistent Container rollback on exception propagation tests For each container an object of that container is constructed a specific member function that requires rollback to a previous known good state is exercised in a try block and then any thrown exceptions lead to error checking in the appropriate catch block The container is compared to the container s last known good state using such parameters as size contents and iterator references Included in these tests are member functions are p
248. ich the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term regardless of how the transaction is characterized the Corresponding Source conveyed under this section must be accompanied by the Installation Information But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product for example the work has been installed in ROM The requirement to provide Installation Information does not include a requirement to continue to provide support service warranty or updates for a work that has been modified or installed by the recipient or for the User Product in which it has been modified or installed Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network Corresponding Source conveyed and Installation Information provided in accord with this section must be in a format that is publicly documented and with an implementation available to the public in source code form and must require no special password or key for unpacking reading or copying 7 Additional Terms Additional permissions are terms that supplement the terms of this License by making exceptions from one or more of its conditions Additional permissions that are applicable to the entire Program shal
249. ike new_allocator that releases memory while debugging use GLIBCXX_FORCE_NEW to bypass the allocator s internal pools or use a custom pool datum that releases resources on destruction On systems with the function __cxa_atexit the allocator can be forced to free all memory allocated before program ter mination with the member function __pool_type _M_destroy However because this member function relies on the The GNU C Library precise and exactly conforming ordering of static destructors including those of a static local __poo1 object it should not be used ever on systems that don t have the necessary underlying support In addition in practice forcing deallocation can be tricky as it requires the __ pool object to be fully constructed before the object that uses it is fully constructed For most but not all STL containers this works as an instance of the allocator is constructed as part of a container s constructor However this assumption is implementation specific and subject to change For an example of a pool that frees memory see the following example 20 1 4 Single Thread Example Let s start by describing how the data on a freelist is laid out in memory This is the first two blocks in freelist for thread id 3 in bin 3 8 bytes With this in mind we simplify things a bit for a while and say that there is only one thread a ST application In this case all operations are made t
250. ike this example taken from the IRIX configuration The GNU C Library 194 253 struct ctype_base typedef unsigned int mask typedef intx HEADS enum space _ISspace print _ISprint cuts IE upper _ISupper lower _ISlower alpha _ISalpha SIRSE EET HERE gt PUNO AS DUNC xdigit _ISxdigit alnum _ISalnum graph _ISgraph he y The mask type is the type of the elements in the table If your C library uses a table to map lower case numbers to upper case numbers and vice versa you should define __to_type to be the type of the elements in that table If you don t mind taking a minor performance penalty or if your library doesn t implement toupper and tolower in this way you can pick any pointer to integer type but you must still define the type The enumeration should give definitions for all the values in the above example using the values from your native lt ctype h gt They can be given symbolically as above or numerically if you prefer You do not have to include lt ct ype h gt in this header it will always be included before ctype_base h is included The next file to write is ct ype_noninline h which also does not require include guards This file defines a few member functions that will be included in include bits locale_facets h The first function that must be written is the cty pe lt char gt ctype constructor Here is the IRIX example ctype lt char gt ctype const
251. iles user code using the profile mode 3 4 Namespaces 3 4 1 Available Namespaces There are three main namespaces e std The ISO C standards specify that all library entities are defined within namespace std This includes namespaces nested within namespace std such as namespace std trl e abi Specified by the C ABI This ABI specifies a number of type and function APIs supplemental to those required by the ISO C Standard but necessary for interoperability e _ gnu Indicating one of several GNU extensions Choices include __gnu_cxx __ gnu_debug nu_pbds gnu_parallel and __g A complete list of implementation namespaces including namespace contents is available in the generated source documenta tion 3 4 2 namespace std One standard requirement is that the library components are defined in namespace std Thus in order to use these types or functions one must do one of two things e put a kind of using declaration in your source either using namespace std ori e using std string This approach works well for individual source files but should not be used in a global context like header files e use a fully qualified name for each library symbol i e std string std cout Always can be used and usually enhanced by strategic use of typedefs In the cases where the qualified verbiage becomes unwieldy 3 4 3 Using Namespace Composition Best practice in programming suggests sequestering new d
252. ill both use the same pool This is the default policy The second policy __per_type_pool_policy implements a separate pool for each instantiating type Thus char and long will use separate pools This allows per type tuning for instance Putting this all together the actual allocator class is The GNU C Library 132 253 template lt typename _Tp typename _Poolp __default_policy gt Glass mi H public mt_alloc_base lt _Tp gt Poolp This class has the interface required for standard library allocator classes namely member functions al locate and deallo cate plus others 20 1 3 Implementation 20 1 3 1 Tunable Parameters Certain allocation parameters can be modified or tuned There exists a nested struct __pool_base _Tune that contains all these parameters which include settings for e Alignment e Maximum bytes before calling operator new directly e Minimum bytes e Size of underlying global allocations e Maximum number of supported threads e Migration of deallocations to the global free list e Shunt for global new and delete Adjusting parameters for a given instance of an allocator can only happen before any allocations take place when the allocator itself is initialized For instance include lt ext mt_allocator h gt struct pod shine 31 LING Jy return 0 int main typedef pod value_type typedef gnu_cxx __mt_alloc lt value_type gt allocator_type t
253. ing While the answer could be both and the difference hidden via renaming a la the debug release containers we must note two things about locale facets 1 They exist as shared state one can create a facet in one translation unit and access the facet via the same type name in a different translation unit This means that we cannot have two different versions of locale facets because the types would not be the same across debug release mode translation unit barriers 2 They have virtual functions returning strings these functions mangle in the same way regardless of the mangling of their return types see above and their precise signatures can be relied upon by users because they may be overridden in derived classes With the design of libstdc debug mode we cannot effectively hide the differences between debug and release mode strings from the user Failure to hide the differences may result in unpredictable behavior and for this reason we have opted to only perform basic_string changes that do not require ABI changes The effect on users is expected to be minimal as there are simple alternatives e g __gnu_debug basic_string and the usability benefit we gain from the ability to mix debug and release compiled translation units is enormous 17 4 2 3 3 Alternatives for Coexistence The coexistence scheme above was chosen over many alternatives including language only solutions and solutions that also required extensions to the C
254. ing g with the v flag This macro was defined in the file lang specs h in the gcc cp directory Later versions defined it in c common c in the gcc directory and from G 3 4 it is defined in c cppbuiltin c and its value determined by the fabi version command line option It is versioned as follows where n is given by fabi version n The GNU C Library 210 253 e gcc 3 0 x 100 e gcc 3 1 x 100 Error should be 101 e gcc 3 2 x 102 e gcc 3 3 x 102 e gcc 3 4 x gcc 4 0 5 x 102 when n 1 e gcc 3 4 x gcc 4 0 5 x 1000 n when n gt 1 e gcc 3 4 x gcc 4 0 5 x 999999 when n 0 6 Changes to the default compiler option for fabi version It is versioned as follows e gcc 3 0 x Error not versioned e gcc 3 1 x Error not versioned e gcc 3 2 x fabi version 1 e gcc 3 3 x fabi version 1 e gcc 3 4 x gcc 4 0 5 x fabi version 2 Incompatible with previous 7 Incremental bumping of a library pre defined macro For releases before 3 4 0 the macro is _ GLIBCPP__ For later releases it s _ GLIBCXX__ The libstdc project generously changed from CPP to CXX throughout its source to allow the C pre processor the CPP macro namespace These macros are defined as the date the library was released in compressed ISO date format as an unsigned long This macro is defined in the file c config in the libstdc include bits directory Up to gcc 4 1 0 i
255. ing mask values are still defined in libio and just included linked We will need to implement these tables independently soon but should take advantage of libio where possible The num_put lt gt put members for integer types are mostly complete A complete list of what has and has not been implemented may be found in CHECKLIST However note that the current definition of codecvt lt wchar_t char mbstate_t gt is wrong It should simply write out the raw bytes representing the wide characters rather than trying to convert each to a corresponding single char value Some of the facets are more important than others Specifically the members of ctype lt gt numpunct lt gt num_put lt gt and num_get lt gt facets are used by other library facilities defined in lt string gt lt istream gt and lt ostream gt and the codecvt lt gt facet is used by basic_filebuf lt gt in lt fstream gt so a conforming iostream implementation depends on these The long long type eventually must be supported but code mentioning it should be wrapped in if guards to allow pedantic mode compiling The GNU C Library Performance of num_put lt gt and num_get lt gt depend critically on caching computed values in ios_base objects and on extensions to the interface with streambufs Specifically the n e g retrieving a copy of the locale object extracti ded fa
256. instantiation say std vector lt int gt compiled in release mode can be linked against a translation unit B that contains the same instantiation compiled in debug mode a feature not present with partial recompilation While this behavior is technically a violation of the One Definition Rule this ability tends to be very important in practice The libstdc debug mode supports this level of recompilation 5 Per unit recompilation The user must only recompile the translation units where checking should occur regardless of where debuggable standard containers are used This has also been dubbed g mode because the g compiler switch works in this way emitting debugging information at a per translation unit granularity We believe that this level of recompilation is in fact not possible if we intend to supply safe iterators leave the program semantics unchanged and not regress in performance under release mode because we cannot associate extra information with an iterator to form a safe iterator without either reserving that space in release mode performance regression or allocating extra memory associated with each iterator with new changes the program semantics The GNU C Library 103 253 17 4 2 Methods This section provides an overall view of the design of the libstdc debug mode and details the relationship between design decisions and the stated design goals 17 4 2 1 The Wrapper Model The libstdc debug mode use
257. ions For example include lt istream gt std ostream amp operator lt lt std ostream amp os MyClass c return os a datald j lt lt a datazi s The GNU C Library 88 253 The std istream and std ostream classes are the abstract parents of the various concrete implementations If you are only using the interfaces then you only need to use the appropriate interface header lt iomanip gt provides extractors and inserters that alter information maintained by class ios_base and its derived classes such as std setprecision and std setw If you need to write expressions like os lt lt setw 3 oris gt gt setbase 8 you must include lt iomanip gt lt sstream gt lt fstream gt declare the six stringstream and fstream classes As they are the standard concrete descendants of istream and ostream you will already know about them Finally lt iostream gt provides the eight standard global objects cin cout etc To do this correctly this header also provides the contents of the lt istream gt and lt ostream gt headers but nothing else The contents of this header look like include lt ostream gt include lt istream gt namespace std extern istream cin extern ostream cout this is explained below state los base imit GOO not its real name Now the runtime penalty mentioned previously the global objects must be initialized before any of your own code uses them t
258. ired We are not currently taking advantage of this yet 27 7 1 3 16 27 8 1 4 10 The effects of pubsetbuf setbuf are described in this chapter 27 5 1 4 16 Calling fst ream sync when a get area exists will whatever fflush does I think 1 1 2 C 200x This table is based on the table of contents of ISO IEC Doc No N3000 09 0190 Date 2009 11 09 Working Draft Standard for Programming Language C In this implementation st d gnu 0x or std c 0x flags must be used to enable language and library features See dialect options The pre defined symbol __GXX_EXPERIMENTAL_CXX0X__ is used to check for the presence of the required flag This page describes the C 0x support in mainline GCC SVN not in any particular release 1 13 C TR1 This table is based on the table of contents of ISO IEC DTR 19768 Doc No N1836 05 0096 Date 2005 06 24 Draft Technical Report on C Library Extensions In this implementation the header names are prefixed by tr1 for instance lt tr1 functional gt lt trl memory gt and so on This page describes the TR1 support in mainline GCC SVN not in any particular release 1 1 4 C TR 24733 This table is based on the table of contents of ISO IEC TR 24733 Date 2009 08 28 Extension for the programming language C to support decimal floating point arithmetic This page describes the TR 24733 support in mainline GCC SVN not in any particular release 1 2 License There
259. is make command executed in the build directory will do much the same thing without the configuration difference and without building everything twice make CXXFLAGS g3 00 fno inline all enable libstdcxx debug flags FLAGS This option is only valid when enable debug is also specified and applies to the debug builds only With this option you can pass a specific string of flags to the compiler to use when building the debug versions of libstdc FLAGS is a quoted string of options like enable libstdcxx debug flags g3 01 fno inline enable cxx flags FLAGS With this option you can pass a string of f functionality flags to the compiler to use when building libstdc This option can change the library ABI FLAGS is a quoted string of options like The GNU C Library 17 253 nable cxx flags fvtable gc fomit frame pointer ansi Note that the flags don t necessarily have to all be f flags as shown but usually those are the ones that will make sense for experimentation and configure time overriding The advantage of enable cxx flags over setting CXXFLAGS in the make environment is that if files are automatically rebuilt the same flags will be used when compiling those files as well so that everything matches Fun flags to try might include combinations of IESE ICE eu ielisjaliale fno exceptions ffunction sections fvtable ge and opposite forms fno of the sam
260. isher a way to get credit for their work while not being considered responsible for modifications made by others This License is a kind of copyleft which means that derivative works of the document must themselves be free in the same sense It complements the GNU General Public License which is a copyleft license designed for free software We have designed this License in order to use it for manuals for free software because free software needs free documentation a free program should come with manuals providing the same freedoms that the software does But this License is not limited to software manuals it can be used for any textual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference 1 APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a notice grants a world wide royalty free license unlimited in duration to use that work under the conditions stated herein The Document below refers to any such manual or work Any member of the public is a licensee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law A Modified Version of the Document means any work containing
261. iss is the fourth major paragraph of the first page mentioned above For most clients which points out that locking must nearly always be done outside the container by client code that d be you not us There is a notable exceptions to this rule Allocators called while a container or element is constructed uses an internal lock obtained and released solely within libstdc code in fact this is the reason STL requires any knowledge of the thread configuration For implementing a container which does its own locking it is trivial to provide a wrapper class which obtains the lock as SGI suggests performs the container operation and then releases the lock This could be templatized to a certain extent on the underlying container and or a locking mechanism Trying to provide a catch all general template solution would probably be more trouble than it s worth The library implementation may be configured to use the high speed caching memory allocator which complicates thread safety issues For all details about how to globally override this at application run time see here Also useful are details on allocator options and capabilities 3 7 Exceptions The C language provides language support for stack unwinding with t ry and catch blocks and the throw keyword These are very powerful constructs and require some thought when applied to the standard library in order to yield components that work efficiently while cleaning up resources
262. ist concept maps N 18 10 Other runtime support Y 19 Diagnostics 19 1 General Y 19 2 Exception classes Y 19 3 Assertions Y 19 4 Error numbers Y 19 5 System error support 19 5 1 Class error_category Y i Missing concept 19 5 2 Class error_code Partial ErrorCodeEnum Class A Missing concept ae error _condition cae ErrorConditionEnum 19 5 4 Comparison operators Y 19 5 5 Class system_error Y 20 General utilities 20 1 General Partial Missing all concepts 20 2 Concepts N 20 3 Utility components The GNU C Library 6 253 Section Description Status Comments 2 General Utilities 2 1 Reference wrappers 211 Additions to header l y lt functional gt synopsis 212 Class template reference_wrapper 2121 reference_wrapper Y construct copy destroy 2 122 reference Wrapper Y assignment 2 123 reference _wrapper Y access 2124 reference_wrapper Y invocation 2125 reference_wrapper Y helper functions 2 2 Smart pointers 221 Additions to header Y lt memory gt synopsis 2 2 2 Class bad_weak_ptr Y Class template USE gode ion 2 2 3 boost shared_ptr shared_ptr 2 2 3 1 shared_ptr constructors Y 2 2 3 2 shared_ptr destructor Y 2 2 3 3 shared_ptr assignment Y 2 2 3 4 shared_ptr modifiers Y 2 2 3 5 shared_ptr observers Y 2 2 3 6 shared_ptr comparison Y 2 2 3 7 shared_p
263. ith an old compiler and a new library and look for testsuite regressions Details on how to set this kind of test up can be found here http gcc gnu org ml gcc 2002 08 msg00142 html Two Use the make check abi rule in the libstdc Makefile This is a proactive check the library ABI Currently exported symbol names that are either weak or defined are checked against a last known good baseline Currently this baseline is keyed off of 3 4 0 binaries as this was the last time the so number was incremented In addition all exported names are demangled and the exported objects are checked to make sure they are the same size as the same object in the baseline Notice that each baseline is relative to a default configured library and compiler in The GNU C Library 216 253 particular if options such as enable clocale or with cpu in case of multilibs are used at configure time the check may fail either because of substantive differences or because of limitations of the current checking machinery This dataset is insufficient yet a start Also needed is a comprehensive check for all user visible types part of the standard library for sizeof and alignof changes Verifying compatible layouts of objects is not even attempted It should be possible to use sizeof alignof and offsetof to compute offsets for each structure and type in the standard library saving to another datafile Then compute this in a similar way for new bi
264. ith link time coexis tence the separate namespaces result in different mangled names and thus unique linkage However components that are defined and used within the C standard library itself face additional constraints For instance some of the member functions of std moneypunct return std basic_string Normally this is not a problem but with a mixed mode standard library that could be using either debug mode or release mode basic_string objects things get more complicated As the return value of a function is not encoded into the mangled name there is no way to specify a release mode or a debug mode string In practice this results in runtime errors A simplified example of this problem is as follows Take this translation unit compiled in debug mode D_GLIBCXX_DEBUG include lt string gt BICC sica CESTO starts gts st Ola return test02 int main test0l1 return 0 The GNU C Library 106 253 and linked to this translation unit compiled in release mode tinclude lt string gt STel A STILL test02 return Stas rung uboasite For this reason we cannot easily provide safe iterators for the std basic_string class template as it is present throughout the C standard library For instance locale facets define typedef that include basic_string in a mixed debug release program should that typedef be based on the debug mode basic_string or the release mode basic_str
265. its gt include lt unordered_map gt include lt unordered_set gt include lt utility gt include lt valarray gt include lt vector gt leg ac_cv_cxx_stdcxx_Ox yes ac_cv_cxx_stdcxx_0x no AC_LANG_RESTORE CXXFLAGS Sac_save_CXXFLAGS 1 if test Sac_cv_cxx_stdcxx_0x yes then AC_DEFINE STDCXX_OX_HEADERS Define if ISO C 0x header files are present T 1 As is the case for TR1 support these autoconf macros can be made for a finer grained per header file check For lt un ordered_map gt AC_HEADER_UNORDERED_MAP AC_DEFUN AC_HEADER_UNORDERED_MAP AC_CACHE_CHECK for unordered_map ac_cv_cxx_unordered_map AC_ REQUIRE AC_COMPILE STDCXX_0X AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS T The GNU C Library 236 253 CXXFLAGS SCXXFLAGS std gnu 0x AC_TRY_COMPILE include lt unordered_map gt using std unordered_map ac_cv_cxx_unordered_map yes ac_cv_cxx_unordered_map no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE 1 if test Sac_cv_cxx_unordered_map yes then AC_DEFINE HAVE_UNORDERED_MAP Define if unordered_map is present Ed AC_HEADER_UNORDERED_SET AC_DEFUN AC_HEADER_UNORDERED_SET AC_CACHE_CHECK for unordered_set ac_cv_cxx_unordered_set AC_REQUIRE AC_COMPILE_STDCXX_0X
266. ive Container 2 2 oe ee 127 19 73 Algorithms 4 5 2 4 a b0 bake ae bee eee Se eee da eae he bee Be ee ee a 127 19 7 3 1 Sort Algorithm Performance 2 2 20 0 000000 ee eee 127 19 74 Data Locality s s ap gars ka espe dor A RR ee ea ee eee Le ee a 127 19 7 4 1 Need Software Prefetch ee ee 128 19 7 42 Linked Structure Locality ea a na a he dy e 128 19 7 5 Multithreaded Data Access ee 129 19 7 5 1 Data Dependence Violations at Container Level oo 129 1937 D2 Pals DATO 2252 i a we ees ATE e AE A A A 130 19 7 6 Statistics 2 402 babe o e bbe eee ee Aa ee bE ee A eee eo 130 19 8 Bibliography v goie e pa Ske Mae Se RS ee Re RO Ee Bee we 130 The GNU C Library 20 21 22 23 24 25 26 Allocators 201 amt allocator ic 9 R a A A A es A a N ZOO ci as a eh RL ee A REE AA ARO 201 2 Desisii ISSUES e cr to RE ee da A A A amp 4 QO 2 1 OVERVIEW suis a a a A a a a a Rh Shae e ae 20 1 3 Implementation sir rss a A So 20 1 3 1 TonableParame ters pe s sida ad a e a da da 20 1 3 2 Initialization css a A 20 1 3 3 Deallocation Notes ee 20 1 4 Single Thread Example 20 1 5 Multiple Thread Example ee 202 bitmapallocator z el eros A A ee A ee ae ee we Be te oe E 20 21 DESIR paisa rs ee SE Re EA eee ee Re EA ees E eS eS 20 2 2 Implementation sos s e 04 da kan oR bebe ea a ee ae ae Sea ee 20 2 2 1 Fre List Store e
267. l ac_cv_cxx_compile_cxx0x_cxx yes ac_cv_cxx_compile_cxx0x_cxx no CXXFLAGS ac_save_CXXELAGS AC_LANG_RESTORE 1 AC_CACHE_CHECK if g supports C 0x features with std gnu 0x ac_cv_cxx_compile_cxx0x_gxx AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS CXXFLAGS SCXXFLAGS std gnu 0x AC_TRY_COMPILE The GNU C Library template lt typename T gt struct check static_assert sizeof int lt sizeof T not big enough y typedef check lt check lt bool gt gt right_angle_brackets ALE Bie decltype a b typedef check lt int gt check_type check_type c check_type amp amp cr c l ac_cv_cxx_compile_cxx0x_gxx yes ac_cv_cxx_compile_cxx0x_gxx no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE 1 if test Sac_cv_cxx_compile_cxx0x_native yes test Sac_cv_cxx_compile_cxx0x_cxx yes test Sac_cv_cxx_compile_cxx0x_gxx yes then AC_DEFINE HAVE_STDCXX_0X Define if g supports C 0x features pa 1 Check for library coverage of the C 0xstandard AC _HEADER_STDCXX_0X AC_DEFUN AC_HEADER_STDCXX_0X AC_CACHE_CHECK for ISO C Ox include files AC CV Cee Storck IE AC_REQUIRE AC_COMPILE_STDCXX_0X AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS SCXXFLAGS CXXFLAGS SCXXFLAGS std gnu 0x AC_TRY_COMPILE
268. l Number of iteration operations memory saved s Example 1 vector lt unordered_set lt int gt gt v 100000 unordered_set lt int gt 100 2 acoja me Kk Os e lt lt AOOOOOR moy 4 3 tore me g OF 3 lt 109 ssp 4 4 WIL case Us ar Spe 5 6 foo cc 1 advice Changing initial unordered_set size from 100 to 10 saves N bytes of memory and M iteration steps The GNU C Library 123 253 19 7 2 3 Inefficient Hash Switch _GLIBCXX_PROFILE_INEFFICIENT_HASH Goal Detect hashtables with polarized distribution Fundamentals A non uniform distribution may lead to long chains thus possibly increasing complexity by a factor up to the number of elements Sample runtime reduction factor up to container size Recommendation Change hash function for container built at site S Distribution score N Access score S Longest chain C in bucket B To instrument unordered_set unordered_map constructor destructor insert iterator Analysis Count the exact number of link traversals Cost model Total number of links traversed Example class dumb_hash public Saiz CE Qosra me a COME I rertian Op y unordered_set lt int dumb_hash gt hs LOI MEE L Op ook COUNTS Ray ee e Pet tans 19 7 2 4 Vector Too Small Switch _GLIBCXX_PROFILE_VECTOR_TOO_SMALL Goal Detect vectors with many resize operations small construction size and large destruction size Fundament
269. l but less readable form of it for parsing command strings and the like If you compiled and ran this code using it suele 2 lis lt sicicable gt sp Ejec le Y tas Ne ate NEN El ese e for std list lt string gt const_iterator i ls begin T YS ls Sieh spa Suele penita lt E 984 lt e 6 lt e Usas You would see this as output Sanas TESE sa Peste with all the whitespace removed The original s is still available for use 1s will clean up after itself and 1s size will return how many tokens there were As always there is a price paid here in that stringtok is not as fast as strtok The other benefits usually outweigh that however Added February 2001 Mark Wilden pointed out that the standard std getline function can be used with standard ist ringstreams to perform tokenizing as well Build an istringstream from the input text and then use std getline with varying delimiters the three argument signature to extract tokens into a string 7 1 5 Shrink to Fit From GCC 3 4 calling s reserve res ona string s with res lt s capacity will reduce the string s capacity to std max s size res The GNU C Library 58 253 This behaviour is suggested but not required by the standard Prior to GCC 3 4 the following alternative can be used instead sta string str data str size swap str This is similar to the idiom for reducing a vector s memory usage see this FAQ entry but
270. l force_parallel __gnu_parallel _Settings set s j Do work all algorithms will be parallelized always return 0 18 4 3 Implementation Namespaces One namespace contain versions of code that are always explicitly sequential __gnu_serial Two namespaces contain the parallel mode std __parallel and __gnu_parallel Parallel implementations of standard components including template helpers to select parallelism are defined in namespace std __parallel For instance std transform from algorithm has a parallel counterpart in std __parall el transform from parallel algorithm In addition these parallel implementations are injected into namespace __gnu_parallel with using declarations Support and general infrastructure is in namespace __gnu_parallel More information and an organized index of types and functions related to the parallel mode on a per namespace basis can be found in the generated source documentation 18 5 Testing Both the normal conformance and regression tests and the supplemental performance tests work To run the conformance and regression tests with the parallel mode active make check parallel The log and summary files for conformance testing are in the testsuite parallel directory To run the performance tests with the parallel mode active make check performance parallel The result file for performance testing are in the test suite directory in the file 1libstdc _performance sum In ad
271. l be treated as though they were included in this License to the extent that they are valid under applicable law If additional permissions apply only to part of the Program that part may be used separately under those permissions but the entire Program remains governed by this License without regard to the additional permissions When you convey a copy of a covered work you may at your option remove any additional permissions from that copy or from any part of it Additional permissions may be written to require their own removal in certain cases when you modify the work You may place additional permissions on material added by you to a covered work for which you have or can give appropriate copyright permission Notwithstanding any other provision of this License for material you add to a covered work you may if authorized by the copyright holders of that material supplement the terms of this License with terms a Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License or b Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it or c Prohibiting misrepresentation of the origin of that material or requiring that modified versions of such material be marked in reasonable ways as different from the original version or d Limiting the use for publicity purposes of nam
272. lates are defined inline ither explicitly or by their placement in class definitions which should not be inline This is a source of code bloat Matt had remarked that he was relying on the compiler to recognize what was too big to benefit from inlining and generate it out of line automatically However this also can result in code bloat except where the linker can eliminate the extra copies Fixing these cases will require an audit of all inline functions defined in the library to determine which merit inlining and moving the rest out of line This is an issue mainly in chapters 23 25 and 27 Of course it can be done incrementally and we should generally accept patches that move large functions out of line and into tcc files which can later be pulled into a repository Compiler linker improvements to recognize very large inline functions and move them out of line but shared among compilation units could make this work unnecessary Pre instantiating template specializations currently produces large amounts of dead code which bloats statically linked programs The current state of the static library libstdct a is intolerable on this account and will fuel further confused speculation about a need for a library subset A compiler improvement that treats each instantiated function as a separate object file for linking purposes would be one solution to this problem An alternative would be to split u
273. lder releases of libstdc do not require such a recent version but to take full advantage of useful space saving features and bug fixes you should use a recent binutils whenever possible The configure process will automatically detect and use these features if the underlying support is present Finally a few system specific requirements linux If gcc 3 1 0 or later on is being used on linux an attempt will be made to use C library functionality necessary for C named locale support For gcc 3 2 1 and later this means that glibc 2 2 5 or later is required and the C library de_DE locale information must be installed Note however that the sanity checks involving the de_DE locale are skipped when an explicit enable clocale gnu con figure option is used only the basic checks are carried out defending against misconfigurations If the gnu locale model is being used the following locales are used and tested in the libstdc testsuites The first column is the name of the locale the second is the character set it is expected to use de_DE ESO esos de_DE euro 1S50 8859 15 The GNU C Library 15 253 en_GB ESOS Sooo a en_HK SO SS ao en_PH MSO slo i en_US TSO 5 SIL en_US ISO 8859 1 TSOS8 8993l Gin US ESO 38095 ESOC Soo es en_US UTF 8 Gs te es_ES SOS T es_MX TSO 35 1L fr_FR TSO 065 9i fr_FR euro TSO GBOO ks e LS UNES sie wear 10 9859 ja_JP eucjp EUG JP LING 5 TSO SLOSS ESO gt 8859 5
274. le was checked in to SVN As per the dejagnu instructions always return 0 from main to indicate success A bunch of utility functions and classes have already been abstracted out into the testsuite utility library libtestc To use this functionality just include the appropriate header file the library or specific object files will automatically be linked in as part of the testsuite run For a test that needs to take advantage of the dejagnu test harness what follows below is a list of special keyword that harness uses Basically a test case contains dg keywords see dg exp indicating what to do and what kinds of behavior are to be expected New test cases should be written with the new style DejaGnu framework in mind To ease transition here is the list of dg keyword documentation lifted from dg exp The currently supported options are ele prms r AN set prms id to N loja opr IONS sao ta roere ESTEE 257 specify special options to pass to the tool eg compiler dg do do what keyword target xfail selector do what keyword is tool specific and is passed unchanged to tool dg test An example is gcc where keyword can be any of preprocess compile assemble link run and will do one of produce a i produce a s produce a o produce an a out or produce an a out and run it the default is compile dg error regexp comment target xfail selector 0 linenum indicate an error message lt regexp gt is
275. le threaded Multithreaded execution without TLS is not supported Environment variable not supported T e _GLIBCXX_HAVE_EXECINFO_H This name should be defined automatically at library configuration time If your library was configured without execinfo h but you have it in your include path you can define it explicitly Without it advice is collected for the program as a whole and not for each call context Environment variable not supported The GNU C Library 117 253 Code Location Use libstdc v3 include std Preprocessor code to redirect to profile extension headers libstdc v3 include profile Profile extension public headers map vector Profile extension internals Implementation files are only libstdc v3 include profile impl included from impl1 profiler h which is the only file included from the public headers Table 19 1 Profile Code Location 19 2 Design 19 2 1 Wrapper Model In order to get our instrumented library version included instead of the release one we use the same wrapper model as the debug mode We subclass entities from the release version Wherever _GLIBCXX_PROFILE is defined the release namespace is std __norm whereas the profile namespace is std __ profile Using plain std translates into std __profile Whenever possible we try to wrap at the public interface level e g in unordered_set rather than in hash
276. led History in the Document create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describing the Modified Version as stated in the previous sentence J Preserve the network location if any given in the Document for public access to a Transparent copy of the Document and likewise the network locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network location for a work that was published at least four years before the Document itself or if the original publisher of the version it refers to gives permission K For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein L Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the equivalent are not considered part of the section titles M Delete any section Entitled Endorsements Such a section may not be included in the Modified Version Z Do not retitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section O Preserve any Warranty Disclaimers The GNU C Library 251 253 If the Modified Version includes new front matter sections or appendices that qualify
277. lgorithms 26_numerics DNS 28_regex 29 Tatomiles 30_threads The GNU C Library 198 253 In addition the following directories include test files mall Tests for components as described by the Extensions TR1 Technical Report on Standard Library lt lt backward Tests for backwards compatibility and deprecated features demangle Tests for __cxa_demangle the IA 64 C ABI demangler ext Tests for extensions performance Tests for performance analysis and performance regressions Some directories don t have test files but instead contain auxiliary information EEIT Files for the dejagnu test harness 1309 Files for the dejagnu test harness O SPA Files for the dejagnu test harness data Sample text files for testing input and output eco Files for libtestc utilities and testing routines Within a directory that includes test files there may be additional subdirectories or files Originally test cases were appended to one file that represented a particular section of the chapter under test and was named accordingly For instance to test items related to 21 3 6 1 basic_string find lib string find in the standard the following was used PAS As Ain ee However that practice soon became a liability as the test cases became huge and unwieldy and testing new or extended function ality like wide characters or named locales became frustrating leading to aggressive pruning of test cases on
278. library state is initialized at the first call to a profiling method This allows us to record the construction of all global objects However we cannot do the same at destruction time The trace is written by a function registered by atexit thus invoked by exit The GNU C Library 120 253 19 6 Developer Information 19 6 1 Big Picture The profile mode headers are included with D_GLIBCXX_PROFILE through preprocessor directives in include std Instrumented implementations are provided in include profile All instrumentation hooks are macros defined in in clude profile profiler h All the implementation of the instrumentation hooks is in include profile impl Although all the code gets included thus is publicly visible only a small number of functions are called from outside this directory All calls to hook implementations must be done through macros defined in profiler h The macro must ensure 1 that the call is guarded against reentrance and 2 that the call can be turned off at compile time using a D_GLIBCXX_PROFILE_ compiler option 19 6 2 How To Add A Diagnostic Let s say the diagnostic name is magic If you need to instrument a header not already under include profile x first edit the corresponding header under incl ude std and add a preprocessor directive such as the one in include std vector ifdef _GLIBCXX_ PROFILE include lt profile vector gt endif If the file you need to instrumen
279. libstdc s0 5 0 4 libstdc so 5 0 5 libstdc so 5 0 5 libstdc so 5 0 5 libstdc s0 6 0 0 Incompatible with previous libstdc s0 6 0 1 libstdc s0 6 0 2 libstdc s0 6 0 3 libstdc s0 6 0 3 libstdc so 6 0 3 libstdc so 6 0 3 libstdc s0 6 0 4 libstdc s0 6 0 5 libstdc s0 6 0 6 libstdc s0 6 0 7 libstdc s0 6 0 7 libstdc so 6 0 8 libstdc so 6 0 8 libstdc s0 6 0 9 libstdc s0 6 0 9 See Note 3 libstdc s0 6 0 9 libstdc s0 6 0 9 libstdc s0 6 0 9 libstdc so 6 0 10 libstdc s0 6 0 10 libstdc s0 6 0 10 libstdc s0 6 0 10 libstdc s0 6 0 10 libstdc s0 6 0 11 libstdc s0 6 0 12 libstdc s0 6 0 13 libstdc s0 6 0 14 208 253 The GNU C Library 209 253 Note 1 Error should be libstdc so 3 0 3 Note 2 Not strictly required Note 3 This release but not previous or subsequent has one known incompatibility see 33678 in the GCC bug database 4 Symbol versioning on the libstdc so binary mapfile libstdc config linker map gnu It is versioned with the following labels and version definitions where the version definition is the maximum for a particular release Note only symbol which are newly introduced will use the maximum version definition Thus for release series with the same label but incremented version definitions the later release has both versions An example of this would be the gcc 3 2 1 release which has GLIBCPP_3 2 1 for new symbols and GLIBCPP_3 2
280. lication code with custom options e You must run the application on representative input The advice is input dependent s The execution time will increase in some cases by factors 19 1 1 Using the Profile Mode This is the anticipated common workflow for program foo cc S cet FO include lt vector gt ae merino Al vector lt int gt v for int k 0 k lt 1024 k v insert v begin k Sig DECLIBCXXEPROEITEE Eoo ce G a out See T sitaclenex ora odes esge vector to list improvement 5 call stack 0x804842c advice change std vector to std list vector size improvement 3 call stack 0x804842c advice change initial container size from 0 to 1024 The GNU C Library 116 253 Anatomy of a warning e Warning id This is a short descriptive string for the class that this warning belongs to E g vector to list e Estimated improvement This is an approximation of the benefit expected from implementing the change suggested by the warning It is given on a logl0 scale Negative values mean that the alternative would actually do worse than the current choice In the example above 5 comes from the fact that the overhead of inserting at the beginning of a vector vs a list is around 1024 1024 2 which is around 10e5 The improvement from setting the initial size to 1024 is in the range of 10e3 since the overhead of dynamic resizing is linear in this case e Call stack Currently the addresse
281. licensing is not allowed section 10 makes it unnecessary 3 Protecting Users Legal Rights From Anti Circumvention Law No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996 or similar laws prohibiting or restricting circumvention of such measures When you convey a covered work you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work and you disclaim any intention to limit operation or modification of the work as a means of enforcing against the work s users your or third parties legal rights to forbid circumvention of technological measures 4 Conveying Verbatim Copies You may convey verbatim copies of the Program s source code as you receive it in any medium provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice keep intact all notices stating that this License and any non permissive terms added in accord with section 7 apply to the code keep intact all notices of the absence of any warranty and give all recipients a copy of this License along with the Program You may charge any price or no price for each copy that you convey and you may offer support or warranty protection for a fee 5 Conveying
282. locator h 4 2 0 or lt T gt Table B 2 Extension Allocators Continued Debug mode first appears Precompiled header support PCH support Macro guard for changed from __GLIBCPP_ to _GLIBCXX_ Extension ext stdio_sync_filebuf h added Extension ext demangle h added B 5 6 4 0 TR1 features first appear Extension allocator ext array_allocator h added Extension codecvt specializations moved to ext codecvt_specializations h Removal of ext demangle h The GNU C Library 220 253 B 5 7 4 1 Removal of cassert from all standard headers now has to be explicitly included for std assert calls Extensions for policy based data structures first added New includes types namespace pb_assoc Extensions for typelists added in ext typelist h Extension for policy based basic_string first added __gnu_cxx __versa_stringinext vstring h B 5 8 4 2 Default visibility attributes applied to namespace std Support for fvisibility TR1 random complex and C compatibility headers added Extensions for concurrent programming consolidated into ext concurrence hand ext atomicity h including change of namespace to__ gnu_cxx in some cases Added types include _Lock_policy _ _concurrence_lock_error __ concurrence_unlock_error mutex scoped_lock Extensions for type traits consolidated into ext type_traits h Additional traits are added __conditional_type __enable_if others Extensions for policy bas
283. lock Yes both at the same time That s because the next super block acquired will be 2 times the previous one and also all super blocks have to be multiples of the _Bits_Per_Block value How does it interact with the free list store The super block is contained in the FLS and the FLS is responsible for getting returning Super Bocks to and from the OS using operator new as defined by the C standard 20 2 2 3 Super Block Data Layout Each Super Block will be of some size that is a multiple of the number of Bits Per Block Typically this value is chosen as Bits_Per_Byte x sizeof size_t On an x86 system this gives the figure 8 x 4 32 Thus each Super Block will be of size 32 x Some Value This Some Value is sizeof value_type For now let it be called K Thus finally Super Block size is 32 x K bytes This value of 32 has been chosen because each size_t has 32 bits and Maximum use of these can be made with such a figure Consider a block of size 64 ints In memory it would look like this assume a 32 bit system where size_t is a 32 bit entity Data gt Space for 64 268 0 4294967295 4294967295 S Table 20 1 Bitmap Allocator Memory Map The first Column 268 represents the size of the Block in bytes as seen by the Bitmap Allocator Internally a global free list is used to keep track of the free blocks used and given back by the bitmap allocator It is this Free List Store that is responsible
284. lt hash_map h gt Many of these are already placed in the subdirectories ext and backward Note that it is better to include them via lt backward hash_map h gt or lt ext hash_map gt than to search the subdirectory itself via a I directive The GNU C Library 189 253 Appendix B Porting and Maintenance AppendixPorting and Maintenance B 1 Configure and Build Hacking B 1 1 Prerequisites As noted previously certain other tools are necessary for hacking on files that control configure configure ac acincl ude m4 and make Makefile am These additional tools automake and autoconf are further described in detail in their respective manuals All the libraries in GCC try to stay in sync with each other in terms of versions of the auto tools used so please try to play nicely with the neighbors B 1 2 Overview What Comes from Where Dependency Graph Configure to Build Files Regenerate all generated files by using the command sequence autoreconf at the top level of the libstdc source directory The following will also work but is much more complex aclocal 1 11 amp amp autoconf 2 64 amp amp autoheade r 2 64 amp amp automake 1 11 The version numbers may be absent entirely or otherwise vary depending on the current requirements and your vendor s choice of installation names B 1 3 Storing Information in non AC files like configure host Until that glorious day when we can use AC_TRY_LINK
285. maskx __table 0 bool __del false size_t __refs 0 _Ctype_nois lt char gt __refs _M del _ table 0 amp amp _ del _M toupper NULL _M _tolower NULL _M _ctable NULL _M table _ table amp Conse masks C ioc eiii EMS o Glass ar L table L There are two parts of this that you might choose to alter The first and most important is the line involving __ 1 ibc_attr That is IRIX system dependent code that gets the base of the table mapping character codes to attributes You need to substitute code that obtains the address of this table on your system If you want to use your operating system s tables to map upper case letters to lower case and vice versa you should initialize_M_toupper and_M_tolower with those tables in similar fashion Now you have to write two functions to convert from upper case to lower case and vice versa Here are the IRIX versions char ctype lt char gt do_toupper char __c const return OUD pea ic char ctype lt char gt do_tolower char __c const returni Colowert 2 Your C library provides equivalents to IRIX s _toupper and _tolower If you initialized_M_toupper and_M_tolower above then you could use those tables instead The GNU C Library 195 253 Finally you have to provide two utility functions that convert strings of characters The versions provided here will always work but you could use specialized routines for greater performance if you have m
286. me Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns See http www gnu org copyleft Each version of the License is given a distinguishing version number If the Document specifies that a particular numbered version of this License or any later version applies to it you have the option of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Software Foundation If the Document does not specify a version number of this License you may choose any version ever published not as a draft by the Free Software Foundation ADDENDUM How to use this License for your documents To use this License in a document you have written include a copy of the License in the document and put the following copyright and license notices just after the title page Copyright C YEAR YOUR NAME Permission is granted to copy distribute and or modify this document under the terms of the GNU Free Documenta tion License Version 1 2 or any later version published by the Free Software Foundation with no Invariant Sections no Front Cover Texts and no Back Cover Texts A copy of the license is included in the section entitled GNU Free Documentation License If you have Invariant Sections Front Cover Texts and Back Cover Texts replace the with Texts line with this with the Invariant
287. minate Compiler support is not strictly necessary except in the case of function try blocks otherwise the following macros almost suffice define throw X define try if true define catch X else if false However there may be a need to use function try blocks in the library implementation and use of macros in this way can make correct diagnostics impossible Furthermore use of this scheme would require the library to call a function to re throw exceptions from a try block Implementing the above semantics in the compiler is preferable Given the support above however implemented it only remains to The GNU C Library 178 253 replace code that throws with a call to a well documented handler function in a separate compilation unit which may be replaced by the user The main source of exceptions that would be difficult for users to avoid is memory allocation failures but users can define their own memory allocation primitives that never throw Otherwise the complete list of such handlers and which library functions may call them would be needed for users to be able to implement the necessary substitutes Fortunately they have the source code Opportunities The template capabilities of C offer enormous opportunities for optimizing common library operations well beyond what would be considered eliminating overhead In particular many operations do
288. mitations are as follows B 6 2 1 Namespace std not supported Some care is required to support C compiler and or library implementation that do not have the standard library in namesp ace std The following sections list some possible solutions to support compilers that cannot ignore std qualified names First see if the compiler has a flag for this Namespace back portability issues are generally not a problem for g compilers that do not have libstdc in std as the compilers use Eno honor std ignore std std by default That is the responsibility for enabling or disabling std is on the user the maintainer does not have to care about it This probably applies to some other compilers as well Second experiment with a variety of pre processor tricks By defining std as a macro fully qualified namespace calls become global Volia ifdef WICKEDLY_OLD_COMPILER define std endif Thanks to Juergen Heinz who posted this solution on gnu gcc help Another pre processor based approach is to define a macro NAMESPACE_STD which is defined to either or std based on a compile type test On GNU systems this can be done with autotools by means of an autoconf test see below for H AVE_NAMESPACE_STD then using that to set a value for the NAMESPACE_STD macro At that point one is able to use NAMESPACE_STD string
289. mpiler g with a compatible ABI Phew On top of all that an additional constraint libstdc did not attempt to version symbols or age gracefully really until version 3 1 0 Most modern Linux and BSD versions particularly ones using gcc 3 1 x tools and more recent vintages will meet the require ments above B 4 2 4 Configuring It turns out that most of the configure options that change default behavior will impact the mangled names of exported symbols and thus impact versioning and compatibility For more information on configure options including ABI impacts see http gcc gnu org onlinedocs libstdc configopts html There is one flag that explicitly deals with symbol versioning enable symvers In particular libstdc acinclude m4 has a macro called GLIBCXX_ENABLE_SYMVERS that defaults to yes or the argument passed in via enable symvers foo At that point the macro attempts to make sure that all the requirement for symbol versioning are in place For more information please consult acinclude m4 B 4 2 5 Checking Active When the GNU C library is being built with symbol versioning on you should see the following at configure time for libstdc checking versioning on shared library symbols gnu If you don t see this line in the configure output or if this line appears but the last word is no then you are out of luck If the compiler is pre installed a quick way to test is to compile the following or
290. mple if you distribute copies of such a program whether gratis or for a fee you must pass on to the recipients the same freedoms that you received You must make sure that they too receive or can get the source code And you must show them these terms so they know their rights Developers that use the GNU GPL protect your rights with two steps 1 assert copyright on the software and 2 offer you this License giving you legal permission to copy distribute and or modify it For the developers and authors protection the GPL clearly explains that there is no warranty for this free software For both users and authors sake the GPL requires that modified versions be marked as changed so that their problems will not be attributed erroneously to authors of previous versions Some devices are designed to deny users access to install or run modified versions of the software inside them although the manufacturer can do so This is fundamentally incompatible with the aim of protecting users freedom to change the software The systematic pattern of such abuse occurs in the area of products for individuals to use which is precisely where it is most unacceptable Therefore we have designed this version of the GPL to prohibit the practice for those products If such problems arise substantially in other domains we stand ready to extend this provision to those domains in future versions of the GPL as needed to protect the freedom of users
291. n AC_DEF izak INE HAVE_TR1_UNORDERED_SET Define if trl unordered_set is present 1 232 253 The GNU C Library 233 253 B 6 3 7 Support for C 0x dialect Check for baseline language coverage in the compiler for the C 0xstandard AC_COMPILE_STDCXX_OX AC_DEFUN AC_COMPILE_STDCXX_0X AC_CACHE_CHECK if g supports C 0x features without additional flags ac cy ooa compile cxx0x native AC_LANG_SAVE AC_LANG_CPLUSPLUS AC_ TRY_COMPILE template lt typename T gt struct check static_assert sizeof int lt sizeof T not big enough y typedef check lt check lt bool gt gt right_angle_brackets int a decltype a b typedef check lt int gt check_type check_type c check_type amp amp cr c l ac_cv_cxx_compile_cxx0x_native yes ac_cv_cxx_compile_cxx0x_native no AC_LANG_RESTORE 1 AC_CACHE_CHECK if g supports C 0x features with std c 0x ac_cv_cxx_compile_cxx0x_cxx AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS CXXFLAGS CXXFLAGS CXXFLAGS std c 0x AC_TRY_COMPILE template lt typename T gt struct check static_assert sizeof int lt sizeof T not big enough y typedef check lt check lt bool gt gt right_angle_brackets ae Elf decltype a b typedef check lt int gt check_type check_type c check_type amp amp cr c
292. n __ ret NOT return _ ret NGT return __ret 14 Location of global variables The GNU C Library 165 253 All global variables of class type whether in the user visible space e g cin or the implementation namespace must be defined as a Character array with the appropriate alignment and then later re initialized to the correct value This is due to startup issues on certain platforms such as AIX For more explanation and examples s src globals cc All such variables should be contained in that file for simplicity 15 Exception abstractions Use the exception abstractions found in functexcept h which allow C programmers to use this library with fno exceptions Even if that is rarely advisable it s a necessary evil for backwards compatibility E 16 Exception error messages All start with the name of the function where the exception is thrown and then optional descriptive text is added Example throw_logic_error __N basic_string _S_construct NULL not valid Reason The verbose terminate handler prints out exception what as well as the typeinfo for the thrown exception As this is the default terminate handler by putting location info into the exception string a very useful error message is printed out for uncaught exceptions So useful in fact that non programmers can give useful error messages and programmers can intelligently speculate
293. n may use additional functions designated with the _switch suffix to dispatch from the ISO C signature to the correct parallel version Also some of the algorithms do not have support for run time conditions so the last overload is therefore missing 18 4 2 Configuration and Tuning 18 4 2 1 Setting up the OpenMP Environment Several aspects of the overall runtime environment can be manipulated by standard OpenMP function calls To specify the number of threads to be used for the algorithms globally use the function omp_set_num_threads An example include lt stdlib h gt include lt omp h gt int main Explicitly set number of threads const int threads_wanted 20 omp_set_dynamic false omp_set_num_threads threads_wanted Call parallel mode algorithms return 0 Some algorithms allow the number of threads being set for a particular call by augmenting the algorithm variant See the next section for further information Other parts of the runtime environment able to be manipulated include nested parallelism omp_set_nested schedule kind omp_set_schedule and others See the OpenMP documentation for more information The GNU C Library 113 253 18 4 2 2 Compile Time Switches To force an algorithm to execute sequentially even though parallelism is switched on in general via the macro _ GLIBCXX_PA RALLEL add__gnu_parallel sequential_tag to the end of the algorithm s argument list
294. n rules in the Makefile which is equivalent to doing xmllint noout valid xml index xml A 4 2 2 Generating the DocBook Files The following Makefile rules generate in order an HTML version of all the DocBook documentation a PDF version of the same a single XML document and the result of validating the entire XML document make doc html docbook make doc pdf docbook make doc xml single docbook make doc xml validate docbook A 4 2 3 File Organization and Basics Which files are important All Docbook files are in the directory libstdc v3 doc xml Inside this directory the files of importance spine xml index to documentation set manual spine xml index to manual manual x xml individual chapters and sections of the manual faq xml index to FAQ api xml index to source level API All x txml files are template xml files i e otherwise empty files with The GNU C Library 171 253 the correct structure suitable for filling in with new information Canonical Writing Style class template function template member function template via C Templates Vandevoorde class in namespace std allocator not std allocator header file iostream not lt iostream gt General structure lt set gt lt book gt lt book gt lt book gt lt chapter gt lt chapter gt lt book gt lt boo lt par K gt t gt lt chapter gt lt sec tion gt lt s
295. n situations such as program startup For usage examples please consult the testsuite 4 debug_allocator A wrapper around an arbitrary allocator A It passes on slightly increased size requests to A and uses the extra memory to store size information When a pointer is passed to deallocate the stored size is checked and assert is used to guarantee they match 5 throw_allocator Includes memory tracking and marking abilities as well as hooks for throwing exceptions at configurable intervals includ ing random all none 6 _ pool_alloc A high performance single pool allocator The reusable memory is shared among identical instantiations of this type It calls through operator new to obtain new memory when its lists run out If a client container requests a block larger than a certain threshold size then the pool is bypassed and the allocate deallocate request is passed to operator new directly The GNU C Library 48 253 Older versions of this class take a boolean template parameter called thr and an integer template parameter called inst The inst number is used to track additional memory pools The point of the number is to allow multiple instantiations of the classes without changing the semantics at all All three of typedef _ pool_alloc lt true 0 gt normal typedef _ pool_alloc lt true 1 gt private typedef _ pool_alloc lt true 42 gt also_private behave exactly the same way However the memor
296. naries and look for differences Another approach might be to use the fdump class hierarchy flag to get information However currently this approach gives insufficient data for use in library testing as class data members their offsets and other detailed data is not displayed with this flag See g 7470 on how this was used to find bugs Perhaps there are other C ABI checkers If so please notify us We d like to know about them B 4 6 2 Multiple ABI Testing A C application dynamically linked to two shared libraries liba libb The dependent library liba is C shared library compiled with gcc 3 3 x and uses io exceptions locale etc The dependent library libb is a C shared library compiled with gcc 3 4 x and also uses io exceptions locale etc As above libone is constructed as follows Sb1d H x86 gec 3 4 0 bin g fPIC DPIC c a ce b1d H4 x86 gcc 3 4 0 bin g shared W1 sonam W1 libone so 1 W1 01 W1l z defs a o iones SO 4 ILO 20 Clie SM On Ss OO Oude One sO SS MOSS O g ESO DI T E Sar cru libone a a o And libtwo is constructed as follows Sbld H x86 gec 3 3 3 bin g fPIC DPIC c b ce b1d H4 x86 gcc 3 3 3 bin g shared Wl sonam W1 libtwo so 1 W1 01 W1 z defs b o gt Litros Orel 0 0 SUS MENOS OO AO MID EwOAS O Go o E sd ear O Ce Ryle Can Ora 100 with the resulting libraries looking like Sldd libone so 1 0 0 libstdc s0 6
297. nce count and incrementing it which could result in a shared_ptr pointing to invalid memory The Boost shared_ptr as used in GCC features a clever lock free algorithm to avoid the race condition but this relies on the processor supporting an atomic Compare And Swap instruction For other platforms there are fall backs using mutex locks Boost as of version 1 35 includes several different implementations and the preprocessor selects one based on the compiler standard library platform etc For the version of shared_ptr in libstdc the compiler and library are fixed which makes things much simpler we have an atomic CAS or we don t see Lock Policy below for details 6 3 3 3 3 Selecting Lock Policy There is a single _Sp_counted_base class which is a template parameterized on the enum __gnu_cxx _Lock_policy The entire family of classes is parameterized on the lock policy right up to__ shared_ptr __weak_ptr and__enable_s hared_from_this The actual std shared_ptr class inherits from __shared_ptr with the lock policy parameter selected automatically based on the thread model and platform that libstdc is configured for so that the best available template specialization will be used This design is necessary because it would not be conforming for shared_ptr to have an extra template parameter even if it had a default value The available policies are 1 _S_Atomic Selected when GCC supports a builtin atomic compare and swap operation
298. nce of a bad_alloc exception or technically some class derived from it You can change this by writing your own function called a new handler and then registering it with set_new_handler typedef void PFV void static charx safety Seems JT old_handler void my_new_handler delete safety popup_window Dude you are running low on heap memory You should like close some windows or something The next time you run out we re gonna burn set_new_handler old_handler return Mane safety new char 500000 old_handler set_new_handler amp my_new_handler bad_alloc is derived from the base exception class defined in Sectl 19 The GNU C Library 40 253 4 3 Termination 4 3 1 Termination Handlers Not many changes here to cstd1ib You should note that the abort function does not call the destructors of automatic nor static objects so if you re depending on those to do cleanup it isn t going to happen The functions registered with atexit don t get called either so you can forget about that possibility too The good old exit function can be a bit funky too until you look closer Basically three points to remember are 1 Static objects are destroyed in reverse order of their creation 2 Functions registered with atexit are called in reverse order of registration once per registration call This isn t actually new 3 The previous two actions are in
299. nctions applies here also The GNU C Library 142 253 21 3 Deprecated HP SGI The SGI hashing classes hash_set and hash_set have been deprecated by the unordered_set unordered_multiset un ordered_map unordered_multimap containers in TR1 and the upcoming C 0x and may be removed in future releases The SGI headers lt hash_map gt lt hash_set gt lt rope gt sellata lt rb_tree gt are all here lt hash_map gt and lt hash_set gt are deprecated but available as backwards compatible extensions as discussed further below lt rope gt is the SGI specialization for large strings rope large strings get it Love that geeky humor lt s list gt is a singly linked list for when the doubly linked 1ist lt gt is too much space overhead and lt rb_tree gt exposes the red black tree classes used in the implementation of the standard maps and sets Each of the associative containers map multimap set and multiset have a counterpart which uses a hashing function to do the arranging instead of a strict weak ordering function The classes take as one of their template parameters a function object that will return the hash value by default an instantiation of hash You should specialize this functor for your class or define your own before trying to use one of the hashing classes The hashing classes support all the usual associative container functions as well as some extra constructors specifying the number of bucket
300. nctions in lt cstring gt are different from the C version generally overloaded on const and non const argument pointers For example in lt cstring gt strchr is overloaded The functions isupper etc in lt cctype gt typically implemented as macros in C are functions in C because they are overloaded with others of the same name defined in lt locale gt Many of the functions required in lt cwctype gt and lt cwchar gt cannot be implemented using underlying C facilities on intended targets because such facilities only partly exist Chapter 22 Locale Headers lt locale gt C headers lt clocale gt We have a mostly complete class locale with the exception of code for constructing and handling the names of named locales The ways that locales are named particularly when categories e g LC_TIME LC_COLLATE are different varies among all target environments This code must be written in various versions and chosen by configuration parameters Members of many of the facets defined in lt locale gt are stubs Generally there are two sets of facets the base class facets which are supposed t t o implement the C locale and the byname facets which are supposed o read files to determine their behavior The base ctype lt gt collate lt gt and numpunct lt gt facets are mostly complete except that the table of bitmask values used for is operations and correspond
301. nd 2 1 x define ct ype h functionality as macros isspace isalpha etc This implementations of libstdc however keep these functions as macros and so it is not back portable to use fully qualified names For example include lt cctype gt aioe meca Af Siecle salsa A Results in something like this sols GC GYD CuO Gant AL NA sao ase short ine Ss A solution is to modify a header file so that the compiler tells ct ype h to define functions instead of macros This keeps isalnum et al from being propagated as macros aE LR define __NO_CTYPE 1 endif Then include ctype h Another problem arises if you puta using namespace std declaration at the top and include ct ype h This will result in ambiguities between the definitions in the global namespace ct ype h and the definitions in namespace std lt ccty pe gt B 6 2 4 No vector at deque at string at One solution is to add an autoconf test for this AC_MSG_CHECKING for container at AC_TRY_COMPILE include lt vector gt include lt deque gt include lt string gt using namespace std L deque lt int gt test_deque 3 test_deque at 2 vector lt int gt test_vector 2 test_vector at 1 string test_string test_string test_string at 3 r AC_MSG_RESULT yes AC_DEFINE HAVE_CONTAINER_AT AC_MSG_RESULT no If you are using othe
302. nd class template unique_lock In header condition_variable classes condition_variable and condition_variable_any In header thread class thread and namespace this_thread In header future class template future and class template shared_future class template promise and packaged _task Full API details The GNU C Library 96 253 Part III Extensions The GNU C Library 97 253 Here we will make an attempt at describing the non Standard extensions to the library Some of these are from SGI s STL some of these are GNU s and some just seemed to appear on the doorstep Before you leap in and use any of these extensions be aware of two things 1 Non Standard means exactly that The behavior and the very existence of these extensions may change with little or no warning Ideally the really good ones will appear in the next revision of C Also other platforms other compilers other versions of g or libstdc may not recognize these names or treat them differently or 2 You should know how to access these headers properly The GNU C Library 98 253 Chapter 16 Compile Time Checks Also known as concept checking In 1999 SGI added concept checkers to their implementation of the STL code which checked the template parameters of instantiated pieces of the STL in order to insure that the parameters being used met the requirements of the standard For example the Standard requires tha
303. nd may need to be executed in the libbuilddir testsuite directory These options include but are not necessarily limited to the following make testsuite files Five files are generated that determine what test files are run These files are e testsuite_files This is a list of all the test cases that will be run Each test case is on a separate line given with an absolute path from the libsrcdir testsuite directory e testsuite_files_interactive This is a list of all the interactive test cases using the same format as the file list above These tests are not run by default e testsuite_files_performance P This is a list of all the performance test cases using the same format as the file list above These tests are not run by default s testsuite_thread This file indicates that the host system can run tests which involved multiple threads s testsuite_wchar_t eal This file indicates that the host system can run the wchar_t tests and corresponds to the macro definition _GLIBCXX_US _WCHAR_T in the file c config h make check abi The library ABI can be tested This involves testing the shared library against an ABI defining previous version of symbol exports make check compil This rule compiles but does not link or execute the testsuite_files test cases and displays the output on stdout The GNU C Library 201 253 make check performance This rule runs through the testsuite_files_perform
304. nding Source need not include anything that users can regenerate automatically from other parts of the Correspond ing Source The Corresponding Source for a work in source code form is that same work 2 Basic Permissions All rights granted under this License are granted for the term of copyright on the Program and are irrevocable provided the stated conditions are met This License explicitly affirms your unlimited permission to run the unmodified Program The output from running a covered work is covered by this License only if the output given its content constitutes a covered work This License acknowledges your rights of fair use or other equivalent as provided by copyright law You may make run and propagate covered works that you do not convey without conditions so long as your license otherwise remains in force You may convey covered works to others for the sole purpose of having them make modifications exclusively for you or provide you with facilities for running those works provided that you comply with the terms of this License in conveying all material for which you do not control copyright Those thus making or running the covered works for you must do so exclusively on your behalf under your direction and control on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you Conveying under any other circumstances is permitted solely under the conditions stated below Sub
305. ne in Glibc with macros that depend on proprietary language extensions can be implemented in pristine Standard C For example the chapter 25 algorithms and even C library functions such as strchr can be specialized for the case of static arrays of known small size Detailed optimization opportunities are identified below where the component where they would appear is discussed Of course new opportunities will be identified during implementation Unimplemented Required Library Features x he standard specifies hundreds of components grouped broadly by chapter These are listed in excruciating detail in the CHECKLIST file 17 general 18 support 19 diagnostics 20 utilities 21 string 22 locale 23 containers 24 iterators 25 algorithms 26 numerics 27 iostreams Annex D backward compatibility Anyone participating in implementation of the library should obtain a copy of the standard ISO 14882 People in the U S can obtain an electronic copy for US 18 from ANSI s web site Those from other countries should visit http www iso org to find out the location of their country s representation in ISO in order to know who can sell them a copy The emphasis in the following sections is on unimplemented features and optimization opportunities Chapter 17 General The GNU C Library 179 253 Chapter 17 concerns overall library requirements The standard doesn t mention
306. newer compilers is problematic AC_TRY_COMPILE include lt new h gt include lt iterator h gt include lt alloc h gt include lt set h gt include lt hashtable h gt include lt hash_set h gt include lt fstream h gt include lt tempbuf h gt include lt istream h gt include lt bvector h gt include lt stack h gt include lt rope h gt include lt complex h gt include lt ostream h gt include lt heap h gt include lt iostream h gt include lt function h gt include lt multimap h gt include lt pair h gt include lt stream h gt include lt iomanip h gt include lt slist h gt include lt tree h gt include lt vector h gt include lt deque h gt include lt multiset h gt include lt list h gt include lt map h gt include lt algobase h gt include lt hash_map h gt include lt algo h gt include lt queue h gt include lt streambuf h gt vr ac_cv_cxx_pre_stdcxx yes ac_cv_cxx_pre_stdcxx no CXXFLAGS Sac_save_CXXFLAGS AC_LANG_RESTORE 19 if test Sac_cv_cxx_pre_stdcxx yes then AC_DEFINE PRE_STDCXX_HEADERS Define if pre ISO C header files are present feels 1 Porting between pre ISO headers and ISO headers is simple headers like vector h can be replaced with vector and a using directive using namespace std can be put at the global scope This should be enough to get this code compiling assuming the other usage
307. ngle NOT void mangle wrong Reason no space before parentheses except after a control flow keyword is near universal practice for C It identifies the parentheses as the function call operator or declarator as opposed to an expression or other overloaded use of parentheses 04 Template function indentation template lt typename T gt void template_function args NOT template lt class T gt void template _function args Reason In class definitions without indentation whitespace is needed both above and below the declaration to distinguish it visually from other members Also re typename rather than class T often could be int which is not a class class here is an anachronism poe 05 Template class indentation template lt typename _CharT typename _Traits gt class basic_ios public ios_base public Types y NOT template lt class _CharT class _Traits gt class basic_ios public ios_base public Types The GNU C Library 163 253 y NOT template lt class _CharT class _Traits gt class basic_ios public ios_base public Types 06 Enumerators enum space _ISspace print _ISprint entrl _ISentrl y NOT enum space _ISspace print _ISprint cntrl _IScntrl 07 Member initialization lists All one line separate from class name gribbl
308. ngle objects ONLY For all n belonging to gt 1 the operator delete is called without further ado and the deallocate function returns However for n 1 a series of steps are performed 1 We first need to locate that super block which holds the memory location given to us by the user For that purpose we maintain a static variable _S_last_dealloc_index which holds the index into the vector of block pairs which indicates the index of the last super block from which memory was freed We use this strategy in the hope that the user will deallocate memory in a region close to what he she deallocated the last time around If the check for belongs_to succeeds then we determine the bit map for the given pointer and locate the index into that bit map and mark that bit as free by setting it 2 If the _S_last_dealloc_index does not point to the memory block that we re looking for then we do a linear search on the block stored in the vector of Block Pairs This vector in code is called _S_mem_blocks When the corresponding super block is found we apply the same procedure as we did for 1 to mark the block as free in the bit map Now whenever a block is freed the use count of that particular super block goes down by 1 When this use count hits 0 we remove that super block from the list of all valid super blocks stored in the vector While doing this we also make sure that the basic invariant is maintained by making sure that _S_last_request and _S_l
309. no longer a firm requirement On the other hand including the C style header lt cmath gt guarantees that the entities will be found in namespace std and perhaps in the global namespace Usage of C style headers is recommended as then C linkage names can be disambiguated by explicit qualification such as by std abort In addition the C style headers can use function overloading to provide a simpler interface to certain families of C functions For instance in lt cmath gt the function std sin has overloads for all the builtin floating point types This means that std sin can be used uniformly instead of a combination of std sinf std sin and std sinl 3 2 4 Precompiled Headers There are three base header files that are provided They can be used to precompile the standard headers and extensions into binary files that may the be used to speed compiles that use these headers s stdc h Includes all standard headers Actual content varies depending on language dialect e stdtrlc h Includes all of lt stdc h gt and adds all the TR1 headers s extc h Includes all of lt stdtr1c h gt and adds all the Extension headers How to construct a gch file from one of these base header files First find the include directory for the compiler One way to do this is Garr asilo ce include lt gt search starts here mnt share bld H x86 gcec 20071201 include ct 4 3 0 auel OE searca Lieti Th
310. ns manipulate the bitmaps and have nothing to do with the memory that is given to the user As I have earlier mentioned a 1 in the bitmap s bit field indicates free while a 0 indicates allocated This lets us check 32 bits at a time to check whether there is at lease one free block in those 32 blocks by testing for equality with 0 Now the allocate function will given a memory block find the corresponding bit in the bitmap and will reset it i e make it re set 0 And when the deallocate function is called it will again set that bit after locating it to indicate that that particular block corresponding to this bit in the bit map is not being used by anyone and may be used to satisfy future requests e g Consider a bit map of 64 bits as represented below 111111111111111111111111111111111111111111111111111111111111111 Now when the first request for allocation of a single object comes along the first block in address order is returned And since the bit maps in the reverse order to that of the address order the last bit LSB if the bit map is considered as a binary word of 64 bits 1s re set to 0 The bit map now looks like this 1111111111111111111111111111111111111111111111111111111111111110 The GNU C Library 140 253 20 2 2 8 Locality Another issue would be whether to keep the all bitmaps in a separate area in memory or to keep them near the actual blocks that will be given out or allocated for the client After some testing
311. nswer remain useful instructional tools however Added September 2000 James Kanze provided a link to a Unicode Technical Report discussing case handling which provides some very good information The GNU C Library 56 253 7 1 3 Arbitrary Character Types The std basic_string is tantalizingly general in that it is parameterized on the type of the characters which it holds In theory you could whip up a Unicode character class and instantiate std basic_string lt my_unicode_char gt or assuming that integers are wider than characters on your platform maybe just declare variables of type std basic_stri ng lt int gt That s the theory Remember however that basic_string has additional type parameters which take default arguments based on the character type called CharT here template lt typename CharT typename Traits char_traits lt CharT gt typename Alloc allocator lt CharT gt gt class Josie sure dl cess IF Now allocator lt CharT gt will probably Do The Right Thing by default unless you need to implement your own allocator for your characters But char_traits takes more work The char_traits template is declared but not defined That means there is only template lt typename CharT gt struct char traits static void foo typel x type2 y y and functions such as char_traits lt CharT gt foo are not actually defined anywhere for the general case The C standard permits this because
312. nternal implementation use These macros cannot be redefined A select handful of macros control libstdc extensions and extra features or provide versioning information for the API Only those macros listed below are offered for consideration by the general public Below is the macro which users may check for library version information ___GLIBCXxX__ The current version of libstdc in compressed ISO date format form of an unsigned long For details on the value of this particular macro for a particular release please consult this document Below are the macros which users may change with define undef or with D U compiler flags The default state of the symbol is listed Configurable or Not configurable means that the symbol is initially chosen or not based on enable disable options at li brary build and configure time documented here with the various enable disable choices being translated to define undef ABI means that changing from the default value may mean changing the ABI of compiled code In other words these choices control code which has already been compiled 1 e in a binary such as libstdc a so If you explicitly define or undef these macros the headers may see different code paths but the libraries which you link against will not Experimenting with different values with the expectation of consistent linkage requires changing the config headers before building installing the library
313. ntuitive it destroys the character string on which it operates and it requires you to handle all the memory problems But it does let the client code decide what to use to break the string into pieces it allows you to choose the whitespace so to speak A C implementation lets us keep the good things and fix those annoyances The implementation here is more intuitive you only call it once not in a loop with varying argument it does not affect the original string at all and all the memory allocation is handled for you It s called stringtok and it s a template function Sources are as below in a less portable form than it could be to keep this example simple for example see the comments on what kind of string it will accept include lt string gt template lt typename Container gt void The GNU C Library 57 253 stringtok Container amp container string const in const char const delimiters tin const string size_type len in length string size_type i 0 z hile i lt len Eat leading whitespace Pei cia Eiest not Chas liners e IS Mn pos return Nothing left but white space Find the end of the token string size_type j in find first_of delimiters i Push token abe a she sealinve ENIE container push_back in substr i return else container push_back in substr i j i Set up for next loop 19T The author uses a more genera
314. o e g cppbits In files throughout the system lines marked with an XXX indicate a bug or incompletely implemented feature Lines marked XXX MT The GNU C Library 158 253 indicate a place that may require attention for multi thread safety A 3 Coding Style A 3 1 Bad Identifiers Identifiers that conflict and should be avoided This is the list of names reserved to the implementation that have been claimed by certain compilers and system headers of interest and should not be used in the library It will grow of course We generally are interested in names that are not all caps except for those like T For Solaris B Q i Z Ax GQ U E N Be Irix adds BSD adds __used _ unused __ inline _Complex __istype __maskrune __tolower __toupper _ wchar_t _ wint_t _res _res_ext __tg_ SPU adds ea For GCC The GNU C Library 159 253 Note that this list is out of date It applies to the old name mangling in G 3 0 and higher a different name mangling is used In addition many of the bugs relating to G interpreting these names as Operators have been fixed The full set of __ identifiers combined from gcc cp lex c and gcc cplus dem c that are either old or new but are definitely recognized by the demangler is _ apl __ array _ ars _ arshift _as __bit_and _ bit_ior __ bit_not _ bit_xor _ Call el _ cm en _ co _ component ___ comp
315. o need to sync with the C streams The right thing to do in this case is to call include any of the I O headers such as ios iostream etc std ios sync_with_stdio false You must do this before performing any I O via the C stream objects Once you call this the C streams will operate independently of the unused C streams For GCC 3 x this means that cout and company will become fully buffered on their own Note by the way that the synchronization requirement only applies to the standard streams cin cout cerr clog and their wide character counterchapters File stream objects that you declare yourself have no such requirement and are fully buffered The GNU C Library 94 253 Chapter 14 Atomics Facilities for atomic operations 14 1 API Reference All items are declared in the standard header file atomic Set of typedefs that map int to atomic_int and so on for all builtin integral types Global enumeration memory_order to control memory ordering Also includes atomic a class template with member functions such as load and store that is instantiable such that atomic_int is the base class of atomic lt int gt Full API details The GNU C Library 95 253 Chapter 15 Concurrency Facilities for concurrent operation and control thereof 15 1 API Reference All items are declared in one of four standard header files In header mut ex class template mut ex and variants class once_f lag a
316. o what is referred to as the global pool thread id 0 No thread may be assigned this id since they span from 1 to _S_max_threads in a MT application When the application requests memory calling allocate we first look at the requested size and if this is gt _S_max_bytes we call new directly and return If the requested size is within limits we start by finding out from which bin we should serve this request by looking in _S_binmap INSEE Ie SOS thread_id 3 DATA NEXE thread_id 3 DATA _S_bin A pointer to here is what is returned to the 3 as 3 points here the application when needed If next NULL it s the last one on the list The GNU C Library 135 253 A quick look at _S_bin bin first O tells us if there are any blocks of this size on the freelist 0 If this is not NULL fine just remove the block that _S_bin bin first O points to from the list update _S_bin bin first O and return a pointer to that blocks data If the freelist is empty the pointer is NULL we must get memory from the system and build us a freelist within this memory All requests for new memory is made in chunks of _S_chunk_size Knowing the size of a block_record and the bytes that this bin stores we then calculate how many blocks we can create within this chunk build the list remove the first block update the pointer _S_bin bin first O and return a p
317. oblem For example requirements to preserve the original author s copyright notice the distribution terms or the list of authors are ok It is also no problem to require modified versions to include notice that they were modified even to have entire sections that may not be deleted or changed as long as these sections deal with nontechnical topics Some GNU manuals have them The GNU C Library 238 253 These kinds of restrictions are not a problem because as a practical matter they don t stop the conscientious programmer from adapting the manual to fit the modified program In other words they don t block the free software community from making full use of the manual However it must be possible to modify all the technical content of the manual and then distribute the result in all the usual media through all the usual channels otherwise the restrictions do block the community the manual is not free and so we need another manual Unfortunately it is often hard to find someone to write another manual when a proprietary manual exists The obstacle is that many users think that a proprietary manual is good enough so they don t see the need to write a free manual They do not see that the free operating system has a gap that needs filling Why do users think that proprietary manuals are good enough Some have not considered the issue I hope this article will do something to change that Other users consider proprietary m
318. ode e std accumulate e std adjacent_difference e std inner_product e std partial_sum The following library components in the include algorithm are included in the parallel mode e std adjacent_find e std count stds count_it e std equal std find e std find_if e std find_first_of std for_each e std generate e std generate_n e std lexicographical_compare e std mismatch e std search The GNU C Library 109 253 e std search_n e std transform e std replace e std replace_1if e std max_element e std merge e std min_element e std nth_element e std partial_sort e std partition e std random_shuffle e std set_union e std set_intersection e std set_symmetric_difference e std set_difference std sort e std stable_sort e std unique_copy 18 2 Semantics The parallel mode STL algorithms are currently not exception safe i e user defined functors must not throw exceptions Also the order of execution is not guaranteed for some functions of course Therefore user defined functors should not have any concurrent side effects Since the current GCC OpenMP implementation does not support OpenMP parallel regions in concurrent threads it is not possible to call parallel STL algorithm in concurrent threads either It might work with other compilers though 18 3 Using 18 3 1 Prerequisite Compiler Flags Any use of pa
319. of Normative Addendum 1 Extended Character Sets 41 Bruno Haible uri The Unicode HOWTO 42 Markus Khun uri UTF 8 and Unicode FAQ for Unix Linux 8 2 3 messages The std messages facet implements message retrieval functionality equivalent to Java s java text MessageFormat using either GNU gettext or IEEE 1003 1 200 functions 8 2 3 1 Requirements The std messages facet is probably the most vaguely defined facet in the standard library It s assumed that this facility was built into the standard library in order to convert string literals from one locale to the other For instance converting the C locale s const char c please to a German localized bitte during program execution 22 2 7 1 Template class messages lib locale messages This class has three public member functions which directly correspond to three protected virtual member functions The public member functions are catalog open const stringg const locales const string_type get catalog int int const string _typeg const void close catalog const While the virtual functions are catalog do_open const string amp const locales const The GNU C Library 73 253 1 Returns A value that may be passed to get to retrieve a message from the message catalog identified by the string name according to an implementation defined mapping The result can be used until it is passed to close Returns a value less than 0 if no such catal
320. of thread safety The library strives to be thread safe when all of the following conditions are met e The system s libc is itself thread safe e The compiler in use reports a thread model other than single This can be tested via output from gcc v Multi thread capable versions of gcc output something like this ee y Using built in specs Thread model posix gcc version 4 1 2 20070925 Red Hat 4 1 2 33 Look for Thread model lines that aren t equal to single e Requisite command line flags are used for atomic operations and threading Examples of this include pthread and mar ch nat ive although specifics vary depending on the host environment See Machine Dependent Options e An implementation of atomicity h functions exists for the architecture in question See the internals documentation for more details The user code must guard against concurrent method calls which may access any particular library object s state Typically the application programmer may infer what object locks must be held based on the objects referenced in a method call Without getting into great detail here is an example which requires user level locks library_class_a shared_object_a thread_main library_class_b xobject_b new library_class_b shared_object_a add_b object_b must hold lock for shared_object_a shared_object_a mutate must hold lock for shared_object_a Multiple copies of thread_main are star
321. og can be opened string_type do_get catalog int int const string_type amp const 3 Requires A catalog cat obtained from open and not yet closed 4 Returns A message identified by arguments set msgid and dfault according to an implementation defined mapping If no such message can be found returns dfault void do_close catalog const 5 Requires A catalog cat obtained from open and not yet closed 6 Effects Releases unspecified resources associated with cat 7 Notes The limit on such resources if any is implementation defined 8 2 3 2 Design A couple of notes on the standard First why is messages_base catalog specified as a typedef to int This makes sense for implementations that use catopen but not for others Fortunately it s not heavily used and so only a minor irritant Second by making the member functions const it is impossible to save state in them Thus storing away information used in the open member function for use in get is impossible This is unfortunate The open member function in particular seems to be oddly designed The signature seems quite peculiar Why specify a co nst string argument for instance instead of just const char Or why specify a const locales argument that is to be used in the get member function How exactly is this locale argument useful What was the intent It might make sense if a locale argument was associated with a given default
322. ointer to that blocks data Deallocation is equally simple the pointer is casted back to a block_record pointer lookup which bin to use based on the size add the block to the front of the global freelist and update the pointer as needed _S_bin bin first O The decision to add deallocated blocks to the front of the freelist was made after a set of performance measurements that showed that this is roughly 10 faster than maintaining a set of last pointers as well 20 1 5 Multiple Thread Example In the ST example we never used the thread_id variable present in each block Let s start by explaining the purpose of this in a MT application The concept of ownership was introduced since many MT applications allocate and deallocate memory to shared containers from different threads such as a cache shared amongst all threads This introduces a problem if the allocator only returns memory to the current threads freelist I e there might be one thread doing all the allocation and thus obtaining ever more memory from the system and another thread that is getting a longer and longer freelist this will in the end consume all available memory Each time a block is moved from the global list where ownership is irrelevant to a threads freelist or when a new freelist is built from a chunk directly onto a threads freelist or when a deallocation occurs on a block which was not allocated by the same thread id as the one doing the deallocation
323. ok A 4 2 1 Prerequisites Editing the DocBook sources requires an XML editor Many exist some notable options include emacs Kate or Conglomerate Some editors support special XML Validation modes that can validate the file as it is produced Recommended is the nXML Mode for emacs Besides an editor additional DocBook files and XML tools are also required Access to the DocBook stylesheets and DTD is required The stylesheets are usually packaged by vendor in something like docbook style xs1 To exactly match generated output please use a version of the stylesheets equivalent to docbook style x 74 0 5 The installation directory for this package corresponds to the XSL_STYLE_DIR in doc Makefile am and de faults to usr share sgml docbook xsl stylesheets For processing XML an XML processor and some style sheets are necessary Defaults are xsltproc provided by libxslt For validating the XML document you ll need something like xmllint and access to the DocBook DTD These are provided by a vendor package like 1ibxm12 For PDF output something that transforms valid XML to PDF is required Possible solutions include dblatex xmlto or prince Other options are listed on the DocBook web pages Please consult the libstdc 0 gcc enu org list when preparing printed manuals for current best practice and suggestions Make sure that the XML documentation and markup is valid for any change This can be done easily with the validatio
324. om Allocators Writing a portable C allocator would dictate that the interface would look much like the one specified for allocator Additional member functions but not subtractions would be permissible Probably the best place to start would be to copy one of the extension allocators say a simple one like new_allocator 6 3 1 6 Extension Allocators Several other allocators are provided as part of this implementation The location of the extension allocators and their names have changed but in all cases functionality is equivalent Starting with gcc 3 4 all extension allocators are standard style Before this point SGI style was the norm Because of this the number of template arguments also changed Here s a simple chart to track the changes More details on each of these extension allocators follows l new_allocator Simply wraps operator newand operator delete 2 malloc_allocator Simply wraps malloc and free There is also a hook for an out of memory handler for new de let e this is taken care of elsewhere 3 array_allocator Allows allocations of known and fixed sizes using existing global or external storage allocated via construction of std tr1l array objects By using this allocator fixed size containers including std string can be used without instances calling operator new and operator delete This capability allows the use of STL abstractions without runtime complications or overhead even i
325. on module above was checked out So if checked out to home maude gdb_printers the path would be as written in the example below python import sys sys path insert 0 home maude gdb_printers python from libstdcxx v6 printers import register_libstdcxx_printers register_libstdcxx_printers None end The path should be the only element that needs to be adjusted in the example Once loaded STL classes that the printers support should print in a more human readable format To print the classes in the old style use the r raw switch in the print command i e print r foo This will print the classes as if the Python pretty printers were not loaded For additional information on STL support and GDB please visit GDB Support for STL in the GDB wiki Additionally in depth documentation and discussion of the pretty printing feature can be found in Pretty Printing node in the GDB manual You can find on line versions of the GDB user manual in GDB s homepage at GDB The GNU Project Debugger The GNU C Library 35 253 3 8 5 Tracking uncaught exceptions The verbose termination handler gives information about uncaught exceptions which are killing the program It is described in the linked to page 3 8 6 Debug Mode The Debug Mode has compile and run time checks for many containers 3 8 7 Compile Time Checking The Compile Time Checks Extension has compile time checks for many algorithms 3 8 8 Profile based
326. on of config h It is versioned as follows gec 3 0 0 3 0 0 gcc 3 0 1 3 0 0 Error should be 3 0 1 gcc 3 0 2 3 0 0 Error should be 3 0 2 gcc 3 0 3 3 0 0 Error should be 3 0 3 gcc 3 0 4 3 0 0 Error should be 3 0 4 gcec 3 1 0 3 1 0 gcc 3 1 1 3 1 1 gec 3 2 0 3 2 gec 3 2 1 3 2 1 gcc 3 2 2 3 2 2 gcec 3 2 3 3 2 3 gec 3 3 0 3 3 gcc 3 3 1 3 3 1 gcc 3 3 2 3 3 2 gec 3 3 3 3 3 3 gcc 3 4 x version unused gec 4 0 5 x version unused The GNU C Library 212 253 9 Matching each specific C compiler release to a specific set of C include files This is only implemented in gcc 3 1 1 releases and higher All C includes are installed in include c then nest in a directory hierarchy corresponding to the C compiler s released version This version corresponds to the variable gcc_version in libstdc acinclude m4 and more details can be found in that file s macro GLIBCXX_CONFIGURE GLIBCPP_CONFIGURE before gcc 3 4 0 C includes are versioned as follows gcec 3 0 0 include g v3 gcec 3 0 1 include g v3 gcec 3 0 2 include g v3 gec 3 0 3 include g v3 gcc 3 0 4 include g v3 gec 3 1 0 include g v3 gcec 3 1 1 include c 3 1 1 gec 3 2 0 include c 3 2 gec 3 2 1 include c 3 2 1 gec 3 2 2 include c 3 2 2 gec 3 2 3 include c 3 2 3 gec 3 3 0 include c 3 3 gec 3 3 1 include c 3 3 1 gec 3 3 2 includ
327. on the target processor see Atomic Builtins The reference counts are maintained using a lock free algorithm and GCC s atomic builtins which provide the required memory synchronisation 2 _S_Mutex The _Sp_counted_base specialization for this policy contains a mutex which is locked in add_ref_lock This policy is used when GCC s atomic builtins aren t available so explicit memory barriers are needed in places 3 _S_Single This policy uses a non reentrant add_ref_lock with no locking It is used when libstdc is built without enable threads The GNU C Library 52 253 For all three policies reference count increments and decrements are done via the functions in ext atomicity h which detect 1f the program is multi threaded If only one thread of execution exists in the program then less expensive non atomic operations are used 6 3 3 3 4 Dual C 0x and TR1 Implementation The classes derived from _Sp_counted_base see Class Hierarchy below and __shared_count are implemented sep arately for C 0x and TRI in bits boost_sp_shared_count h and tr1 boost_sp_shared_count h respec tively All other classes including _Sp_counted_base are shared by both implementations The TR1 implementation is considered relatively stable so is unlikely to change unless bug fixes require it If the code that is common to both C 0x and TR modes needs to diverge further then it might be necessary to duplicate additional classes and
328. on to the other topics on this page we ll note here some of the C99 features that appear in libstdc The C99 features depend on the enable c99 configure flag This flag is already on by default but it can be disabled by the user Also the configuration machinery will disable it if the necessary support for C99 e g header files cannot be found As of GCC 3 0 C99 support includes classification functions such as isnormal isgreater isnan etc The functions used for long long support such as st rto11 are supported as is the 1 1div_t typedef Also supported are the wide character functions using long long like wcsto11 The GNU C Library 87 253 Chapter 13 Input and Output 13 1 lostream Objects To minimize the time you have to wait on the compiler it s good to only include the headers you really need Many people simply include lt iostream gt when they don t need to and that can penalize your runtime as well Here are some tips on which header to use for which situations starting with the simplest lt iosfwd gt should be included whenever you simply need the name of an I O related class such as ofstream or basic_streambuf Like the name implies these are forward declarations A word to all you fellow old school programmers trying to forward de clare classes like class istream won t work Look in the iosfwd header if you d like to know why For example include lt iosfwd gt class My
329. onditions or cascading catch blocks that dispatch error handling or recovery efforts based on the type of exception object thrown Oh and by the way none of this hackery is at all special Although perhaps well deserving of a raised eyebrow Support continues to evolve and may change in the future Similar and even additional techniques are used in other C libraries and compilers C hackers with a bent for language and control flow purity have been successfully consoled by grizzled C veterans lamenting the substitution of the C language keyword const with the uglified doppelganger __ const 3 7 4 Compatibility 3 7 4 1 With C C language code that is expecting to interoperate with C should be compiled with fexceptions This will make debugging a C language function called as part of C induced stack unwinding possible In particular unwinding into a frame with no exception handling data will cause a runtime abort If the unwinder runs out of unwind info before it finds a handler std terminate is called Please note that most development environments should take care of getting these details right For GNU systems all appropriate parts of the GNU C library are already compiled with fexceptions 3 7 4 2 With POSIX thread cancellation GNU systems re use some of the exception handling mechanisms to track control flow for POSIX thread cancellation Cancellation points are functions defined by POSIX as worthy of special treatm
330. onditions whatsoever to those of this License You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute However you may accept compensation in exchange for copies If you distribute a large enough number of copies you must also follow the conditions in section 3 You may also lend copies under the same conditions stated above and you may publicly display copies 3 COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Document numbering more than 100 and the Document s license notice requires Cover Texts you must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Document and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too voluminous to fit legibly you should put the first ones listed as many as fit reasonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute O
331. onforming 3 2 3 Class decimal64 Partial extension for conversion from scalar decimal floating point Missing 3 2 4 5 conversion to integral type conforming 3 2 4 Class decimal128 Partial extension for conversion from scalar decimal floating point 325 Initialization from Y coefficient and exponent 326 Conversion to generic Y floating point type 3 2 7 Unary arithmetic operators Y 3 2 8 Binary arithmetic operators Y 3 2 9 Comparison operators Y 3 2 10 Formatted input N 3 2 11 Formatted output N 33 Additions to header N limits 34 Headers cfloat and float h 342 Additions to header Y cfloat synopsis Additions to header Tap float h synopsis N 3 4 4 Maximum finite value Y 3 4 5 Epsilon Y 346 Minimum positive normal Y value 347 Minimum positive Y subnormal value 3 4 8 Evaluation format Y 3 5 O OE Outside the scope of GCC fenv h 3 6 AO O PEDO Outside the scope of GCC math h 3 7 Additions PES TORO das Outside the scope of GCC stdio h Additions to cstdlib and A 3 8 AN Outside the scope of GCC 3 9 O Ao Outside the scope of GCC wchar h 3 10 Facets N ae ae mm AT The GNU C Library 8 253 1 2 1 The Code GPL The source code is distributed under the GNU General Public License version 3 with the addition under section 7 of an exception described in the GCC Runtime Library Exception version 3 1 as follows or see the file COPYING RUNTIME GCC RUNTIME LIBRARY EXCEPTION T Version 3 1
332. only make changes to the C 0x versions 6 3 3 3 5 Related functions and classes dynamic_pointer_cast static_pointer_cast const_pointer_cast As noted in N2351 these functions can be implemented non intrusively using the alias constructor However the aliasing constructor is only available in C 0x mode so in TR mode these casts rely on three non standard constructors in shared_ptr and __shared_ptr In C 0x mode these constructors and the related tag types are not needed enable_shared_from_this The clever overload to detect a base class of type enable_shared_from_this comes straight from Boost There is an extra overload for__enable_shared_from_this to work smoothly with __sha red_ptr lt Tp Lp gt using any lock policy make_shared allocate_shared make_shared simply forwards to allocate_shared with std allocator as the allocator Although these functions can be implemented non intrusively using the alias constructor if they have access to the implementation then it is possible to save storage and reduce the number of heap allocations The newly constructed object and the _Sp_counted_ can be allocated in a single block and the standard says implementations are encouraged but not required to do so This implementation provides additional non standard constructors selected with the type _Sp_make_shared_tag which create an object of type _Sp_counted_ptr_inplace to hold the new object The returned shared prt r lt A gt needs to know t
333. or run a copy of the Program Ancillary propagation of a covered work occurring solely as a consequence of using peer to peer transmission to receive a copy likewise does not require acceptance However nothing other than this License grants you permission to propagate or modify any covered work These actions infringe copyright if you do not accept this License Therefore by modifying or propagating a covered work you indicate your acceptance of this License to do so 10 Automatic Licensing of Downstream Recipients Each time you convey a covered work the recipient automatically receives a license from the original licensors to run modify and propagate that work subject to this License You are not responsible for enforcing compliance by third parties with this License An entity transaction is a transaction transferring control of an organization or substantially all assets of one or subdividing an organization or merging organizations If propagation of a covered work results from an entity transaction each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party s predecessor in interest had or could give under the previous paragraph plus a right to possession of the Corresponding Source of the work from the predecessor in interest if the predecessor has it or can get it with reasonable efforts You may not impose any further restrictions on the exercise of the rights grante
334. ot see many of the template definitions they now see and rely instead on ready instantiated specializations in the library This technique would be useful for the following substantial components string locale iostreams valarray It would xnotx be useful or usable with the following containers algorithms iterators allocator Since these constitute a large though decreasing fraction of the library the benefit the technique offers is limited The language specifies the semantics of the export keyword but the gcc compiler does not yet support it When it does problems with large template inclusions can largely disappear given some minor library reorganization along with the need for the apparatus described above Overhead Flexibility Cost The library offers many places where users can specify operations to be performed by the library in place of defaults Sometimes this seems to require that the library use a more roundabout and possibly slower way to accomplish the default requirements than would be used otherwis The primary protection against this overhead is thorough compiler optimization to crush out layers of inline function interfaces Kuck amp Associates has demonstrated the practicality of this kind of optimization The second line of defense against this overhead is explicit specialization By defining helper function templates and writing specialized code for the default case o
335. ound __cond _ convert delete aL dv eq __method_call o mi min The GNU C Library 160 253 _ minus ml _ mm mn _ mult mx ne __negate __new nop nt nw 00 op _ plus __ postdecrement __ postincrement PP pt rf _ rm _ Ys SZ __trunc_div __trunc_mod __truth_andif _ truth_not __truth_orif vc vd vn SGI badnames __builtin_alloca builtin_fsqrt _ builtin sqrt builtin_fabs builtin_dabs _ builtin_cast_ builtin_cast_ __ builtin_cast_d211 builtin_cast_112d builtin_copy_dhi2i __builtin_copy_i2dhi builtin_copy_dlo2i __builtin_copy_i2dlo __add_and_fetch sub_and_fetch __or_and _fetch __xor_and_fetch __and_and_fetch __nand_and_fetch __mpy_and_fetch _ min and Let O _ max and_fetc S 5 The GNU C Library A 3 2 fetch_and_add fetch_and_sub fetch_and_or fetch_and_xor fetch_and_and fetch_and_nand fetch_and_mpy fetch_and_min fetch_and_max lock_test_and_set lock_release __lock_acquire _ compare_and_swap __ synchronize __high_multiply _ unix sgi _ linux __i386__ _i486__ _ cplusplus __ embedded_cplusplus long double conversion members mangled as __opr http gcc gnu org ml libstdc 1999 q4 msg00060 html opr By Example This library is written to appropriate C coding standards As such it is intended to precede the recommendations of the
336. overloaded functions rather than a single function 17 Bad bool parsing Apparently extracting Boolean values was messed up 19 Noconv definition too vague If codecvt do_in returns noconv there are no changes to the values in to to _limit 22 Member open vs flags Re opening a file stream does not clear the state flags 23 Num_get overflow result Implement the proposed resolution 25 String operator lt lt uses width value wrong Padding issues 48 Use of non existent exception constructor An instance of ios_base failure is constructed instead 49 Underspecification of ios_base sync_with_stdio The return type is the previous state of synchronization 50 Copy constructor and assignment operator of ios_base These members functions are declared private and are thus in accessible Specifying the correct semantics of copying stream state was deemed too complicated 60 What is a formatted input function This DR made many widespread changes to basic_istream and basic_ost ream all of which have been implemented 63 Exception handling policy for unformatted output Make the policy consistent with that of formatted input unformatted input and formatted output 68 Extractors for char should store null at end And they do now An editing glitch in the last item in the list of 27 6 1 2 3 7 74 Garbled text for codecvt do_max_length The text of the standard was gibberish Typos gone rampant 75 Contradiction in codecvt
337. p the manual instantiation files into dozens upon dozens of little files each compiled separately but an abortive attempt at this was done for lt string gt and though it is far from complete it is already a nuisance A better interim solution just until we have export is badly needed When building a shared library the current compiler linker cannot automatically generate the instantiations needed This creates a miserable situation it means any time something is changed in the library before a shared library can be built someone must manually The GNU C Library 177 253 copy the declarations of all templates that are needed by other parts of the library to an instantiation file and add it to the build system to be compiled and linked to the library This process is readily automated and should be automated as soon as possible Users building their own shared libraries experience identical frustrations Sharing common aspects of template definitions among instantiations can radically reduce code bloat The compiler could help a great deal here by recognizing when a function depends on nothing about a template parameter or only on its size and giving the resulting function a link name equate that allows it to be shared with other instantiations Implementation code could take advantage of the capability by factoring out code that does not depend on the template argumen
338. p uscar 0 endif X temp iss gt gt temp le Ass tarli throw runtime _error any temo Another example of using stringstreams is in this howto There is additional information in the libstdc v2 info files in particular info iostream B 6 2 9 Little or no wide character support Classes wst ring and char_traits lt wchar_t gt are not supported 226 253 The GNU C Library 227 253 B 6 2 10 No templatized iostreams Classes wfilebuf and wstringstream are not supported B 6 2 11 Thread safety issues Earlier GCC releases had a somewhat different approach to threading configuration and proper compilation Before GCC 3 0 configuration of the threading model was dictated by compiler command line options and macros both of which were somewhat thread implementation and port specific There were no guarantees related to being able to link code compiled with one set of options and macro setting with another set For GCC 3 0 configuration of the threading model used with libraries and user code is performed when GCC is configured and built using the enable threads and disable threads options The ABI is stable for symbol name mangling and limited functional compatibility exists between code compiled under different threading models The libstdc library has been designed so that it can be used in multithreaded applications with libstdc v2 this was only true of the STL parts The fi
339. paque copies of the Document numbering more than 100 you must either include a machine readable Transparent copy along with each Opaque copy or state in or with each Opaque copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent The GNU C Library 250 253 copy of the Document free of added material If you use the latter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public It is requested but not required that you contact the authors of the Document well before redistributing any large number of copies to give them a chance to provide you with an updated version of the Document 4 MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provided that you release the Modified Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it In addition you must do these things in the Modified Version A Use in the Title Page and on the cove
340. part of a callback event When closing the underlying file basic_filebuf close will swallow non cancellation exceptions thrown and return NULL s Thread The constructors of thread that take a callable function argument swallow all exceptions resulting from executing the function argument 3 7 3 Doing without C is a language that strives to be as efficient as is possible in delivering features As such considerable care is used by both language implementer and designers to make sure unused features not impose hidden or unexpected costs The GNU system tries to be as flexible and as configurable as possible So it should come as no surprise that GNU C provides an optional language extension spelled fno exceptions as a way to excise the implicitly generated magic necessary to support try and catch blocks and thrown objects Language support for fno exceptions is documented in the GNU GCC manual Before detailing the library support for fno exceptions first a passing note on the things lost when this flag is used it will break exceptions trying to pass through code compiled with fno exceptions whether or not that code has any t ry or catch constructs If you might have some code that throws you shouldn t use fno exceptions If you have some code that uses try or catch you shouldn t use fno exceptions And what it to be gained tinkering in the back alleys with a language like this Exception handling overhead can be meas
341. peration based on current size and insert position Report instance with high insertion overhead e Cost model Sum cost vector method Sum cost list method for method in push_back insert erase Cost iterate vector Cost iterate list s Example IL Vector sico Wip 2 ixoie ia a Me a lt WOOOOs lt a 4 3 v insert v begin i a o to ae ile comics CnN Myecioj TO Miliisicw mll seve clon 5000000 operations The GNU C Library 126 253 19 7 2 9 List to Vector e Switch _GLIBCXX_PROFILE_LIST_TO_VECTOR e Goal Detect cases where 1 ist could be substituted with vector for better performance e Fundamentals Iterating through a vector is faster than through a list e Sample runtime reduction 64 e Recommendation Replace list with vector at site S e To instrument vector operations and access methods e Analysis Issue the advice if there are no insert operations e Cost model Sum cost vector method Sum cost list method for method in push_back insert erase Cost iterate vector Cost iterate list s Example L Ateca Le 2 ime Suum 07 SE O ES ESO O AO AO Sn e We TT TTI 4 sum x1t Sl foo cc 1 advice Changing list to vector will save about 1000000 indirect memory references 19 7 2 10 List to Forward List Slist e Switch _GLIBCXX_PROFILE_LIST_TO_SLIST e Goal Detect cases where list could be substituted with forward_list for better perfo
342. pport is implied 17 4 4 5 Non reentrant functions are probably best discussed in the various sections on multithreading see above 18 1 4 The type of NULL is described here 18 3 S Even though it s listed in the library sections libstdc has zero control over what the cleanup code hands back to the runtime loader Talk to the compiler people 18 4 2 1 5 bad_alloc 18 5 2 5 bad_cast 18 5 3 5 bad_typeid 18 6 1 8 exception 18 6 2 1 5 bad_exception The what member function of class std exception and these other classes publicly derived from it simply returns the name of the class But they are the mangled names you will need to call c filt and pass the names as command line parameters to demangle them or call a runtime demangler function The classes in lt stdexcept gt have constructors which require an argument to use later for what calls so the problem of what s value does not arise in most user defined exceptions 18 5 1 7 The return value of std type_info name is the mangled type name see the previous entry for more The GNU C Library 3 253 Section Description Status Comments 18 Language support 18 1 Types Y 18 2 Implementation properties Y 18 2 1 Numeric Limits 18 2 1 1 G Y num
343. r non GNU compilers it might be a good idea to check for string at separately The GNU C Library 225 253 B 6 2 5 No std char traits lt char gt eof Use some kind of autoconf test plus this ifdef HAVE_CHAR_TRAITS define CPP_EOF std char_traits lt char gt eof else define CPP_EOF EOF endif B 6 2 6 No string clear There are two functions for deleting the contents of a string clear and erase the latter returns the string void clear _M mutate 0 this gt size 0 basic_string amp rase size_type __pos 0 size_type __n npos return this gt replace _M_check __pos _M_fold __pos iM y _M data _M _data Unfortunately clear is not implemented in this version so you should use erase which is probably faster than operato r charTx B 6 2 7 Removal of ostream form and istream scan extensions These are no longer supported Please use stringstreams instead B 6 2 8 Nobasic_stringbuf basic_stringstream Although the ISO standard i ostringstream classes are provided sst ream for compatibility with older implementa tions the pre ISO i ostrstream strstream interface is also provided with these caveats e strstream is considered to be deprecated e strstream is limited to char e with ostringstream you don t have to take care of terminating the string or freeing its memory e istringstream can be re filled clear str input Yo
344. r than being shared with other instantiations Third some of the flexibility mentioned above comes from virtual functions both in regular classes and template classes which current linkers add to the executable fil ven when they manifestly cannot be called The library is specified to use a language feature exceptions which in the current gcc compiler ABI imposes a run time and code space cost to handle the possibility of exceptions even when they are not used Under the new ABI accessed with fnew abi there is a space overhead and a small reduction in code efficiency resulting from lost optimization opportunities associated with non local branches associated with exceptions What can be done to eliminate this overhead A variety of coding techniques and compiler linker and library improvements and extensions may be used as covered below Most are not difficult and some are already implemented in varying degrees Overhead Compilation Time Providing ready instantiated template code in object code archives allows us to avoid generating and optimizing template instantiations in each compilation unit which uses them However the number of such instantiations that are useful to provide is limited and anyway this is not enough by itself to minimize compilation time In particular it does not reduce time spent parsing conforming headers Quicker header parsing will depend on libra
345. r does not optimize named temporaries out of existence 7 1 2 Case Sensitivity The well known and if it isn t well known it ought to be Guru of the Week discussions held on Usenet covered this topic in January of 1998 Briefly the challenge was write a ci_string class which is identical to the standard string class but is case insensitive in the same way as the common but nonstandard C function stricmp CAS SS AO CU e case insensitive assert s abcde assert s ABCDE still case preserving of course assert stremp s c_str AbCdE assert strcmp s c_str abcde The solution is surprisingly easy The original answer was posted on Usenet and a revised version appears in Herb Sutter s book Exceptional C and on his website as GotW 29 See Told you it was easy Added June 2000 The May 2000 issue of C Report contains a fascinating article by Matt Austern yes the Matt Austern on why case insensitive comparisons are not as easy as they seem and why creating a class is the wrong way to go about it in production code The GotW answer mentions one of the principle difficulties his article mentions more Basically this is easy only if you ignore some things things which may be too important to your program to ignore I chose to ignore them when originally writing this entry and am surprised that nobody ever called me on it The GotW question and a
346. racters Instantiations on mbstate_t perform conversion between en codings known to the library implementor Other encodings can be converted by specializing on a user defined stateT type The stateT object can contain any state that is useful to communicate to or from the specialized do_convert member At this point a couple points become clear One The standard clearly implies that attempts to add non required yet useful and widely used conversions need to do so through the third template parameter stateT Two The required conversions by specifying mbstate_t as the third template parameter imply an implementation strategy that is mostly or wholly based on the underlying C library and the functions mcsrtombs and wesrtombs in particular 8 2 2 2 Design 8 2 2 2 1 wchar_t Size The simple implementation detail of wchar_t s size seems to repeatedly confound people Many systems use a two byte unsigned integral type to represent wide characters and use an internal encoding of Unicode or UCS2 See AIX Microsoft NT Java others Other systems use a four byte unsigned integral type to represent wide characters and use an internal encoding of UCS4 GNU Linux systems using glibc in particular The C programming language and thus C does not specify a specific size for the type wchar_t Thus portable C code cannot assume a byte size or endianness either The GNU C Library 69 253 8 2 2 2 2 Support for Unicode
347. rallel functionality requires additional compiler and runtime support in particular support for OpenMP Adding this support is not difficult just compile your application with the compiler flag fopenmp This will link in 1ibgomp the GNU OpenMP implementation whose presence is mandatory In addition hardware that supports atomic operations and a compiler capable of producing atomic operations is mandatory GCC defaults to no support for atomic operations on some common hardware architectures Activating atomic operations may require explicit compiler flags on some targets like sparc and x86 such as march i686 march native or mcpu v9 See the GCC manual for more information The GNU C Library 110 253 18 3 2 Using Parallel Mode To use the libstdc parallel mode compile your application with the prerequisite flags as detailed above and in addition add D _GLIBCXX_PARALLEL This will convert all use of the standard sequential algorithms to the appropriate parallel equivalents Please note that this doesn t necessarily mean that everything will end up being executed in a parallel manner but rather that the heuristics and settings coded into the parallel versions will be used to determine if all some or no algorithms will be executed using parallel variants Note that the _GLIBCXX_PARALLEL define may change the sizes and behavior of standard class templates such as std search and therefore one can only
348. rams or libraries and other system dependent information 19 5 3 Concurrency Our current model is simplistic but precise We cannot afford to approximate because some of our diagnostics require precise matching of operations to container instance and call context During profiling we keep a single information table per diagnostic There is a single lock per information table 19 5 4 Using the Standard Library in the Instrumentation Implementation As much as we would like to avoid uses of libstdc within our instrumentation library containers such as unordered_map are very appealing We plan to use them as long as they are named properly to avoid ambiguity 19 5 5 Malloc Hooks User applications libraries can provide malloc hooks When the implementation of the malloc hooks uses stdlibc there can be an infinite cycle between the profile mode instrumentation and the malloc hook code We protect against reentrance to the profile mode instrumentation code which should avoid this problem in most cases The protection mechanism is thread safe and exception safe This mechanism does not prevent reentrance to the malloc hook itself which could still result in deadlock if for instance the malloc hook uses non recursive locks XXX A definitive solution to this problem would be for the profile extension to use a custom allocator internally and perhaps not to use libstdc 19 5 6 Construction and Destruction of Global Objects The profiling
349. rations will be faster There are versions of single bit test set reset and flip member functions which do no range checking If we call them member functions of an instantiation of bitset lt N gt then their names and signatures are bitset lt N gt amp _Unchecked_set size_t pos bitset lt N gt amp _Unchecked_set Slade pos nit EJ bitset lt N gt amp _Unchecked_reset size_t pos bitset lt N gt amp _Unchecked_flip SERES OS Ey bool _Unchecked_test size OS Note that these may in fact be removed in the future although we have no present plans to do so and there doesn t seem to be any immediate reason to The semantics of member function operator L are not specified in the C standard A long standing defect report calls for sensible obvious semantics which are already implemented here op on a const bitset returns a bool and for a non const bitset returns a reference a nested type However this implementation does no range checking on the index argument which is in keeping with other containers op L requirements The defect report s proposed resolution calls for range checking to be done We ll just wait and see Finally two additional searching functions have been added They return the index of the first on bit and the index of the first on bit that is after prev respectively Size mime irst const size_t _Find_next size_t prev const The same caveat given for the _Unchecked_ fu
350. re which is most helpful for debugging while dnl d lines just vanish Since the macros in ancilliary files generate code which appears in odd places their outside comments tend to not be useful while reading configure Do not use any target x variables such as St arget_alias The single exception is in configure ac for automake dejagnu s sake B 1 5 The acinclude m4 layout The nice thing about acinclude m4 aclocal m4 is that macros aren t actually performed called expanded whatever here just loaded So we can arrange the contents however we like As of this writing acinclude m4 is arranged as follows GLIBCXX_CHECK_HOST GLIBCXX_TOPREL_CONF IGURE GLIBCXX_CONFIGURE All the major variable discovery is done here CXX multilibs etc fragments included from elsewhere Right now fragments the math linkage bits GLIBCXX_CHECK_COMPILER_FEATURES GLIBCXX_CHECK_LINKER_FEATURES GLIBCXX_CHECK_WCHAR_T_ SUPPORT Next come extra compiler linker feature tests Wide character support was placed here because I couldn t think of another place for it It will probably get broken apart like the math tests because we re still disabling wchars on systems which could actually support them GLIBCXX_CHECK_SETRLIMIT_ancilliary LIBCXX_CHECK_SETRLIMI LIBCXX CHECK S TSREG OR_S LPREG LIBCXX_CHE LIBCXX_CHECK_WRITEV GLIBCXX_CON
351. re Foundation Inc http www fsf org Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed Preamble The GNU General Public License is a free copyleft license for software and other kinds of works The licenses for most software and other practical works are designed to take away your freedom to share and change the works By contrast the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program to make sure it remains free software for all its users We the Free Software Foundation use the GNU General Public License for most of our software it applies also to any other work released this way by its authors You can apply it to your programs too When we speak of free software we are referring to freedom not price Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software and charge for them if you wish that you receive source code or can get it if you want it that you can change the software or use pieces of it in new free programs and that you know you can do these things To protect your rights we need to prevent others from denying you these rights or asking you to surrender the rights Therefore you have certain responsibilities 1f you distribute copies of the software or if you modify it responsibilities to respect the freedom of others For exa
352. re SGI style such classes can be changed to a conforming interface with this wrapper __allocator lt T _ _ alloc gt is thus the same as allocator lt T gt The class allocator used the typedef __alloc to select an underlying allocator that satisfied memory allocation requests The selection of this underlying allocator was not user configurable Allocator 3 4 Header 3 4 Allocator 3 0 3 Header 3 0 3 5 1 t Ll tor oe ee BOERNE AOC Ser std __new_alloc memory locator lt T gt h _ _gnu_cxx malloc ext malloc_ std __malloc_all nenat _allocator lt T gt allocator h oc_template lt int gt gnu_cxx debug_ xt debug_ std debug_alloc lt SMA allocator lt T gt allocator h T gt Y std _ default_al gnu_cxx __pool ext pool_ OE E iener _alloc lt T gt allocator h ae p a y int gt gnu_cxx t__mt_a ext mt_allocator h lloc lt T gt __gnu_cxx bitmap ext bitmap_ _allocator lt T gt allocator h Table B 1 Extension Allocators Releases after gcc 3 4 have continued to add to the collection of available allocators All of these new allocators are standard style The following table includes details along with the first released version of GCC that included the extension allocator Allocator Include Version nu_cxx array_allocat S S ext array_allocator h 4 0 0 or lt T gt nu_cxx throw_allocat i om A ext throw_al
353. rent threads counter And here comes the free and used counters to service Each time a deallocation call is made the length of the current threads freelist is compared to the amount memory in use by this thread Let s go back to the example of an application that has one thread that does all the allocations and one that deallocates Both these threads use say 516 32 byte blocks that was allocated during thread creation for example Their used counters will both say 516 at this point The allocation thread now grabs 1000 32 byte blocks and puts them in a shared container The used counter for this thread is now 1516 The deallocation thread now deallocates 500 of these blocks For each deallocation made the used counter of the allocating thread 1s decreased and the freelist of the deallocation thread gets longer and longer But the calculation made in deallocate will limit the length of the freelist in the deallocation thread to _S_ freelist_headroom of it s used counter In this case when the freelist given that the _S_ freelist_headroom is at it s default value of 10 exceeds 52 516 10 blocks will be returned to the global pool where the allocating thread may pick them up and reuse them In order to reduce lock contention since this requires this bins mutex to be locked this operation is also made in chunks of blocks just like when chunks of blocks are moved from the global freelist to a threads freelist mentioned above The formul
354. result The result is modified and the function returns nothing The GNU C Library 147 253 Chapter 26 Input and Output Extensions allowing ilebufs to be constructed from C types like FILE s and file descriptors 26 1 Derived filebufs The v2 library included non standard extensions to construct std filebufs from C stdio types such as FILExs and POSIX file descriptors Today the recommended way to use stdio types with libstdc IOStreams is via the st dio_filebuf class see below but earlier releases provided slightly different mechanisms 3 0 x ilebufs have another ctor with this signature basic_filebuf __c_file _typex ios_base openmo de int_type This comes in very handy in a number of places such as attaching Unix sockets pipes and anything else which uses file descriptors into the IOStream buffering classes The three arguments are as follows __c file typex F the_c_file_type typedef usually boils down to stdio s FILE ios_base openmode M same as all the other uses of openmode int_type B buffer size defaults to BUFSIZ if not specified For those wanting to use file descriptors instead of FILE s I invite you to contemplate the mysteries of C s fdopen In library snapshot 3 0 95 and later ilebufs bring back an old extension the fd member function The integer returned from this function can be used for whatever file descriptors can be used for on your platform Naturally
355. rious versions and platforms are available on the GCC website in the build status section of each individual release and are also archived on a daily basis on the gcc testresults mailing list Please check either of these places for a similar combination of source version operating system and host CPU B 3 2 2 Variations There are several options for running tests including testing the regression tests testing a subset of the regression tests testing the performance tests testing just compilation testing installed tools etc In addition there is a special rule for checking the exported symbols of the shared library To debug the dejagnu test harness during runs try invoking with a specific argument to the variable RUNTESTFLAGS as below make check target 1libstdc v3 RUNTESTFLAGS v or make check target libstdc v3 RUNTESTFLAGS v y To run a subset of the library tests you will need to generate the testsuite_files file by running make testsuite_files in the libbuilddir testsuite directory described below Edit the file to remove the tests you don t want and then run the testsuite as normal There are two ways to run on a simulator set up DEJAGNU to point to a specially crafted site exp or pass down target_board flags Example flags to pass down for various embedded builds are as follows The GNU C Library 200 253 target powerpc eabism libgloss sim make check target libstdc v3 RUNTEST
356. rmance e Fundamentals The memory footprint of a forward_list is smaller than that of a list This has beneficial effects on memory subsystem e g fewer cache misses e Sample runtime reduction 40 Note that the reduction is only noticeable if the size of the forward_list node is in fact larger than that of the list node For memory allocators with size classes you will only notice an effect when the two node sizes belong to different allocator size classes e Recommendation Replace list with forward_list at site S e To instrument 1ist operations and iteration methods e Analysis Issue the advice if there are no backwards traversals or insertion before a given node e Cost model Always true s Example IS PL ime sur 07 tone Misc Kaine gt 6 8 EST EEE aa Losa ae Y I esorel 2 craralic A sum xit Oe WN e o eagle T Change Hilats ro Mirorayelaol sie o The GNU C Library 127 253 19 7 2 11 Ordered to Unordered Associative Container e Switch _GLIBCXX_PROFILE_ORDERED_TO_UNORDERED e Goal Detect cases where ordered associative containers can be replaced with unordered ones e Fundamentals Insert and search are quicker in a hashtable than in a red black tree e Sample runtime reduction 52 e Recommendation Replace set with unordered_set at site S e To instrument set multiset map mult imap methods e Analysis Issue the advice only if we are not using opera
357. rms of section 4 Replacing Invariant Sections with translations requires special permission from their copyright holders but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections You may include a translation of this License and all the license notices in the Document and any Warranty Disclaimers provided that you also include the original English version of this License and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail If a section in the Document is Entitled Acknowledgements Dedications or History the requirement section 4 to Preserve its Title section 1 will typically require changing the actual title 9 TERMINATION You may not copy modify sublicense or distribute the Document except as expressly provided for under this License Any other attempt to copy modify sublicense or distribute the Document is void and will automatically terminate your rights under this License However parties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance 10 FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new revised versions of the GNU Free Documentation License from time to ti
358. roduct is either 1 a consumer product which means any tangible personal property which is normally used for personal family or household purposes or 2 anything designed or sold for incorporation into a dwelling In determining whether a product is a consumer product doubtful cases shall be resolved in favor of coverage For a particular product received by a particular user normally used refers to a typical or common use of that class of product regardless of the status of the particular user or of the way in which the particular user actually uses or expects or is expected to use the product A product is a consumer product regardless of whether the product has substantial commercial industrial or non consumer uses unless such uses represent the only significant mode of use of the product Installation Information for a User Product means any methods procedures authorization keys or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding The GNU C Library 243 253 Source The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made If you convey an object code work under this section in or with or specifically for use in a User Product and the conveying occurs as part of a transaction in wh
359. rray of size_t This keeps track of the number of blocks on a specific thread s freelist in each bin Le if a thread has 12 32 byte blocks on it s freelists and allocates one of these this counter would be decreased to 11 bin_record gt used An array of size_t This keeps track of the number of blocks currently in use of this size by this thread Le if a thread has made 678 requests and no deallocations of 32 byte blocks this counter will read 678 The above created arrays are now initialized with their initial values Le _S_bin n free n 0 Initialize the mutex of each bin_record The bin_record gt mutex is used to protect the global freelist This concept of a global freelist is explained in more detail in the section A multi threaded example but basically this mutex is locked whenever a block of memory is retrieved or returned to the global freelist for this specific bin This only occurs when a number of blocks are grabbed from the global list to a thread specific list or when a thread decides to return some blocks to the global freelist 20 1 3 3 Deallocation Notes Notes about deallocation This allocator does not explicitly release memory Because of this memory debugging programs like valgrind or purify may notice leaks sorry about this inconvenience Operating systems will reclaim allocated memory at program termination anyway If sidestepping this kind of noise is desired there are three options use an allocator l
360. rs if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission B List on the Title Page as authors one or more persons or entities responsible for authorship of the modifications in the Modified Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement State on the Title page the name of the publisher of the Modified Version as the publisher Preserve all the copyright notices of the Document Add an appropriate copyright notice for your modifications adjacent to the other copyright notices mm U O Include immediately after the copyright notices a license notice giving the public permission to use the Modified Version under the terms of this License in the form shown in the Addendum below G Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document s license notice H Include an unaltered copy of this License I Preserve the section Entitled History Preserve its Title and add to it an item stating at least the title year new authors and publisher of the Modified Version as given on the Title Page If there is no section Entit
361. rs new and delete directly for every allocation See include ext new_allocator h for instance However that option would involve changing source code to use a non default allocator Another option is to force the default allocator to remove caching and pools and to directly allocate with every call of allocate and directly deallocate with every call of deallocate regardless of efficiency As it turns out this last option is also available To globally disable memory caching within the library for the default allocator merely set GLIBCXX_FORCE_NEW with any value in the system s environment before running the program If your program crashes with GLIBCXX_FORCE_NEW in the environment it likely means that you linked against objects built against the older library objects which might still using the cached allocations The GNU C Library 47 253 6 3 1 4 Using a Specific Allocator You can specify different memory management schemes on a per container basis by overriding the default Allocator template parameter For example an easy but non portable method of specifying that only malloc or free should be used instead of the default node allocator is Steele 3 lis Kame Gai Exes Bellos llos sincs gt malloc list Likewise a debugging form of whichever allocator is currently in use std deque lt int __gnu_cxx debug_allocator lt std allocator lt int gt gt gt debug_deque 6 3 1 5 Cust
362. rst problem is finding a fast method of implementation portable to all platforms Due to historical reasons some of the library is written against per CPU architecture spinlocks and other parts against the gthr h abstraction layer which is provided by gcc A minor problem that pops up every so often is different interpretations of what thread safe means for a library not a general program We currently use the same definition that SGI uses for their STL subset However the exception for read only containers only applies to the STL components This definition is widely used and something similar will be used in the next version of the C standard library Here is a small link farm to threads no pun in the mail archives that discuss the threading problem Each link is to the first relevant message in the thread from there you can use Thread Next to move down the thread This farm is in latest to oldest order e Our threading expert Loren gives a breakdown of the six situations involving threads for the 3 0 release series e This message inspired a recent updating of issues with threading and the SGI STL library It also contains some example POSIX multithreaded STL code A large selection of links to older messages has been removed many of the messages from 1999 were lost in a disk crash and the few people with access to the backup tapes have been too swamped with work to restore them Many of the points have been superseded anyhow B 6
363. rt exception classes For example include lt exception gt include lt iostream gt include lt cxxabi h gt struct empty template lt typename T int N gt SUrUCcE bar Y iy Ii Mela E Status ehar xrealname exception classes not in lt stdexcept gt thrown by the implementation instead of the user std bad_exception e realname abi __cxa_demangle e what 0 0 amp status atel Sicicihe lt lt Sawin lt lt Ves Y lt lt raalnane lt lt us lt lt steras lt lt in 9 free realname typeid bar lt empty 17 gt us const std type_info sti typeid u realname abi __cxa_demangle ti name 0 0 amp status gte reout lt lt cil mems O lt lt Vets Y lt lt realamcae lt lt us Y lt lt Srarus lt lt free realname return 0 The GNU C Library 149 253 This prints St13bad_exception gt std bad_exception e 0 3barI5emptyLil7EE gt bar lt empty 17 gt g 0 The demangler interface is described in the source documentation linked to above It is actually written in C so you don t need to be writing C in order to demangle C That also means we have to use crummy memory management facilities so don t forget to free the returned char array The GNU C Library 150 253 Chapter 28 Concurrency 28 1 Design 28 1 1 Interface to Locks and Mutexes The file lt ext concurrence h gt contains all the higher l
364. ry extensions and compiler improvements One approach is some variation on the techniques previously marketed as pre compiled headers now standardized as support for the export keyword Exported template definitions can be placed once in a repository really just a library but of template definitions rather than object code to be drawn upon at link time when an instantiation is needed rather than placed in header files to be parsed along with every compilation unit Until export is implemented we can put some of the lengthy template definitions in if guards or alternative headers so that users can skip over the full definitions when they need only the ready instantiated specializations To be precise this means that certain headers which define templates which users normally use only for certain arguments can be instrumented to avoid exposing the template definitions to the compiler unless a macro is defined For example in lt string gt we might have template lt class _CharT gt class basic_string member declarations y The GNU C Library 175 253 operator declarations ifdef _STRICT_ISO_ if _G_NO_TEMPLATE_ EXPORT include lt bits std_locale h gt headers needed by definitions i include lt bits string tcc gt member and global template definitions endif endif Users who compile without specifying a strict ISO conforming flag would n
365. ry that you linked against And operators new and delete are not always called to pass the memory on either which is a speed bonus Examples of allocators that use these techniques are __gnu_cxx bitmap_allocator __gnu_cxx pool_allocator and__gnu_cxx __mt_alloc Depending on the implementation techniques used the underlying operating system and compilation environment scaling caching allocators can be tricky In particular order of destruction and order of creation for memory pools may be difficult to pin down with certainty which may create problems when used with plugins or loading and unloading shared objects in memory As such using caching allocators on systems that do not support abi __cxa_atexit is not recommended The GNU C Library 46 253 6 3 1 3 Implementation 6 3 1 3 1 Interface Design The only allocator interface that is supported is the standard C interface As such all STL containers have been adjusted and all external allocators have been modified to support this change The class allocator just has typedef constructor and rebind members It inherits from one of the high speed extension allocators covered below Thus all allocation and deallocation depends on the base class The base class that al locator is derived from may not be user configurable 6 3 1 3 2 Selecting Default Allocation Policy It s difficult to pick an allocation strategy that will provide maximum utility without excessivel
366. s and in case links librt Note that the latter is not always desirable because in glibc for example in turn it triggers the linking of libpthread too which activates locking a large overhead for single thread programs OPTION no skips the tests completely The default is OPTION no 2 3 Make If you have never done this before you should read the basic GCC Installation Instructions first Read all of them Twice Then type make and congratulations you re started to build The GNU C Library 19 253 Chapter 3 Using 3 1 Command Options The set of features available in the GNU C library is shaped by several GCC Command Options Options that impact libstdc are enumerated and detailed in the table below By default g is equivalent to g std gnu 98 The standard library also defaults to this dialect Option Flags Description std c 98 Use the 1998 ISO C standard plus amendments std gnu 98 As directly above with GNU extensions Use the working draft of the upcoming ISO C 0x std c 0x standard std gnu 0x As directly above with GNU extensions fexceptions See exception free dialect frtti As above but RTTI free dialect For ISO C 0x lt thread gt lt future gt lt mutex gt or pthread or pthreads ne lt condition_variable gt fopenmp For parallel mode Table 3 1 C Command Options 3 2 Headers 3 2 1 Header
367. s and then have to change all the code that uses those data types to keep up with the change If your code makes use of the standard algorithms this isn t as scary as it sounds The algorithms don t know nor care about the kind of container on which they work since the algorithms are only given endpoints to work with For the container classes these are iterators usually begin and end but not always For builtin arrays these are the address of the first element and the past the end element Some very simple wrapper functions can hide all of that from the rest of the code For example a pair of functions called beg inof can be written one that takes an array another that takes a vector The first returns a pointer to the first element and the second returns the vector s begin iterator The functions should be made template functions and should also be declared inline As pointed out in the comments in the code below this can lead to beginof being optimized out of existence so you pay absolutely nothing in terms of increased code size or execution time The result is that if all your algorithm calls look like std transform beginof foo endof foo beginof foo SomeFunction then the type of foo can change from an array of ints to a vector of ints to a deque of ints and back again without ever changing any client code beginof template lt typename T gt inline typename vector lt T gt iterator
368. s See paper The LRPD test speculative run time parallelization of loops with privatization and reduction parallelization e Cost model Number of accesses to elements referenced from multiple threads s Example The GNU C Library 130 253 19 7 5 2 False Sharing Switch _GLIBCXX_PROFILE_FALSE_SHARING Goal Detect elements in the same container which share a cache line are written by at least one thread and accessed by different threads Fundamentals Under these assumptions cache protocols require communication to invalidate lines which may be expensive Sample runtime reduction 68 Recommendation Reorganize container or use padding to avoid false sharing To instrument Container access methods and iterators Analysis First get the cache line size For each shared container record all the associated iterator dereferences and member access methods with the thread id Compare the address lists across threads to detect references in two different threads to the same cache line Issue a warning only if the ratio to total references is significant Do the same for iterator dereference values if they are pointers Cost model Number of accesses to same cache line from different threads Example 1 VECTOR SI 2 pragma omp parallel for shared v SIZE schedule static 1 3 ojo ak 08 al lt Sida ma h 4 5 o SEDA ES an OMP_NUM_THREADS 2 a out foo cc 1 advice Change container structure
369. s etc Why would you want to use a hashing class instead of the normal implementations Matt Austern writes W ith a well chosen hash function hash tables generally provide much better average case performance than binary search trees and much worse worst case performance So if your implementation has hash_map if you don t mind using nonstandard components and if you aren t scared about the possibility of pathological cases you ll probably get better performance from hash_map The GNU C Library 143 253 Chapter 22 Utilities The lt functional gt header contains many additional functors and helper functions extending section 20 3 They are implemented in the file stl_function h identity_element for addition and multiplication e The functor identity whose operator returns the argument unchanged e Composition functors unary_function and binary_function and their helpers composel and compose2 e select1st and select2na to strip pairs e projectlst and project2nad e A set of functors functions which always return the same result They are constant_void_fun constant_binary_ fun constant_unary_fun constant0 constant 1 and constant2 s The class subtractive_rng e mem Tun adaptor helpers mem_fun1 and mem_funl_ref are provided for backwards compatibility 20 4 1 can use several different allocators they are described on the main extensions page 20 4 3 is extended with a special
370. s License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invariant Sections of all of the original documents unmodified and list them all as Invariant Sections of your combined work in its license notice and that you preserve all their Warranty Disclaimers The combined work need only contain one copy of this License and multiple identical Invariant Sections may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each such section unique by adding at the end of it in parentheses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History in the various original documents forming one section Entitled History likewise combine any sections Entitled Acknowledgements and any sections Entitled Dedications You must delete all sections Entitled Endorsements 6 COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License and replace the indi vidual copies of this License in the various documents with a single copy that is included in the collection provided that you follow the rules of this Licen
371. s a wrapper model where the debugging versions of library components e g iterators and con tainers form a layer on top of the release versions of the library components The debugging components first verify that the operation is correct aborting with a diagnostic if an error is found and will then forward to the underlying release mode con tainer that will perform the actual work This design decision ensures that we cannot regress release mode performance because the release mode containers are left untouched and partially enables mixing debug and release code at link time although that will not be discussed at this time Two types of wrappers are used in the implementation of the debug mode container wrappers and iterator wrappers The two types of wrappers interact to maintain relationships between iterators and their associated containers which are necessary to detect certain types of standard library usage errors such as dereferencing past the end iterators or inserting into a container using an iterator from a different container 17 4 2 1 1 Safe lterators Iterator wrappers provide a debugging layer over any iterator that is attached to a particular container and will manage the information detailing the iterator s state singular dereferenceable etc and tracking the container to which the iterator is attached Because iterators have a well defined common interface the iterator wrapper is implemented with the iterator adaptor cl
372. s and is lightly documented below and fully documented in gettext s distributed documentation The GNU C Library 74 253 e ieee_1003 1 200x This is a complete though untested implementation based on the IEEE standard The functions catopen catgets catclose are used to retrieve locale specific messages given the appropriate message catalogs that have been constructed for their use Note the script po2msg sed that is part of the gettext distribution can convert gettext catalogs into catalogs that catopen can use A new standards conformant non virtual member function signature was added for open so that a directory could be specified with a given message catalog This simplifies calling conventions for the gnu model 8 2 3 3 2 The GNU Model The messages facet because it is retrieving and converting between characters sets depends on the ctype and perhaps the codecvt facet in a given locale In addition underlying C library locale support is necessary for more than just the LC_MESSAGES mask LC_CTYPE is also necessary To avoid any unpleasantness all bits of the C mask i e LC_ALL are set before retrieving messages Making the message catalogs can be initially tricky but become quite simple with practice For complete info see the gettext documentation Here s an idea of what is required e Make a source file with the required string literals that need to be translated See int1 string_literals cc
373. s are printed without symbol name or code location attribution Users are expected to postprocess the output using for instance addr2line e The warning message For some warnings this is static text e g change vector to list For other warnings such as the one above the message contains numeric advice e g the suggested initial size of the vector Three files are generated libstdcxx profile txt contains human readable advice libstdcxx profile raw con tains implementation specific data about each diagnostic Their format is not documented They are sufficient to generate all the advice given in libstdcxx profile txt The advantage of keeping this raw format is that traces from multiple executions can be aggregated simply by concatenating the raw traces We intend to offer an external utility program that can issue advice from a trace Libstdcxx profile conf out lists the actual diagnostic parameters used To alter parameters edit this file and rename it to Libstdcxx profile conf Advice is given regardless whether the transformation is valid For instance we advise changing a map to an unordered_map even if the application semantics require that data be ordered We believe such warnings can help users understand the performance behavior of their application better which can lead to changes at a higher abstraction level 19 1 2 Tuning the Profile Mode Compile time switches and environment variables see also file profiler h Unles
374. s code in the same CPU directory in which case no more work is needed to locate the file For examples of this approach see the atomicity h file for IRIX or 1A64 Alternatively if the primitives are more closely related to the OS than they are to the CPU you can put the atomicity h file in the Operating system directory instead In this case you must edit configure host and in the switch statement that handles operating systems override the ATOMICITYH variable to point to the appropriate os_include_dir For examples of this approach see the atomicity h file for AIX With those bits out of the way you have to actually write atomicity h itself This file should be wrapped in an include guard named _GLIBCXX_ATOMICITY_H It should define one type and two functions The type is_Atomic_word Here is the version used on IRIX typedef long _Atomic_word This type must be a signed integral type supporting atomic operations If you re using the OS approach use the same type used by your system s primitives Otherwise use the type for which your CPU provides atomic primitives Then you must provide two functions The bodies of these functions must be equivalent to those provided here but using atomic Operations static inline _Atomic_word __ attribute _unused_ __exchange_and_add _Atomic_word _ mem int _ val Atomic_word result x__mem mem _ val return _ result static inline void __ attribute __unus
375. s of the General Public License Of course your program s commands might be different for a GUI interface you would use an about box You should also get your employer if you work as a programmer or school if any to sign a copyright disclaimer for the program if necessary For more information on this and how to apply and follow the GNU GPL see http www gnu org licenses The GNU General Public License does not permit incorporating your program into proprietary programs If your program is a subroutine library you may consider it more useful to permit linking proprietary applications with the library If this is what you want to do use the GNU Lesser General Public License instead of this License But first please read http www gnu org philosophy why not lgpl html The GNU C Library 248 253 Appendix E GNU Free Documentation License Copyright C 2000 2001 2002 Free Software Foundation Inc 51 Franklin St Fifth Floor Boston MA 02110 1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed 0 PREAMBLE The purpose of this License is to make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or without modifying it either commercially or noncommercially Secondarily this License preserves for the author and publ
376. s or container implementations For instance iterating through a vector is X times faster than iterating through a list Under development We are working on customizing this to a particular machine by providing an automated way to compute the actual relative weights for operations on the given machine Under development We plan to provide a performance parameter database format that can be filled in either by hand or by an automated training mechanism The analysis module will then use this database instead of the built in generic parameters 19 5 Implementation Issues 19 5 1 Stack Traces Accurate stack traces are needed during profiling since we group events by call context and dynamic instance Without accurate traces diagnostics may be hard to interpret For instance when giving advice to the user it is imperative to reference application code not library code Currently we are using the libc backt race routine to get stack traces _GLIBCXX_PROFILE_STACK_DEPTH can be set to 0 if you are willing to give up call context information or to a small positive value to reduce run time overhead 19 5 2 Symbolization of Instruction Addresses The profiling and analysis phases use only instruction addresses An external utility such as addr2line is needed to postprocess the result We do not plan to add symbolization support in the profile extension This would require access to symbol tables debug information tables external prog
377. s specified otherwise they can be set at compile time using D_ lt name gt or by setting variable lt name gt in the environment where the program is run before starting execution e _GLIBCXX_PROFILE_NO_ lt diagnostic gt disable specific diagnostics See section Diagnostics for possible values Environment variables not supported T e _GLIBCXX_PROFILE_TRACE_PATH_ROOT set an alternative root path for the output files e _GLIBCXX_PROFILE_MAX_WARN_COUNT set it to the maximum number of warnings desired The default value is 10 e _GLIBCXX_PROFILE_MAX STACK_DEPTH if set to 0 the advice will be collected and reported for the program as a whole and not for each call context This could also be used in continuous regression tests where you just need to know whether there is a regression or not The default value is 32 e _GLIBCXX_PROFILE_MEM_PER_DIAGNOSTIC set a limit on how much memory to use for the accounting tables for each diagnostic type When this limit is reached new events are ignored until the memory usage decreases under the limit Generally this means that newly created containers will not be instrumented until some live containers are deleted The default 1s 128 MB e _GLIBCXX_PROFILE_NO_THREADS Make the library not use threads If thread local storage TLS is not available you will get a preprocessor error asking you to set D_GLIBCXX_PROFILE_NO_THREADS if your program is sing
378. s trying to offer as an option a high quality implementation damn the additional complexity For the required specialization codecvt lt wchar_t char mbstate_t gt conversions are made between the internal character set always UCS4 on GNU Linux and whatever the currently selected locale for the LC_CTYPE category implements 8 2 2 3 Implementation The two required specializations are implemented as follows codecvt lt char char mbstate_t gt This is a degenerate i e does nothing specialization Implementing this was a piece of cake codecvt lt char wchar_t mbstate_t gt This specialization by specifying all the template parameters pretty much ties the hands of implementors As such the imple mentation is straightforward involving mcsrtombs for the conversions between char to wchar_t and wesrtombs for conversions between wchar_t and char Neither of these two required specializations deals with Unicode characters As such libstdc implements a partial specializa tion of the codecvt class with and iconv wrapper class encoding_state as the third template parameter This implementation should be standards conformant First of all the standard explicitly points out that instantiations on the third template parameter stateT are the proper way to implement non required conversions Second of all the standard says in Chapter 17 that partial specializations of required classes are a ok Third of all the requirements for the s
379. s used for MT implementation should be exposed as an extension for users own work We need cross CPU mutex support multi processor shared memory atomic integer operations and single processor uninterruptible integer operations and all three configurable to be stubbed out for non MT use or to use an appropriately loaded dynamic library for the actual runtime environment or statically compiled in for cases where the target architecture is known Chapter 21 String Headers lt string gt C headers lt cctype gt lt cwctype gt lt cstring gt lt cwchar gt also in 27 lt cstdlib gt also in 18 25 26 We have mostly complete char_traits lt gt implementations Many of the char_traits lt char gt operations might be optimized further using existing proprietary language extensions We have a mostly complete basic_string lt gt implementation The work to manually instantiate char and wchar_t specializations in object files to improve link time behavior is extremely unsatisfactory literally tripling library build time with no commensurate improvement in static program link sizes It must be redone Similar work is needed for some components in chapters 22 and 27 Other work needed for strings is MT safety as discussed under the chapter 20 heading The standard C type mbstate_t from lt cwchar gt and used in char_traits lt gt must be different in C than in C because in C the d
380. se for verbatim copying of each of the documents in all other respects You may extract a single document from such a collection and distribute it individually under this License provided you insert a copy of this License into the extracted document and follow this License in all other respects regarding verbatim copying of that document 7 AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the compilation s users beyond what the individual works permit When the Document is included in an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document If the Cover Text requirement of section 3 is applicable to these copies of the Document then if the Document is less than one half of the entire aggregate the Document s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic equivalent of covers if the Document is in electronic form Otherwise they must appear on printed covers that bracket the whole aggregate The GNU C Library 252 253 8 TRANSLATION Translation is considered a kind of modification so you may distribute translations of the Document under the te
381. set unordered_set gnu_debug unor dered_set unordered_set LD td unordered_mu tiset H unordered_set gnu_debug unor dered_multiset unordered_set Table 17 2 Debugging Containers C 0x The GNU C Library 102 253 17 4 Design 17 4 1 Goals The libstdc debug mode replaces unsafe but efficient standard containers and iterators with semantically equivalent safe standard containers and iterators to aid in debugging user programs The following goals directed the design of the libstdc debug mode Correctness the libstdc debug mode must not change the semantics of the standard library for all cases specified in the ANSI ISO C standard The essence of this constraint is that any valid C program should behave in the same manner regardless of whether it is compiled with debug mode or release mode In particular entities that are defined in namespace std in release mode should remain defined in namespace std in debug mode so that legal specializations of namespace std entities will remain valid A program that is not valid C e g invokes undefined behavior is not required to behave similarly although the debug mode will abort with a diagnostic when it detects undefined behavior Performance the additional of the libstdc debug mode must not affect the performance of the library when it is compiled in release mode Performance of the libstdc debug mode is
382. share a single configuration directory for example alpha alphaev5 and alphaev 6 all use the config cpu alpha directory and there is an entry in the configure host switch statement to handle this The cpu_include_dir sets default locations for the files controlling Thread safety and Numeric limits if the defaults are not appropriate for your chip B 2 3 Character Types The library requires that you provide three header files to implement character classification analogous to that provided by the C libraries lt ct ype h gt header You can model these on the files provided in config os generic However these files will almost certainly need some modification The first file to write is ctype_base h This file provides some very basic information about character classification The libstdc library assumes that your C library implements lt ctype h gt by using a table indexed by character code containing integers where each of these integers is a bit mask indicating whether the character is upper case lower case alphabetic etc The ctype_base h file gives the type of the integer and the values of the various bit masks You will have to peer at your own lt ctype h gt to figure out how to define the values required by this file The ctype_base h header file does not need include guards It should contain a single struct definition called ctype_ base This struct should contain two type declarations and one enumeration declaration l
383. slate characters between native files and the locale character encoding In general this involves two buffers one of char representing the file and another of char_type for the stream with codecvt lt gt translating The process is complicated by the variable length nature of the translation and the need to seek to corresponding places in the two representations For the case of basic _filebuf lt char gt when no translation is needed a single buffer suffices A specialized filebuf can be used to reduce code space overhead when no locale has been imbued Matt Austern s work at SGI will be useful perhaps directly as a source of code or at least as an example to draw on Filebuf almost uniquely cf operator new depends heavily on underlying environmental facilities In current releases iostream depends fairly heavily on libio constant definitions but it should be made independent It also depends on operating system primitives for file operations There is immense room for optimizations using e g mmap for reading The shadow directory wraps besides the standard C headers the libio h and unistd h headers for use mainly by filebuf These wrappings have not been completed though there is scaffolding in place The encapsulation of certain C header lt cstdio gt names presents an interesting problem It is possible to define an inline std fprintf implemented in terms of the extern C vfprintf
384. ss this is done libstdc will use generic settings which may not be correct for your target even if they are correct they will likely be inefficient Before you get started make sure that you have a working C library on your target The C library need not precisely comply with any particular standard but should generally conform to the requirements imposed by the ANSI ISO standard In addition you should try to verify that the C compiler generally works It is difficult to test the C compiler without a working library but you should at least try some minimal test cases Note that what we think of as a target the library refers to as a host The comment at the top of configure ac explains why B 2 1 Operating System If you are porting to a new operating system as opposed to a new chip using an existing operating system you will need to create a new directory in the config os hierarchy For example the IRIX configuration files are all in config os irix There is no set way to organize the OS configuration directory For example config os solaris solaris 2 6 and config os solaris solaris 2 7 are used as configuration directories for these two versions of Solaris On the other hand both Solaris 2 7 and Solaris 2 8 use the config os solaris solaris 2 7 directory The important information is that there needs to be a directory under config os to store the files for your operating system You might have to change the configure
385. stance the std adjacent_find function is declared as namespace std template lt typename _Flter gt BEE adjacent_find _Flter _Flter Which means that there should be something equivalent for the parallel version Indeed this is the case The GNU C Library 111 253 Algorithm Header Parallel algorithm Parallel header A nu_parallel a F std accumulate numeric ears parallel numeric ccumulate std adjacent_dif gnu_parallel a y numeric ie parallel numeric ference djacent_difference nu_parallel i E l std inner_product numeric oe parallel numeric nner_product F A nu_parallel p E a c std partial_sum numeric gr p parallel numeric artial_sum E gnu_parallel a p E g E std adjacent_find algorithm s arallel algorithm E gt a djacent_find p nag nu_parallel c A a E std count algorithm dE parallel algorithm ount gnu_parallel c E std count_if algorithm 7 arallel algorithm as ane ount_if p lgori nu_parallel e A g std equal algorithm aon parallel algorithm qual y nu_parallel f z S std find algorithm md P parallel algorithm std find_if algorithm gn paralleli
386. stract base class See if just smash overriding is a better approach Clarify add sanity to naming 8 2 1 3 Bibliography 26 Roland McGrathUlrich Drepper The GNU C Library Copyright 2007 FSF Chapters 6 Character Set Handling and 7 Locales and Internationalization 27 Ulrich Drepper Correspondence Copyright 2002 28 ISO IEC 14882 1998 Programming languages C Copyright 1998 ISO 29 ISO IEC 9899 1999 Programming languages C Copyright 1999 ISO 30 uri The Open Group Base Specifications Issue 6 IEEE Std 1003 1 2004 Copyright 1999 The Open Group The Institute of Electrical and Electronics Engineers Inc 31 Bjarne Stroustrup The C Programming Language Special Edition Copyright 2000 Addison Wesley Inc Appendix D Addison Wesley 32 Angelika LangerKlaus Kreft Standard C IOStreams and Locales Advanced Programmer s Guide and Reference Copyright 2000 Addison Wesley Longman Inc Addison Wesley Longman The GNU C Library 68 253 8 2 2 codecvt The standard class codecvt attempts to address conversions between different character encoding schemes In particular the standard attempts to detail conversions between the implementation defined wide characters hereafter referred to as wchar_t and the standard type char that is so beloved in classic C which can now be referred to as narrow characters This document attempts to describe how the GNU libstdc impl
387. string This is because libstdc uses GCC s xtern template extension to provide explicit instantiations of std string and std wstring and those explicit instantiations don t include the debug mode checks If the containing functions are inlined then the checks will run so compiling with 01 might be enough to enable them Alternatively D_GLIBCXX_EXTERN_TEMPLATE 0 will suppress the declara tions of the explicit instantiations and cause the functions to be instantiated with the debug mode checks included but this is unsupported and not guaranteed to work For full debug mode support you can use the __gnu_debug basic_string debugging container directly which always works correctly 17 3 Using 17 3 1 Using the Debug Mode To use the libstdc debug mode compile your application with the compiler flag D_GLIBCXX_DEBUG Note that this flag changes the sizes and behavior of standard class templates such as std vector and therefore you can only link code compiled with debug mode and code compiled without debug mode if no instantiation of a container is passed between the two translation units By default error messages are formatted to fit on lines of about 78 characters The environment variable GLIBCXX_DEBUG_ MESSAGE_LENGTH can be used to request a different length 17 3 2 Using a Specific Debug Container When it is not feasible to recompile your entire application or only specific contain
388. sulate more general memory models and that support non equal instances In such implementations any requirements imposed on allocators by containers beyond those requirements that appear in Table 32 and the semantics of containers and algorithms when allocator instances compare non equal are implementation defined As yet we don t have any allocators which compare non equal so we can t describe how they behave 21 1 3 1 3 4 21 1 3 2 2 23 s foo iterator 27 s foo _type others Nope these types are called implementation defined because you shouldn t be taking advantage of their underlying types Listing them here would defeat the purpose 21 1 3 1 5 1 don t really know about the mbstate_t stuff see the chapter 22 notes for what does exist 22 Anything and everything we have on locale implementation will be described over here 26 2 8 9 I have no idea what complex lt T gt s pow 0 0 returns 27 4 2 4 2 Calling std ios_base sync_with_stdio after I O has already been performed on the standard stream objects will flush the buffers and destroy and recreate the underlying buffer instances Whether or not the previously written I O is destroyed in this process depends mostly on the enable libio choice for stdio if the written data is already in the stdio buffer the data may be completely safe 27 6 1 1 2 27 6 2 3 The VO sentry ctor and dtor can perform additional work than the minimum requ
389. t lt please in german lt lt s01l lt lt n come lt lt Wulaciale Yon ala cermeie lt lt S02 lt lt al mssg_de close cat_de 8 2 3 5 Future Things that are sketchy or remain unimplemented _M_convert_from_char _M_convert_to_char are in flux depending on how the library ends up doing character set conver sions It might not be possible to do a real character set based conversion due to the fact that the template parameter for messages is not enough to instantiate the codecvt facet 1 supplied need at least 2 but would prefer 3 There are issues with gettext needing the global locale set to extract a message This dependence on the global locale makes the current gnu model non MT safe Future versions of glibc i e glibc 2 3 x will fix this and the C library bits are already in place Development versions of the GNU C library glibc 2 3 will allow a more efficient MT implementation of std messages and will allow the removal of the M name messages data member If this is done it will change the library ABI The C parts to support glibc 2 3 have already been coded but are not in use once this version of the C library is released the marked parts of the messages implementation can be switched over to the new C library functionality At some point in the near future std numpunct will probably use std messages facilities to implement truename falsename correctly This is currently no
390. t basic wchar_t functionality Support for char_t raits beyond builtin types Conformant allocator class and usage in containers As part of this the following extensions are added ext bitmap_ allocator h ext debug_allocator h ext mt_allocator h ext malloc_allocator h ext new_allocat h ext pool_allocator h This is a change from all previous versions and may require source level changes due to allocator related changes to structures names and template parameters filenames and file locations Some like __simple_alloc _ allocator _ alloc and _Alloc_traits have been removed Default behavior of std allocator has changed Previous versions prior to 3 4 cache allocations in a memory pool instead of passing through to call the global allocation operators i e _gnu_cxx pool_allocator More recent versions default to the simpler__gnu_cxx new_allocator The GNU C Library 219 253 Previously all allocators were written to the SGI style and all STL containers expected this interface This interface had a traits class called _Alloc_traits that attempted to provide more information for compile time allocation selection and optimization This traits class had another allocator wrapper __s imp le_alloc lt T A gt which was a wrapper around another allocator A which itself is an allocator for instances of T But wait there s more __allocator lt T A gt is another adapter Many of the provided allocator classes we
391. t done but entries in libstdc pot have already been made for true and false string literals so all that remains is the std numpunct coding and the configure make hassles to make the installed library search its own catalog Currently the libstdc mo catalog is only searched for the testsuite cases involving messages members The following member functions catalog open const basic_string lt char gt amp __s const locale amp __loc const catalog open const basic_string lt char gt amp const localeg const charx const Don t actually return a value less than 0 if no such catalog can be opened as required by the standard in the gnu model As of this writing it is unknown how to query to see if a specified message catalog exists using the gettext package 8 2 3 6 Bibliography 43 Roland McGrathUlrich Drepper The GNU C Library Copyright 2007 FSF Chapters 6 Character Set Handling and 7 Locales and Internationalization 44 Ulrich Drepper Correspondence Copyright 2002 45 ISO IEC 14882 1998 Programming languages C Copyright 1998 ISO 46 ISO IEC 9899 1999 Programming languages C Copyright 1999 ISO 47 uri System Interface Definitions Issue 7 IEEE Std 1003 1 2008 Copyright 2008 The Open Group The Institute of Electrical and Electronics Engineers Inc 48 Bjarne Stroustrup The C Programming Language Special Edition Copyright 2000 Addison Wesley Inc Appendix D
392. t into separate functions to be merged by the compiler Until such a compiler optimization is implemented much can be done manually if tediously in this direction One such optimization is to derive class templates from non template classes and move as much implementation as possible into the base class Another is to partial specialize certain common instantiations such as vector lt Tx gt to share code for instantiations on all types T While these techniques work they are far from the complete solution that a compiler improvement would afford Overhead Expensive Language Features The main expensive language feature used in the standard library is exception support which requires compiling in cleanup code with static table data to locate it and linking in library code to use the table For small embedded programs the amount of such library code and table data is assumed by some to b xcessive Under th new ABI this perception is generally exaggerated although in some cases it may actually be excessive To implement a library which does not use exceptions directly is not difficult given minor compiler support to turn off exceptions and ignore exception constructs and results in no great library maintenance difficulties To be precise given fno exceptions the compiler should treat try blocks as ordinary blocks and catch blocks as dead code to ignore or eli
393. t is not yet under include profile make a copy of the one in include debug or the main implementation You ll need to include the main implementation and inherit the classes you want to instrument Then define the methods you want to instrument define the instrumentation hooks and add calls to them Look at include prof ile vector for an example Add macros for the instrumentation hooks in include profile impl profiler h Hook names must start with __ p rofcxx_ Make sure they transform in no code with D_NO_GLBICXX_PROFILE_MAGIC Make sure all calls to any method in namespace ___gnu_profile is protected against reentrance using macro_GLIBCXX_PROFILE_REENTRANCE_GUARD All names of methods in namespace __ gnu_profile called from profiler h must start with__trace_magic_ T Add the implementation of the diagnostic e Create new file include profile impl profiler_magic h e Define class__magic_info public __object_info_base This is the representation of a line in the object table The __merge method is used to aggregate information across all dynamic instances created at the same call context The _ _magnitude must return the estimation of the benefit as a number of small operations e g number of words copied The __ write method is used to produce the raw trace The __ advice method is used to produce the advice string e Define class__magic_stack_info public __magic_info This defines the content of a line in
394. t long long lt type gt lt varname gt lt varname gt fs lt varname gt i lt literal gt Weffc lt literal gt lt literal gt A lt literal gt rel_ops lt literal gt lt constant gt _GNU_SOURCE lt constant gt lt constant gt lt constant gt 3 0 lt constant gt lt command gt lt command gt g lt command gt lt errortext gt lt errortext gt In instantiation of lt errortext gt lt filename class headerfile gt ctype h lt filename gt lt filename gt lt filename class directory gt home gcc build lt filename gt lt filename class libraryfile gt libstdc so lt filename gt Table A 3 Docbook XML Element Use The GNU C Library 173 253 A 4 3 Combines A 4 3 1 Generating Combines and Assemblages The following Makefile rules are defaults and are usually aliased to variable rules make doc html make doc man make doc pdf A 5 Design Notes he Library x This paper is covers two major areas Features and policies not mentioned in the standard that the quality of the library implementation depends on including extensions and implementation defined features Plans for required but unimplemented library features and optimizations to them Overhead The standard defines a large library much larger than the standard C library A naive implementation would suffer substantial overhead in compile time executable size and speed rendering it unusable in many p
395. t order e Sample runtime reduction 36 Code similar to example below e Recommendation Set initial size to N at construction site S s To instrument unordered_set unordered_map constructor destructor rehash e Analysis For each dynamic instance of unordered_ multi set map record initial size and call context of the con structor Record size increase if any after each relevant operation such as insert Record the estimated rehash cost e Cost model Number of individual rehash operations cost per rehash s Example 1 unordered_set lt int gt us 2 for int k 0 k lt 1000000 k 3 us insert k ay foo cc 1 advice Changing initial unordered_set size from 10 to 1000000 saves 1025530 rehash operations 19 7 2 2 Hashtable Too Large s Switch GLIBCXX_PROFILE_HASHTABLE_TOO_LARGE e Goal Detect hashtables which are never filled up because fewer elements than reserved are ever inserted e Fundamentals Save memory which is good in itself and may also improve memory reference performance through fewer cache and TLB misses e Sample runtime reduction unknown s Recommendation Set initial size to N at construction site S s To instrument unordered_set unordered_map constructor destructor rehash e Analysis For each dynamic instance of unordered_ multi set map record initial size and call context of the con structor and correlate it with its size at destruction time e Cost mode
396. t output buffer std ostream out amp ob QUEENS T TT cima lt lt Std hex lt lt 31 lt lt sted senal return 0 Try it yourself More examples can be found in 3 1 x code in include ext x _filebuf h and in this article by James Kanze Filtering Streambufs 13 2 2 Buffering First are you sure that you understand buffering Chaptericularly the fact that C may not in fact have anything to do with it The rules for buffering can be a little odd but they aren t any different from those of C Maybe that s why they can be a bit odd Many people think that writing a newline to an output stream automatically flushes the output buffer This is true only when the output stream is in fact a terminal and not a file or some other device and that may not even be true since C says nothing about files nor terminals All of that is system dependent The newline buffer flushing only occurring on terminals thing is mostly true on Unix systems though Some people also believe that sending endl down an output stream only writes a newline This is incorrect after a newline is written the buffer is also flushed Perhaps this is the effect you want when writing to a screen get the text out as soon as possible etc but the buffering is largely wasted when doing this to a file output lt lt a line of text lt lt endl output lt lt some_data_variable lt lt endl output lt lt another line of text lt lt
397. t types passed as template parameters to vector be Assignable which means what you think it means The checking was done during compilation and none of the code was executed at runtime Unfortunately the size of the compiler files grew significantly as a result The checking code itself was cumbersome And bugs were found in it on more than one occasion The primary author of the checking code Jeremy Siek had already started work on a replacement implementation The new code has been formally reviewed and accepted into the Boost libraries and we are pleased to incorporate it into the GNU C library The new version imposes a much smaller space overhead on the generated object file The checks are also cleaner and easier to read and understand They are off by default for all versions of GCC from 3 0 to 3 4 the latest release at the time of writing They can be enabled at configure time with enable concept checks You can enable them on a per translation unit basis with define _GLIBCXX _CONCEPT_CHECKS for GCC 3 4 and higher or with tdefine _GLIBCPP_CONCEPT_CHECKS for versions 3 1 3 2 and 3 3 Please note that the upcoming C standard has first class support for template parameter constraints based on concepts in the core language This will obviate the need for the library simulated concept checking described above The GNU C Library 99 253 Chapter 17 Debug Mode 17 1 Intro
398. t was changed every night by an automated script Since gcc 4 1 0 it is the same value as gcc DATESTAMP It is versioned as follows gec 3 0 0 20010615 gec 3 0 1 20010819 gec 3 0 2 20011023 gec 3 0 3 20011220 gec 3 0 4 20020220 gec 3 1 0 20020514 gcc 3 1 1 20020725 gec 3 2 0 20020814 gec 3 2 1 20021119 gec 3 2 2 20030205 gec 3 2 3 20030422 gcec 3 3 0 20030513 gec 3 3 1 20030804 gec 3 3 2 20031016 gec 3 3 3 20040214 gec 3 4 0 20040419 gcc 3 4 1 20040701 gcc 3 4 2 20040906 gcec 3 4 3 20041105 gcc 3 4 4 20050519 gcec 3 4 5 20051201 gcc 3 4 6 20060306 The GNU C Library 211 253 gec 4 0 0 20050421 gcc 4 0 1 20050707 gcec 4 0 2 20050921 gec 4 0 3 20060309 gec 4 1 0 20060228 gec 4 1 1 20060524 gec 4 1 2 20070214 gec 4 2 0 20070514 gec 4 2 1 20070719 gec 4 2 2 20071007 gcc 4 2 3 20080201 gec 4 2 4 20080519 gcc 4 3 0 20080306 gcc 4 3 1 20080606 gec 4 3 2 20080827 gec 4 3 3 20090124 gec 4 4 0 20090421 gcec 4 4 1 20090722 gcec 4 4 2 20091015 8 Incremental bumping of a library pre defined macro GLIBCPP_VERSION This macro is defined as the released version of the library as a string literal This is only implemented in gcc 3 1 0 releases and higher and is deprecated in 3 4 where it is called GLIBCXX_VERSION This macro is defined in the file c config in the libstdc include bits directory and is generated automatically by autoconf as part of the configure time generati
399. table in order not to depend on implementation Mixing object files built with and without the profile mode must not affect the program execution However there are no guaran tees to the accuracy of diagnostics when using even a single object not built with D_GLIBCXX_PROFILE Currently mixing the profile mode with debug and parallel extensions is not allowed Mixing them at compile time will result in preprocessor errors Mixing them at link time is undefined 19 2 2 Instrumentation Instead of instrumenting every public entry and exit point we chose to add instrumentation on demand as needed by individual diagnostics The main reason is that some diagnostics require us to extract bits of internal state that are particular only to that diagnostic We plan to formalize this later after we learn more about the requirements of several diagnostics All the instrumentation points can be switched on and off using D _NO _GLIBCXX_PROFILE_ lt diagnostic gt options With all the instrumentation calls off there should be negligible overhead over the release version This property is needed to support diagnostics based on timing of internal operations For such diagnostics we anticipate turning most of the instrumentation off in order to prevent profiling overhead from polluting time measurements and thus diagnostics All the instrumentation on off compile time switches live in include profile profiler h 19 2 3 Run Time Behavior For practi
400. tateT type elsewhere in the standard see 21 1 2 traits typedefs only indicate that this type be copy constructible As such the type encoding_state is defined as a non templatized POD type to be used as the third type of a codecvt instantiation This type is just a wrapper class for iconv and provides an easy interface to iconv functionality There are two constructors for encoding_state encoding_state __in_desc 0 __out_desc 0 This default constructor sets the internal encoding to some default currently UCS4 and the external encoding to whatever is returned by nl_langinfo CODESET encoding_state const char _ int const char __ ext This constructor takes as parameters string literals that indicate the desired internal and external encoding There are no defaults for either argument One of the issues with iconv is that the string literals identifying conversions are not standardized Because of this the thought of mandating and or enforcing some set of pre determined valid identifiers seems iffy thus a more practical and non migraine inducing strategy was implemented end users can specify any string subject to a pre determined length qualifier currently 32 bytes for encodings It is up to the user to make sure that these strings are valid on the target system void _M_init Strangely enough this member function attempts to open conversion descriptors for a given encoding_state object If the con version descrip
401. tatic locale id id s Derived from another facet class gnu_codecvt public std ctype lt user defined type gt Of interest in this class are the memory management options explicitly specified as an argument to facet s constructor Each constructor of a facet class takes a std size_t __refs argument if __refs 0 the facet is deleted when the locale containing it is destroyed If rets 1 the facet is not destroyed even when it is no longer referenced class id 22 1 1 1 3 Class locale id Provides an index for looking up specific facets 8 1 1 2 Design The major design challenge is fitting an object orientated and non global locale design on top of POSIX and other relevant standards which include the Single Unix nee X Open Because C and earlier versions of POSIX fall down so completely portability is an issue The GNU C Library 61 253 8 1 1 3 Implementation 8 1 1 3 1 Interacting with C locales e locale a displays available locales af_ZA ar_A ar_A ar_B ela 13 ar_DZ ar DA UbES SETS ma Fl Fl ES ar_EG utf8 ar TO uE ES eye JO Whe 113 ar_KW ut 8 aL URES SA AS ar_MA utf8 ar_OM utf8 ar_QA utf8 ar_SA utf8 ire SID sible 38 elie SNe 5 ote acs ar_TN utf8 ENL 1 s be_BY utf8 bg_BG utf8 n _ES euro ES utf8leuro un He 9 9 ca_ Ca CH Cs CUZ URES EYAGB da_DK da_DK iso885915 da_DK ut 8 de_AT de_AT euro
402. ted in independent threads Under the assumption that object_a and object_b are never exposed to another thread here is an example that should not require any user level locks thread_main library_class_a object_a library_class_b xobject_b new library_class_b object_a add_b object_b object_a mutate All library objects are safe to use in a multithreaded program as long as each thread carefully locks out access by any other thread while it uses any object visible to another thread i e treat library objects like any other shared resource In general this requirement includes both read and write access to objects unless otherwise documented as safe do not assume that two threads may access a shared standard library object at the same time 3 6 3 Atomics 3 6 4 lO This gets a bit tricky Please read carefully and bear with me The GNU C Library 28 253 3 6 4 1 Structure A wrapper type called __basic_file provides our abstraction layer for the std filebuf classes Nearly all decisions dealing with actual input and output must be made in__basic_file A generic locking mechanism is somewhat in place at the filebuf layer but is not used in the current code Providing locking at any higher level is akin to providing locking within containers and is not done for the same reasons see the links above 3 6 4 2 Defaults The __basic_file type is simply a collection of small wrappers around the C stdio layer a
403. terleaved that is given this pseudocode SALCEDA AO ol ae Penis extern VE OE UE word Ta ores Sivaitea Culham groDyie atexit f1 greawte Tinne ela atexit 2 then at a call of exit 2 will be called then ob32 will be destroyed then 1 will be called and finally obj1 will be destroyed If 1 or 2 allow an exception to propagate out of them Bad Things happen Note also that atexit is only required to store 32 functions and the compiler library might already be using some of those slots If you think you may run out we recommend using the xatexit xexit combination from 1ibibert y which has no such limit 4 3 2 Verbose Terminate Handler If you are having difficulty with uncaught exceptions and want a little bit of help debugging the causes of the core dumps you can make use of a GNU extension the verbose terminate handler include lt exception gt int main std set_terminate __gnu_cxx __verbose_terminate_handler throw anything The __verbose_terminate_handler function obtains the name of the current exception attempts to demangle it and prints it to stderr If the exception is derived from exception then the output from what will be included Any replacement termination function is required to kill the program without returning this one calls abort For example include lt exception gt include lt stdexcept gt struct argument_error public std runtime_error
404. the case of dg do it specifies whether the test case is even attempted on the specified target The target selector is always optional The format is one of sara 000 if the test is expected to fail for the given targets target x the option only applies to the given targets At least one target must be specified use x x for all targets At present it is not possible to specify both xfail and target native may be used in place of x x x Example 1 Testing compilation only dg do compile Example 2 Testing for expected warnings on line 36 which all targets fail Fi A cas Serias literala Ww p ranil gt Y 36 Example 3 Testing for expected warnings on line 36 IU ranas Usera laterals UW i target sis 36 Example 4 Testing for compilation errors on line 41 dg do compile Ji A Slaaie as merca tort VY f targas aoe y Ail Example 5 Testing with special command line settings or without the use of pre compiled headers in particular the stdc h gch file Any options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set up in the normal exp file dg options 00 target x x x The GNU C Library 203 253 More examples can be found in the libstdc v3 testsuite cc files B 3 4 Test Harness and Utilities B 3 4 1 Dejagnu Harness Details Underlying details of testing for conformance and regressions are
405. the conditions of this License they do not excuse you from the conditions of this License If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations then as a consequence you may not convey it at all For example if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program 13 Use with the GNU Affero General Public License Notwithstanding any other provision of this License you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work and to convey the resulting work The terms of this License will continue to apply to the part which is the covered work but the special requirements of the GNU Affero General Public License section 13 concerning interaction through a network will apply to the combination as such 14 Revised Versions of this License The Free Software Foundation may publish revised and or new versions of the GNU General Public License from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns Each version is given a distinguishing version number If the Program specifies that a
406. the last reference is dropped This is the simplest form and is used when there is no custom deleter or allocator _Sp_counted_deleter lt Ptr Deleter Alloc gt Inherits from _Sp_counted_ptr and adds support for custom deleter and allocator Empty Base Optimization is used for the allocator This class is used even when the user only provides a custom deleter in which case allocator is used as the allocator _Sp_counted_ptr_inplace lt Tp Alloc Lp gt Used by allocate shared and make shared Contains aligned storage to hold an object of type Tp which is constructed in place with placement new Has a variadic template construc tor allowing any number of arguments to be forwarded to Tp s constructor Unlike the other _Sp_counted_ x classes this one is parameterized on the type of object not the type of pointer this is purely a convenience that simplifies the implementation slightly The GNU C Library 51 253 6 3 3 3 2 Thread Safety The interface of tr1 shared_ptr was extended for C 0x with support for rvalue references and the other features from N2351 As with other libstdc headers shared by TR1 and C 0x boost_shared_ptr h uses conditional compilation based on the macros _ GLIBCXX_INCLUDE_AS _CXXOX and _GLIBCXX_INCLUDE_AS_TR1 to enable and disable features C 0x only features are rvalue ref move support allocator support aliasing constructor make_shared amp allocate_shared Ad ditionally the constructors takin
407. the library ABI enable libstdcxx allocator This is an abbreviated form of enable libstdcxx allocator auto described next enable libstdcxx allocator OPTION Select a target specific underlying std allocator The choices are new to specify a wrapper for new malloc to specify a wrapper for malloc mt for a fixed power of two allocator pool for the SGI pooled allocator or bitmap for a bitmap allocator See this page for more information on allocator extensions This option can change the library ABI enable cheaders OPTION This allows the user to define the approach taken for C header compatibility with C Op tions are c c_std and c_global These correspond to the source directory s include c include c_std and include c_global and may also include include c_compatibility The default is c_global enable threads This is an abbreviated form of nable threads yes described next enable threads OPTION Select a threading library A full description is given in the general compiler configuration instructions This option can change the library ABI enable libstdcxx debug Build separate debug libraries in addition to what is normally built By default the debug libraries are compiled with CXXFLAGS g3 00 fno inline are installed in libdir debug and have the same names and versioning information as the non debug libraries This option is off by default Note th
408. the regular copy constructor cannot be used because libstdc s st ring is Copy On Write 7 1 6 CString MFC A common lament seen in various newsgroups deals with the Standard string class as opposed to the Microsoft Foundation Class called CString Often programmers realize that a standard portable answer is better than a proprietary nonportable one but in porting their application from a Win32 platform they discover that they are relying on special functions offered by the CString class Things are not as bad as they seem In this message Joe Buck points out a few very important things e The Standard st ring supports all the operations that CString does with three exceptions e Two of those exceptions whitespace trimming and case conversion are trivial to implement In fact we do so on this page e The third is CString Format which allows formatting in the style of sprintf This deserves some mention The old libg library had a function called form which did much the same thing But for a Standard solution you should use the stringstream classes These are the bridge between the iostream hierarchy and the string class and they operate with regular streams seamlessly because they inherit from the iostream hierarchy An quick example include lt iostream gt include lt string gt include lt sstream gt string f string amp incoming OMS Yoe NE istringstream incoming_stream incoming string the_word e the_n
409. the source tree run_doxygen which does the actual work of running Doxygen and then most importantly massaging the output files If for some reason you prefer to not go through the Makefile you can call this script directly Start by passing he 1p If you wish to tweak the Doxygen settings do so by editing doc doxygen user cfg in Notes to fellow library hackers are written in triple comments The GNU C Library 169 253 A 4 1 3 Markup In general libstdc files should be formatted according to the rules found in the Coding Standard Before any doxygen specific formatting tweaks are made please try to make sure that the initial formatting is sound Adding Doxygen markup to a file informally called doxygenating is very simple The Doxygen manual can be found here We try to use a very recent version of Doxygen For classes use deque vector list and std pair as examples For functions see their member functions and the free functions in st 1_algobase h Member functions of other container like types should read similarly to these member functions Some commentary to accompany the first list in the Special Documentation Blocks section of the Doxygen manual 1 For longer comments use the Javadoc style 2 not the Qt style The intermediate s are preferred 3 Use the triple slash style only for one line comments the brief mode 4 This is disgusting Don t do this Some specific guidelines
410. the stack table e Define class__trace_magic public trace_base lt __magic_info magic_stack_info gt Itdefines the content of the trace associated with this diagnostic Add initialization and reporting calls in include profile impl profiler_trace h Use__trace_vector_t o_list as an example Add documentation in file doc xm1 manual profile_mode xml The GNU C Library 121 253 19 7 Diagnostics The table below presents all the diagnostics we intend to implement Each diagnostic has a corresponding compile time switch D_GLIBCXX_PROFILE_ lt diagnostic gt Groups of related diagnostics can be turned on with a single switch For instance D_GLIBCXX_PROFILE_LOCALITY is equivalent to D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH D_GLIBCX X_PROFILE_RBTREE_LOCALITY The benefit cost expected frequency and accuracy of each diagnostic was given a grade from 1 to 10 where 10 is highest A high benefit means that if the diagnostic is accurate the expected performance improvement is high A high cost means that turning this diagnostic on leads to high slowdown A high frequency means that we expect this to occur relatively often A high accuracy means that the diagnostic is unlikely to be wrong These grades are not perfect They are just meant to guide users with specific needs or time budgets Group Flag Benefit Cost Freq Implemented
411. thorizing them to use propagate modify or convey a specific copy of the covered work then the patent license you grant is automatically extended to all recipients of the covered work and works based on it A patent license is discriminatory if it does not include within the scope of its coverage prohibits the exercise of or is conditioned on the non exercise of one or more of the rights that are specifically granted under this License You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software under which you make payment to the third party based on the extent of your activity of conveying the work and under which the third party grants to any of the parties who would receive the covered work from you a discriminatory patent license a in connection with copies of the covered work conveyed by you or copies made from those copies or b primarily for and in connection with specific products or compilations that contain the covered work unless you entered into that arrangement or that patent license was granted prior to 28 March 2007 Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law 12 No Surrender of Others Freedom If conditions are imposed on you whether by court order agreement or otherwise that contradict
412. threads A multi thread MT extension primarily affects operators new and delete 18 allocator 20 string 21 locale 22 and iostreams 27 The common underlying support needed for this is discussed under chapter 20 The standard requirements on names from the C headers create a lot of work mostly done Names in the C headers must be visible in the std and sometimes the global namespace the names in the two scopes must refer to the same object More stringent is that Koenig lookup implies that any types specified as defined in std really are defined in std Names optionally implemented as macros in C cannot be macros in C An overview may be read at lt http www cantrip org cheaders html gt The scripts inclosure and mkcshadow and the directories shadow and cshadow are the beginning of an effort to conform in this area A correct conforming definition of C header names based on underlying C library headers and practical linking of conforming namespaced customer code with third party C libraries depends ultimately on an ABI change allowing namespaced C type names to be mangled into type names as if they were global somewhat as C function names in a namespace or C global variabl names are left unmangled Perhaps another extern mode such as extern C global would be an appropriate place for such type definitions Such a type would affect mangling as follows namespac
413. time system will translate between for example n and the appropriate end of line sequence LF on Unix CRLF on DOS CR on Macintosh etc There are other things that normal mode does but that s the most obvious The GNU C Library 92 253 Opening a file in binary mode disables this conversion so reading a CRLF sequence under Windows won t accidentally get mapped to a n character etc Binary mode is not supposed to suddenly give you a bitstream and if it is doing so in your program then you ve discovered a bug in your vendor s compiler or some other chapter of the C implementation possibly the runtime system Second using lt lt to write and gt gt to read isn t going to work with the standard file stream classes even if you use skipws during reading Why not Because ifstream and ofstream exist for the purpose of formatting not reading and writing Their job is to interpret the data into text characters and that s exactly what you don t want to happen during binary I O Third using the get and put write member functions still aren t guaranteed to help you These are unformatted T O functions but still character based This may or may not be what you want see below Notice how all the problems here are due to the inappropriate use of formatting functions and classes to perform something which requires that formatting not be done There are a seemingly infinite number of solutions and
414. tion and operator calls via new and delete operator or member function calls Second allocation via allocator And finally smart pointer and intelligent pointer abstractions 6 3 1 Allocators Memory management for Standard Library entities is encapsulated in a class template called allocator The allocator abstraction is used throughout the library in st ring container classes algorithms and parts of iostreams This class and base classes of it are the superset of available free store heap management classes 6 3 1 1 Requirements The C standard only gives a few directives in this area e When you add elements to a container and the container must allocate more memory to hold them the container makes the request via its Allocator template parameter which is usually aliased to allocator_type This includes adding chars to the string class which acts as a regular STL container in this respect e The default Allocator argument of every container of T is allocator lt T gt e The interface of the allocator lt T gt class is extremely simple It has about 20 public declarations nested typedefs member functions etc but the two which concern us most are Tx allocate size_ type n const voidx hint 0 void deallocate Tx p size _type n The n arguments in both those functions is a count of the number of T s to allocate space for not their total size This is a simplification the real signatures use nested typedefs
415. tion will issue an error if you try to compile code like this include lt vector gt include lt memory gt vota Edo Stds viector lt star sautouprer lt intk gt gt vec_ap_int Should you try this with the checks enabled you will see an error The GNU C Library 50 253 6 3 3 shared_ptr The shared ptr class template stores a pointer usually obtained via new and implements shared ownership semantics 6 3 3 1 Requirements The standard deliberately doesn t require a reference counted implementation allowing other techniques such as a circular linked list At the time of writing the C 0x working paper doesn t mention how threads affect shared_ptr but it is likely to follow the existing practice set by boost shared_ptr The shared pr in libstdc is derived from Boost s so the same rules apply 6 3 3 2 Design Issues The shared_ptr code is kindly donated to GCC by the Boost project and the original authors of the code The basic design and algorithms are from Boost the notes below describe details specific to the GCC implementation Names have been uglified in this implementation but the design should be recognisable to anyone familiar with the Boost 1 32 shared ptr The basic design is an abstract base class _Sp_counted_base that does the reference counting and calls virtual functions when the count drops to zero Derived classes override those functions to destroy resources in a context where the corr
416. tions for templates typeinfo information and virtual tables all may cause ABI leakage across shared library boundaries Because of this mixing C ABIs is not recommended at this time For more background on this issue see these bugzilla entries 24660 versioning weak symbols in libstdc 19664 libstdc headers should have pop push of the visibility around the declarations B 4 8 Bibliography 55 uri ABIcheck a vague idea of checking ABI compatibility 56 uri C ABI Reference 57 uri Intel Compilers for Linux Compatibility with the GNU Compilers 58 uri Sun Solaris 2 9 Linker and Libraries Guide document 816 1386 59 uri Sun Solaris 2 9 C Migration Guide document 816 2459 60 Ulrich Drepper uri How to Write Shared Libraries 61 uri C ABI for the ARM Architecture 62 Benjamin Kosnik uri Dynamic Shared Objects Survey and Issues ISO C J16 06 0046 63 Benjamin Kosnik uri Versioning With Namespaces ISO C J16 06 0083 64 Pavel ShvedDenis Silakov uri Binary Compatibility of Shared Libraries Implemented in C on GNU Linux Systems SYRCoSE 2009 B 5 API Evolution and Deprecation History A list of user visible changes in chronological order The GNU C Library 218 253 B 5 1 3 0 Extensions moved to include ext Include files from the SGI HP sources that pre date the ISO standard are added These files are placed into the include backward directory and
417. to allow C visibility of this feature on GNU Linux the flag is D_ISOC99_SOURCE which is added automatically via CPLUSPLUS_CPP_SPEC s addition of _ GNU_SOURCE This option can change the library ABI enable fully dynamic string This option enables a special version of basic_string avoiding the optimization that allocates empty objects in static memory Mostly useful together with shared memory allocators see PR libstdc 16612 for details enable concept checks This turns on additional compile time checks for instantiated library templates in the form of specialized templates described here They can help users discover when they break the rules of the STL before their programs run enable symvers style In 3 1 and later tries to turn on symbol versioning in the shared library if a shared library has been requested Values for style that are currently supported are gnu gnu versioned namespace darwin and darwin export Both gnu options require that a recent version of the GNU linker be in use Both darwin options are equivalent With no style given the configure script will try to guess correct defaults for the host system probe to see if additional requirements are necessary and present for activation and if so will turn symbol versioning on This option can change the library ABI enable visibility In 4 2 and later enables or disables visibility attributes If enabled as by default and t
418. to get at that member with rdbuf Then the public version of set buf can be called The arguments are the same as those for the Standard C I O Library function a buffer area followed by its size A great deal of this is implementation dependent For example st reambuf does not specify any actions for its own setbu f ish functions the classes derived from streambuf each define behavior that makes sense for that class an argument of 0 0 turns off buffering for filebuf but does nothing at all for its siblings st ringbuf and strstreambuf and specifying anything other than 0 0 has varying effects User defined classes derived from st reambuf can do whatever they want For filebuf and arguments for p s other than zeros libstdc does what you d expect the first s bytes of p are used as a buffer which you must allocate and deallocate A last reminder there are usually more buffers involved than just those at the language library level Kernel buffers disk buffers and the like will also have an effect Inspecting and changing those are system dependent 13 3 Memory Based Streams 13 3 1 Compatibility With strstream Stringstreams defined in the header lt sst ream gt are in this author s opinion one of the coolest things since sliced time An example of their use is in the Received Wisdom section for Sect 21 Strings describing how to format strings The quick definition is they are siblings of ifstream and ofstream an
419. to give better performance we print the advice and estimated performance gain The advice is usually associated to a code position and possibly a call stack Second we report performance characteristics for which we do not have a clear solution for improvement For instance we can point to the user the top 10 mult imap locations which have the worst data locality in actual traversals Although this does not offer a solution it helps the user focus on the key problems and ignore the uninteresting ones 19 2 7 Testing First we want to make sure we preserve the behavior of the release mode You can just type make check profile which builds and runs the whole test suite in profile mode Second we want to test the correctness of each diagnostic We created a profile directory in the test suite Each diagnostic must come with at least two tests one for false positives and one for false negatives 19 3 Extensions for Custom Containers Many large projects use their own data structures instead of the ones in the standard library If these data structures are similar in functionality to the standard library they can be instrumented with the same hooks that are used to instrument the standard library The instrumentation API is exposed in file profiler h look for Instrumentation hooks The GNU C Library 119 253 19 4 Empirical Cost Model Currently the cost model uses formulas with predefined relative weights for alternative container
420. tomic_word is a signed integral type supporting atomic operations The two functions functions are The GNU C Library 151 253 _Atomic_word __exchange_and_add_dispatch volatile _Atomic_wordx int void __atomic_add_dispatch volatile _Atomic_word int Both of these functions are declared in the header file lt ext atomicity h gt and are in namespace __gnu_cxx e _ exchange_and_add _dispatch Adds the second argument s value to the first argument Returns the old value atomic_add_dispatch Adds the second argument s value to the first argument Has no return value These functions forward to one of several specialized helper functions depending on the circumstances For instance __exchange_and_add_dispatch Calls through to either of e _ exchange_and_add Multi thread version Inlined if compiler generated builtin atomics can be used otherwise resolved at link time to a non builtin code sequence e _ exchange_and_add_single Single threaded version Inlined However only__ ex change_and_add_dispatch and__atomic_add_dispatch should be used These functions can be used in a portable manner regardless of the specific environment They are carefully designed to provide optimum efficiency and speed abstracting out atomic accesses when they are not required even on hosts that support compiler intrinsics for atomic operations In addition there are two macros GLIBCXX_READ_ME T BARRIER
421. tor on any iterator on a particular multi set map e Cost model Sum cost hashtable method Sum cost rbtree method for method in insert erase find Cost iterate hashtable Cost iterate rbtree s Example 19 7 3 Algorithms Switch _GLIBCXX_PROFILE_ALGORITHMS 19 7 3 1 e Switch _GLIBCXX_PROFILE T 1 set lt int gt s 2 ore amne at OF a lt LOS spat 3 s insert i a y 5 ne sum OF S fom Gua 1 Oe i lt 100000 Sepa 7 sum x s find i 8 Sort Algorithm Performance _SORT e Goal Give measure of sort algorithm performance based on actual input For instance advise Radix Sort over Quick Sort for a particular call context e Fundamentals See papers A framework for adaptive algorithm selection in STAPL and Optimizing Sorting with Machine Learning Algorithms e Sample runtime reduction 60 e Recommendation Change sort algorithm at site S from X Sort to Y Sort e To instrument sort algorithm e Analysis Issue the advice if the cost model tells us that another sort algorithm would do better on this input Requires us to know what algorithm we are using in our sort implementation in release mode e Cost model Runtime algo for algo in radix quick merge s Example 19 7 4 Data Locality Switch _GLIBCXX_PROFILE_LOCALITY The GNU C Library 128 253 19 7 4 1 Need Software Prefetch e Switch _GLIBCXX_PROFILE_SOFTWARE_PREFE
422. tors are not valid the conversion descriptors returned will not be valid and the resulting calls to the codecvt conversion functions will return error bool _M_good Provides a way to see if the given encoding _state object has been properly initialized If the string literals describing the desired internal and external encoding are not valid initialization will fail and this will return false If the internal and external encodings The GNU C Library 71 253 are valid but iconv_open could not allocate conversion descriptors this will also return false Otherwise the object is ready to convert and will return true encoding_state const encoding_state As iconv allocates memory and sets up conversion descriptors the copy constructor can only copy the member data pertaining to the internal and external code conversions and not the conversion descriptors themselves Definitions for all the required codecvt member functions are provided for this specialization and usage of codecvt lt internal character type external character type encoding_state gt is consistent with other codecvt usage 8 2 2 4 Use A conversions involving string literal typedef codecvt_base result result typedef unsigned short unicode_t typedef unicode_t int_type typedef char ext_type typedef encoding_state state_type typedef codecvt lt int_type ext_type state_type gt unicode_codecvt const ext_typex e_lit black pearl jasmine tea
423. tr I O Y 2238 shared_ptr specialized Y algorithms 2 2 3 9 shared_ptr casts Y 2 2 3 10 get_deleter Y 2 2 4 Class template weak_ptr 2 2 4 1 weak_ptr constructors Y 2 2 4 2 weak_ptr destructor Y 2 2 4 3 weak_ptr assignment Y 2 2 4 4 weak_ptr modifiers Y 2 2 4 5 weak_ptr observers Y 2 2 4 6 weak_ptr comparison Y 2247 weak_ptr specialized Y algorithms Class template enable_ aoe shared_from_this T 3 Function Objects 3 1 Definitions Y Additions to 3 2 lt functional gt Y synopsis 3 3 Requirements Y 3 4 Function return types Y 3 5 Function template mem_fn Y 3 6 Function object binders 361 Class template Y is_bind_expression Class template 0 is_placeholder 3 6 3 Function template bind Y 3 6 4 Placeholders Y 37 Polymorphic function wrappers The GNU C Library 7 253 Section Description Status Comments 0 Introduction 1 Normative references 2 Conventions 3 Decimal floating point types 3 1 Characteristics of decimal floating point types 3 2 Decimal Types Missing declarations for formatted input output 3 2 1 Class decima1 synopsis Partial non conforming extension for functions converting to integral type Missing 3 2 2 5 conversion to integral type conforming 3 2 2 Class decima132 Partial extension for conversion from scalar decimal floating point Missing 3 2 3 5 conversion to integral type c
424. ts of the test such as it is will be in the variable enable_ FEATURE where FEATURE has been squashed Example ext ra foo controlled by the enable extra foo option and stored in enable_extra_foo DEFAULT is the value to store in enable FEATURE if the user does not pass enable disable It should be one of the permit ted values passed later Examples yes or bar or 1 which passes the argument given to the GLIBCXX_ENABLE FOO macro as the default For cases where we need to probe for particular models of things it is useful to have an undocumented auto value here see GLIBCXX_ENABLE_CLOCALE for an example HELP ARG is any text to append to the option string itself in the help output Examples e an empty string which appends nothing BAR which produces nabl xtra foo BAR and lt BAR gt which produces nabl xtra foo BAR See the difference See what it implies to the user If you re wondering what that line noise in the last example was that s how you embed autoconf special characters in output text They re called quadrigraphs and you should use them whenever necessary HELP STRING is what you think it is Do not include the default text like we used to do it will be done for you by GLIBCXX_ENABLE By convention these are not full English sentences Example turn on extra foo With no other arguments only the standard autoconf patterns are allowed enable
425. u can then use output stringstreams like this ifdef HAVE_SSTREAM include lt sstream gt else include lt strstream gt endif ifdef HAVE_SSTREAM std ostringstream oss else std ostrstream oss endif The GNU C Library oss lt lt Name lt lt m_name lt lt number lt lt m_number lt lt std endl ifndef HAVE _SSTREAM oss lt lt std ends terminate the charx string fendif str returns charx for ostrstream and a string for ostringstream this also causes ostrstream to think that the buffer s memory IS As youses m_label set_text oss str ifndef HAVE_SSTREAM let the ostrstream take care of freeing the memory oss freeze false tendif Input stringstreams can be used similarly Suela a STELE alioyarbuc y ifdef HAVE_SSTREAM std istringstream iss input else SCS H LEE T E ERL les aimjomic E Sie endif Aae Lp LSS gt gt lp One the only restriction is that an istrstream cannot be re filled std istringstream iss numerator iss gt gt m_num this is not possible with istrstream iss clear iss str denominator iss gt gt m_den If you don t care about speed you can put these conversions in a template function template lt class X gt void fromString const stringg input X amp any ifdef HAVE_SSTREAM std istringstream iss input else starts sie antes s Am
426. umber incoming_stream gt gt the_word if earract Troon gt gt the_number extract N ostringstream Output_stream output_stream lt lt The word was lt lt the_word lt lt and 3xN was lt lt 3xthe_number return output stream str A serious problem with CString is a design bug in its memory allocation Specifically quoting from that same message CString suffers from a common programming error that results in poor performance Consider the following code CStuing necoplcsmor consi CSeringe OO unsigned CString Tamor ioe Wiasilciaco Gk OP a lt my iF tmp foo return tmp This function is O n 2 not O n The reason is that each The GNU C Library 59 253 causes a reallocation and copy of the existing string Microsoft applications are full of this kind of thing quadratic performance on tasks that can be done in linear time on the other hand we should be thankful as it s created such a big market for high end ix86 hardware If you replace CString with string in the above function the performance is O n Joe Buck also pointed out some other things to keep in mind when comparing CString and the Standard string class e CString permits access to its internal representation coders who exploited that may have problems moving to st ring e Microsoft ships the source to CString in the files MFC SRC Str core ex cpp so you could fix the allocation bug and rebuild your M
427. ured in the size of the executable binary and varies with the capabilities of the underlying operating system and specific configuration of the C compiler On recent hardware with GNU system software of the same age the combined code and data size overhead for enabling exception handling is around 7 Of course if code size is of singular concern than using the appropriate optimizer setting with exception handling enabled ie Os fexceptions may save up to twice that and preserve error checking So Hell bent we race down the slippery track knowing the brakes are a little soft and that the right front wheel has a tendency to wobble at speed Go on detail the standard library support for fno exceptions In sum valid C code with exception handling is transformed into a dialect without exception handling In detailed steps all use of the C keywords try catch and throw in the standard library have been permanently replaced with the pre processor controlled equivalents spelled __try __catch and__throw_exception_again They are defined as follows ifdef _ EXCEPTIONS define _ try try define __ catch X catch X The GNU C Library 31 253 define _ throw_exception_again throw else define _ try if true define _ catch X if false define __throw_exception_again endif In addition for every object derived from class exception there exists a corresponding function with C language linkage An
428. ve the global C locale through the use of the C functions toupper tolower This is absolutely guaranteed to work but only if the string contains only characters from the basic source character set and there are only 96 of The GNU C Library 55 253 those Which means that not even all English text can be represented certain British spellings proper names and so forth So 1f all your input forevermore consists of only those 96 characters hahahahahaha then you re done Note that the ToUpper and ToLower function objects are needed because toupper and tolower are overloaded names declared in lt cctype gt and lt locale gt so the template arguments for t ransform lt gt cannot be deduced as explained in this message At minimum you can write short wrappers like char toLower char c return std tolower c Thanks to James Kanze for assistance and suggestions on all of this Another common operation is trimming off excess whitespace Much like transformations this task is trivial with the use of string s find family These examples are broken into multiple statements for readability Siecle Sicilias str Y Ye olan olar olan a e trim leading whitespace errime Elda os mois T T ole GEU ic Vail 6 str erase 0 notwhite trim trailing whitespace momias Str bal last mer ar Ne e str erase notwhite 1 Obviously the calls to find could be inserted directly into the calls to erase in case your compile
429. ver at no charge c Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source This alternative is allowed only occasionally and noncommercially and only if you received the object code with such an offer in accord with subsection 6b d Convey the object code by offering access from a designated place gratis or for a charge and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge You need not require recipients to copy the Corresponding Source along with the object code If the place to copy the object code is a network server the Corresponding Source may be on a different server operated by you or a third party that supports equivalent copying facilities provided you maintain clear directions next to the object code saying where to find the Corresponding Source Regardless of what server hosts the Corresponding Source you remain obligated to ensure that it is available for as long as needed to satisfy these requirements e Convey the object code using peer to peer transmission provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d A separable portion of the object code whose source code is excluded from the Corresponding Source as a System Library need not be included in conveying the object code work A User P
430. verhead can be eliminated for that case without sacrificing flexibility This takes full advantage of any ability of the optimizer to crush out degenerate code The library specifies many virtual functions which current linkers load even when they cannot be called Some minor improvements to the compiler and to ld would eliminate any such overhead by simply omitting virtual functions that the complete program does not call A prototype of this work has already been done For targets where GNU ld is not used a pre linker could do the same job The main areas in the standard interface where user flexibility can result in overhead are The GNU C Library 176 253 Allocators Containers are specified to use user definable allocator types and objects making tuning for the container characteristics tricky Locales the standard specifies locale objects used to implement iostream operations involving many virtual functions which use streambuf iterators Algorithms and containers these may be instantiated on any type frequently duplicating code for identical operations Tostreams and strings users are permitted to use these on their own types and specify the operations the stream must use on these types Note that these sources of overhead are _avoidable_ The techniques to avoid them are covered below Code Bloat In the SGI STL and in some other headers many of the temp
431. version from a floating point type str precision is specified in the conversion specification Insertion hints in associative containers Implement N1780 first check before then check after insert as close to hint as possible No specification of default ctor for reverse_iterator The declaration of reverse_iterator lists a default constructor However no specification is given what this constructor should do Does unique_copy require CopyConstructible and Assignable Add a helper for forward_iterator output_iterator fix the existing one for input_iterator output_iterator to not rely on Assignability get and getline when sentry reports failure Store a null character only if the character array has a non zero size basic_stringbuf missing allocator_type This nested typedef was originally not specified valarray helper functions are almost entirely useless Make the copy constructor and copy assignment operator declara tions public in gslice_array indirect_array mask_array slice_array provide definitions std pair pair effects overly restrictive The default ctor would build its members from copies of temporaries now it simply uses their respective default ctors bad_exception bad_exception missing Effects clause The bad_ classes no longer have destructors they are trivial since no description of them was ever given basic_iostream missing typedefs The typedefs it inherits from its base classes can t be used since for
432. version of get_temporary_buffer taking a second argument The argument is a pointer which is ignored but can be used to specify the template type instead of using explicit function template arguments like the standard version does That is in addition to get_temporary_buffer lt int gt 5 you can also use get_temporary_buffer 5 intx 0 A class temporary_buf fer is given in stl_tempbuf h The specialized algorithms of section 20 4 4 are extended with uninitialized_copy_n The GNU C Library 144 253 Chapter 23 Algorithms 25 1 6 count count_if is extended with two more versions of count and count_if The standard versions return their results The additional signatures return void but take a final parameter by reference to which they assign their results e g sold count fist Last value Na 25 2 mutating algorithms is extended with two families of signatures random_sample and random_sample_n 25 2 1 copy is extended with coe ma OPUS st olya Corie OU putters eS ml ee which copies the first count elements at first into result 25 3 sorting n heaps n stuff is extended with some helper predicates Look in the doxygen generated pages for notes on these e is_heap tests whether or not a range is a heap e is_sorted tests whether or not a range is sorted in nondescending order 25 3 8 lexicographical_compare is extended with lexicographical_compare_3way _Inputlterl firstl
433. w Is vector lt reverse_iterator lt char gt gt forbidden Tweak the debug mode checks in _Safe_iterator Closing an fstream should clear the error state Have open clear the error flags Swapping containers with unequal allocators Implement Option 3 as per N1599 stringbuf overflow makes only one write position available Implement the resolution beyond DR 169 bitset to_string hard to use Add three overloads taking fewer template arguments Ambiguity in the do the right thing clause Implement the resolution basically cast less basic_stringbuf seekoff need not always fail for an empty stream Don t fail if the next pointer is null and newoff is zero cerr tie and wcerr tie are overspecified Initialize cerr tied to cout and wcerr tied to wcout Suggestion for new member functions in standard containers Add data to std vectorand at const key _type to std map Bad parameters for ranlux64_base_01 Fix the parameters Seeding subtract_with_carry_01 from a single unsigned long Construct a linear_congruential engine and seed with it Ts it undefined if a function in the standard changes in parameters Use amp value 241 again Does unique_copy require CopyConstructible and Assignable In case of input_iterator output_iterator rely on Assignability of input_iterator value_type partial_sum and adjacent_difference should mention requirements We were almost doing the right thing just use std move in adjacent_diff
434. well because we are mainly concerned with speed of allocation deallocation and memory consumption whereas here the allocation deallocation part does have some linear logarithmic complexity components in it Thus to try and minimize them would be a good thing to do at the cost of a little bit of memory Another thing to be noted is the pool size will double every time the internal pool gets exhausted and all the free blocks have been given away The initial size of the pool would be sizeof size_t x 8 which is the number of bits in an integer which can fit exactly in a CPU register Hence the term given is exponential growth of the internal pool The GNU C Library 141 253 Chapter 21 Containers 21 1 Policy Based Data Structures More details here 21 2 HP SGI A few extensions and nods to backwards compatibility have been made with containers Those dealing with older SGI style allocators are dealt with elsewhere The remaining ones all deal with bits The old pre standard bit_vector class is present for backwards compatibility It is simply a typedef for the vector lt bool gt specialization The bit set class has a number of extensions described in the rest of this item First we ll mention that this implementation of bitset lt N gt is specialized for cases where N number of bits will fit into a single word of storage If your choice of N is within that range lt 32 on 1686 pc linux gnu for example then all of the ope
435. what went wrong without even using a debugger 17 The doxygen style guide to comments is a separate document see index The library currently has a mixture of GNU C and modern C coding styles The GNU C usages will be combed out gradually Name patterns For nonstandard names appearing in Standard headers we are constrained to use names that begin with underscores This is called uglification The convention is Local and argument names _ a z Examples _ count __ix _ sl Type names and template formal argument names _ A Z _ Examples _Helper _CharT _N ember data and function names _M_ x Examples _M num elements _M initialize Static data members constants and enumerations _S_ x Examples _S_max_elements _S_default_value The GNU C Library 166 253 Don t use names in the same scope that differ only in the prefix e g _S_top and _M top See BADNAMES for a list of forbidden names The most tempting of these seem to be and _T and __sz Names must never have __ internally it would confuse name unmanglers on some targets Also never use __ 0 9 same reason BY EXAMPLE ifndef _HEADER_ define _HEADER_ 1 namespace std class gribble public gribble throw gribble const gribbles explicit gribble int __howmany gribbles operator const gribbles virtual gribble throw
436. with a cross compiler we have to hardcode the results of what the tests would have shown if they could be run So we have an inflexible mess like crossconfig m4 Wouldn t it be nice if we could store that information in files like configure host which can be modified without needing to regenerate anything and can even be tweaked without really knowing how the configury all works Perhaps break the pieces of crossconfig m4 out and place them in their appropriate config cpu os directory Alas writing macros like AC_DEF INE HAVE_A_NICE_DAY can only be done inside files which are passed through auto conf Files which are pure shell script can be source d at configure time Files which contain autoconf macros must be processed with autoconf We could still try breaking the pieces out into config cross m4 bits for instance but then we would need arguments to aclocal autoconf to properly find them all when generating configure I would discourage that B 1 4 Coding and Commenting Conventions Most comments should use octothorpes shibboleths hash marks pound signs whatever rather than dnl Nearly all com ments in configure ac should Comments inside macros written in ancilliary m4 files should About the only comments which The GNU C Library 190 253 should not use but use dnl instead are comments outside our own macros in the ancilliary files The difference is that com ments show up in configu
437. x pow return type is ambiguous In C 0x mode remove the pow complex lt T gt int signature to_string needs updating with zero and one Update add the signatures More algorithms that throw away information The traditional HP SGI return type and value is blessed by the resolution of the DR The GNU C Library 14 253 Chapter 2 Setup To transform libstdc sources into installed include files and properly built binaries useful for linking to other software is a multi step process Steps include getting the sources configuring and building the sources testing and installation The general outline of commands is something like get geo sources Extras Aint ET ge e Sis qua mkdir gecbuilddir ed geebua lddin gccsrcdir configure prefix destdir other opts make make check make install Each step is described in more detail in the following sections 2 1 Prerequisites Because libstdc is part of GCC the primary source for installation instructions is the GCC install page In particular list of prerequisite software needed to build the library starts with those requirements The same pages also list the tools you will need if you wish to modify the source Additional data is given here only where it applies to libstdc As of GCC 4 0 1 the minimum version of binutils required to build libstdc is 2 15 90 0 1 1 You can get snapshots as well as releases of binutils from ftp sources redhat com pub binutils O
438. y markers beginning end This is bad Always having to remember to add or subtract one Off by one bugs very common here M V array of N elements al O ess INEZ ew SS 842 is ds Cons Wats is Same Myks is guaranteed to work Just don t dereference end beginning end See Everything between the boundary markers is chapter of the array Simple Now think back to your junior high school algebra course when you were learning how to draw graphs Remember that a graph terminating with a solid dot meant Everything up through this point and a graph terminating with an open dot meant Everything up to but not including this point respectively called closed and open ranges Remember how closed ranges were written with brackets fa b and open ranges were written with parentheses a b The boundary markers for arrays describe a half open range starting with and including the first element and ending with but not including the last element beginning end See I told you it would be simple in the end Iterators and everything working with iterators follows this same time honored tradition A container s begin method returns an iterator referring to the first element and its end method returns a past the end iterator which is guaranteed to be unique and comparable against any other iterator pointing into the middle of the container Container constructors container methods and algorithms
439. y safe_base_mutex He ome O al T arral _Safe_iterator_basex __ old _ iter _ iter _ iter lt _M next old lt _M_detach_single In this sample code an anonymous namespace is used to keep the __ mut ex private to the compilation unit and ___scoped_ lock is used to guard access to the critical section within the for loop locking the mutex on creation and freeing the mutex as control moves out of this block Several exception classes are used to keep track of concurrence related errors These classes are concurrence_lock_ error concurrence_unlock_error concurrence_wait_error and concurrence_broadcast_ error The GNU C Library 154 253 Part IV Appendices The GNU C Library 155 253 Appendix A Contributing AppendixContributing The GNU C Library follows an open development model Active contributors are assigned maintainer ship responsibility and given write access to the source repository First time contributors should follow this procedure A 1 Contributor Checklist A 1 1 Reading Get and read the relevant sections of the C language specification Copies of the full ISO 14882 standard are available on line via the ISO mirror site for committee members Non members or those who have not paid for the privilege of sitting on the committee and sustained their two meeting commitment for voting rights may get a copy of the standard from their respective national standards organization
440. y a small part of the program can use debugging features 2 Full user recompilation The user must recompile his or her entire application and all C libraries it depends on but not the C standard library itself This must be done even if only a small part of the program can use debugging features This can be achieved given a full recompilation system by compiling two versions of the standard library when the compiler is installed and linking against the appropriate one e g a multilibs approach 3 Partial recompilation The user must recompile the parts of his or her application and the C libraries it depends on that will use the debugging facilities directly This means that any code that uses the debuggable standard containers would need to be recompiled but code that does not use them but may for instance use IOStreams would not have to be recompiled 4 Per use recompilation The user must recompile the parts of his or her application and the C libraries it depends on where debugging should occur and any other code that interacts with those containers This means that a set of translation units that accesses a particular standard container instance may either be compiled in release mode no checking or debug mode full checking but must all be compiled in the same way a translation unit that does not see that standard container instance need not be recompiled This also means that a translation unit A that contains a particular
441. y among possible extensions on the same level as implementation of the template export feature Chapter 18 Language support Headers lt limits gt lt new gt lt typeinfo gt lt exception gt C headers lt cstddef gt lt climits gt lt cfloat gt lt cstdarg gt lt csetjmp gt lt ctime gt lt csignal gt lt cstdlib gt also 21 25 26 This defines the built in exceptions rtti numeric_limits lt gt operator new and delete Much of this is provided by the compiler in its static runtime library Work to do includes defining numeric_limits lt gt specializations in separate files for all target architectures Values for integer types except for bool and wchar_t are readily obtained from the C header lt limits h gt but values for the remaining numeric types bool wchar_t Float double long double must be entered manually This is largely dog work except for those members whose values are not easily deduced from available documentation Also this involves some work in target configuration to identify the correct choice of file to build against and to install The definitions of the various operators new and delete must be made thread safe which depends on a portable exclusion mechanism discussed under chapter 20 Of course there is always plenty of room for improvements to the speed of operators new and delete lt cstdarg gt in Glibc defines some macros that gcc does not
442. y name or part of a longer file name and indicates that this file or the files within this directory are testing the wchar_t instantiation of a template Some hosts do not support wchar_t functionality so for these targets all of these tests will not be run s thread This can either be a directory name or part of a longer file name and indicates that this file or the files within this directory are testing situations where multiple threads are being used e performance This can either be an enclosing directory name or part of a specific file name This indicates a test that is used to analyze runtime performance for performance regression testing or for other optimization related analysis At the moment these test cases are not run by default B 3 2 Running the Testsuite B 3 2 1 Basic You can check the status of the build without installing it using the dejagnu harness much like the rest of the gcc tools make check in the libbuilddir directory or make check target libstdc v3 in the gccbuilddir directory These commands are functionally equivalent and will create a testsuite directory underneath libbuilddir containing the results of the tests Two results files will be generated libstdc sum which is a PASS FAIL summary for each test and libstdc log which is a log of the exact command line passed to the compiler the compiler output and the executable output 1f any Archives of test results for va
443. y penalizing some behavior In fact it s difficult just deciding which typical actions to measure for speed Three synthetic benchmarks have been created that provide data that is used to compare different C allocators These tests are 1 Insertion Over multiple iterations various STL container objects have elements inserted to some maximum amount A variety of allocators are tested Test source for sequence and associative containers 2 Insertion and erasure in a multi threaded environment This test shows the ability of the allocator to reclaim memory on a per thread basis as well as measuring thread contention for memory resources Test source here 3 A threaded producer consumer model Test source for sequence and associative containers The current default choice for allocator is__gnu_cxx new_allocator 6 3 1 3 3 Disabling Memory Caching In use al locator may allocate and deallocate using implementation specified strategies and heuristics Because of this every call to an allocator object s allocate member function may not actually call the global operator new This situation is also duplicated for calls to the deal locate member function This can be confusing In particular this can make debugging memory errors more difficult especially when using third party tools like valgrind or debug versions of new There are various ways to solve this problem One would be to use a custom allocator that just called operato
444. y pool for each type and remember that different instantiations result in different types remains separate The library uses 0 in all its instantiations If you wish to keep separate free lists for a particular purpose use a different number The thr boolean determines whether the pool should be manipulated atomically or not When thr t rue the allocator is thread safe while thr false is slightly faster but unsafe for multiple threads For thread enabled configurations the pool is locked with a single big lock In some situations this implementation detail may result in severe performance degradation Note that the GCC thread abstraction layer allows us to provide safe zero overhead stubs for the threading routines if threads were disabled at configuration time 7 mt_alloc A high performance fixed size allocator with exponentially increasing allocations It has its own documentation found here 8 bitmap_allocator A high performance allocator that uses a bit map to keep track of the used and unused memory locations It has its own documentation found here 6 3 1 7 Bibliography 9 Matt Austern uri The Standard Librarian What Are Allocators Good For C C Users Journal 10 Emery Berger uri The Hoard Memory Allocator 11 Emery BergerBen ZornKathryn McKinley uri Reconsidering Custom Memory Allocation Copyright O 2002 OOPSLA 12 Klaus KreftAngelika Langer uri Allocator Types C C Users Journal
445. ype requirements for testing numeric data structures and instantiating algorithms Of particular interest is extending testing to algorithms and then to parallel algorithms Also io and locales The test instrumentation should also be extended to add instrumentation to iterator and const_iterator types that throw conditionally on iterator operations B 3 5 1 3 C 0x Requirements Test Sequence Descriptions e Basic Basic consistency on exception propagation tests For each container an object of that container is constructed a specific member function is exercised in a t ry block and then any thrown exceptions lead to error checking in the appropriate catch block The container s use of resources is compared to the containers use prior to the test block Resource monitoring is limited to allocations made through the container s allocator_type which should be sufficient for container data structures Included in these tests are member functions are iterator and const_iterator operations pop_front pop_back push_ front push_back insert erase swap clear and rehash The container in question is instantiated with two instrumented template arguments with __gnu_cxx throw_allocator_limit as the allocator type and with __g nu_cxx throw_type_limit as the value type This allows the test to loop through conditional throw points The general form is demonstrated in testsuite 23_containers list requirements exception basic cc The instant
446. ypedef Gigi eera e OOl oes Tune tune_type tune_type t_default caso e INS S20 SA AO 20 Ea ESS casco esa SAS S20 S42 S120 i 10 relse oiis oy pe E7 t allocator_type _M_get_options allocator_type _M_set_options t_opt t allocator_type _M_get_options allocator_type a allocator_type pointer pl a allocate 128 allocator_type pointer p2 a allocate 5128 a deallocate pl 128 a deallocate p2 5128 The GNU C Library 133 253 20 1 3 2 Initialization The static variables pointers to freelists tuning parameters etc are initialized as above or are set to the global defaults The very first allocate call will always call the _S_initialize_once function In order to make sure that this function is called exactly once we make use of a __gthread_once call in MT applications and check a static bool _S_init in ST applications The _S_initializeQ function If the GLIBCXX_FORCE_NEW environment variable is set it sets the bool _S_force_new to true and then returns This will cause subsequent calls to allocate to return memory directly from a new call and deallocate will only do a delete call If the GLIBCXX_FORCE_NEW environment variable is not set both ST and MT applications will Calculate the number of bins needed A bin is a specific power of two size of bytes Le by default the allocator will deal with requests of up to 128 bytes or whatever the value of _S_max_bytes is when _S_init

The GNU C++ Library

Contents

Download Pdf Manuals

Related Search

Related Contents