443 lines · plain
1.. _user-documentation:2 3==================4User documentation5==================6 7.. contents::8 :local:9 10This page contains information for users of libc++: how to use libc++ if it is not11the default library used by the toolchain, and what configuration knobs are available12if libc++ is used by the toolchain. This page is aimed at users of libc++, whereas a13separate page contains documentation aimed at vendors who build and ship libc++14as part of their toolchain.15 16 17Using a different version of the C++ Standard18=============================================19 20Libc++ implements the various versions of the C++ standard. Changing the version of21the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will22automatically detect what standard is being used and will provide functionality that23matches that standard in the library.24 25.. code-block:: bash26 27 $ clang++ -std=c++17 test.cpp28 29Note that using ``-std=c++XY`` with a version of the standard that has not been ratified30yet is considered unstable. While we strive to maintain stability, libc++ may be forced to31make breaking changes to features shipped in a C++ standard that has not been ratified yet.32Use these versions of the standard at your own risk.33 34 35Using libc++ when it is not the system default36==============================================37 38Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle39(operating system distribution, SDK, toolchain, etc) and users don't need to do40anything special in order to use the library.41 42However, on systems where libc++ is provided but is not the default, Clang can be invoked43with the ``-stdlib=`` flag to select which standard library is used.44Using ``-stdlib=libc++`` will select libc++:45 46.. code-block:: bash47 48 $ clang++ -stdlib=libc++ test.cpp49 50This flag is not required on systems where libc++ is the default standard library,51such as macOS and FreeBSD.52 53 54Enabling experimental C++ Library features55==========================================56 57Libc++ provides implementations of some experimental features. Experimental features58are either Technical Specifications (TSes) or official features that were voted to59the C++ standard but whose implementation is not complete or stable yet in libc++.60Those are disabled by default because they are neither API nor ABI stable. However,61users can enable the ``-fexperimental-library`` compiler flag to turn those features on.62 63On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),64users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against65the appropriate static library (usually shipped as ``libc++experimental.a``) to get66access to experimental library features.67 68The following features are currently considered experimental and are only provided69when ``-fexperimental-library`` is passed:70 71* The parallel algorithms library (``<execution>`` and the associated algorithms)72* ``std::chrono::tzdb`` and related time zone functionality73* ``<syncstream>``74 75Additionally, assertion semantics are an experimental feature that can be used76to customize the behavior of Hardening (see :ref:`here <assertion-semantics>`).77Assertion semantics mirror the evaluation semantics of C++26 Contracts but are78not a standard feature.79 80.. note::81 Experimental libraries are experimental.82 * The contents of the ``<experimental/...>`` headers and the associated static83 library may not remain compatible between versions.84 * No guarantees of API or ABI stability are provided.85 * When the standardized version of an experimental feature is implemented,86 the experimental feature is removed two releases after the non-experimental87 version has shipped. The full policy is explained :ref:`here <experimental features>`.88 89 90.. _libcxx-configuration-macros:91 92Libc++ Configuration Macros93===========================94 95Libc++ provides a number of configuration macros that can be used by developers to96enable or disable extended libc++ behavior.97 98.. warning::99 Configuration macros that are not documented here are not intended to be customized100 by developers and should not be used. In particular, some configuration macros are101 only intended to be used by vendors and changing their value from the one provided102 in your toolchain can lead to unexpected behavior.103 104**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:105 This macro disables warnings when using deprecated components. For example,106 using `std::auto_ptr` when compiling in C++11 mode will normally trigger a107 warning saying that `std::auto_ptr` is deprecated. If the macro is defined,108 no warning will be emitted. By default, this macro is not defined.109 110**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:111 This macro is used to disable all visibility annotations inside libc++.112 Defining this macro and then building libc++ with hidden visibility gives a113 build of libc++ which does not export any symbols, which can be useful when114 building statically for inclusion into another library.115 116**_LIBCPP_ENABLE_EXPERIMENTAL**:117 This macro enables experimental features. This can be used on compilers that do118 not support the ``-fexperimental-library`` flag. When used, users also need to119 ensure that the appropriate experimental library (usually ``libc++experimental.a``)120 is linked into their program.121 122**_LIBCPP_HARDENING_MODE**:123 This macro is used to choose the :ref:`hardening mode <using-hardening-modes>`.124 125**_LIBCPP_NO_VCRUNTIME**:126 Microsoft's C and C++ headers are fairly entangled, and some of their C++127 headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled128 in from a lot of other headers and provides definitions which clash with129 libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so130 there's no way for libc++ to provide a compatible definition, since you can't131 have multiple definitions).132 133 By default, libc++ solves this problem by deferring to Microsoft's vcruntime134 headers where needed. However, it may be undesirable to depend on vcruntime135 headers, since they may not always be available in cross-compilation setups,136 or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro137 prevents libc++ from depending on vcruntime headers. Consequently, it also138 prevents libc++ headers from being interoperable with vcruntime headers (from139 the aforementioned clashes), so users of this macro are promising to not140 attempt to combine libc++ headers with the problematic vcruntime headers. This141 macro also currently prevents certain `operator new`/`operator delete`142 replacement scenarios from working, e.g. replacing `operator new` and143 expecting a non-replaced `operator new[]` to call the replaced `operator new`.144 145**_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:146 When this macro is defined, the standard library headers will adhere to a147 stricter policy regarding the (transitive) inclusion of other standard library148 headers, only guaranteeing to provide those definitions explicitly mandated by149 the standard. Please notice that defining this macro might break existing codebases150 that implicitly rely on standard headers providing definitions not explicitly151 required by the standard.152 153 The primary motivation for this configuration macro is to improve compilation154 times. In most standard library implementations, header files include more155 definitions than officially required because the implementation details give rise156 to internal dependencies. The common practice is to have the standard headers157 internally include other standard headers, but this generally results in158 increased compilation overhead. This configuration option attempts to mitigate159 this problem by avoiding such unnecessary inclusions. Compiling160 a codebase with this macro may improve portability by identifying161 missing standard header inclusions.162 163 However, be aware that enabling this macro may lead to breakages164 when updating to a newer version of the library, since transitive includes165 that your code was previously relying on may have been removed.166 167C++17 Specific Configuration Macros168-----------------------------------169**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:170 This macro is used to re-enable `auto_ptr`.171 172**_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**:173 This macro is used to re-enable the `binder1st`, `binder2nd`,174 `pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`,175 `mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`,176 `const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t`177 class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`,178 and `ptr_fun` functions.179 180**_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**:181 This macro is used to re-enable the `random_shuffle` algorithm.182 183**_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**:184 This macro is used to re-enable `unary_function` and `binary_function`.185 186**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:187 This macro is used to re-enable `set_unexpected`, `get_unexpected`, and188 `unexpected`.189 190C++20 Specific Configuration Macros191-----------------------------------192**_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:193 This macro is used to re-enable the `argument_type`, `result_type`,194 `first_argument_type`, and `second_argument_type` members of class195 templates such as `plus`, `logical_not`, `hash`, and `owner_less`.196 197**_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**:198 This macro is used to re-enable `not1`, `not2`, `unary_negate`,199 and `binary_negate`.200 201**_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:202 This macro is used to re-enable `raw_storage_iterator`.203 204**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:205 This macro is used to re-enable the function206 ``std::shared_ptr<...>::unique()``.207 208**_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:209 This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.210 211**_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:212 This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,213 `result_of` and `result_of_t`.214 215**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:216 This macro is used to re-enable `uncaught_exception`.217 218C++26 Specific Configuration Macros219-----------------------------------220 221**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:222 This macro is used to re-enable redundant member of ``allocator<T>::is_always_equal``.223 224**_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:225 This macro is used to re-enable all named declarations in ``<codecvt>``.226 227**_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**:228 This macro is used to re-enable the function229 ``std::basic_string<...>::reserve()``.230 231**_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:232 This macro is used to re-enable all named declarations in ``<strstream>``.233 234**_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**:235 This macro is used to re-enable the ``wstring_convert`` and ``wbuffer_convert``236 in ``<locale>``.237 238Libc++ Extensions239=================240 241This section documents various extensions provided by libc++242and any information regarding how to use them.243 244Extended integral type support245------------------------------246 247Several platforms support types that are not specified in the C++ standard,248such as the 128-bit integral types ``__int128_t`` and ``__uint128_t``.249As an extension, libc++ does a best-effort attempt to support these types like250other integral types, by supporting them notably in:251 252* ``<bits>``253* ``<charconv>``254* ``<functional>``255* ``<format>``256* ``<random>``257* ``<type_traits>``258 259Additional types supported in random distributions260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~261 262The `C++ Standard <http://eel.is/c++draft/rand#req.genl-1.5>`_ mentions that instantiating several random number263distributions with types other than ``short``, ``int``, ``long``, ``long long``, and their unsigned versions is264undefined. As an extension, libc++ supports instantiating ``binomial_distribution``, ``discrete_distribution``,265``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``, and ``uniform_int_distribution``266with ``int8_t``, ``__int128_t`` and their unsigned versions.267 268Extensions to ``<format>``269--------------------------270 271The exposition only type ``basic-format-string`` and its typedefs272``format-string`` and ``wformat-string`` became ``basic_format_string``,273``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types274available in C++20 as an extension.275 276For padding Unicode strings the ``format`` library relies on the Unicode standard.277Libc++ retroactively updates the Unicode standard in older C++ versions.278This allows the library to have better estimates for newly introduced Unicode code points,279without requiring the user to use the latest C++ version in their code base.280 281In C++26 formatting pointers gained a type ``P`` and allows to use282zero-padding. These options have been retroactively applied to C++20.283 284Extensions to the C++23 modules ``std`` and ``std.compat``285----------------------------------------------------------286 287Like other major implementations, libc++ provides C++23 modules ``std`` and288``std.compat`` in C++20 as an extension.289 290Constant-initialized std::string291--------------------------------292 293As an implementation-specific optimization, ``std::basic_string`` (``std::string``,294``std::wstring``, etc.) may either store the string data directly in the object, or else store a295pointer to heap-allocated memory, depending on the length of the string.296 297As of C++20, the constructors are now declared ``constexpr``, which permits strings to be used298during constant-evaluation time. In libc++, as in other common implementations, it is also possible299to constant-initialize a string object (e.g. via declaring a variable with ``constinit`` or300``constexpr``), but only if the string is short enough to not require a heap allocation.301Reliance upon this is discouraged in portable code, as the allowed length differs based on the302standard-library implementation and also based on whether the platform uses 32-bit or 64-bit303pointers.304 305.. code-block:: cpp306 307 // Non-portable: 11-char string works on 64-bit libc++, but not on 32-bit.308 constinit std::string x = "hello world";309 310 // Prefer to use string_view, or remove constinit/constexpr from the variable definition:311 constinit std::string_view x = "hello world";312 std::string_view y = "hello world";313 314.. _turning-off-asan:315 316Turning off ASan annotation in containers317-----------------------------------------318 319``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable320`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators.321This may be necessary for allocators that access allocated memory.322This customization point exists only when ``_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS`` Feature Test Macro is defined.323 324For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_325instead of disabling annotations altogether.326 327The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_328with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.329 330The annotations for a ``user_allocator`` can be disabled like this:331 332.. code-block:: cpp333 334 #ifdef _LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS335 template <class T>336 struct std::__asan_annotate_container_with_allocator<user_allocator<T>> : std::false_type {};337 #endif338 339Why may I want to turn it off?340~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~341 342There are a few reasons why you may want to turn off annotations for an allocator.343Unpoisoning may not be an option, if (for example) you are not maintaining the allocator.344 345* You are using allocator, which does not call destructor during deallocation.346* You are aware that memory allocated with an allocator may be accessed, even when unused by container.347 348Support for compiler extensions349-------------------------------350 351Clang, GCC and other compilers all provide their own set of language extensions. These extensions352have often been developed without particular consideration for their interaction with the library,353and as such, libc++ does not go out of its way to support them. The library may support specific354compiler extensions which would then be documented explicitly, but the basic expectation should be355that no special support is provided for arbitrary compiler extensions.356 357Platform specific behavior358==========================359 360Windows361-------362 363The ``stdout``, ``stderr``, and ``stdin`` file streams can be placed in364Unicode mode by a suitable call to ``_setmode()``. When in this mode,365the sequence of bytes read from, or written to, these streams is interpreted366as a sequence of little-endian ``wchar_t`` elements. Thus, use of367``std::cout``, ``std::cerr``, or ``std::cin`` with streams in Unicode mode368will not behave as they usually do since bytes read or written won't be369interpreted as individual ``char`` elements. However, ``std::wcout``,370``std::wcerr``, and ``std::wcin`` will behave as expected.371 372Wide character stream such as ``std::wcin`` or ``std::wcout`` imbued with a373locale behave differently than they otherwise do. By default, wide character374streams don't convert wide characters but input/output them as is. If a375specific locale is imbued, the IO with the underlying stream happens with376regular ``char`` elements, which are converted to/from wide characters377according to the locale. Note that this will not behave as expected if the378stream has been set in Unicode mode.379 380 381Third-party Integrations382========================383 384Libc++ provides integration with a few third-party tools.385 386Debugging libc++ internals in LLDB387----------------------------------388 389LLDB hides the implementation details of libc++ by default.390 391E.g., when setting a breakpoint in a comparator passed to ``std::sort``, the392backtrace will read as393 394.. code-block::395 396 (lldb) thread backtrace397 * thread #1, name = 'a.out', stop reason = breakpoint 3.1398 * frame #0: 0x000055555555520e a.out`my_comparator(a=1, b=8) at test-std-sort.cpp:6:3399 frame #7: 0x0000555555555615 a.out`void std::__1::sort[abi:ne200000]<std::__1::__wrap_iter<int*>, bool (*)(int, int)>(__first=(item = 8), __last=(item = 0), __comp=(a.out`my_less(int, int) at test-std-sort.cpp:5)) at sort.h:1003:3400 frame #8: 0x000055555555531a a.out`main at test-std-sort.cpp:24:3401 402Note how the caller of ``my_comparator`` is shown as ``std::sort``. Looking at403the frame numbers, we can see that frames #1 until #6 were hidden. Those frames404represent internal implementation details such as ``__sort4`` and similar405utility functions.406 407To also show those implementation details, use ``thread backtrace -u``.408Alternatively, to disable those compact backtraces, use ``frame recognizer list``409and ``frame recognizer disable`` on the "libc++ frame recognizer".410 411Futhermore, stepping into libc++ functions is disabled by default. This is controlled via the412setting ``target.process.thread.step-avoid-regexp`` which defaults to ``^std::`` and can be413disabled using ``settings set target.process.thread.step-avoid-regexp ""``.414 415GDB Pretty printers for libc++416------------------------------417 418GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does419provide pretty-printers itself. Those can be used as:420 421.. code-block:: bash422 423 $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \424 -ex "python register_libcxx_printer_loader()" \425 <args>426 427 428.. _include-what-you-use:429 430include-what-you-use (IWYU)431---------------------------432 433libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,434which drastically improves the accuracy of the tool when using libc++. To use the mapping file with435IWYU, you should run the tool like so:436 437.. code-block:: bash438 439 $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp440 441If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``442file with the libc++-provided ``libcxx.imp`` file.443