Skip to content

R
riscv-gcc-1
Commit 01b3b9e3 by Jonathan Wakely Committed by Jonathan Wakely
Options

Update libstdc++ documentation for Support and Diagnostics clauses 

	* doc/xml/manual/diagnostics.xml: Update list of headers that define
	exception classes.
	* doc/xml/manual/support.xml: Rewrite advice around NULL. Rewrite
	section about new/delete overloads. Improve section on verbose
	terminate handler.
	* doc/html/*: Regenerate.

From-SVN: r271782
parent 30f78ec7
Showing with 436 additions and 172 deletions
libstdc++-v3/ChangeLog
2019-05-30 Jonathan Wakely <jwakely@redhat.com> 2019-05-30 Jonathan Wakely <jwakely@redhat.com>
* doc/xml/manual/diagnostics.xml: Update list of headers that define
exception classes.
* doc/xml/manual/support.xml: Rewrite advice around NULL. Rewrite
section about new/delete overloads. Improve section on verbose
terminate handler.
* doc/html/*: Regenerate.
* doc/xml/manual/status_cxx2020.xml: Add feature-test macro for * doc/xml/manual/status_cxx2020.xml: Add feature-test macro for
P0811R3. Change status of P1353R0. P0811R3. Change status of P1353R0.
* doc/html/*: Regenerate. * doc/html/*: Regenerate.
......
libstdc++-v3/doc/html/index.html
...@@ -28,7 +28,7 @@ ...@@ -28,7 +28,7 @@
</a></span></dt><dd><dl><dt><span class="chapter"><a href="manual/support.html">4. </a></span></dt><dd><dl><dt><span class="chapter"><a href="manual/support.html">4.
Support Support
</a></span></dt><dd><dl><dt><span class="section"><a href="manual/support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="manual/support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="manual/support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="manual/support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="manual/dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="manual/termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="manual/termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="manual/termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="manual/diagnostics.html">5. </a></span></dt><dd><dl><dt><span class="section"><a href="manual/support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="manual/support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="manual/support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="manual/support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="manual/dynamic_memory.html">Dynamic Memory</a></span></dt><dd><dl><dt><span class="section"><a href="manual/dynamic_memory.html#std.support.memory.notes">Additional Notes</a></span></dt></dl></dd><dt><span class="section"><a href="manual/termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="manual/termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="manual/termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="manual/diagnostics.html">5.
Diagnostics Diagnostics
</a></span></dt><dd><dl><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="manual/errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="manual/concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="manual/utilities.html">6. </a></span></dt><dd><dl><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="manual/diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="manual/errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="manual/concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="manual/utilities.html">6.
......
libstdc++-v3/doc/html/manual/diagnostics.html
...@@ -8,20 +8,32 @@ ...@@ -8,20 +8,32 @@
Diagnostics Diagnostics
<a id="id-1.3.4.3.1.1.1" class="indexterm"></a> <a id="id-1.3.4.3.1.1.1" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.diagnostics.exceptions"></a>Exceptions</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.api"></a>API Reference</h3></div></div></div><p> </h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.diagnostics.exceptions"></a>Exceptions</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.api"></a>API Reference</h3></div></div></div><p>
All exception objects are defined in one of the standard header Most exception classes are defined in one of the standard headers
files: <code class="filename">exception</code>, <code class="filename">&lt;exception&gt;</code>,
<code class="filename">stdexcept</code>, <code class="filename">new</code>, and <code class="filename">&lt;stdexcept&gt;</code>,
<code class="filename">typeinfo</code>. <code class="filename">&lt;new&gt;</code>, and
<code class="filename">&lt;typeinfo&gt;</code>.
The C++ 2011 revision of the standard added more exception types
in the headers
<code class="filename">&lt;functional&gt;</code>,
<code class="filename">&lt;future&gt;</code>,
<code class="filename">&lt;regex&gt;</code>, and
<code class="filename">&lt;system_error&gt;</code>.
The C++ 2017 revision of the standard added more exception types
in the headers
<code class="filename">&lt;any&gt;</code>,
<code class="filename">&lt;filesystem&gt;</code>,
<code class="filename">&lt;optional&gt;</code>, and
<code class="filename">&lt;variant&gt;</code>.
</p><p> </p><p>
The base exception object is <code class="classname">exception</code>, All exceptions thrown by the library have a base class of type
located in <code class="filename">exception</code>. This object has no <code class="classname">std::exception</code>,
<code class="classname">string</code> member. defined in <code class="filename">&lt;exception&gt;</code>.
This type has no <code class="classname">std::string</code> member.
</p><p> </p><p>
Derived from this are several classes that may have a Derived from this are several classes that may have a
<code class="classname">string</code> member: a full hierarchy can be <code class="classname">std::string</code> member. A full hierarchy can be
found in the source documentation. found in the source documentation.
</p><p>
Full API details.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.data"></a>Adding Data to <code class="classname">exception</code></h3></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.diagnostics.exceptions.data"></a>Adding Data to <code class="classname">exception</code></h3></div></div></div><p>
The standard exception classes carry with them a single string as The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took data (usually describing what went wrong or where the 'throw' took
......
libstdc++-v3/doc/html/manual/dynamic_memory.html
...@@ -3,45 +3,120 @@ ...@@ -3,45 +3,120 @@
Support Support
</th><td width="20%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.memory"></a>Dynamic Memory</h2></div></div></div><p> </th><td width="20%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.memory"></a>Dynamic Memory</h2></div></div></div><p>
There are six flavors each of <code class="function">new</code> and In C++98 there are six flavors each of <code class="function">operator new</code>
<code class="function">delete</code>, so make certain that you're using the right and <code class="function">operator delete</code>, so make certain that you're
ones. Here are quickie descriptions of <code class="function">new</code>: using the right ones.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Here are quickie descriptions of <code class="function">operator new</code>:
single object form, throwing a </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">void* operator new(std::size_t);</code></span></dt><dd>
<code class="classname">bad_alloc</code> on errors; this is what most Single object form.
people are used to using Throws <code class="classname">std::bad_alloc</code> on error.
</p></li><li class="listitem"><p> This is what most people are used to using.
Single object "nothrow" form, returning NULL on errors </dd><dt><span class="term"><code class="code">void* operator new(std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd>
</p></li><li class="listitem"><p> Single object <span class="quote">“<span class="quote">nothrow</span>”</span> form.
Array <code class="function">new</code>, throwing Calls <code class="code">operator new(std::size_t)</code> but if that throws,
<code class="classname">bad_alloc</code> on errors returns a null pointer instead.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="code">void* operator new[](std::size_t);</code></span></dt><dd>
Array nothrow <code class="function">new</code>, returning Array <code class="function">new</code>.
<code class="constant">NULL</code> on errors Calls <code class="code">operator new(std::size_t)</code> and so
</p></li><li class="listitem"><p> throws <code class="classname">std::bad_alloc</code> on error.
Placement <code class="function">new</code>, which does nothing (like </dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></span></dt><dd>
it's supposed to) Array <span class="quote">“<span class="quote">nothrow</span>”</span><code class="function">new</code>.
</p></li><li class="listitem"><p> Calls <code class="code">operator new[](std::size_t)</code> but if that throws,
Placement array <code class="function">new</code>, which also does returns a null pointer instead.
nothing </dd><dt><span class="term"><code class="code">void* operator new(std::size_t, void*) noexcept;</code></span></dt><dd>
</p></li></ul></div><p> Non-allocating, <span class="quote">“<span class="quote">placement</span>”</span> single-object <code class="function">new</code>,
They are distinguished by the parameters that you pass to them, like which does nothing except return its argument.
any other overloaded function. The six flavors of <code class="function">delete</code> This function cannot be replaced.
</dd><dt><span class="term"><code class="code">void* operator new[](std::size_t, void*) noexcept;</code></span></dt><dd>
Non-allocating, <span class="quote">“<span class="quote">placement</span>”</span> array <code class="function">new</code>,
which also does nothing except return its argument.
This function cannot be replaced.
</dd></dl></div><p>
They are distinguished by the arguments that you pass to them, like
any other overloaded function. The six flavors of
<code class="function">operator delete</code>
are distinguished the same way, but none of them are allowed to throw are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (They match up for an exception under any circumstances anyhow. (The overloads match up
completeness' sake.) with the ones above, for completeness' sake.)
</p><p> </p><p>
Remember that it is perfectly okay to call <code class="function">delete</code> on a The C++ 2014 revision of the standard added two additional overloads of
NULL pointer! Nothing happens, by definition. That is not the <code class="function">operator delete</code> for <span class="quote">“<span class="quote">sized deallocation</span>”</span>,
same thing as deleting a pointer twice. allowing the compiler to provide the size of the storage being freed.
</p><p>
The C++ 2017 standard added even more overloads of both
<code class="function">operator new</code> and <code class="function">operator delete</code>
for allocating and deallocating storage for overaligned types.
These overloads correspond to each of the allocating forms of
<code class="function">operator new</code> and <code class="function">operator delete</code>
but with an additional parameter of type <span class="type">std::align_val_t</span>.
These new overloads are not interchangeable with the versions without
an aligment parameter, so if memory was allocated by an overload of
<code class="function">operator new</code> taking an alignment parameter,
then it must be decallocated by the corresponding overload of
<code class="function">operator delete</code> that takes an alignment parameter.
</p><p>
Apart from the non-allocating forms, the default versions of the array
and nothrow <code class="function">operator new</code> functions will all result
in a call to either <code class="function">operator new(std::size_t)</code> or
<code class="function">operator new(std::size_t, std::align_val_t)</code>,
and similarly the default versions of the array and nothrow
<code class="function">operator delete</code> functions will result in a call to
either <code class="function">operator delete(void*)</code> or
<code class="function">operator delete(void*, std::align_val_t)</code>
(or the sized versions of those).
</p><p> </p><p>
By default, if one of the <span class="quote">“<span class="quote">throwing <code class="function">new</code>s</span>”</span> can't Apart from the non-allocating forms, any of these functions can be
allocate the memory requested, it tosses an instance of a replaced by defining a function with the same signature in your program.
<code class="classname">bad_alloc</code> exception (or, technically, some class derived Replacement versions must preserve certain guarantees, such as memory
from it). You can change this by writing your own function (called a obtained from a nothrow <code class="function">operator new</code> being free-able
new-handler) and then registering it with <code class="function">set_new_handler()</code>: by the normal (non-nothrow) <code class="function">operator delete</code>,
and the sized and unsized forms of <code class="function">operator delete</code>
being interchangeable (because it's unspecified whether
the compiler calls the sized delete instead of the normal one).
The simplest way to meet the guarantees is to only replace the ordinary
<code class="function">operator new(size_t)</code> and
<code class="function">operator delete(void*)</code> and
<code class="function">operator delete(void*, std::size_t)</code>
functions, and the replaced versions will be used by all of
<code class="function">operator new(size_t, nothrow_t)</code>,
<code class="function">operator new[](size_t)</code> and
<code class="function">operator new[](size_t, nothrow_t)</code>
and the corresponding <code class="function">operator delete</code> functions.
To support types with extended alignment you may also need to replace
<code class="function">operator new(size_t, align_val_t)</code> and
<code class="function">operator delete(void*, align_val_t)</code>
<code class="function">operator delete(void*, size_t, align_val_t)</code>
(which will then be used by the nothrow and array forms for
extended alignments).
If you do need to replace other forms (e.g. to define the nothrow
<code class="function">operator new</code> to allocate memory directly, so it
works with exceptions disabled) then make sure the memory it allocates
can still be freed by the non-nothrow forms of
<code class="function">operator delete</code>.
</p><p>
If the default versions of <code class="function">operator new(std::size_t)</code>
and <code class="function">operator new(size_t, std::align_val_t)</code>
can't allocate the memory requested, they usually throw an exception
object of type <code class="classname">std::bad_alloc</code> (or some class
derived from that). However, the program can influence that behavior
by registering a <span class="quote">“<span class="quote">new-handler</span>”</span>, because what
<code class="function">operator new</code> actually does is something like:
</p><pre class="programlisting"> </p><pre class="programlisting">
typedef void (*PFV)(void); while (true)
{
if (void* p = /* try to allocate memory */)
return p;
else if (std::new_handler h = std::get_new_handler ())
h ();
else
throw bad_alloc{};
}
</pre><p>
This means you can influence what happens on allocation failure by
writing your own new-handler and then registering it with
<code class="function">std::set_new_handler</code>:
</p><pre class="programlisting">
typedef void (*PFV)();
static char* safety; static char* safety;
static PFV old_handler; static PFV old_handler;
...@@ -49,6 +124,7 @@ ...@@ -49,6 +124,7 @@
void my_new_handler () void my_new_handler ()
{ {
delete[] safety; delete[] safety;
safety = nullptr;
popup_window ("Dude, you are running low on heap memory. You" popup_window ("Dude, you are running low on heap memory. You"
" should, like, close some windows, or something." " should, like, close some windows, or something."
" The next time you run out, we're gonna burn!"); " The next time you run out, we're gonna burn!");
...@@ -62,10 +138,15 @@ ...@@ -62,10 +138,15 @@
old_handler = set_new_handler (&amp;my_new_handler); old_handler = set_new_handler (&amp;my_new_handler);
... ...
} }
</pre><p> </pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.memory.notes"></a>Additional Notes</h3></div></div></div><p>
<code class="classname">bad_alloc</code> is derived from the base <code class="classname">exception</code> Remember that it is perfectly okay to <code class="function">delete</code> a
class defined in Sect1 19. null pointer! Nothing happens, by definition. That is not the
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4.  same thing as deleting a pointer twice.
</p><p>
<code class="classname">std::bad_alloc</code> is derived from the base
<code class="classname">std::exception</code> class,
see <a class="xref" href="diagnostics.html#std.diagnostics.exceptions" title="Exceptions">Exceptions</a>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="support.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="termination.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. 
Support Support
 </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Termination</td></tr></table></div></body></html>  </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Termination</td></tr></table></div></body></html>
