______________________________________________________________________
18 Language support library [lib.language.support]
______________________________________________________________________
1 This clause describes the function signatures that are called implic
itly, and the types of objects generated implicitly, during the execu
tion of some C++ programs. It also describes the headers that declare
these function signatures and define any related types.
2 The following subclauses describe common type definitions used
throughout the library, characteristics of the predefined types, func
tions supporting start and termination of a C++ program, support for
dynamic memory management, support for dynamic type identification,
support for exception processing, and other runtime support, as summa
rized in Table 1:
Table 1--Language support library summary
+--------------------------------------------------------------+
| Subclause Header(s) |
+--------------------------------------------------------------+
|_lib.support.types_ Types <cstddef> |
+--------------------------------------------------------------+
| <limits> |
|_lib.support.limits_ Implementation properties <climits> |
| <cfloat> |
+--------------------------------------------------------------+
|_lib.support.start.term_ Start and termination <cstdlib> |
+--------------------------------------------------------------+
|_lib.support.dynamic_ Dynamic memory management <new> |
+--------------------------------------------------------------+
|_lib.support.rtti_ Type identification <typeinfo> |
+--------------------------------------------------------------+
|_lib.support.exception_ Exception handling <exception> |
+--------------------------------------------------------------+
| <cstdarg> |
| <csetjmp> |
|_lib.support.runtime_ Other runtime support <ctime> |
| <csignal> |
| <cstdlib> |
+--------------------------------------------------------------+
18.1 Types [lib.support.types]
1 Common definitons.
2 Header <cstddef> (Table 2):
Table 2--Header <cstddef> synopsis
+----------------------------------------------------+
| Type Name(s) |
+----------------------------------------------------+
|Macros: NULL <cstddef> offsetof |
+----------------------------------------------------+
|Types: ptrdiff_t<cstddef> size_t <cstddef> |
+----------------------------------------------------+
3 The contents are the same as the Standard C library, with the follow
ing changes:
4 The macro NULL is an implementation-defined C++ null-pointer constant
in this International Standard (_conv.ptr_).1)
5 The macro offsetof accepts a restricted set of type arguments in this
International Standard. type shall be a POD structure or a POD union
(_class_).
SEE ALSO: subclause _expr.sizeof_, Sizeof, subclause _expr.add_, Addi
tive operators, subclause _class.free_, Free store, and ISO C sub
clause 7.1.6.
18.2 Implementation properties [lib.support.limits]
1 Characteristics of implementation-dependent fundamental types
(_basic.fundamental_).
18.2.1 Numeric limits [lib.limits]
1 The numeric_limits component provides a C++ program with information
about various properties of the implementation's representation of the
fundamental types.
2 Specializations shall be provided for each fundamental type, both
floating point and integer, including bool. The member is_specialized
shall be true for all such specializations of numeric_limits.
3 Non-scalar types, such as complex<T> (_lib.complex_), shall not have
specializations.
Header <limits> synopsis
_________________________
1) Possible definitions include 0 and 0L, but not (void*)0.
namespace std {
template<class T> class numeric_limits;
enum float_rounds_style;
class numeric_limits<bool>;
class numeric_limits<char>;
class numeric_limits<signed char>;
class numeric_limits<unsigned char>;
class numeric_limits<wchar_t>;
class numeric_limits<short>;
class numeric_limits<int>;
class numeric_limits<long>;
class numeric_limits<unsigned short>;
class numeric_limits<unsigned int>;
class numeric_limits<unsigned long>;
class numeric_limits<float>;
class numeric_limits<double>;
class numeric_limits<long double>;
}
18.2.1.1 Template class numeric_limits [lib.numeric.limits]
namespace std {
template<class T> class numeric_limits {
public:
static const bool is_specialized;
static T min();
static T max();
static const int digits;
static const int digits10;
static const bool is_signed;
static const bool is_integer;
static const bool is_exact;
static const int radix;
static T epsilon();
static T round_error();
static const int min_exponent;
static const int min_exponent10;
static const int max_exponent;
static const int max_exponent10;
static const bool has_infinity;
static const bool has_quiet_NaN;
static const bool has_signaling_NaN;
static const bool has_denorm;
static T infinity();
static T quiet_NaN();
static T signaling_NaN();
static T denorm_min();
static const bool is_iec559;
static const bool is_bounded;
static const bool is_modulo;
static const bool traps;
static const bool tinyness_before;
static const float_round_style round_style;
};
}
1 The member is_specialized makes it possible to distinguish between
scalar types, which have specializations, and non-scalar types, which
do not.
2 The members radix, epsilon(), and round_error() shall have meaningful
values for all floating point type specializations.
3 For types with has_denorm == false, the member denorm_min() shall
return the same value as the member min().
4 The default numeric_limits<T> template shall have all members, but
with meaningless (0 or false) values.
+------- BEGIN BOX 1 -------+
Editorial proposal:
Add exception specifications of throw() to each member function, per
95-0020/N0620.
+------- END BOX 1 -------+
18.2.1.2 numeric_limits members [lib.numeric.limits.members]
static T min();
1 Minimum finite value.2)
_________________________
2 For floating types with denormalization, returns the minimum positive
normalized value, denorm_min().
3 Meaningful for all specializations in which is_bounded == true, or
is_bounded == false && is_signed == false.
static T max();
4 Maximum finite value.3)
5 Meaningful for all specializations in which is_bounded == true.
static const int digits;
6 Number of radix digits which can be represented without change.
7 For built-in integer types, the number of non-sign bits in the repre
sentation.
8 For floating point types, the number of radix digits in the
mantissa.4)
static const int digits10;
9 Number of base 10 digits which can be represented without change.5)
10Meaningful for all specializations in which is_bounded == true.
static const bool is_signed;
11True if the type is signed.
12Meaningful for all specializations.
static const bool is_integer;
_________________________
2) Equivalent to CHAR_MIN, SHRT_MIN, FLT_MIN, DBL_MIN, etc.
3) Equivalent to CHAR_MAX, SHRT_MAX, FLT_MAX, DBL_MAX, etc.
4) Equivalent to FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG.
5) Equivalent to FLT_DIG, DBL_DIG, LDBL_DIG.
13True if the type is integer.
14Meaningful for all specializations.
static const bool is_exact;
15True if the type uses an exact representation. All integer types are
exact, but not vice versa. For example, rational and fixed-exponent
representations are exact but not integer.
16Meaningful for all specializations.
static const int radix;
17For floating types, specifies the base or radix of the exponent repre
sentation (often 2).6)
18For integer types, specifies the base of the representation.7)
19Meaningful for all specializations.
static T epsilon();
20Machine epsilon: the difference between 1 and the least value greater
than 1 that is representable.8)
21Meaningful only for floating point types.
static T round_error();
22Measure of the maximum rounding error.9)
static const int min_exponent;
23Minimum negative integer such that radix raised to that power is in
range.10)
_________________________
6) Equivalent to FLT_RADIX.
7) Distinguishes types with bases other than 2 (e.g. BCD).
8) Equivalent to FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON.
9) This has a precise definition in the Language Independent Arith
metic (LIA-1) standard. Required by LIA-1.
10) Equivalent to FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP.
24Meaningful only for floating point types.
static const int min_exponent10;
25Minimum negative integer such that 10 raised to that power is in
range.11)
26Meaningful only for floating point types.
static const int max_exponent;
27Maximum positive integer such that radix raised to that power is in
range.12)
28Meaningful only for floating point types.
static const int max_exponent10;
29Maximum positive integer such that 10 raised to that power is in
range.13)
30Meaningful only for floating point types.
static const bool has_infinity;
31True if the type has a representation for positive infinity.
32Meaningful only for floating point types.
33Shall be true for all specializations in which is_iec559 == true.
static const bool has_quiet_NaN;
34True if the type has a representation for a quiet (non-signaling)
``Not a Number.''14)
_________________________
11) Equivalent to FLT_MIN_10_EXP, DBL_MIN_10_EXP, LDBL_MIN_10_EXP.
12) Equivalent to FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP.
13) Equivalent to FLT_MAX_10_EXP, DBL_MAX_10_EXP, LDBL_MAX_10_EXP.
14) Required by LIA-1.
35Meaningful only for floating point types.
36Shall be true for all specializations in which is_iec559 == true.
static const bool has_signaling_NaN;
37True if the type has a representation for a signaling ``Not a
Number.''15)
38Meaningful only for floating point types.
39Shall be true for all specializations in which is_iec559 == true.
static const bool has_denorm;
40True if the type allows denormalized values (variable number of expo
nent bits).16)
41Meaningful only for flotaing point types.
static T infinity();
42Representation of positive infinity, if available.17)
43Meaningful only in specializations for which has_infinity == true.
Required in specializations for which is_iec559 == true.
static T quiet_NaN();
44Representation of a quiet ``Not a Number,'' if available.18)
45Meaningful only in specializations for which has_quiet_NaN == true.
Required in specializations for which is_iec559 == true.
static T signaling_NaN();
_________________________
15) Required by LIA-1.
16) Required by LIA-1.
17) Required by LIA-1.
18) Required by LIA-1.
46Representation of a signaling ``Not a Number,'' if available.19)
47Meaningful only in specializations for which has_signaling_NaN ==
true. Required in specializations for which is_iec559 == true.
static T denorm_min();
48Minimum positive denormalized value.20)
49Meaningful for all floating point types.
50In specializations for which has_denorm == false, returns the minimum
positive normalized value.
static const bool is_iec559;
51True if and only if the type adheres to IEC 559 standard.21)
52Meaningful only for floating point types.
static const bool is_bounded;
53True if the set of values representable by the type is finite.22) All
built-in types are bounded, this member would be false for arbitrary
precision types.
54Meaningful for all specializations.
static const bool is_modulo;
55True if the type is modulo.23) A type is modulo if it is possible to
add two positive numbers and have a result which wraps around to a
third number which is less.
56Generally, this is false for floating types, true for unsigned inte
gers, and true for signed integers on most machines.
_________________________
19) Required by LIA-1.
20) Required by LIA-1.
21) International Electrotechnical Commission standard 559 is the same
as IEEE 754.
22) Required by LIA-1.
23) Required by LIA-1.
57Meaningful for all specializations.
static const bool traps;
58true if trapping is implemented for the type.24)
59Meaningful for all specializations.
static const bool tinyness_before;
60true if tinyness is detected before rounding.25)
61Meaningful only for floating point types.
static const float_round_style round_style;
62The rounding style for the type.26)
63Meaningful for all floating point types. Specializations for integer
types shall return round_toward_zero.
18.2.1.3 Type float_round_style [lib.round.style]
namespace std {
enum float_round_style {
round_indeterminate = -1,
round_toward_zero = 0,
round_to_nearest = 1,
round_toward_infinity = 2,
round_toward_neg_infinity = 3
};
}
18.2.1.4 numeric_limits specializations [lib.numeric.special]
1 All members shall be provided for all specializations. However, many
values are only required to be meaningful under certain conditions
(for example, epsilon() is only meaningful if is_integer is false).
Any value which is not ``meaningful'' shall be set to 0 or false.
_________________________
24) Required by LIA-1.
25) Refer to IEC 559. Required by LIA-1.
26) Equivalent to FLT_ROUNDS. Required by LIA-1.
2 [Example:
namespace std {
class numeric_limits<float> {
public:
static const bool is_specialized = true;
inline static float min() { return 1.17549435E-38F; }
inline static float max() { return 3.40282347E+38F; }
static const int digits = 24;
static const int digits10 = 6;
static const bool is_signed = true;
static const bool is_integer = false;
static const bool is_exact = false;
static const int radix = 2;
inline static float epsilon() { return 1.19209290E-07F; }
inline static float round_error() { return 0.5F; }
static const int min_exponent = -125;
static const int min_exponent10 = - 37;
static const int max_exponent = +128;
static const int max_exponent10 = + 38;
static const bool has_infinity = true;
static const bool has_quiet_NaN = true;
static const bool has_signaling_NaN = true;
static const bool has_denorm = false;
inline static float infinity() { return ...; }
inline static float quiet_NaN() { return ...; }
inline static float signaling_NaN() { return ...; }
inline static float denorm_min() { return min(); }
static const bool is_iec559 = true;
static const bool is_bounded = true;
static const bool is_modulo = false;
static const bool traps = true;
static const bool tinyness_before = true;
static const float_round_style round_style = round_to_nearest;
};
}
--end example]
18.2.2 C Library [lib.c.limits]
1 Header <climits> (Table 3):
Table 3--Header <climits> synopsis
+---------------------------------------------------------------------+
| Type Name(s) |
+---------------------------------------------------------------------+
|Values: |
|CHAR_BIT INT_MAX LONG_MIN SCHAR_MIN UCHAR_MAX USHRT_MAX |
|CHAR_MAX INT_MIN MB_LEN_MAX SHRT_MAX UINT_MAX |
|CHAR_MIN LONG_MAX SCHAR_MAX SHRT_MIN ULONG_MAX |
+---------------------------------------------------------------------+
2 The contents are the same as the Standard C library.
3 Header <cfloat> (Table 4):
Table 4--Header <cfloat> synopsis
+-------------------------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------------------------+
|Values: |
|DBL_DIG DBL_MIN_EXP FLT_MIN_10_EXP LDBL_MAX_10_EXP |
|DBL_EPSILON FLT_DIG FLT_MIN_EXP LDBL_MAX_EXP |
|DBL_MANT_DIG FLT_EPSILON FLT_RADIX LDBL_MIN |
|DBL_MAX FLT_MANT_DIG FLT_ROUNDS LDBL_MIN_10_EXP |
|DBL_MAX_10_EXP FLT_MAX LDBL_DIG LDBL_MIN_EXP |
|DBL_MAX_EXP FLT_MAX_10_EXP LDBL_EPSILON |
|DBL_MIN FLT_MAX_EXP LDBL_MANT_DIG |
|DBL_MIN_10_EXP FLT_MIN LDBL_MAX |
+-------------------------------------------------------------------+
4 The contents are the same as the Standard C library.
SEE ALSO: ISO C subclause 7.1.5, 5.2.4.2.2, 5.2.4.2.1.
18.3 Start and termination [lib.support.start.term]
1 Header <cstdlib> (partial), Table 5:
Table 5--Header <cstdlib> synopsis
+-------------------------------------------+
| Type Name(s) |
+-------------------------------------------+
|Macros: EXIT_FAILURE EXIT_SUCCESS |
+-------------------------------------------+
|Functions: abort atexit exit |
+-------------------------------------------+
2 The contents are the same as the Standard C library, with the follow
ing changes:
atexit(void (*f)(void))
3 The function atexit(), has additional behavior in this International
Standard:
--For the execution of a function registered with atexit, if control
leaves the function because it provides no handler for a thrown
exception, terminate() is called (_lib.terminate_).
exit(int status)
4 The function exit() has additional behavior in this International
Standard:
--First, all functions f registered by calling atexit(f) are called,
in the reverse order of their registration.27)
--Next, all static objects are destroyed in the reverse order of their
construction. (Automatic objects are not destroyed as a result of
calling exit().)28)
--Next, all open C streams (as mediated by the function signatures
declared in <cstdio>) with unwritten buffered data are flushed, all
open C streams are closed, and all files created by calling tmp
file() are removed.29)
--Finally, control is returned to the host environment. If status is
zero or EXIT_SUCCESS, an implementation-defined form of the status
successful termination is returned. If status is EXIT_FAILURE, an
implementation-defined form of the status unsuccessful termination
is returned. Otherwise the status returned is
implementation-defined.30)
5 The function exit() never returns to its caller.
SEE ALSO: subclauses _basic.start_, _basic.start.term_, ISO C sub
clause 7.10.4.
18.4 Dynamic memory management [lib.support.dynamic]
1 The header <new> defines several functions that manage the allocation
of dynamic storage in a program. It also defines components for
reporting storage management errors.
Header <new> synopsis
_________________________
27) A function is called for every time it is registered. The func
tion signature atexit(void (*)()), is declared in <cstdlib>.
28) Automatic objects are all destroyed in a program whose function
main() contains no automatic objects and executes the call to exit().
Control can be transferred directly to such a main() by throwing an
exception that is caught in main().
29) Any C streams associated with cin, cout, etc
(_lib.iostream.objects_) are flushed and closed when static objects
are destroyed in the previous phase. The function tmpfile() is de
clared in <cstdio>.
30) The macros EXIT_FAILURE and EXIT_SUCCESS are defined in <cstdlib>.
#include <cstdlib> // for size_t
#include <stdexcept> // for exception
namespace std {
void* operator new(size_t size) throw(bad_alloc);
struct nothrow {};
void* operator new(size_t size, const nothrow&) throw();
void operator delete(void* ptr) throw();
void* operator new[](size_t size) throw(bad_alloc);
void* operator new[](size_t size, const nothrow&) throw();
void operator delete[](void* ptr) throw();
void* operator new (size_t size, void* ptr) throw();
void* operator new[](size_t size, void* ptr) throw();
void operator delete (void* ptr, void*) throw();
void operator delete[](void* ptr, void*) throw();
class bad_alloc;
typedef void (*new_handler)();
new_handler set_new_handler(new_handler new_p);
}
SEE ALSO: subclauses _intro.memory_, _basic.stc.dynamic_, _expr.new_,
_expr.delete_, _class.free_, subclause _lib.memory_, Memory.
18.4.1 Storage allocation and deallocation [lib.new.delete]
18.4.1.1 Single-object forms [lib.new.delete.single]
void* operator new(size_t size) throw(bad_alloc);
Effects:
The allocation function (_basic.stc.dynamic.allocation_) called by a
new-expression (_expr.new_) to allocate size bytes of storage suit
ably aligned to represent any object of that size.
Replaceable:
a C++ program may define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
Return a pointer to dynamically allocated storage
(_basic.stc.dynamic_), or else throw a bad_alloc exception.
Default behavior:
--Executes a loop: Within the loop, the function first attempts to
allocate the requested storage. Whether the attempt involves a call
to the Standard C library function malloc is unspecified.
--Returns a pointer to the allocated storage if the attempt is suc
cessful. Otherwise, if the last argument to set_new_handler() was a
null pointer, throw bad_alloc.
--Otherwise, the function calls the current new_handler
(_lib.new.handler_). If the called function returns, the loop
repeats.
--The loop terminates when an attempt to allocate the requested stor
age is successful or when a called new_handler function does not
return.
void* operator new(size_t size, const nothrow&) throw();
Effects:
Same as above, except that it is called by a placement version of a
new-expression when a C++ program prefers a null pointer result as
an error indication, instead of a bad_alloc exception.
Replaceable:
a C++ program may define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
Return a pointer to dynamically allocated storage
(_basic.stc.dynamic_), or else return a null pointer.
Default behavior:
--Executes a loop: Within the loop, the function first attempts to
allocate the requested storage. Whether the attempt involves a call
to the Standard C library function malloc is unspecified.
--Returns a pointer to the allocated storage if the attempt is suc
cessful. Otherwise, if the last argument to set_new_handler() was a
null pointer, return a null pointer.
--Otherwise, the function calls the current new_handler
(_lib.new.handler_). If the called function returns, the loop
repeats.
--The loop terminates when an attempt to allocate the requested stor
age is successful or when a called new_handler function does not
return. If the called new_handler function terminates by throwing a
bad_alloc exception, the function returns a null pointer.
1 [Example:
T* p1 = new T; // throws bad_alloc if it fails
T* p2 = new(nothrow()) T; // returns 0 if it fails
--end example]
void operator delete(void* ptr) throw();
Effects:
The deallocation function (_basic.stc.dynamic.deallocation_) called
by a delete-expression to render the value of ptr invalid.
Replaceable:
a C++ program may define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
accept a value of ptr that is null or that was returned by an ear
lier call to the default operator new(size_t) or operator
new(size_t,const nothrow&).
Default behavior:
--For a null value of ptr, do nothing.
--Any other value of ptr shall be a value returned earlier by a call
to the default operator new.31) For such a non-null value of ptr,
reclaims storage allocated by the earlier call to the default opera
tor new.
Notes:
It is unspecified under what conditions part or all of such
reclaimed storage is allocated by a subsequent call to operator new
or any of calloc, malloc, or realloc, declared in <cstdlib>.
18.4.1.2 Array forms [lib.new.delete.array]
void* operator new[](size_t size) throw(bad_alloc);
Effects:
The allocation function (_basic.stc.dynamic.allocation_) called by
the array form of a new-expression (_expr.new_) to allocate size
bytes of storage suitably aligned to represent any array object of
that size or smaller.32)
Replaceable:
a C++ program can define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
Same as for operator new(size_t).
Default behavior:
Returns operator new(size).
void* operator new[](size_t size, const nothrow&) throw();
Effects:
Same as above, except that it is called by a placement version of a
new-expression when a C++ program prefers a null pointer result as
an error indication, instead of a bad_alloc exception.
_________________________
31) The value must not have been invalidated by an intervening call to
operator delete(void*) (_lib.res.on.arguments_).
32) It is not the direct responsibility of operator new[](size_t) or
operator delete[](void*) to note the repetition count or element size
of the array. Those operations are performed elsewhere in the array
new and delete expressions. The array new expression, may, however,
increase the size argument to operator new[](size_t) to obtain space
to store supplemental information.
Replaceable:
a C++ program can define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
Same as for operator new(size_t,const nothrow&).
Default behavior:
Returns operator new(size,nothrow()).
void operator delete[](void* ptr) throw();
Effects:
The deallocation function (_basic.stc.dynamic.deallocation_) called
by the array form of a delete-expression to render the value of ptr
invalid.
Replaceable:
a C++ program can define a function with this function signature
that displaces the default version defined by the C++ Standard
library.
Required behavior:
accept a value of ptr that is null or that was returned by an ear
lier call to operator new[](size_t).
Default behavior:
--For a null value of ptr, does nothing.
--Any other value of ptr shall be a value returned earlier by a call
to the default operator new[](size_t).33) For such a non-null value
of ptr, reclaims storage allocated by the earlier call to the
default operator new[](size_t) or operator new[](size_t,nothrow).
1 It is unspecified under what conditions part or all of such reclaimed
storage is allocated by a subsequent call to operator new(size_t) or
any of calloc, malloc, or realloc, declared in <cstdlib>.
18.4.1.3 Placement forms [lib.new.delete.placement]
1 These functions are reserved, a C++ program may not define functions
that displace the versions in the Standard C++ library
(_lib.constraints_).
void* operator new(size_t size, void* ptr) throw();
Returns:
ptr.
Notes:
Intentionally performs no other action.34)
_________________________
33) The value must not have been invalidated by an intervening call to
operator delete[](void*) (_lib.res.on.arguments_).
2 [Example: This can be useful for constructing an object at a known
address:
char place[sizeof(Something)];
Something* p = new (place) Something();
--end example]
void* operator new[](size_t size, void* ptr) throw();
Returns:
ptr.
Notes:
Intentionally performs no other action.
void operator delete(void* ptr, void*) throw();
Effects:
Intentionally performs no action.
Notes:
Default function called for a placement delete expression. Comple
ments default placement new.
void operator delete[](void* ptr, void*) throw();
Effects:
Intentionally performs no action.
Notes:
Default function called for a placement array delete expression.
Complements default placement new[].
18.4.2 Storage allocation errors [lib.alloc.errors]
18.4.2.1 Class bad_alloc [lib.bad.alloc]
namespace std {
class bad_alloc : public exception {
public:
bad_alloc() throw();
bad_alloc(const bad_alloc&) throw();
bad_alloc& operator=(const bad_alloc&) throw();
virtual ~bad_alloc() throw();
virtual const char* what() const throw();
};
}
1 The class bad_alloc defines the type of objects thrown as exceptions
by the implementation to report a failure to allocate storage.
bad_alloc() throw();
Effects:
Constructs an object of class bad_alloc.
bad_alloc(const bad_alloc&) throw();
bad_alloc& operator=(const bad_alloc&) throw();
Effects:
Copies an object of class bad_alloc.
Notes:
The result of calling what() on the newly constructed object is
implementation-defined.
virtual const char* what() const throw();
Returns:
An implementation-defined value.
18.4.2.2 Type new_handler [lib.new.handler]
typedef void (*new_handler)();
1 The type of a handler function to be called by operator new() or oper
ator new[]() (_lib.new.delete_) when they cannot satisfy a request for
addtional storage.
Required behavior:
A new_handler shall perform one of the following:
--make more storage available for allocation and then return;
--throw an exception of type bad_alloc or a class derived from
bad_alloc;
--call either abort() or exit();
Default behavior:
The implementation's default new_handler throws an exception of type
bad_alloc.
18.4.2.3 set_new_handler [lib.set.new.handler]
new_handler set_new_handler(new_handler new_p);
Effects:
Establishes the function designated by new_p as the current
new_handler.
Returns:
the previous new_handler.
18.5 Type identification [lib.support.rtti]
1 The header <typeinfo> defines two types associated with type informa
tion generated by the implementation. It also defines two types for
reporting dynamic type identification errors.
Header <typeinfo> synopsis
#include <stdexcept> // for exception
namespace std {
class type_info;
class bad_cast;
class bad_typeid;
}
SEE ALSO: subclauses _expr.dynamic.cast_, _expr.typeid_.
18.5.1 Class type_info [lib.type.info]
namespace std {
class type_info {
public:
virtual ~type_info();
bool operator==(const type_info& rhs) const;
bool operator!=(const type_info& rhs) const;
bool before(const type_info& rhs) const;
const char* name() const;
private:
type_info(const type_info& rhs);
type_info& operator=(const type_info& rhs);
};
}
1 The class type_info describes type information generated by the imple
mentation. Objects of this class effectively store a pointer to a
name for the type, and an encoded value suitable for comparing two
types for equality or collating order. The names, encoding rule, and
collating sequence for types are all unspecified and may differ
between programs.
bool operator==(const type_info& rhs) const;
Effects:
Compares the current object with rhs.
Returns:
true if the two values describe the same type.
bool operator!=(const type_info& rhs) const;
Returns:
!(*this == rhs).
bool before(const type_info& rhs) const;
Effects:
Compares the current object with rhs.
Returns:
true if *this precedes rhs in the implementation's collation order.
const char* name() const;
Returns:
an implementation-defined value.
Notes:
The message may be a null-terminated multibyte string
(_lib.multibyte.strings_), suitable for conversion and display as a
wstring (_lib.wstring_, _lib.locale.codecvt_)
type_info(const type_info& rhs);
type_info& operator=(const type_info& rhs);
Effects:
Copies a type_info object.
Notes:
Since the copy constructor and assignment operator for type_info are
private to the class, objects of this type cannot be copied.
18.5.2 Class bad_cast [lib.bad.cast]
namespace std {
class bad_cast : public exception {
public:
bad_cast() throw();
bad_cast(const bad_cast&) throw();
bad_cast& operator=(const bad_cast&) throw();
virtual ~bad_cast() throw();
virtual const char* what() const throw();
};
}
1 The class bad_cast defines the type of objects thrown as exceptions by
the implementation to report the execution of an invalid dynamic-cast
expression (_expr.dynamic.cast_).
bad_cast() throw();
Effects:
Constructs an object of class bad_cast.
bad_cast(const bad_cast&) throw();
bad_cast& operator=(const bad_cast&) throw();
Effects:
Copies an object of class bad_cast.
Notes:
The result of calling what() on the newly constructed object is
implementation-defined.
virtual const char* what() const throw();
Returns:
An implementation-defined value.
Notes:
The message may be a null-terminated multibyte string
(_lib.multibyte.strings_), suitable for conversion and display as a
wstring (_lib.wstring_, _lib.locale.codecvt_)
18.5.3 Class bad_typeid [lib.bad.typeid]
namespace std {
class bad_typeid : public exception {
public:
bad_typeid() throw();
bad_typeid(const bad_typeid&) throw();
bad_typeid& operator=(const bad_typeid&) throw();
virtual ~bad_typeid() throw();
virtual const char* what() const throw();
};
}
1 The class bad_typeid defines the type of objects thrown as exceptions
by the implementation to report a null pointer in a typeid expression
(_expr.typeid_).
bad_typeid() throw();
Effects:
Constructs an object of class bad_typeid.
bad_typeid(const bad_typeid&) throw();
bad_typeid& operator=(const bad_typeid&) throw();
Effects:
Copies an object of class bad_typeid.
Notes:
The result of calling what() on the newly constructed object is
implementation-defined.
virtual const char* what() const throw();
Returns:
An implementation-defined value.
Notes:
The message may be a null-terminated multibyte string
(_lib.multibyte.strings_), suitable for conversion and display as a
wstring (_lib.wstring_, _lib.locale.codecvt_)
18.6 Exception handling [lib.support.exception]
1 The header <exception> defines several types and functions related to
the handling of exceptions in a C++ program.
Header <exception> synopsis
#include <stdexcept> // for exception
namespace std {
class bad_exception;
typedef void (*unexpected_handler)();
unexpected_handler set_unexpected(unexpected_handler f);
void unexpected();
typedef void (*terminate_handler)();
terminate_handler set_terminate(terminate_handler f);
void terminate();
}
SEE ALSO: subclause _except.special_.
18.6.1 Violating exception- [lib.exception.unexpected]
specifications
18.6.1.1 Class bad_exception [lib.bad.exception]
namespace std {
class bad_exception : public exception {
public:
bad_exception() throw();
bad_exception(const bad_exception&) throw();
bad_exception& operator=(const bad_exception&) throw();
virtual ~bad_exception() throw();
virtual const char* what() const throw();
};
}
1 The class bad_exception defines the type of objects thrown as excep
tions by the implementation to report a violation of an exception-
specification (_except.unexpected_).
bad_exception() throw();
Effects:
Constructs an object of class bad_exception.
bad_exception(const bad_exception&) throw();
bad_exception& operator=(const bad_exception&) throw();
Effects:
Copies an object of class bad_exception.
Notes:
The result of calling what() on the newly constructed object is
implementation-defined.
virtual const char* what() const throw();
Returns:
An implementation-defined value.
Notes:
The message may be a null-terminated multibyte string
(_lib.multibyte.strings_), suitable for conversion and display as a
wstring (_lib.wstring_, _lib.locale.codecvt_)
18.6.1.2 Type unexpected_handler [lib.unexpected.handler]
typedef void (*unexpected_handler)();
1 The type of a handler function to be called by unexpected() when a
function attempts to throw an exception not listed in its exception-
specification.
Required behavior:
an unexpected_handler shall either throw an exception or terminate
execution of the program without returning to the caller. An unex
pected_handler may perform any of the following:
--throw an exception that satisfies the exception specification;
--throw a bad_exception exception;
--call terminate();
--call either abort() or exit();
Default behavior:
The implementation's default unexpected_handler calls terminate().
18.6.1.3 set_unexpected [lib.set.unexpected]
unexpected_handler set_unexpected(unexpected_handler f);
Effects:
Establishes the function designated by f as the current unex
pected_handler.
Requires:
f shall not be a null pointer.
Returns:
The previous unexpected_handler.
18.6.1.4 unexpected [lib.unexpected]
void unexpected();
1 Called by the implementation when a function with an exception-
specification throws an exception that is not listed in the exception-
specification (_except.unexpected_).
Effects:
Calls the current unexpected_handler handler function
(_lib.unexpected.handler_).
18.6.2 Abnormal termination [lib.exception.terminate]
18.6.2.1 Type terminate_handler [lib.terminate.handler]
typedef void (*terminate_handler)();
1 The type of a handler function to be called by terminate() when termi
nating exception processing.
Required behavior:
A terminate_handler shall terminate execution of the program without
returning to the caller.
Default behavior:
The implementation's default terminate_handler calls abort().
18.6.2.2 set_terminate [lib.set.terminate]
terminate_handler set_terminate(terminate_handler f);
Effects:
Establishes the function designated by f as the current handler
function for terminating exception processing.
Requires:
f shall not be a null pointer.
Returns:
The previous terminate_handler.
18.6.2.3 terminate [lib.terminate]
void terminate();
1 Called by the implementation when exception handling must be abandoned
for any of several reasons (_except.terminate_).
Effects:
Calls the current terminate_handler handler function
(_lib.terminate.handler_).
18.7 Other runtime support [lib.support.runtime]
1 Headers <cstdarg> (variable arguments), <csetjmp> (nonlocal jumps),
<ctime> (system clock clock(), time()), <csignal> (signal handling),
and <cstdlib> (runtime environment getenv(), system()).
Table 5--Header <cstdarg> synopsis
+--------------------------------------+
| Type Name(s) |
+--------------------------------------+
|Macros: va_arg va_end va_start |
+--------------------------------------+
|Type: va_list |
+--------------------------------------+
Table 5--Header <csetjmp> synopsis
+--------------------+
| Type Name(s) |
+--------------------+
|Macro: setjmp |
+--------------------+
|Type: jmp_buf |
+--------------------+
|Function: longjmp |
+--------------------+
Table 5--Header <ctime> synopsis
+----------------------------+
| Type Name(s) |
+----------------------------+
|Macros: CLOCKS_PER_SEC |
+----------------------------+
|Types: clock_t |
+----------------------------+
|Functions: clock |
+----------------------------+
Table 5--Header <csignal> synopsis
+-------------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------------+
|Macros: SIGABRT SIGILL SIGSEGV SIG_DFL |
|SIG_IGN SIGFPE SIGINT SIGTERM SIG_ERR |
+-------------------------------------------------------+
|Type: sig_atomic_t |
+-------------------------------------------------------+
|Functions: raise signal |
+-------------------------------------------------------+
Table 5--Header <cstdlib> synopsis
+-----------------------------+
| Type Name(s) |
+-----------------------------+
|Functions: getenv system |
+-----------------------------+
2 The contents are the same as the Standard C library, with the follow
ing changes:
3 The function signature longjmp(jmp_buf jbuf, int val) has more
restricted behavior in this International Standard. If any automatic
objects would be destroyed by a thrown exception transferring control
to another (destination) point in the program, then a call to
longjmp(jbuf, val) at the throw point that transfers control to the
same (destination) point has undefined behavior.
SEE ALSO: ISO C subclause 7.10.4, 7.8, 7.6, 7.12.