libcwd: The C++ Debugging Support Library - Reference Manual
Author: Carlo Wood
Description: C++ debugging support library with ostream debug output
Keywords: libcwd, debug output, debug facility, debug channel, object orientation, OO, C++, nested debug output, ostream, memory allocation, debugging, source file and line number

Main Page Reference Manual Namespace List Compound List Namespace Members Compound Members File Members

# libcwd Namespace Reference

namespace for libcwd. More...

## Namespaces
namespace | channels

| The default DEBUGCHANNELS namespace.
## Classes
class | buf2str
| Print a (`char`) buffer with a given size to a debug ostream, escaping non-printable characters. More...
class | char2str
| Print a `char` to a debug ostream, escaping non-printable characters as needed. More...
class | alloc_ct
| An object of type alloc_ct contains information about one allocated memory block. More...
class | channel_ct
| This object represents a debug channel, it has a fixed label. A debug channel can be viewed upon as a single bit: on or off. More...
class | debug_ct
| The Debug Object class, this object represents one output device (`ostream`). More...
class | debug_string_ct
| A string class used for the debug output margin and marker.This type is used for the public attributes debug_ct::margin and debug_ct::marker of the debug object class. More...
class | marker_ct
| A memory allocation marker. More...
class | object_file_ct
| An object representing the main executable or a shared library. More...
class | rcfile_ct
| This object represents a runtime configuration file. More...
class | type_info_ct
| Class that holds type information for debugging purposes. Returned by type_info_of(). More...
interface | cwprint
| Print an object to a debug stream without needing an operator<<. More...
interface | cwprint_using
| Print an object to an ostream using an arbitrary method of that object. More...
## Typedefs
typedef unsigned short int | alloc_format_t
| The type used for the formatting flags of an alloc_filter_ct object.
typedef unsigned int | control_flag_t
## Enumerations
enum | continued_cf_nt { continued_cf }
| continued_cf has its own type for overloading purposes. More...
enum | memblk_types_nt { memblk_type_new, memblk_type_deleted, memblk_type_new_array, memblk_type_deleted_array, memblk_type_malloc, memblk_type_realloc, memblk_type_freed, memblk_type_external, memblk_type_posix_memalign, memblk_type_memalign, memblk_type_valloc }
| A flag indicating the type of allocation. More...
## Functions
void | core_dump (void)
| Dump core of current thread.
channel_ct * | find_channel (char const *label)
| Find debug channel with label label.
void | list_channels_on (debug_ct &debug_object)
| List all debug channels to a given debug object.
std::ostream & | operator<< (std::ostream &os, memblk_types_nt memblk_type)
| Allow writing a `memblk_types_nt` directly to an ostream.
bool | test_delete (void const *void_ptr)
| Test if a pointer points to the start of an allocated memory block.
size_t | mem_size (void)
| Returns the total number of allocated bytes.
unsigned long | mem_blocks (void)
| Returns the total number of allocated memory blocks.
std::ostream & | operator<< (std::ostream &o, malloc_report_nt)
| Allow writing of enum malloc_report_nt to an ostream.
unsigned long | list_allocations_on (debug_ct &debug_object)
| List all current allocations to a given debug object.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.
unsigned long | list_allocations_on (debug_ct &debug_object, alloc_filter_ct const &filter)
| List all current allocations to a given debug object using a specified format.With CWDEBUG_ALLOC set to 1, it is possible to write the overview of allocated memory to a Debug Object.
void | make_invisible (void const *void_ptr)
| Make allocation pointed to by ptr invisible.The allocation pointed to by ptr is made invisible; it won't show up anymore in the overview of allocated memory.
void | make_all_allocations_invisible_except (void const *ptr)
| Make all current allocations invisible except the given pointer.All allocations, except the given pointer, are made invisible; they won't show up anymore in the overview of allocated memory.
alloc_ct const * | find_alloc (void const *ptr)
| Find information about a memory allocation.Given a pointer, which points to the start of or inside an allocated memory block, it is possible to find information about this memory block using the libcwd function `find_alloc`.
void | read_rcfile (void)
| Calls libcwd::rcfile.read().
control_flag_t | cond_nonewline_cf (bool cond)
| Returns nonewline_cf when cond is true.
control_flag_t | cond_noprefix_cf (bool cond)
| Returns noprefix_cf when cond is true.
control_flag_t | cond_nolabel_cf (bool cond)
| Returns nolabel_cf when cond is true.
control_flag_t | cond_error_cf (bool err)
| Returns error_cf when cond is true.
void | demangle_type (char const *input, std::string &output)
| Demangle mangled type name `input` and write the result to string `output`.
void | demangle_symbol (char const *input, std::string &output)
| Demangle mangled symbol name `input` and write the result to string `output`.
template<typename T >
type_info_ct const & | type_info_of (void)
| Get type information of a given class or type.
template<typename T >
type_info_ct const & | type_info_of (T const &)
| Get type information of a given class instance.
## Variables
debug_ct | libcw_do
| The default debug object.
control_flag_t const | nonewline_cf
| Omit the default new line at the end.
control_flag_t const | noprefix_cf
| Omit margin, label, marker and indentation.
control_flag_t const | nolabel_cf
| Omit label, marker and indentation.
control_flag_t const | blank_margin_cf
| Replace margin by white space.
control_flag_t const | blank_label_cf
| Replace label by white space.
control_flag_t const | blank_marker_cf
| Replace marker by white space.
control_flag_t const | cerr_cf
| Force output to be written to cerr.
control_flag_t const | flush_cf
| Flush ostream after writing this output.
control_flag_t const | wait_cf
| If interactive, wait till return is pressed.
control_flag_t const | error_cf
| Append error string according to errno.
unsigned short const | max_label_len_c
| The maximum number of characters that are allowed in a debug channel label.
int const | builtin_return_address_offset
| Offset to __builtin_return_address() needed to get the correct line number from location_ct.