\ No newline at end of file
libstdc++-v3/doc/html/manual/index.html
...@@ -9,7 +9,7 @@ ...@@ -9,7 +9,7 @@
</a></span></dt><dd><dl><dt><span class="chapter"><a href="support.html">4. </a></span></dt><dd><dl><dt><span class="chapter"><a href="support.html">4.
Support Support
</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5. </a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dd><dl><dt><span class="section"><a href="dynamic_memory.html#std.support.memory.notes">Additional Notes</a></span></dt></dl></dd><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5.
Diagnostics Diagnostics
</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6. </a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6.
......
libstdc++-v3/doc/html/manual/std_contents.html
...@@ -6,7 +6,7 @@ ...@@ -6,7 +6,7 @@
</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="support.html">4. </h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="support.html">4.
Support Support
</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5. </a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dd><dl><dt><span class="section"><a href="dynamic_memory.html#std.support.memory.notes">Additional Notes</a></span></dt></dl></dd><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="diagnostics.html">5.
Diagnostics Diagnostics
</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6. </a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions">Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.api">API Reference</a></span></dt><dt><span class="section"><a href="diagnostics.html#std.diagnostics.exceptions.data">Adding Data to <code class="classname">exception</code></a></span></dt></dl></dd><dt><span class="section"><a href="errno.html">Use of errno by the library</a></span></dt><dt><span class="section"><a href="concept_checking.html">Concept Checking</a></span></dt></dl></dd><dt><span class="chapter"><a href="utilities.html">6.
......
libstdc++-v3/doc/html/manual/support.html
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
</th><td width="20%" align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="std.support"></a>Chapter 4.  </th><td width="20%" align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="std.support"></a>Chapter 4. 
Support Support
<a id="id-1.3.4.2.1.1.1" class="indexterm"></a> <a id="id-1.3.4.2.1.1.1" class="indexterm"></a>
</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></div><p> </h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="support.html#std.support.types">Types</a></span></dt><dd><dl><dt><span class="section"><a href="support.html#std.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.numeric_limits">Numeric Properties</a></span></dt><dt><span class="section"><a href="support.html#std.support.types.null">NULL</a></span></dt></dl></dd><dt><span class="section"><a href="dynamic_memory.html">Dynamic Memory</a></span></dt><dd><dl><dt><span class="section"><a href="dynamic_memory.html#std.support.memory.notes">Additional Notes</a></span></dt></dl></dd><dt><span class="section"><a href="termination.html">Termination</a></span></dt><dd><dl><dt><span class="section"><a href="termination.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="section"><a href="termination.html#support.termination.verbose">Verbose Terminate Handler</a></span></dt></dl></dd></dl></div><p>
This part deals with the functions called and objects created This part deals with the functions called and objects created
automatically during the course of a program's existence. automatically during the course of a program's existence.
</p><p> </p><p>
...@@ -53,7 +53,7 @@ ...@@ -53,7 +53,7 @@
Specializing parts of the library on these types is prohibited: Specializing parts of the library on these types is prohibited:
instead, use a POD. instead, use a POD.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.types.numeric_limits"></a>Numeric Properties</h3></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="std.support.types.numeric_limits"></a>Numeric Properties</h3></div></div></div><p>
The header <code class="filename">limits</code> defines The header <code class="filename">&lt;limits&gt;</code> defines
traits classes to give access to various implementation traits classes to give access to various implementation
defined-aspects of the fundamental types. The traits classes -- defined-aspects of the fundamental types. The traits classes --
fourteen in total -- are all specializations of the class template fourteen in total -- are all specializations of the class template
...@@ -102,28 +102,36 @@ ...@@ -102,28 +102,36 @@
The only change that might affect people is the type of The only change that might affect people is the type of
<code class="constant">NULL</code>: while it is required to be a macro, <code class="constant">NULL</code>: while it is required to be a macro,
the definition of that macro is <span class="emphasis"><em>not</em></span> allowed the definition of that macro is <span class="emphasis"><em>not</em></span> allowed
to be <code class="constant">(void*)0</code>, which is often used in C. to be an expression with pointer type such as
<code class="constant">(void*)0</code>, which is often used in C.
</p><p> </p><p>
For <span class="command"><strong>g++</strong></span>, <code class="constant">NULL</code> is For <span class="command"><strong>g++</strong></span>, <code class="constant">NULL</code> is
<code class="code">#define</code>'d to be <code class="code">#define</code>'d to be
<code class="constant">__null</code>, a magic keyword extension of <code class="constant">__null</code>, a magic keyword extension of
<span class="command"><strong>g++</strong></span>. <span class="command"><strong>g++</strong></span> that is slightly safer than a plain integer.
</p><p> </p><p>
The biggest problem of #defining <code class="constant">NULL</code> to be The biggest problem of #defining <code class="constant">NULL</code> to be
something like <span class="quote">“<span class="quote">0L</span>”</span> is that the compiler will view something like <span class="quote">“<span class="quote">0L</span>”</span> is that the compiler will view
that as a long integer before it views it as a pointer, so that as a long integer before it views it as a pointer, so
overloading won't do what you expect. (This is why overloading won't do what you expect. It might not even have the
<span class="command"><strong>g++</strong></span> has a magic extension, so that same size as a pointer, so passing <code class="constant">NULL</code> to a
<code class="constant">NULL</code> is always a pointer.) varargs function where a pointer is expected might not even work
</p><p>In his book <a class="link" href="http://www.aristeia.com/books.html" target="_top"><span class="emphasis"><em>Effective correctly if <code class="code">sizeof(NULL) &lt; sizeof(void*)</code>.
C++</em></span></a>, Scott Meyers points out that the best way The G++ <code class="constant">__null</code> extension is defined so that
to solve this problem is to not overload on pointer-vs-integer <code class="code">sizeof(__null) == sizeof(void*)</code> to avoid this problem.
types to begin with. He also offers a way to make your own magic </p><p>
<code class="constant">NULL</code> that will match pointers before it Scott Meyers explains this in more detail in his book
matches integers. <a class="link" href="https://www.aristeia.com/books.html" target="_top"><span class="emphasis"><em>Effective
</p><p>See the Modern C++</em></span></a> and as a guideline to solve this problem
<a class="link" href="http://www.aristeia.com/books.html" target="_top"><span class="emphasis"><em>Effective recommends to not overload on pointer-vs-integer types to begin with.
C++ CD</em></span></a> example. </p><p>
The C++ 2011 standard added the <code class="constant">nullptr</code> keyword,
which is a null pointer constant of a special type,
<code class="classname">std::nullptr_t</code>. Values of this type can be
implicitly converted to <span class="emphasis"><em>any</em></span> pointer type,
and cannot convert to integer types or be deduced as an integer type.
Unless you need to be compatible with C++98/C++03 or C you should prefer
to use <code class="constant">nullptr</code> instead of <code class="constant">NULL</code>.
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="std_contents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="std_contents.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II.  </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="std_contents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="std_contents.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dynamic_memory.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. 
Standard Contents Standard Contents
 </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Dynamic Memory</td></tr></table></div></body></html>  </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Dynamic Memory</td></tr></table></div></body></html>
