______________________________________________________________________
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 (_lib.support.types_), characteristics of the
predefined types (_lib.support.limits_), functions supporting start
and termination of a C++ program (_lib.support.start.term_), support
for dynamic memory management (_lib.support.dynamic_), support for
dynamic type identification (_lib.support.rtti_), support for excep
tion processing (_lib.support.exception_), and other runtime support
(_lib.support.runtime_).
18.1 Types [lib.support.types]
1 Common definitons.
2 Required by subclauses _expr.sizeof_ and _class.free_.
3 Headers:
--<stddef>
--<cstddef>
4 Table 1:
Table 1--Header <stddef> synopsis
+------------------------------------------------+
| Type Name(s) |
+------------------------------------------------+
|Types: |
|capacity ptrdiff_t <stddef> wint_t <stddef> |
|fvoid_t size_t <stddef> |
+------------------------------------------------+
5 Table 2:
Table 2--Header <cstddef> synopsis
+----------------------------------------------------------+
| Type Name(s) |
+----------------------------------------------------------+
|Macros: NULL <cstddef> offsetof |
+----------------------------------------------------------+
|Types: ptrdiff_t<cstddef> size_t <cstddef> wchar_t |
+----------------------------------------------------------+
6 The header <stddef> defines a constant and several types used widely
throughout the Standard C++ library. Some are also defined in C head
ers.
18.1.1 Values [lib.stddef.values]
const size_t NPOS = (size_t)(-1);
1 which is the largest representable value of type size_t.
18.1.2 Types [lib.stddef.types]
+------- BEGIN BOX 1 -------+
This is not used anywhere. Remove it.
+------- END BOX 1 -------+
typedef void fvoid_t();
1 The type fvoid_t is a function type used to simplify the writing of
several declarations in this clause.
+------- BEGIN BOX 2 -------+
This is redundant with <cstddef>. Remove it.
+------- END BOX 2 -------+
typedef T ptrdiff_t;
2 The type ptrdiff_t is a synonym for T, the implementation-defined
signed integral type of the result of subtracting two pointers.
+------- BEGIN BOX 3 -------+
This is redundant with <cstddef>. Remove it.
+------- END BOX 3 -------+
typedef T size_t;
3 The type size_t is a synonym for T, the implementation-defined
unsigned integral type of the result of the sizeof operator.
+------- BEGIN BOX 4 -------+
This is redundant with <cwchar>. Remove it.
+------- END BOX 4 -------+
typedef T wint_t;
4 The type wint_t is a synonym for T, the implementation-defined inte
gral type, unchanged by integral promotions, that can hold any value
of type wchar_t as well as at least one value that does not correspond
to the code for any member of the extended character set.1)
typedef T capacity;
static const capacity default_size;
static const capacity reserve;
5 The type capacity is an enumerated type (indicated here as T), with
the elements:
--default_size, as an argument value indicates that no reserve capac
ity argument is present in the argument list;
--reserve, as an argument value indicates that the preceding argument
specifies a reserve capacity.
SEE ALSO: ISO C subclause 7.1.6.
18.2 Implementation properties [lib.support.limits]
1 Limits.
2 Required by subclause _basic.fundamental_.
3 Headers:
--<climits>
--<cfloat>
4 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 |
+---------------------------------------------------------------------+
_________________________
1) The extra value is denoted by the macro WEOF, defined in <cwchar>.
It is permissible for WEOF to be in the range of values representable
by wchar_t.
5 Table 4:
Table 4--Header <cfloat> synopsis
+-------------------------------------------------------------------+
| Type Name(s) |
+-------------------------------------------------------------------+
|Values: |
|DBL_DIG DBL_MIN_DIG FLT_MIN_10_EXP LDBL_MAX_10_EXP |
|DBL_EPSILON FLT_DIG FLT_MIN_DIG 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_DIG |
|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 |
+-------------------------------------------------------------------+
6 The contents are the same as the Standard C library.
SEE ALSO: subclause _lex.key_, 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 Required by subclauses _basic.start_, _basic.start.term_.
2 Headers:
--<cstdlib> (partial)
3 Table 5:
Table 5--Header <cstdlib> synopsis
+-------------------------------------------+
| Type Name(s) |
+-------------------------------------------+
|Macros: EXIT_FAILURE EXIT_SUCCESS |
+-------------------------------------------+
|Functions: abort atexit exit |
+-------------------------------------------+
4 The contents are the same as the Standard C library, with the follow
ing changes:
18.3.0.1 atexit [lib.atexit]
atexit(void (*f)(void))
1 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_).
18.3.0.2 exit [lib.exit]
exit(int status)
1 The function exit has additional behavior in this International Stan
dard:
--First, all functions f registered by calling atexit(f), are called,
in the reverse order of their registration.2)
--Next, all static objects are destroyed in the reverse order of their
construction. (Automatic objects are not destroyed as a result of
calling exit.)3)
--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.4)
--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.5)
2 The function exit never returns to its caller.
SEE ALSO: ISO C subclause 7.10.4.
_________________________
2) A function is called for every time it is registered. The function
signature atexit(void (*)()), is declared in <cstdlib>.
3) 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 ex
ception that is caught in main.
4) Any C streams associated with cin, cout, etc
(_lib.header.iostream_) are flushed and closed when static objects are
destroyed in the previous phase. The function signature tmpfile() is
declared in <cstdio>.
5) The macros EXIT_FAILURE and EXIT_SUCCESS are defined in <cstdlib>.
18.4 Dynamic memory management [lib.support.dynamic]
1 Required by subclauses _intro.memory_, _basic.stc.dynamic_,
_expr.new_, _expr.delete_, _class.free_.
2 Headers:
--<new>
3 Table 6:
Table 6--Header <new> synopsis
+-------------------------------------------+
| Type Name(s) |
+-------------------------------------------+
|Type: new_handler |
+-------------------------------------------+
|Class: bad_alloc |
+-------------------------------------------+
|Operator functions: |
|operator delete operator new (void*) |
|operator delete[] operator new[] |
|operator new operator new[] (void*) |
+-------------------------------------------+
|Function: set_new_handler |
+-------------------------------------------+
4 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.
SEE ALSO: subclause _lib.memory_.
18.4.1 Storage allocation and deallocation [lib.new.delete]
18.4.1.1 Single-object forms [lib.new.delete.single]
18.4.1.1.1 operator new [lib.op.new]
void* operator new(size_t size);
1 The allocation function (_basic.stc.dynamic.allocation_) called by a
new-expression (_expr.new_) to allocate size bytes of storage suitably
aligned to represent any object of that size.
2 Replaceable: a C++ program may define a function with this function
signature that displaces the default version defined by the Standard
C++ library.
3 Required behavior: return a pointer to dynamically allocated storage
(_basic.stc.dynamic_).
4 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, the result is implementation-defined.6)
--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.
18.4.1.1.2 operator delete [lib.op.delete]
void operator delete(void* ptr);
1 The deallocation function (_basic.stc.dynamic.deallocation_) called by
a delete-expression to render the value of ptr invalid.
2 Replaceable: a C++ program may define a function with this function
signature that displaces the default version defined by the Standard
C++ library.
3 Required behavior: accept a value of ptr that is null or that was
returned by an earlier call to operator new(size_t).
4 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(size_t).7) For such a non-null value of
ptr, reclaims storage allocated by the earlier call to the default
operator new(size_t).
5 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>.
_________________________
6) A common extension when new_handler is a null pointer is for opera
tor new(size_t) to return a null pointer, in accordance with many ear
lier implementations of C++.
7) The value must not have been invalidated by an intervening call to
operator delete(size_t), or it would be an invalid argument for a
Standard C++ library function call.
18.4.1.2 Array forms [lib.new.delete.array]
18.4.1.3 operator new[] [lib.op.new.array]
void* operator new[](size_t size);
1 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.8)
2 Replaceable: a C++ program can define a function with this function
signature that displaces the default version defined by the Standard
C++ library.
3 Required behavior: same as for operator new(size_t).
4 Default behavior: returns operator new(size).
18.4.1.4 operator delete[] [lib.op.delete.array]
void operator delete[](void* ptr);
1 The deallocation function (_basic.stc.dynamic.deallocation_) called by
the array form of a delete-expression to render the value of ptr
invalid.
2 Replaceable: a C++ program can define a function with this function
signature that displaces the default version defined by the Standard
C++ library.
3 Required behavior: accept a value of ptr that is null or that was
returned by an earlier call to operator new[](size_t).
4 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).9) For such a non-null value
of ptr, reclaims storage allocated by the earlier call to the
default operator new[](size_t).
5 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
_________________________
8) 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.
9) The value must not have been invalidated by an intervening call to
operator delete[](size_t), or it would be an invalid argument for a
Standard C++ library function call.
any of calloc, malloc, or realloc, declared in <cstdlib>.
18.4.1.5 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.
18.4.1.5.1 Placement operator new [lib.placement.op.new]
void* operator new(size_t size, void* ptr);
1 Returns ptr.
18.4.1.5.2 Placement operator new[] [lib.placement.op.new.array]
void* operator new[](size_t size, void* ptr);
1 Returns ptr.
18.4.2 Storage allocation errors [lib.alloc.errors]
18.4.2.1 Class bad_alloc [lib.bad.alloc]
class bad_alloc : public runtime_error {
public:
bad_alloc();
virtual ~bad_alloc();
virtual string what() const;
private:
// static string alloc_msg; exposition only
};
1 The class bad_alloc defines the type of objects thrown as exceptions
by the implementation to report a failure to allocate storage.
2 For the sake of exposition, the maintained data is presented here as:
--static string alloc_msg, an object of type string whose value is
intended to briefly describe an allocation failure, initialized to
an unspecified value.
18.4.2.1.1 bad_alloc constructor [lib.cons.bad.alloc]
bad_alloc();
1 Constructs an object of class alloc, initializing the base class with
runtime_error().
18.4.2.1.2 bad_alloc destructor [lib.des.bad.alloc]
virtual ~bad_alloc();
1 Destroys an object of class alloc.
18.4.2.1.3 bad_alloc::what [lib.bad.alloc::what]
virtual string what() const;
1 Returns an implementation-defined value.10)
_________________________
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[]() when they cannot satisfy a request for addtional storage.
2 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();
3 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);
1 Establishes the function designated by new_p as the current
new_handler.
2 Returns the previous new_handler.
18.5 Type identification [lib.support.rtti]
1 Required by subclauses _expr.dynamic.cast_, _expr.typeid_.
2 Headers:
--<typeinfo>
3 Table 7:
Table 7--Header <typeinfo> synopsis
+------------------------------------------+
| Type Name(s) |
+------------------------------------------+
|Classes: bad_cast bad_typeid typeid |
+------------------------------------------+
4 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.
_________________________
10) A possible return value is &alloc_msg.
18.5.1 Type information [lib.rtti]
18.5.1.1 Class typeid [lib.typeid]
+------- BEGIN BOX 5 -------+
TO BE SPECIFIED
+------- END BOX 5 -------+
18.5.1.2 Class type_info [lib.type.info]
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);
// const char* name; exposition only
// T desc; exposition only
};
1 The class type_info describes type information generated within the
program by the implementation. 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.
2 For the sake of exposition, the stored objects are presented here as:
--const char* name, points at a static NTMBS;
--T desc, an object of a type T that has distinct values for all the
distinct types in the program, stores the value corresponding to
name.
18.5.1.2.1 type_info destructor [lib.des.type.info]
virtual ~type_info();
1 Destroys an object of type type_info.
18.5.1.2.2 type_info::operator== [lib.type.info::op==]
bool operator==(const type_info& rhs) const;
1 Compares the value stored in desc with rhs.desc.
2 Returns true if the two values represent the same type.
18.5.1.2.3 type_info::operator!= [lib.type.info::op!=]
bool operator!=(const type_info& rhs) const;
1 Returns true if !(*this == rhs).
18.5.1.2.4 type_info::before [lib.type.info::before]
bool before(const type_info& rhs) const;
1 Compares the value stored in desc with rhs.desc.
2 Returns true if *this precedes rhs in the collation order.
18.5.1.2.5 type_info::name [lib.type.info::name]
const char* name() const;
1 Returns name.
18.5.1.2.6 Copying and assignment [lib.cons.type.info]
type_info(const type_info& rhs);
1 Constructs an object of class type_info and initializes name to
rhs.name and desc to rhs.desc.11)
type_info& operator=(const type_info& rhs);
2 Assigns rhs.name to name and rhs.desc to desc.
3 Returns *this.
18.5.2 Type identification errors [lib.rtti.errors]
18.5.2.1 Class bad_cast [lib.bad.cast]
class bad_cast : public logic_error {
public:
bad_cast(const string& what_arg);
virtual ~bad_cast();
// virtual string what() const; inherited
};
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.
18.5.2.1.1 bad_cast constructor [lib.cons.bad.cast]
bad_cast(const string& what_arg);
1 Constructs an object of class bad_cast, initializing the base class
with logic_error(what_arg.
_________________________
11) Since the copy constructor and assignment operator for type_info
are private to the class, objects of this type cannot be copied, but
objects of derived classes possibly can be.
18.5.2.1.2 bad_cast destructor [lib.des.bad.cast]
virtual ~bad_cast();
1 Destroys an object of class bad_cast.
18.5.2.1.3 bad_cast::what [lib.bad.cast::what]
// virtual string what() const inherited;
1 Behaves the same as exception::what().
18.5.2.2 Class bad_typeid [lib.bad.typeid]
class bad_typeid : public logic_error {
public:
bad_typeid();
virtual ~bad_typeid();
};
1 The class bad_typeid defines the type of objects thrown as exceptions
by the implementation to report a null pointer p in an expression of
the form typeid (*p).
18.5.2.2.1 bad_typeid constructor [lib.cons.bad.type.id]
bad_typeid();
1 Constructs an object of class bad_typeid, initializing the base class
logic_error with an unspecified constructor.
18.5.2.2.2 bad_typeid destructor [lib.des.bad.type.id]
virtual ~bad_typeid();
1 Destroys an object of class bad_typeid.
18.6 Exception handling [lib.support.exception]
1 Required by subclause _except.special_.
2 Headers:
--<exception>
3 Table 8:
Table 8--Header <exception> synopsis
+----------------------------------------------------+
| Type Name(s) |
+----------------------------------------------------+
|Types: terminate_handler unexpected_handler |
+----------------------------------------------------+
|Functions: set_terminate set_unexpected |
| terminate unexpected |
+----------------------------------------------------+
4 The header <exception> defines several types and functions related to
the handling of exceptions in a C++ program.
18.6.1 Abnormal termination [lib.exception.terminate]
18.6.1.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.
2 Required behavior: a terminate_handler shall terminate execution of
the program without returning to the caller.
3 Default behavior: the implementation's default terminate_handler calls
abort().
18.6.1.2 set_terminate [lib.set.terminate]
terminate_handler set_terminate(terminate_handler new_p);
1 Establishes the function designated by new_p as the current handler
function for terminating exception processing.
2 new_p shall not be a null pointer.
3 Returns the previous terminate_handler.
18.6.1.3 terminate [lib.terminate]
void terminate();
1 Called by the implementation when exception handling must be abandoned
for any of several reasons (_except.terminate_).
2 Calls the current terminate_handler handler function
(_lib.terminate.handler_).
18.6.2 Violating exception- [lib.exception.unexpected]
specifications
18.6.2.1 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.
2 Required behavior: an unexpected_handler shall either throw an excep
tion or terminate execution of the program without returning to the
caller.
3 An unexpected_handler may perform any of the following:
--rethrow the exception;
--throw another exception;
--call terminate();
--call either abort() or exit();
4 Default behavior: the implementation's default unexpected_handler
calls terminate().
18.6.2.2 set_unexpected [lib.set.unexpected]
unexpected_handler set_unexpected(unexpected_handler new_p);
1 Establishes the function designated by new_p as the current unex
pected_handler.
2 new_p shall not be a null pointer.
3 Returns the previous unexpected_handler.
18.6.2.3 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_).
2 Calls the current unexpected_handler handler function
(_lib.unexpected.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
--<cstdlib> Runtime environment getenv(), system()
2 Table 9:
Table 9--Header <cstdarg> synopsis
+--------------------------------------+
| Type Name(s) |
+--------------------------------------+
|Macros: va_arg va_end va_start |
+--------------------------------------+
|Type: va_list |
+--------------------------------------+
3 Table 10:
Table 10--Header <csetjmp> synopsis
+--------------------+
| Type Name(s) |
+--------------------+
|Macro: setjmp |
+--------------------+
|Type: jmp_buf |
+--------------------+
|Function: longjmp |
+--------------------+
4 Table 11:
Table 11--Header <ctime> synopsis
+----------------------------+
| Type Name(s) |
+----------------------------+
|Macros: CLOCKS_PER_SEC |
+----------------------------+
|Types: clock_t |
+----------------------------+
|Functions: clock |
+----------------------------+
5 Table 12:
Table 12--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 |
+-------------------------------------------------------+
6 Table 13:
Table 13--Header <cstdlib> synopsis
+-----------------------------+
| Type Name(s) |
+-----------------------------+
|Functions: getenv system |
+-----------------------------+
7 The contents are the same as the Standard C library, with the follow
ing changes:
8 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.