## Detailed Description

namespace for libcwd.

The d in libcwd stands for Debugging. The cw stand for the initials of the designer/developer of this life-span project.

This namespace contains all user accessible classes, functions and variables.
Things defined in this namespace belong to the libcwd API and will be supported through-out version 1.x.

## Enumeration Type Documentation

enum libcwd::memblk_types_nt

A flag indicating the type of allocation.

This is returned by alloc_ct::memblk_type. The flags `memblk_type_marker` and `memblk_type_deleted_marker` only exist when libcwd was configured with --enable-marker (CWDEBUG_MARKER).

See also:
  alloc_ct

Enumerator:

  memblk_type_new | Allocated with `operator new`
  memblk_type_deleted | Deleted with `operator delete`
  memblk_type_new_array | Allocated with `operator new []`
  memblk_type_deleted_array | Deleted with `operator delete []`
  memblk_type_malloc | Allocated with `calloc()` or `malloc()`
  memblk_type_realloc | Reallocated with `realloc()`
  memblk_type_freed | Freed with `free()`
  memblk_type_external | Externally allocated with `malloc()` (no magic numbers!).
  memblk_type_posix_memalign | Allocated with `posix_memalign()`
  memblk_type_memalign | Allocated with `memalign()`
  memblk_type_valloc | Allocated with `valloc()`

## Function Documentation

std::ostream & libcwd::operator<< | ( | std::ostream & | os,
|  | memblk_types_nt | memblk_type |
| ) |  |  |

Allow writing a `memblk_types_nt` directly to an ostream.

Writes the name of the `memblk_types_nt` memblk_type to `ostream` os.

void libcwd::read_rcfile | ( | void |  | ) | `[inline]`

Calls libcwd::rcfile.read().

See also:
  group_rcfile

References libcwd::rcfile_ct::read().

## Variable Documentation

int const libcwd::builtin_return_address_offset

Offset to __builtin_return_address() needed to get the correct line number from location_ct.

Example

       libcwd::location_ct loc((char*)__builtin_return_address(0) + libcwd::builtin_return_address_offset);

Referenced by libcwd::debug_ct::set_ostream().

debug_ct libcwd::libcw_do

The default debug object.

The debug object that is used by default by Dout and DoutFatal, the only debug object used by libcwd itself.

See also:
  Custom Debug Objects