\ No newline at end of file
libstdc++-v3/doc/html/manual/termination.html
...@@ -3,7 +3,9 @@ ...@@ -3,7 +3,9 @@
Support Support
</th><td width="20%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.termination"></a>Termination</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.handlers"></a>Termination Handlers</h3></div></div></div><p> </th><td width="20%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="std.support.termination"></a>Termination</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.handlers"></a>Termination Handlers</h3></div></div></div><p>
Not many changes here to <code class="filename">cstdlib</code>. You should note that the Not many changes here to
<code class="filename">&lt;cstdlib&gt;</code>.
You should note that the
<code class="function">abort()</code> function does not call the <code class="function">abort()</code> function does not call the
destructors of automatic nor static objects, so if you're destructors of automatic nor static objects, so if you're
depending on those to do cleanup, it isn't going to happen. depending on those to do cleanup, it isn't going to happen.
...@@ -24,8 +26,8 @@ ...@@ -24,8 +26,8 @@
The previous two actions are <span class="quote">“<span class="quote">interleaved,</span>”</span> that is, The previous two actions are <span class="quote">“<span class="quote">interleaved,</span>”</span> that is,
given this pseudocode: given this pseudocode:
</p><pre class="programlisting"> </p><pre class="programlisting">
extern "C or C++" void f1 (void); extern "C or C++" void f1 ();
extern "C or C++" void f2 (void); extern "C or C++" void f2 ();
static Thing obj1; static Thing obj1;
atexit(f1); atexit(f1);
...@@ -43,11 +45,20 @@ ...@@ -43,11 +45,20 @@
Note also that <code class="function">atexit()</code> is only required to store 32 Note also that <code class="function">atexit()</code> is only required to store 32
functions, and the compiler/library might already be using some of functions, and the compiler/library might already be using some of
those slots. If you think you may run out, we recommend using those slots. If you think you may run out, we recommend using
the <code class="function">xatexit</code>/<code class="function">xexit</code> combination from <code class="literal">libiberty</code>, which has no such limit. the <code class="function">xatexit</code>/<code class="function">xexit</code> combination
from <code class="literal">libiberty</code>, which has no such limit.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.verbose"></a>Verbose Terminate Handler</h3></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="support.termination.verbose"></a>Verbose Terminate Handler</h3></div></div></div><p>
If you are having difficulty with uncaught exceptions and want a If you are having difficulty with uncaught exceptions and want a
little bit of help debugging the causes of the core dumps, you can little bit of help debugging the causes of the core dumps, you can
make use of a GNU extension, the verbose terminate handler. make use of a GNU extension, the verbose terminate handler.
</p><p>
The verbose terminate handler is only available for hosted environments
(see <a class="xref" href="configure.html" title="Configure">Configuring</a>) and will be used
by default unless the library is built with
<code class="option">--disable-libstdcxx-verbose</code>
or with exceptions disabled.
If you need to enable it explicitly you can do so by calling the
<code class="function">std::set_terminate</code> function.
</p><pre class="programlisting"> </p><pre class="programlisting">
#include &lt;exception&gt; #include &lt;exception&gt;
...@@ -61,12 +72,13 @@ int main() ...@@ -61,12 +72,13 @@ int main()
</pre><p> </pre><p>
The <code class="function">__verbose_terminate_handler</code> function The <code class="function">__verbose_terminate_handler</code> function
obtains the name of the current exception, attempts to demangle obtains the name of the current exception, attempts to demangle
it, and prints it to stderr. If the exception is derived from it, and prints it to <code class="literal">stderr</code>.
<code class="classname">exception</code> then the output from If the exception is derived from
<code class="classname">std::exception</code> then the output from
<code class="function">what()</code> will be included. <code class="function">what()</code> will be included.
</p><p> </p><p>
Any replacement termination function is required to kill the Any replacement termination function is required to kill the
program without returning; this one calls abort. program without returning; this one calls <code class="function">std::abort</code>.
</p><p> </p><p>
For example: For example:
</p><pre class="programlisting"> </p><pre class="programlisting">
...@@ -99,13 +111,14 @@ int main(int argc) ...@@ -99,13 +111,14 @@ int main(int argc)
Aborted Aborted
</code> </code>
</pre><p> </pre><p>
The 'Aborted' line comes from the call to The 'Aborted' line is printed by the shell after the process exits
<code class="function">abort()</code>, of course. by calling <code class="function">abort()</code>.
</p><p> </p><p>
This is the default termination handler; nothing need be done to As this is the default termination handler, nothing need be done to
use it. To go back to the previous <span class="quote">“<span class="quote">silent death</span>”</span> use it. To go back to the previous <span class="quote">“<span class="quote">silent death</span>”</span>
method, simply include <code class="filename">exception</code> and method, simply include
<code class="filename">cstdlib</code>, and call <code class="filename">&lt;exception&gt;</code> and
<code class="filename">&lt;cstdlib&gt;</code>, and call
</p><pre class="programlisting"> </p><pre class="programlisting">
std::set_terminate(std::abort); std::set_terminate(std::abort);
</pre><p> </pre><p>
...@@ -113,8 +126,8 @@ int main(int argc) ...@@ -113,8 +126,8 @@ int main(int argc)
<code class="function">abort</code> as the terminate handler. <code class="function">abort</code> as the terminate handler.
</p><p> </p><p>
Note: the verbose terminate handler will attempt to write to Note: the verbose terminate handler will attempt to write to
stderr. If your application closes stderr or redirects it to an <code class="literal">stderr</code>. If your application closes
inappropriate location, <code class="literal">stderr</code> or redirects it to an inappropriate location,
<code class="function">__verbose_terminate_handler</code> will behave in <code class="function">__verbose_terminate_handler</code> will behave in
an unspecified manner. an unspecified manner.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Dynamic Memory </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5.  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dynamic_memory.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Dynamic Memory </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. 
......
libstdc++-v3/doc/xml/manual/diagnostics.xml
...@@ -21,28 +21,38 @@ ...@@ -21,28 +21,38 @@
<section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info> <section xml:id="std.diagnostics.exceptions.api"><info><title>API Reference</title></info>
<para> <para>
All exception objects are defined in one of the standard header Most exception classes are defined in one of the standard headers
files: <filename>exception</filename>, <filename class="headerfile">&lt;exception&gt;</filename>,
<filename>stdexcept</filename>, <filename>new</filename>, and <filename class="headerfile">&lt;stdexcept&gt;</filename>,
<filename>typeinfo</filename>. <filename class="headerfile">&lt;new&gt;</filename>, and
<filename class="headerfile">&lt;typeinfo&gt;</filename>.
The C++ 2011 revision of the standard added more exception types
in the headers
<filename class="headerfile">&lt;functional&gt;</filename>,
<filename class="headerfile">&lt;future&gt;</filename>,
<filename class="headerfile">&lt;regex&gt;</filename>, and
<filename class="headerfile">&lt;system_error&gt;</filename>.
The C++ 2017 revision of the standard added more exception types
in the headers
<filename class="headerfile">&lt;any&gt;</filename>,
<filename class="headerfile">&lt;filesystem&gt;</filename>,
<filename class="headerfile">&lt;optional&gt;</filename>, and
<filename class="headerfile">&lt;variant&gt;</filename>.
</para> </para>
<para> <para>
The base exception object is <classname>exception</classname>, All exceptions thrown by the library have a base class of type
located in <filename>exception</filename>. This object has no <classname>std::exception</classname>,
<classname>string</classname> member. defined in <filename class="headerfile">&lt;exception&gt;</filename>.
This type has no <classname>std::string</classname> member.
</para> </para>
<para> <para>
Derived from this are several classes that may have a Derived from this are several classes that may have a
<classname>string</classname> member: a full hierarchy can be <classname>std::string</classname> member. A full hierarchy can be
found in the source documentation. found in the source documentation.
</para> </para>
<para>
Full API details.
</para>
<!-- Doxygen XML: api/group__exceptions.xml --> <!-- Doxygen XML: api/group__exceptions.xml -->
</section> </section>
......
libstdc++-v3/doc/xml/manual/support.xml
...@@ -91,10 +91,8 @@ ...@@ -91,10 +91,8 @@
</section> </section>
<section xml:id="std.support.types.numeric_limits" xreflabel="Numeric Properties"><info><title>Numeric Properties</title></info> <section xml:id="std.support.types.numeric_limits" xreflabel="Numeric Properties"><info><title>Numeric Properties</title></info>
<para> <para>
The header <filename class="headerfile">limits</filename> defines The header <filename class="headerfile">&lt;limits&gt;</filename> defines
traits classes to give access to various implementation traits classes to give access to various implementation
defined-aspects of the fundamental types. The traits classes -- defined-aspects of the fundamental types. The traits classes --
fourteen in total -- are all specializations of the class template fourteen in total -- are all specializations of the class template
...@@ -150,37 +148,45 @@ ...@@ -150,37 +148,45 @@
The only change that might affect people is the type of The only change that might affect people is the type of
<constant>NULL</constant>: while it is required to be a macro, <constant>NULL</constant>: while it is required to be a macro,
the definition of that macro is <emphasis>not</emphasis> allowed the definition of that macro is <emphasis>not</emphasis> allowed
to be <constant>(void*)0</constant>, which is often used in C. to be an expression with pointer type such as
<constant>(void*)0</constant>, which is often used in C.
</para> </para>
<para> <para>
For <command>g++</command>, <constant>NULL</constant> is For <command>g++</command>, <constant>NULL</constant> is
<code>#define</code>'d to be <code>#define</code>'d to be
<constant>__null</constant>, a magic keyword extension of <constant>__null</constant>, a magic keyword extension of
<command>g++</command>. <command>g++</command> that is slightly safer than a plain integer.
</para> </para>
<para> <para>
The biggest problem of #defining <constant>NULL</constant> to be The biggest problem of #defining <constant>NULL</constant> to be
something like <quote>0L</quote> is that the compiler will view something like <quote>0L</quote> is that the compiler will view
that as a long integer before it views it as a pointer, so that as a long integer before it views it as a pointer, so
overloading won't do what you expect. (This is why overloading won't do what you expect. It might not even have the
<command>g++</command> has a magic extension, so that same size as a pointer, so passing <constant>NULL</constant> to a
<constant>NULL</constant> is always a pointer.) varargs function where a pointer is expected might not even work
correctly if <code>sizeof(NULL) &lt; sizeof(void*)</code>.
The G++ <constant>__null</constant> extension is defined so that
<code>sizeof(__null) == sizeof(void*)</code> to avoid this problem.
</para> </para>
<para>In his book <link xmlns:xlink="http://www.w3.org/1999/xlink" <para>
xlink:href="http://www.aristeia.com/books.html"><emphasis>Effective Scott Meyers explains this in more detail in his book
C++</emphasis></link>, 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
<constant>NULL</constant> that will match pointers before it
matches integers.
</para>
<para>See the
<link xmlns:xlink="http://www.w3.org/1999/xlink" <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.aristeia.com/books.html"><emphasis>Effective xlink:href="https://www.aristeia.com/books.html"><emphasis>Effective
C++ CD</emphasis></link> example. Modern C++</emphasis></link> and as a guideline to solve this problem
recommends to not overload on pointer-vs-integer types to begin with.
</para>
<para>
The C++ 2011 standard added the <constant>nullptr</constant> keyword,
which is a null pointer constant of a special type,
<classname>std::nullptr_t</classname>. Values of this type can be
implicitly converted to <emphasis>any</emphasis> pointer type,
and cannot convert to integer types or be deduced as an integer type.
Unless you need to be compatible with C++98/C++03 or C you should prefer
to use <constant>nullptr</constant> instead of <constant>NULL</constant>.
</para> </para>
</section> </section>
...@@ -190,57 +196,155 @@ ...@@ -190,57 +196,155 @@
<?dbhtml filename="dynamic_memory.html"?> <?dbhtml filename="dynamic_memory.html"?>
<para> <para>
There are six flavors each of <function>new</function> and In C++98 there are six flavors each of <function>operator new</function>
<function>delete</function>, so make certain that you're using the right and <function>operator delete</function>, so make certain that you're
ones. Here are quickie descriptions of <function>new</function>: using the right ones.
</para> Here are quickie descriptions of <function>operator new</function>:
<itemizedlist> </para>
<listitem><para> <variablelist>
single object form, throwing a <varlistentry>
<classname>bad_alloc</classname> on errors; this is what most <term><code>void* operator new(std::size_t);</code></term>
people are used to using <listitem>
</para></listitem> Single object form.
<listitem><para> Throws <classname>std::bad_alloc</classname> on error.
Single object "nothrow" form, returning NULL on errors This is what most people are used to using.
</para></listitem> </listitem>
<listitem><para> </varlistentry>
Array <function>new</function>, throwing <varlistentry>
<classname>bad_alloc</classname> on errors <term><code>void* operator new(std::size_t, std::nothrow_t) noexcept;</code></term>
</para></listitem> <listitem>
<listitem><para> Single object <quote>nothrow</quote> form.
Array nothrow <function>new</function>, returning Calls <code>operator new(std::size_t)</code> but if that throws,
<constant>NULL</constant> on errors returns a null pointer instead.
</para></listitem> </listitem>
<listitem><para> </varlistentry>
Placement <function>new</function>, which does nothing (like <varlistentry>
it's supposed to) <term><code>void* operator new[](std::size_t);</code></term>
</para></listitem> <listitem>
<listitem><para> Array <function>new</function>.
Placement array <function>new</function>, which also does Calls <code>operator new(std::size_t)</code> and so
nothing throws <classname>std::bad_alloc</classname> on error.
</para></listitem> </listitem>
</itemizedlist> </varlistentry>
<varlistentry>
<term><code>void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></term>
<listitem>
Array <quote>nothrow</quote> <function>new</function>.
Calls <code>operator new[](std::size_t)</code> but if that throws,
returns a null pointer instead.
</listitem>
</varlistentry>
<varlistentry>
<term><code>void* operator new(std::size_t, void*) noexcept;</code></term>
<listitem>
Non-allocating, <quote>placement</quote> single-object <function>new</function>,
which does nothing except return its argument.
This function cannot be replaced.
</listitem>
</varlistentry>
<varlistentry>
<term><code>void* operator new[](std::size_t, void*) noexcept;</code></term>
<listitem>
Non-allocating, <quote>placement</quote> array <function>new</function>,
which also does nothing except return its argument.
This function cannot be replaced.
</listitem>
</varlistentry>
</variablelist>
<para> <para>
They are distinguished by the parameters that you pass to them, like They are distinguished by the arguments that you pass to them, like
any other overloaded function. The six flavors of <function>delete</function> any other overloaded function. The six flavors of
<function>operator delete</function>
are distinguished the same way, but none of them are allowed to throw are distinguished the same way, but none of them are allowed to throw
an exception under any circumstances anyhow. (They match up for an exception under any circumstances anyhow. (The overloads match up
completeness' sake.) with the ones above, for completeness' sake.)
</para> </para>
<para> <para>
Remember that it is perfectly okay to call <function>delete</function> on a The C++ 2014 revision of the standard added two additional overloads of
NULL pointer! Nothing happens, by definition. That is not the <function>operator delete</function> for <quote>sized deallocation</quote>,
same thing as deleting a pointer twice. allowing the compiler to provide the size of the storage being freed.
</para>
<para>
The C++ 2017 standard added even more overloads of both
<function>operator new</function> and <function>operator delete</function>
for allocating and deallocating storage for overaligned types.
These overloads correspond to each of the allocating forms of
<function>operator new</function> and <function>operator delete</function>
but with an additional parameter of type <type>std::align_val_t</type>.
These new overloads are not interchangeable with the versions without
an aligment parameter, so if memory was allocated by an overload of
<function>operator new</function> taking an alignment parameter,
then it must be decallocated by the corresponding overload of
<function>operator delete</function> that takes an alignment parameter.
</para> </para>
<para> <para>
By default, if one of the <quote>throwing <function>new</function>s</quote> can't Apart from the non-allocating forms, the default versions of the array
allocate the memory requested, it tosses an instance of a and nothrow <function>operator new</function> functions will all result
<classname>bad_alloc</classname> exception (or, technically, some class derived in a call to either <function>operator new(std::size_t)</function> or
from it). You can change this by writing your own function (called a <function>operator new(std::size_t, std::align_val_t)</function>,
new-handler) and then registering it with <function>set_new_handler()</function>: and similarly the default versions of the array and nothrow
<function>operator delete</function> functions will result in a call to
either <function>operator delete(void*)</function> or
<function>operator delete(void*, std::align_val_t)</function>
(or the sized versions of those).
</para>
<para>
Apart from the non-allocating forms, any of these functions can be
replaced by defining a function with the same signature in your program.
Replacement versions must preserve certain guarantees, such as memory
obtained from a nothrow <function>operator new</function> being free-able
by the normal (non-nothrow) <function>operator delete</function>,
and the sized and unsized forms of <function>operator delete</function>
being interchangeable (because it's unspecified whether
the compiler calls the sized delete instead of the normal one).
The simplest way to meet the guarantees is to only replace the ordinary
<function>operator new(size_t)</function> and
<function>operator delete(void*)</function> and
<function>operator delete(void*, std::size_t)</function>
functions, and the replaced versions will be used by all of
<function>operator new(size_t, nothrow_t)</function>,
<function>operator new[](size_t)</function> and
<function>operator new[](size_t, nothrow_t)</function>
and the corresponding <function>operator delete</function> functions.
To support types with extended alignment you may also need to replace
<function>operator new(size_t, align_val_t)</function> and
<function>operator delete(void*, align_val_t)</function>
<function>operator delete(void*, size_t, align_val_t)</function>
(which will then be used by the nothrow and array forms for
extended alignments).
If you do need to replace other forms (e.g. to define the nothrow
<function>operator new</function> to allocate memory directly, so it
works with exceptions disabled) then make sure the memory it allocates
can still be freed by the non-nothrow forms of
<function>operator delete</function>.
</para>
<para>
If the default versions of <function>operator new(std::size_t)</function>
and <function>operator new(size_t, std::align_val_t)</function>
can't allocate the memory requested, they usually throw an exception
object of type <classname>std::bad_alloc</classname> (or some class
derived from that). However, the program can influence that behavior
by registering a <quote>new-handler</quote>, because what
<function>operator new</function> actually does is something like:
</para> </para>
<programlisting> <programlisting>
typedef void (*PFV)(void); while (true)
{
if (void* p = /* try to allocate memory */)
return p;
else if (std::new_handler h = std::get_new_handler ())
h ();
else
throw bad_alloc{};
}
</programlisting>
<para>
This means you can influence what happens on allocation failure by
writing your own new-handler and then registering it with
<function>std::set_new_handler</function>:
</para>
<programlisting>
typedef void (*PFV)();
static char* safety; static char* safety;
static PFV old_handler; static PFV old_handler;
...@@ -248,6 +352,7 @@ ...@@ -248,6 +352,7 @@
void my_new_handler () void my_new_handler ()
{ {
delete[] safety; delete[] safety;
safety = nullptr;
popup_window ("Dude, you are running low on heap memory. You" popup_window ("Dude, you are running low on heap memory. You"
" should, like, close some windows, or something." " should, like, close some windows, or something."
" The next time you run out, we're gonna burn!"); " The next time you run out, we're gonna burn!");
...@@ -262,10 +367,21 @@ ...@@ -262,10 +367,21 @@
... ...
} }
</programlisting> </programlisting>
<section xml:id="std.support.memory.notes" xreflabel="Dynamic Memory Notes"><info><title>Additional Notes</title></info>
<para>
Remember that it is perfectly okay to <function>delete</function> a
null pointer! Nothing happens, by definition. That is not the
same thing as deleting a pointer twice.
</para>
<para> <para>
<classname>bad_alloc</classname> is derived from the base <classname>exception</classname> <classname>std::bad_alloc</classname> is derived from the base
class defined in Sect1 19. <classname>std::exception</classname> class,
see <xref linkend="std.diagnostics.exceptions"/>.
</para> </para>
</section>
</section> </section>
<section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info> <section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info>
...@@ -274,7 +390,9 @@ ...@@ -274,7 +390,9 @@
<section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info> <section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info>
<para> <para>
Not many changes here to <filename class="headerfile">cstdlib</filename>. You should note that the Not many changes here to
<filename class="headerfile">&lt;cstdlib&gt;</filename>.
You should note that the
<function>abort()</function> function does not call the <function>abort()</function> function does not call the
destructors of automatic nor static objects, so if you're destructors of automatic nor static objects, so if you're
depending on those to do cleanup, it isn't going to happen. depending on those to do cleanup, it isn't going to happen.
...@@ -306,8 +424,8 @@ ...@@ -306,8 +424,8 @@
given this pseudocode: given this pseudocode:
</para> </para>
<programlisting> <programlisting>
extern "C or C++" void f1 (void); extern "C or C++" void f1 ();
extern "C or C++" void f2 (void); extern "C or C++" void f2 ();
static Thing obj1; static Thing obj1;
atexit(f1); atexit(f1);
...@@ -329,7 +447,8 @@ ...@@ -329,7 +447,8 @@
Note also that <function>atexit()</function> is only required to store 32 Note also that <function>atexit()</function> is only required to store 32
functions, and the compiler/library might already be using some of functions, and the compiler/library might already be using some of
those slots. If you think you may run out, we recommend using those slots. If you think you may run out, we recommend using
the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit. the <function>xatexit</function>/<function>xexit</function> combination
from <literal>libiberty</literal>, which has no such limit.
</para> </para>
</section> </section>
...@@ -342,6 +461,16 @@ ...@@ -342,6 +461,16 @@
make use of a GNU extension, the verbose terminate handler. make use of a GNU extension, the verbose terminate handler.
</para> </para>
<para>
The verbose terminate handler is only available for hosted environments
(see <xref linkend="manual.intro.setup.configure"/>) and will be used
by default unless the library is built with
<option>--disable-libstdcxx-verbose</option>
or with exceptions disabled.
If you need to enable it explicitly you can do so by calling the
<function>std::set_terminate</function> function.
</para>
<programlisting> <programlisting>
#include &lt;exception&gt; #include &lt;exception&gt;
...@@ -357,14 +486,15 @@ int main() ...@@ -357,14 +486,15 @@ int main()
<para> <para>
The <function>__verbose_terminate_handler</function> function The <function>__verbose_terminate_handler</function> function
obtains the name of the current exception, attempts to demangle obtains the name of the current exception, attempts to demangle
it, and prints it to stderr. If the exception is derived from it, and prints it to <literal>stderr</literal>.
<classname>exception</classname> then the output from If the exception is derived from
<classname>std::exception</classname> then the output from
<function>what()</function> will be included. <function>what()</function> will be included.
</para> </para>
<para> <para>
Any replacement termination function is required to kill the Any replacement termination function is required to kill the
program without returning; this one calls abort. program without returning; this one calls <function>std::abort</function>.
</para> </para>
<para> <para>
...@@ -407,15 +537,16 @@ int main(int argc) ...@@ -407,15 +537,16 @@ int main(int argc)
</screen> </screen>
<para> <para>
The 'Aborted' line comes from the call to The 'Aborted' line is printed by the shell after the process exits
<function>abort()</function>, of course. by calling <function>abort()</function>.
</para> </para>
<para> <para>
This is the default termination handler; nothing need be done to As this is the default termination handler, nothing need be done to
use it. To go back to the previous <quote>silent death</quote> use it. To go back to the previous <quote>silent death</quote>
method, simply include <filename>exception</filename> and method, simply include
<filename>cstdlib</filename>, and call <filename class="headerfile">&lt;exception&gt;</filename> and
<filename class="headerfile">&lt;cstdlib&gt;</filename>, and call
</para> </para>
<programlisting> <programlisting>
...@@ -429,8 +560,8 @@ int main(int argc) ...@@ -429,8 +560,8 @@ int main(int argc)
<para> <para>
Note: the verbose terminate handler will attempt to write to Note: the verbose terminate handler will attempt to write to
stderr. If your application closes stderr or redirects it to an <literal>stderr</literal>. If your application closes
inappropriate location, <literal>stderr</literal> or redirects it to an inappropriate location,
<function>__verbose_terminate_handler</function> will behave in <function>__verbose_terminate_handler</function> will behave in
an unspecified manner. an unspecified manner.
</para> </para>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment