1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
|
.. _user-documentation:
==================
User documentation
==================
.. contents::
:local:
This page contains information for users of libc++: how to use libc++ if it is not
the default library used by the toolchain, and what configuration knobs are available
if libc++ is used by the toolchain. This page is aimed at users of libc++, whereas a
separate page contains documentation aimed at vendors who build and ship libc++
as part of their toolchain.
Using a different version of the C++ Standard
=============================================
Libc++ implements the various versions of the C++ standard. Changing the version of
the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will
automatically detect what standard is being used and will provide functionality that
matches that standard in the library.
.. code-block:: bash
$ clang++ -std=c++17 test.cpp
Note that using ``-std=c++XY`` with a version of the standard that has not been ratified
yet is considered unstable. While we strive to maintain stability, libc++ may be forced to
make breaking changes to features shipped in a C++ standard that has not been ratified yet.
Use these versions of the standard at your own risk.
Using libc++ when it is not the system default
==============================================
Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
(operating system distribution, SDK, toolchain, etc) and users don't need to do
anything special in order to use the library.
However, on systems where libc++ is provided but is not the default, Clang can be invoked
with the ``-stdlib=`` flag to select which standard library is used.
Using ``-stdlib=libc++`` will select libc++:
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp
This flag is not required on systems where libc++ is the default standard library,
such as macOS and FreeBSD.
Enabling experimental C++ Library features
==========================================
Libc++ provides implementations of some experimental features. Experimental features
are either Technical Specifications (TSes) or official features that were voted to
the C++ standard but whose implementation is not complete or stable yet in libc++.
Those are disabled by default because they are neither API nor ABI stable. However,
users can enable the ``-fexperimental-library`` compiler flag to turn those features on.
On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
the appropriate static library (usually shipped as ``libc++experimental.a``) to get
access to experimental library features.
The following features are currently considered experimental and are only provided
when ``-fexperimental-library`` is passed:
* The parallel algorithms library (``<execution>`` and the associated algorithms)
* ``std::chrono::tzdb`` and related time zone functionality
* ``<syncstream>``
.. note::
Experimental libraries are experimental.
* The contents of the ``<experimental/...>`` headers and the associated static
library may not remain compatible between versions.
* No guarantees of API or ABI stability are provided.
* When the standardized version of an experimental feature is implemented,
the experimental feature is removed two releases after the non-experimental
version has shipped. The full policy is explained :ref:`here <experimental features>`.
.. _libcxx-configuration-macros:
Libc++ Configuration Macros
===========================
Libc++ provides a number of configuration macros that can be used by developers to
enable or disable extended libc++ behavior.
.. warning::
Configuration macros that are not documented here are not intended to be customized
by developers and should not be used. In particular, some configuration macros are
only intended to be used by vendors and changing their value from the one provided
in your toolchain can lead to unexpected behavior.
**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
This macro disables warnings when using deprecated components. For example,
using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.
**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
This macro is used to disable all visibility annotations inside libc++.
Defining this macro and then building libc++ with hidden visibility gives a
build of libc++ which does not export any symbols, which can be useful when
building statically for inclusion into another library.
**_LIBCPP_ENABLE_EXPERIMENTAL**:
This macro enables experimental features. This can be used on compilers that do
not support the ``-fexperimental-library`` flag. When used, users also need to
ensure that the appropriate experimental library (usually ``libc++experimental.a``)
is linked into their program.
**_LIBCPP_HARDENING_MODE**:
This macro is used to choose the :ref:`hardening mode <using-hardening-modes>`.
**_LIBCPP_NO_VCRUNTIME**:
Microsoft's C and C++ headers are fairly entangled, and some of their C++
headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
in from a lot of other headers and provides definitions which clash with
libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
there's no way for libc++ to provide a compatible definition, since you can't
have multiple definitions).
By default, libc++ solves this problem by deferring to Microsoft's vcruntime
headers where needed. However, it may be undesirable to depend on vcruntime
headers, since they may not always be available in cross-compilation setups,
or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
prevents libc++ from depending on vcruntime headers. Consequently, it also
prevents libc++ headers from being interoperable with vcruntime headers (from
the aforementioned clashes), so users of this macro are promising to not
attempt to combine libc++ headers with the problematic vcruntime headers. This
macro also currently prevents certain `operator new`/`operator delete`
replacement scenarios from working, e.g. replacing `operator new` and
expecting a non-replaced `operator new[]` to call the replaced `operator new`.
**_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:
When this macro is defined, the standard library headers will adhere to a
stricter policy regarding the (transitive) inclusion of other standard library
headers, only guaranteeing to provide those definitions explicitly mandated by
the standard. Please notice that defining this macro might break existing codebases
that implicitly rely on standard headers providing definitions not explicitly
required by the standard.
The primary motivation for this configuration macro is to improve compilation
times. In most standard library implementations, header files include more
definitions than officially required because the implementation details give rise
to internal dependencies. The common practice is to have the standard headers
internally include other standard headers, but this generally results in
increased compilation overhead. This configuration option attempts to mitigate
this problem by avoiding such unnecessary inclusions. Compiling
a codebase with this macro may improve portability by identifying
missing standard header inclusions.
However, be aware that enabling this macro may lead to breakages
when updating to a newer version of the library, since transitive includes
that your code was previously relying on may have been removed.
C++17 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
This macro is used to re-enable `auto_ptr`.
**_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**:
This macro is used to re-enable the `binder1st`, `binder2nd`,
`pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`,
`mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`,
`const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t`
class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`,
and `ptr_fun` functions.
**_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**:
This macro is used to re-enable the `random_shuffle` algorithm.
**_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**:
This macro is used to re-enable `unary_function` and `binary_function`.
**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
This macro is used to re-enable `set_unexpected`, `get_unexpected`, and
`unexpected`.
C++20 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:
This macro is used to re-enable the `argument_type`, `result_type`,
`first_argument_type`, and `second_argument_type` members of class
templates such as `plus`, `logical_not`, `hash`, and `owner_less`.
**_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**:
This macro is used to re-enable `not1`, `not2`, `unary_negate`,
and `binary_negate`.
**_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:
This macro is used to re-enable `raw_storage_iterator`.
**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
This macro is used to re-enable the function
``std::shared_ptr<...>::unique()``.
**_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:
This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
**_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:
This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
`result_of` and `result_of_t`.
**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
This macro is used to re-enable `uncaught_exception`.
C++26 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
This macro is used to re-enable redundant member of ``allocator<T>::is_always_equal``.
**_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:
This macro is used to re-enable all named declarations in ``<codecvt>``.
**_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**:
This macro is used to re-enable the function
``std::basic_string<...>::reserve()``.
**_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:
This macro is used to re-enable all named declarations in ``<strstream>``.
**_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**:
This macro is used to re-enable the ``wstring_convert`` and ``wbuffer_convert``
in ``<locale>``.
Libc++ Extensions
=================
This section documents various extensions provided by libc++
and any information regarding how to use them.
Extended integral type support
------------------------------
Several platforms support types that are not specified in the C++ standard,
such as the 128-bit integral types ``__int128_t`` and ``__uint128_t``.
As an extension, libc++ does a best-effort attempt to support these types like
other integral types, by supporting them notably in:
* ``<bits>``
* ``<charconv>``
* ``<functional>``
* ``<format>``
* ``<random>``
* ``<type_traits>``
Additional types supported in random distributions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `C++ Standard <http://eel.is/c++draft/rand#req.genl-1.5>`_ mentions that instantiating several random number
distributions with types other than ``short``, ``int``, ``long``, ``long long``, and their unsigned versions is
undefined. As an extension, libc++ supports instantiating ``binomial_distribution``, ``discrete_distribution``,
``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``, and ``uniform_int_distribution``
with ``int8_t``, ``__int128_t`` and their unsigned versions.
Extensions to ``<format>``
--------------------------
The exposition only type ``basic-format-string`` and its typedefs
``format-string`` and ``wformat-string`` became ``basic_format_string``,
``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types
available in C++20 as an extension.
For padding Unicode strings the ``format`` library relies on the Unicode standard.
Libc++ retroactively updates the Unicode standard in older C++ versions.
This allows the library to have better estimates for newly introduced Unicode code points,
without requiring the user to use the latest C++ version in their code base.
In C++26 formatting pointers gained a type ``P`` and allows to use
zero-padding. These options have been retroactively applied to C++20.
Extensions to the C++23 modules ``std`` and ``std.compat``
----------------------------------------------------------
Like other major implementations, libc++ provides C++23 modules ``std`` and
``std.compat`` in C++20 as an extension.
Constant-initialized std::string
--------------------------------
As an implementation-specific optimization, ``std::basic_string`` (``std::string``,
``std::wstring``, etc.) may either store the string data directly in the object, or else store a
pointer to heap-allocated memory, depending on the length of the string.
As of C++20, the constructors are now declared ``constexpr``, which permits strings to be used
during constant-evaluation time. In libc++, as in other common implementations, it is also possible
to constant-initialize a string object (e.g. via declaring a variable with ``constinit`` or
``constexpr``), but only if the string is short enough to not require a heap allocation.
Reliance upon this is discouraged in portable code, as the allowed length differs based on the
standard-library implementation and also based on whether the platform uses 32-bit or 64-bit
pointers.
.. code-block:: cpp
// Non-portable: 11-char string works on 64-bit libc++, but not on 32-bit.
constinit std::string x = "hello world";
// Prefer to use string_view, or remove constinit/constexpr from the variable definition:
constinit std::string_view x = "hello world";
std::string_view y = "hello world";
.. _turning-off-asan:
Turning off ASan annotation in containers
-----------------------------------------
``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable
`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators.
This may be necessary for allocators that access allocated memory.
This customization point exists only when ``_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS`` Feature Test Macro is defined.
For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_
instead of disabling annotations altogether.
The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_
with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.
The annotations for a ``user_allocator`` can be disabled like this:
.. code-block:: cpp
#ifdef _LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS
template <class T>
struct std::__asan_annotate_container_with_allocator<user_allocator<T>> : std::false_type {};
#endif
Why may I want to turn it off?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few reasons why you may want to turn off annotations for an allocator.
Unpoisoning may not be an option, if (for example) you are not maintaining the allocator.
* You are using allocator, which does not call destructor during deallocation.
* You are aware that memory allocated with an allocator may be accessed, even when unused by container.
Support for compiler extensions
-------------------------------
Clang, GCC and other compilers all provide their own set of language extensions. These extensions
have often been developed without particular consideration for their interaction with the library,
and as such, libc++ does not go out of its way to support them. The library may support specific
compiler extensions which would then be documented explicitly, but the basic expectation should be
that no special support is provided for arbitrary compiler extensions.
Platform specific behavior
==========================
Windows
-------
The ``stdout``, ``stderr``, and ``stdin`` file streams can be placed in
Unicode mode by a suitable call to ``_setmode()``. When in this mode,
the sequence of bytes read from, or written to, these streams is interpreted
as a sequence of little-endian ``wchar_t`` elements. Thus, use of
``std::cout``, ``std::cerr``, or ``std::cin`` with streams in Unicode mode
will not behave as they usually do since bytes read or written won't be
interpreted as individual ``char`` elements. However, ``std::wcout``,
``std::wcerr``, and ``std::wcin`` will behave as expected.
Wide character stream such as ``std::wcin`` or ``std::wcout`` imbued with a
locale behave differently than they otherwise do. By default, wide character
streams don't convert wide characters but input/output them as is. If a
specific locale is imbued, the IO with the underlying stream happens with
regular ``char`` elements, which are converted to/from wide characters
according to the locale. Note that this will not behave as expected if the
stream has been set in Unicode mode.
Third-party Integrations
========================
Libc++ provides integration with a few third-party tools.
Debugging libc++ internals in LLDB
----------------------------------
LLDB hides the implementation details of libc++ by default.
E.g., when setting a breakpoint in a comparator passed to ``std::sort``, the
backtrace will read as
.. code-block::
(lldb) thread backtrace
* thread #1, name = 'a.out', stop reason = breakpoint 3.1
* frame #0: 0x000055555555520e a.out`my_comparator(a=1, b=8) at test-std-sort.cpp:6:3
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:3
frame #8: 0x000055555555531a a.out`main at test-std-sort.cpp:24:3
Note how the caller of ``my_comparator`` is shown as ``std::sort``. Looking at
the frame numbers, we can see that frames #1 until #6 were hidden. Those frames
represent internal implementation details such as ``__sort4`` and similar
utility functions.
To also show those implementation details, use ``thread backtrace -u``.
Alternatively, to disable those compact backtraces, use ``frame recognizer list``
and ``frame recognizer disable`` on the "libc++ frame recognizer".
Futhermore, stepping into libc++ functions is disabled by default. This is controlled via the
setting ``target.process.thread.step-avoid-regexp`` which defaults to ``^std::`` and can be
disabled using ``settings set target.process.thread.step-avoid-regexp ""``.
GDB Pretty printers for libc++
------------------------------
GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
provide pretty-printers itself. Those can be used as:
.. code-block:: bash
$ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
-ex "python register_libcxx_printer_loader()" \
<args>
.. _include-what-you-use:
include-what-you-use (IWYU)
---------------------------
libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
IWYU, you should run the tool like so:
.. code-block:: bash
$ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
file with the libc++-provided ``libcxx.imp`` file.
|