Menu
▾
▴
[libcw-cvs] [CVS] Module src
|
From: Carlo W. <li...@us...> - 2001-12-06 06:01:30
|
CVSROOT : /cvsroot/libcw
Module : src
Branch tags: branch-threading
Commit time: 2001-11-06 06:01:27 UTC
Modified files:
Tag: branch-threading
libcwd/bfd.cc libcwd/debug.cc libcwd/debugmalloc.cc
libcwd/demangle.cc libcwd/demangle3.cc libcwd/elf32.cc
libcwd/type_info.cc libcwd/documentation/alloc_intro.dox
libcwd/documentation/allocated_memory_overview.dox
libcwd/documentation/custom-debug.h.dox
libcwd/documentation/custom_do.dox
libcwd/documentation/deallocation_pointer_validation.dox
libcwd/documentation/debug_channels.dox
libcwd/documentation/doxygen.config
libcwd/documentation/html.header
libcwd/documentation/location.dox libcwd/documentation/magic.dox
libcwd/documentation/mainpage.dox
libcwd/documentation/memory_leak_checking.dox
libcwd/documentation/modules.dox libcwd/documentation/nested.dox
libcwd/documentation/preparation.dox
libcwd/include/libcw/buf2str.h libcwd/include/libcw/char2str.h
libcwd/include/libcw/class_alloc.h
libcwd/include/libcw/class_channel.h
libcwd/include/libcw/class_debug.h
libcwd/include/libcw/class_debug_string.h
libcwd/include/libcw/class_location.h
libcwd/include/libcw/control_flag.h
libcwd/include/libcw/cwprint.h libcwd/include/libcw/debug.h
libcwd/include/libcw/debug_config.ho.in
libcwd/include/libcw/debugmalloc.h
libcwd/include/libcw/enum_memblk_types.h
libcwd/include/libcw/macro_AllocTag.h
libcwd/include/libcw/macro_ForAllDebugChannels.h
libcwd/include/libcw/macro_ForAllDebugObjects.h
libcwd/include/libcw/pc_mangled_function_name.h
libcwd/include/libcw/type_info.h libcwd/utils/exec_prog.cc
Added files:
Tag: branch-threading
libcwd/documentation/control_flags.dox
libcwd/documentation/debug_object.dox
libcwd/documentation/destination.dox
libcwd/documentation/fatal_output.dox
libcwd/documentation/finding.dox
libcwd/documentation/formatting.dox
libcwd/documentation/invisible.dox
libcwd/documentation/locations.dox
libcwd/documentation/reference.dox
libcwd/documentation/special.dox
libcwd/documentation/symbols_intro.dox
libcwd/documentation/type_info.dox
libcwd/documentation/writing_intro.dox libcwd/include/cwd_debug.h
Removed files:
Tag: branch-threading
libcwd/include/debug.h
Log message:
Work in progress (mostly on the documentation).
Moved include/debug.h to include/cwd_debug.h because
doxygen doesn't understand what a directory is.
---------------------- diff included ----------------------
Index: src/libcwd/bfd.cc
diff -u src/libcwd/bfd.cc:1.85.2.31 src/libcwd/bfd.cc:1.85.2.32
--- src/libcwd/bfd.cc:1.85.2.31 Sat Dec 1 17:01:30 2001
+++ src/libcwd/bfd.cc Wed Dec 5 22:01:14 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.31 2001/12/02 01:01:30 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/bfd.cc,v 1.85.2.32 2001/12/06 06:01:14 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -45,7 +45,7 @@
#endif
#include <cstdio> // Needed for vsnprintf.
#include <algorithm>
-#include "debug.h"
+#include "cwd_debug.h"
#include "ios_base_Init.h"
#ifdef CWDEBUG_DLOPEN_DEFINED
#undef dlopen
@@ -1098,7 +1098,7 @@
} // namespace cwbfd
- /** \addtogroup chapter_locations */
+ /** \addtogroup group_locations */
/** \{ */
char const* const unknown_function_c = "<unknown function>";
@@ -1124,7 +1124,7 @@
return symbol->get_symbol()->name;
}
- /** \} */ // End of group 'chapter_locations'.
+ /** \} */ // End of group 'group_locations'.
struct bfd_location_ct : public location_ct {
friend _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, bfd_location_ct const& data);
@@ -1385,7 +1385,7 @@
* Write the contents of a location_ct object to an ostream in
* the form source-%file:line-number, or writes "<unknown location>"
* when the location is unknown.
- * \ingroup chapter_locations
+ * \ingroup group_locations
*/
std::ostream& operator<<(std::ostream& os, location_ct const& location)
{
Index: src/libcwd/debug.cc
diff -u src/libcwd/debug.cc:1.46.2.39 src/libcwd/debug.cc:1.46.2.40
--- src/libcwd/debug.cc:1.46.2.39 Sat Dec 1 17:01:30 2001
+++ src/libcwd/debug.cc Wed Dec 5 22:01:15 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.39 2001/12/02 01:01:30 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debug.cc,v 1.46.2.40 2001/12/06 06:01:15 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -19,7 +19,7 @@
#include <sys/resource.h> // Needed for setrlimit()
#include <algorithm>
#include <new>
-#include "debug.h"
+#include "cwd_debug.h"
#include <libcw/strerrno.h>
#include "private_debug_stack.inl"
@@ -149,7 +149,7 @@
* \brief The default %debug object.
*
* The %debug object that is used by default by Dout and DoutFatal, the only %debug object used by libcwd itself.
- * \sa \ref custom_do
+ * \sa \ref chapter_custom_do
*/
debug_ct libcw_do;
@@ -162,7 +162,9 @@
namespace channels {
namespace dc {
- /** \addtogroup group_default_dc Pre-Defined Debug Channels
+ /**
+ * \addtogroup group_default_dc Predefined Debug Channels
+ * \ingroup chapter_debug_channels
*
* These are the default %debug %channels pre-defined in libcwd.
*/
@@ -438,6 +440,12 @@
static char WST_dummy_laf[sizeof(laf_ct)] __attribute__((__aligned__));
}
+ /**
+ * \fn void core_dump(void)
+ * \ingroup group_special
+ *
+ * \brief Dump core of current thread.
+ */
void core_dump(void)
{
#ifdef LIBCWD_THREAD_SAFE
@@ -969,6 +977,9 @@
}
/**
+ * \fn channel_ct* find_channel(char const* label)
+ * \ingroup group_special
+ *
* \brief Find %debug channel with label \a label.
*
* \return A pointer to the %debug channel object whose name starts with \a label.
@@ -990,7 +1001,9 @@
return tmp;
}
- /** \fn void list_channels_on(debug_ct const& debug_object)
+ /**
+ * \fn void list_channels_on(debug_ct const& debug_object)
+ * \ingroup group_special
*
* \brief List all %debug %channels to a given %debug object.
*
Index: src/libcwd/debugmalloc.cc
diff -u src/libcwd/debugmalloc.cc:1.61.2.45 src/libcwd/debugmalloc.cc:1.61.2.46
--- src/libcwd/debugmalloc.cc:1.61.2.45 Sat Dec 1 17:01:30 2001
+++ src/libcwd/debugmalloc.cc Wed Dec 5 22:01:15 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.45 2001/12/02 01:01:30 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/debugmalloc.cc,v 1.61.2.46 2001/12/06 06:01:15 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -152,7 +152,7 @@
#endif // LIBCWD_THREAD_SAFE
#include <iostream>
#include <iomanip>
-#include "debug.h"
+#include "cwd_debug.h"
#include "ios_base_Init.h"
#include <libcw/cwprint.h>
@@ -1505,6 +1505,16 @@
// 'Accessor' functions
//
+/**
+ * \brief Test if a pointer points to the start of an allocated memory block.
+ * \ingroup book_allocations
+ *
+ * \returns \c true when \a ptr does \em not point to the start of an allocated memory block.
+ * No checks are performed on the type of allocator that was used: that is done when
+ * the memory block is actually deleted, see \ref chapter_validation.
+ *
+ * Unlike \ref find_alloc, \c test_delete also works for \ref group_invisible "invisible" memory blocks.
+ */
bool test_delete(void const* ptr)
{
ACQUIRE_READ_LOCK
@@ -1519,6 +1529,10 @@
return res;
}
+/**
+ * \brief Returns the total number of allocated bytes.
+ * \ingroup book_allocations
+ */
size_t mem_size(void)
{
ACQUIRE_READ_LOCK
@@ -1527,6 +1541,10 @@
return memsize;
}
+/**
+ * \brief Returns the total number of allocated memory blocks.
+ * \ingroup book_allocations
+ */
unsigned long mem_blocks(void)
{
ACQUIRE_READ_LOCK
@@ -1535,6 +1553,12 @@
return memblks;
}
+/**
+ * \brief Allow writing of enum malloc_report_nt to an ostream.
+ * \ingroup chapter_overview
+ *
+ * \sa \ref malloc_report
+ */
std::ostream& operator<<(std::ostream& o, malloc_report_nt)
{
ACQUIRE_READ_LOCK
@@ -1545,9 +1569,9 @@
return o;
}
-/** \fn void list_allocations_on(debug_ct& debug_object)
- *
+/**
* \brief List all current allocations to a given %debug object.
+ * \ingroup chapter_overview
*
* With both, \link enable_libcwd_debugm DEBUGMALLOC \endlink and
* \link enable_libcwd_debug DEBUGDEBUG \endlink defined, it is possible
@@ -1561,8 +1585,6 @@
*
* which would print on \link libcw::debug::libcw_do libcw_do \endlink using
* \ref chapter_debug_channels "debug channel" \link libcw::debug::dc::malloc dc::malloc \endlink.
- *
- * \sa \ref chapter_overview
*/
void list_allocations_on(debug_ct& debug_object)
{
@@ -1603,6 +1625,22 @@
// 'Manipulator' functions
//
+/**
+ * \brief Make allocation pointed to by \a ptr invisible.
+ * \ingroup group_invisible
+ *
+ * The allocation pointed to by \a ptr is made invisible; it won't show up
+ * anymore in the \ref chapter_overview "overview of allocated memory".
+ *
+ * \sa \ref group_invisible
+ * \sa \ref chapter_overview
+ *
+ * <b>Example:</b>
+ *
+ * \code
+ * Debug( make_invisible(p) );
+ * \endcode
+ */
void make_invisible(void const* ptr)
{
LIBCWD_TSD_DECLARATION
@@ -1625,6 +1663,24 @@
__libcwd_tsd.internal = 0;
}
+/**
+ * \brief Make all current allocations invisible except the given pointer.
+ * \ingroup group_invisible
+ *
+ * All allocations, except the given pointer, are made invisible; they won't show up
+ * anymore in the \ref chapter_overview "overview of allocated memory".
+ *
+ * If you want to make \em all allocations invisible, just pass \c NULL as parameter.
+ *
+ * \sa \ref group_invisible
+ * \sa \ref chapter_overview
+ *
+ * <b>Example:</b>
+ *
+ * \code
+ * Debug( make_all_allocations_invisible_except(NULL) );
+ * \endcode
+ */
void make_all_allocations_invisible_except(void const* ptr)
{
LIBCWD_TSD_DECLARATION
@@ -1802,6 +1858,33 @@
}
#endif // DEBUGMARKER
+/**
+ * \brief Find information about a memory allocation.
+ * \ingroup group_finding
+ *
+ * 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
+ * \c find_alloc.
+ *
+ * \returns a const pointer to an object of class alloc_ct.
+ *
+ * \sa \ref test_delete()
+ *
+ * <b>Example:</b>
+ *
+ * \code
+ * char* buf = new char [40];
+ * AllocTag(buf, "A buffer");
+ * libcw::debug::alloc_ct const* alloc = libcw::debug::find_alloc(&buf[10]);
+ * std::cout << '"' << alloc->description() << "\" is " << alloc->size() << " bytes.\n";
+ * \endcode
+ *
+ * gives as output,
+ *
+ * \exampleoutput <PRE>
+ * "A buffer" is 40 bytes.</PRE>
+ * \endexampleoutput
+ */
alloc_ct const* find_alloc(void const* ptr)
{
#ifdef DEBUGDEBUGMALLOC
Index: src/libcwd/demangle.cc
diff -u src/libcwd/demangle.cc:1.20.2.9 src/libcwd/demangle.cc:1.20.2.10
--- src/libcwd/demangle.cc:1.20.2.9 Sat Oct 20 20:14:01 2001
+++ src/libcwd/demangle.cc Wed Dec 5 22:01:15 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle.cc,v 1.20.2.9 2001/10/21 03:14:01 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle.cc,v 1.20.2.10 2001/12/06 06:01:15 libcw Exp $
//
// Copyright (C) 2000 - 2001, by
//
@@ -32,7 +32,7 @@
#if __GXX_ABI_VERSION == 0
#include <cctype>
-#include "debug.h"
+#include "cwd_debug.h"
#include <libcw/demangle.h>
#ifdef HAVE_LIMITS
Index: src/libcwd/demangle3.cc
diff -u src/libcwd/demangle3.cc:1.8.2.18 src/libcwd/demangle3.cc:1.8.2.19
--- src/libcwd/demangle3.cc:1.8.2.18 Sat Dec 1 17:01:31 2001
+++ src/libcwd/demangle3.cc Wed Dec 5 22:01:15 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.18 2001/12/02 01:01:31 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/demangle3.cc,v 1.8.2.19 2001/12/06 06:01:15 libcw Exp $
//
// Copyright (C) 2001, by
//
@@ -12,8 +12,8 @@
//
/*!
-\addtogroup group_demangle demangle_type() And demangle_symbol()
-\ingroup chapter_type_info
+\addtogroup group_demangle demangle_type() and demangle_symbol()
+\ingroup group_type_info
Libcwd comes with its own demangler functions.
@@ -41,7 +41,7 @@
#undef CPPFILTCOMPATIBLE
#include "sys.h"
-#include "debug.h"
+#include "cwd_debug.h"
#include <libcw/demangle.h>
#include <libcw/private_assert.h>
Index: src/libcwd/documentation/alloc_intro.dox
diff -u src/libcwd/documentation/alloc_intro.dox:1.1.2.1 src/libcwd/documentation/alloc_intro.dox:1.1.2.2
--- src/libcwd/documentation/alloc_intro.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/alloc_intro.dox Wed Dec 5 22:01:16 2001
@@ -1,6 +1,10 @@
/*!
-
-\addtogroup chapter_allocations_intro
+\defgroup book_allocations_intro Memory Allocation Debug Support: Introduction
+\ingroup book_allocations
+*/
+/*!
+\page page_allocations_intro
+\ingroup book_allocations_intro
Unless \link enable_libcwd_alloc --disable-libcwd-alloc \endlink was specified during configuration then
the following memory allocation and de-allocation debugging features are provided by libcwd:
Index: src/libcwd/documentation/allocated_memory_overview.dox
diff -u src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.1 src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.2
--- src/libcwd/documentation/allocated_memory_overview.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/allocated_memory_overview.dox Wed Dec 5 22:01:16 2001
@@ -1,6 +1,10 @@
/*!
-
-\addtogroup chapter_overview
+\defgroup chapter_overview Overview Of Allocated Memory
+\ingroup book_allocations
+*/
+/*!
+\page page_overview
+\ingroup chapter_overview
An example output, using libcw-0.2.5, is given below.
Please follow the links to get a short explanation.
Index: src/libcwd/documentation/control_flags.dox
diff -u /dev/null src/libcwd/documentation/control_flags.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:27 2001
+++ src/libcwd/documentation/control_flags.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,8 @@
+/*!
+\addtogroup group_control_flags Control Flags
+\ingroup book_writing
+*/
+/*!
+\page page_control_flags
+\ingroup group_control_flags
+*/
Index: src/libcwd/documentation/custom-debug.h.dox
diff -u src/libcwd/documentation/custom-debug.h.dox:1.1.2.3 src/libcwd/documentation/custom-debug.h.dox:1.1.2.4
--- src/libcwd/documentation/custom-debug.h.dox:1.1.2.3 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/custom-debug.h.dox Wed Dec 5 22:01:16 2001
@@ -2,8 +2,12 @@
#define debug somethingelse
/*!
-
-\defgroup custom_debug_h The Custom debug.h file
+\defgroup chapter_custom_debug_h The Custom debug.h File
+\ingroup book_start
+*/
+/*!
+\page page_custom_debug_h
+\ingroup chapter_custom_debug_h
\section debug_channels_and_namespace Debug channels and namespace
Index: src/libcwd/documentation/custom_do.dox
diff -u src/libcwd/documentation/custom_do.dox:1.1.2.2 src/libcwd/documentation/custom_do.dox:1.1.2.3
--- src/libcwd/documentation/custom_do.dox:1.1.2.2 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/custom_do.dox Wed Dec 5 22:01:16 2001
@@ -1,14 +1,18 @@
/*!
+\defgroup chapter_custom_do Custom Debug Objects
+\ingroup group_destination
+*/
+/*!
+\page page_custom_do
+\ingroup chapter_custom_do
-\page custom_do Custom Debug Objects
-
Each %debug object is associated with one ostream.
The default %debug output macros Dout and DoutFatal use the \em default debug object libcw::debug::libcw_do.
Other %debug objects may be created as global objects;
it is convenient to define new macros for each (custom) %debug object using the generic macros
-\link libcw::debug::LibcwDout LibcwDout \endlink and \link libcw::debug::LibcwDoutFatal LibcwDoutFatal \endlink.
+\ref LibcwDout and \ref LibcwDoutFatal.
-For example, add something like the following to your own \link custom_debug_h "debug.h" \endlink file:
+For example, add something like the following to your own \link chapter_custom_debug_h "debug.h" \endlink file:
\code
#ifdef CWDEBUG
Index: src/libcwd/documentation/deallocation_pointer_validation.dox
diff -u src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.2 src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.3
--- src/libcwd/documentation/deallocation_pointer_validation.dox:1.1.2.2 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/deallocation_pointer_validation.dox Wed Dec 5 22:01:16 2001
@@ -1,7 +1,11 @@
/*!
+\defgroup chapter_validation De-Allocation Pointer Validation
+\ingroup book_allocations
+*/
+/*!
+\page page_validation
+\ingroup chapter_validation
-\addtogroup chapter_validation
-
A pointer passed to a de-allocation (or re-allocation) function is checked to be valid;
it should be previously returned by a corresponding (re-)allocation function and not
have been de-allocated before.
@@ -40,7 +44,7 @@
Note: When libcwd was configured with \link enable_libcwd_magic --disable-libcwd-magic \endlink
then the check whether or not the de-allocated memory block was allocated with the corresponding
-allocation function is \em not performed when the memory block is \ref chapter_invisible "invisible".
+allocation function is \em not performed when the memory block is \ref group_invisible "invisible".
The reason for this is that invisible memory blocks are simply not stored in the internal data structure:
No information is known about them.
Index: src/libcwd/documentation/debug_channels.dox
diff -u src/libcwd/documentation/debug_channels.dox:1.1.2.1 src/libcwd/documentation/debug_channels.dox:1.1.2.2
--- src/libcwd/documentation/debug_channels.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/debug_channels.dox Wed Dec 5 22:01:16 2001
@@ -1,6 +1,12 @@
/*!
+\defgroup chapter_debug_channels Controlling The Output Level (Debug Channels)
+\ingroup book_writing
+*/
+/*!
+\page page_debug_channels
+\ingroup chapter_debug_channels
-\addtogroup chapter_debug_channels
+<hr>
Whenever debug output is written, one or more <i>debug channels</i> must be specified.
The debug output is then written to the ostream of the debug object
@@ -29,7 +35,7 @@
be seen as the bit-wise OR operation on the bit-masks that these
channels actually represent.
-\sa chapter_control_flags
+\sa group_control_flags
<b>Example:</b>
Index: src/libcwd/documentation/debug_object.dox
diff -u /dev/null src/libcwd/documentation/debug_object.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/debug_object.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,27 @@
+/*!
+\defgroup chapter_debug_object The Output Device (Debug Object)
+\ingroup book_writing
+*/
+/*!
+\page page_debug_object
+\ingroup chapter_debug_object
+
+<hr>
+
+Libcwd declares a %debug class (\ref libcw::debug::debug_ct "debug_ct") which can be assigned an <code>ostream</code>
+ to which %debug output will be written.
+Such a %debug object can dynamically be turned \link libcw::debug::debug_ct::on on \endlink
+and \link libcw::debug::debug_ct::off off \endlink.
+When the %debug object is turned off, no %debug output is written to its \link group_destination ostream \endlink;
+in fact, the data that otherwise would be written is not even evaluated (see \ref eval_example "example").
+The %debug code can also completely be omitted, by not defining the macro CWDEBUG.
+
+Libcwd defines and uses only one %debug object: \ref libcw::debug::libcw_do "libcw_do" (the _do stands for %Debug Object).
+However, it is possible to \link chapter_custom_do create more \endlink %debug objects which would allow one to write %debug output to
+two or more different output devices at the same time (for instance, the screen and a file).
+
+For each %debug object it is possible to set a margin and a marker string and to set the size of the current indentation.
+The methods used for setting or changing these prefix formatting attributes are listed in \ref group_formatting.
+
+*/
+
Index: src/libcwd/documentation/destination.dox
diff -u /dev/null src/libcwd/documentation/destination.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/destination.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,20 @@
+/*!
+\addtogroup group_destination Setting The Output Destination
+\ingroup book_writing
+*/
+/*!
+\page page_destination
+\ingroup group_destination
+
+<hr><h2>Detailed Description</h2>
+
+Basically, a %debug object (\link libcw::debug::debug_ct debug_ct \endlink) is a pointer to an ostream
+with a few extra attributes added to give it an internal state for \link libcw::debug::debug_ct::on() on \endlink
+(pass output on) and \link libcw::debug::debug_ct::off() off \endlink (don't pass output on)
+as well as some \link group_formatting formatting \endlink information of how to write the
+data that is passed on to its ostream.
+
+The methods of \link libcw::debug::debug_ct debug_ct \endlink given here allow you to set
+or get this ostream (pointer).
+
+*/
Index: src/libcwd/documentation/doxygen.config
diff -u src/libcwd/documentation/doxygen.config:1.1.2.8 src/libcwd/documentation/doxygen.config:1.1.2.9
--- src/libcwd/documentation/doxygen.config:1.1.2.8 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/doxygen.config Wed Dec 5 22:01:16 2001
@@ -7,7 +7,7 @@
PROJECT_NUMBER = "libcwd 0.99.16"
OUTPUT_DIRECTORY =
OUTPUT_LANGUAGE = English
-EXTRACT_ALL = NO
+EXTRACT_ALL = YES
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
HIDE_UNDOC_MEMBERS = YES
@@ -97,7 +97,7 @@
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
-DISABLE_INDEX = NO
+DISABLE_INDEX = YES
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = NO
TREEVIEW_WIDTH = 250
Index: src/libcwd/documentation/fatal_output.dox
diff -u /dev/null src/libcwd/documentation/fatal_output.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/fatal_output.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,45 @@
+/*!
+\defgroup chapter_fatal_output Fatal Debug Output
+\ingroup book_writing
+*/
+/*!
+\page page_fatal_output
+\ingroup chapter_fatal_output
+
+<hr>
+
+Often an application needs to be terminated when a fatal error occurs (whether or not CWDEBUG
+is defined). Libcwd defines for these cases the macro DoutFatal.
+
+This allows you to write
+
+\code
+if (error)
+ DoutFatal(dc::core|error_cf, "An error occurred");
+\endcode
+
+instead of the equivalent
+
+\code
+if (error)
+{
+ Dout(dc::core|error_cf, "An error occurred");
+ std::cerr << "An error occurred" << std::endl;
+ exit(254);
+}
+\endcode
+
+The big difference with Dout is that DoutFatal is not replaced with white space when
+the macro CWDEBUG is not defined.
+
+There are two %debug %channels that can be used together with DoutFatal:
+\link libcw::debug::channels::dc::fatal dc::fatal \endlink and
+\link libcw::debug::channels::dc::core dc::core \endlink.
+The first terminates by calling <CODE>exit(254)</CODE>,
+the second terminates by raising SIGABORT, causing the application to core dump.
+
+\sa \ref group_default_dc
+ \n \ref group_control_flags
+ \n \link chapter_custom_do Defining your own debug objects \endlink
+
+*/
Index: src/libcwd/documentation/finding.dox
diff -u /dev/null src/libcwd/documentation/finding.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/finding.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,9 @@
+/*!
+\addtogroup group_finding Finding (Information About) Memory Allocations
+\ingroup book_allocations
+*/
+/*!
+\page page_finding
+\ingroup group_finding
+*/
+
Index: src/libcwd/documentation/formatting.dox
diff -u /dev/null src/libcwd/documentation/formatting.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/formatting.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,56 @@
+/*!
+\addtogroup group_formatting Format Of The Debug Output
+\ingroup book_writing
+*/
+/*!
+\page page_formatting
+\ingroup group_formatting
+
+<hr><h2>Detailed Description</h2>
+
+All debug output is written in the following format:
+
+<margin> <label> <marker> <indentation> <data> <suffix>
+
+The <margin> field can for instance be used to print the ID of the process or thread
+(useful when writing %debug messages from more than one process or thread to the same ostream device).
+
+The <marker> field can be used to identify regions (for example with a vertical line) depending on the current context.
+
+The <indentation> field consists of spaces and is intended to make %debug output better readable by grouping lines of %debug output
+as an easier alternative than using the marker field for that purpose.
+
+The <label> field exists of the channel label (as passed to the constructor of a \link libcw::debug::channel_ct channel_ct \endlink)
+padded by spaces to make this field constant in width (it is padded to the length of the longest existing channel label),
+followed by the marker, which is by default a colon plus a final space; for example "NOTICE : ".
+
+The <data> field represents the second field of the \ref Dout macro, written to the %debug ostream with the operator<< inserters.
+
+Finally, the <suffix> field is by default a new-line, optionally followed by a flush.
+The %debug control flag error_cf however, causes an error message to be inserted first.
+The suffix field could become for example ": EAGAIN (Try again)\\n".
+
+\sa group_control_flags
+
+<b>Example:</b>
+
+\code
+Debug( libcw_do.margin.assign("*** ", 4) );
+Debug( libcw_do.marker.assign(": | ", 4) );
+Dout(dc::notice, "This line is not indented");
+Debug( libcw_do.set_indent(4) );
+Dout(dc::notice, "This line is indented 4 spaces");
+Debug( libcw_do.inc_indent(2) );
+Dout(dc::notice, "This line is indented 6 spaces");
+\endcode
+
+Outputs
+
+<PRE class="example-output">
+*** NOTICE : | This line is not indented
+*** NOTICE : | This line is indented 4 spaces
+*** NOTICE : | This line is indented 6 spaces
+</PRE>
+
+*/
+
Index: src/libcwd/documentation/html.header
diff -u src/libcwd/documentation/html.header:1.1.2.1 src/libcwd/documentation/html.header:1.1.2.2
--- src/libcwd/documentation/html.header:1.1.2.1 Fri Oct 26 15:58:03 2001
+++ src/libcwd/documentation/html.header Wed Dec 5 22:01:16 2001
@@ -16,10 +16,12 @@
<center>
<a class="qindex" href="index.html">Main Page</a>
+<a class="qindex" href="reference.html">Reference Manual</a>
<a class="qindex" href="namespaces.html">Namespace List</a>
<a class="qindex" href="annotated.html">Compound List</a>
-<a class="qindex" href="files.html">File List</a>
<a class="qindex" href="namespacemembers.html">Namespace Members</a>
+<a class="qindex" href="functions.html">Compound Members</a>
+<a class="qindex" href="globals.html">File Members</a>
</center>
<HR SIZE=1 NOSHADE>
Index: src/libcwd/documentation/invisible.dox
diff -u /dev/null src/libcwd/documentation/invisible.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/invisible.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,20 @@
+/*!
+\addtogroup group_invisible Invisible Allocations
+\ingroup chapter_overview
+*/
+/*!
+\page page_invisible
+\ingroup group_invisible
+
+<hr><h2>Detailed Description</h2>
+
+Allocated memory blocks can be made invisible: They won't show up in
+the \ref chapter_overview "overview of allocated memory" anymore.
+Even more, the corresponding \ref libcw::debug::alloc_ct "alloc_ct" is destroyed:
+\ref libcw::debug::find_alloc "find_alloc" will not find them anymore.
+There is no other effect, \ref libcw::debug::test_delete "test_delete" will still work
+and they still can be deleted in the normal way.
+
+*/
+
+
Index: src/libcwd/documentation/location.dox
diff -u src/libcwd/documentation/location.dox:1.1.2.2 src/libcwd/documentation/location.dox:1.1.2.3
--- src/libcwd/documentation/location.dox:1.1.2.2 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/location.dox Wed Dec 5 22:01:16 2001
@@ -1,9 +1,13 @@
/*!
+\defgroup chapter_alloc_locations Memory Allocation Debugging And Locations
+\ingroup book_start
+*/
+/*!
+\page page_alloc_locations
+\ingroup chapter_alloc_locations
-\addtogroup chapter_alloc_locations Memory allocation debugging and locations
+\section section_The_BFD_library The BFD library
-\par The BFD library
-\n
Libcwd attempts to determine the source file and line number where memory is allocated.
It does this by directly reading the .stabs section of the ELF32 object files.
If you are using an Operating System that isn't ELF then you need to enable the use of libbfd for
@@ -11,30 +15,32 @@
If you don't have an ELF system and you don't have libbfd installed and are not able to install it
yourself (note: you also need libiberty and libdl) then you can disable it
using \link enable_libcwd_location --disable-libcwd-location \endlink.
-There is a seperate page that deals with libcwd and \link chapter_locations location \endlink support.
+There is a seperate page that deals with libcwd and \link group_locations location \endlink support.
This paragraph describes the effect of disabling source file and line number location support in
relation to the memory allocation debugging support.
-\par With location support
-\n
+\section section_With_location_support With location support
+
With \link enable_libcwd_location --enable-libcwd-location \endlink, libcwd
will write the source file and line number information about where memory allocations are done to the
\link chapter_debug_channels debug channels \endlink \link libcw::debug::channels::dc::bfd dc::bfd \endlink.
-<br><br>
+
For example,
+
\exampleoutput <PRE>
MALLOC : operator new (size = 4) = <unfinished>
BFD : 0x804bc9b is at (deb.cc:179)
MALLOC : <continued> 0x8137220</PRE>
\endexampleoutput
+
which means that <CODE>operator new</CODE> was called
at address 0x804bc9b corresponding to line 179 of source file <TT>deb.cc</TT>.
-<br><br>
+
Source file and line number information is also shown in the
\ref chapter_overview "overview of allocated memory" and when a memory block is freed.
+
+\section section_Without_location_support Without location support
-\par Without location support
-\n
Without support the source file and line number information will not be available.
%Debug channel \link libcw::debug::channels::dc::bfd dc::bfd \endlink doesn't exist and
the Allocated memory Overview will lack the source file location in column three.
Index: src/libcwd/documentation/locations.dox
diff -u /dev/null src/libcwd/documentation/locations.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/locations.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,15 @@
+/*!
+\addtogroup group_locations Source-file:Line-number Information
+\ingroup book_symbols
+*/
+/*!
+\page page_locations
+\ingroup group_locations
+
+<hr><h2>Detailed Description</h2>
+
+When libcwd was configured with \ref enable_libcwd_location "--enable-libcwd-location",
+then libcw allows one to easily obtain source-file / line-number information of a given address
+using the class \ref libcw::debug::location_ct "location_ct".
+
+*/
Index: src/libcwd/documentation/magic.dox
diff -u src/libcwd/documentation/magic.dox:1.1.2.1 src/libcwd/documentation/magic.dox:1.1.2.2
--- src/libcwd/documentation/magic.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/magic.dox Wed Dec 5 22:01:16 2001
@@ -1,6 +1,10 @@
/*!
-
-\addtogroup chapter_magic_numbers Overflow/Underflow Protection (Red Zones)
+\defgroup chapter_magic_numbers Overflow/Underflow Protection (Red Zones)
+\ingroup book_allocations
+*/
+/*!
+\page page_magic_numbers
+\ingroup chapter_magic_numbers
Memory corruption bugs are usually very hard to find because they often lead to a program
crash in a source line far from the point of the actual bug.
Index: src/libcwd/documentation/mainpage.dox
diff -u src/libcwd/documentation/mainpage.dox:1.1.2.4 src/libcwd/documentation/mainpage.dox:1.1.2.5
--- src/libcwd/documentation/mainpage.dox:1.1.2.4 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/mainpage.dox Wed Dec 5 22:01:16 2001
@@ -14,7 +14,7 @@
\li \ref downloading
\li \ref preparation
-\li \htmlonly <A href="modules.html">Reference manual</A> \endhtmlonly
+\li \ref reference
\section output_example Example output
Index: src/libcwd/documentation/memory_leak_checking.dox
diff -u src/libcwd/documentation/memory_leak_checking.dox:1.1.2.2 src/libcwd/documentation/memory_leak_checking.dox:1.1.2.3
--- src/libcwd/documentation/memory_leak_checking.dox:1.1.2.2 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/memory_leak_checking.dox Wed Dec 5 22:01:16 2001
@@ -1,6 +1,10 @@
/*!
-
-\addtogroup chapter_markers Memory Allocation Markers: Memory Leak Checking
+\defgroup chapter_markers Memory Allocation Markers: Memory Leak Checking
+\ingroup book_allocations
+*/
+/*!
+\page page_markers
+\ingroup chapter_markers
Libcwd does a weak attempt to support debugging of memory leaks.
I hope to greatly improve this in the future.
Index: src/libcwd/documentation/modules.dox
diff -u src/libcwd/documentation/modules.dox:1.1.2.1 src/libcwd/documentation/modules.dox:1.1.2.2
--- src/libcwd/documentation/modules.dox:1.1.2.1 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/modules.dox Wed Dec 5 22:01:16 2001
@@ -1,46 +1,8 @@
-/** \addtogroup chapter_writing Writing Debug Output */
-/** \{ */
-/** \addtogroup chapter_writing_intro Writing Debug Output: Introduction */
-/** \addtogroup chapter_destination Setting The Output Destination */
-/** \{ */
-/** \addtogroup chapter_debug_object The Output Device (Debug Object) */
-/** \addtogroup custom_do Custom Debug Objects */
-/** \} */
-/** \addtogroup chapter_debug_channels Controlling The Output Level (Debug Channels) */
-/** \{ */
-/** \addtogroup group_default_dc */
-/** \} */
-/** \addtogroup chapter_formatting Format Of The Debug Output */
-/** \addtogroup chapter_control_flags Control Flags */
-/** \addtogroup chapter_fatal_output Fatal Debug Output */
-/** \addtogroup chapter_nesting Nesting Debug Output */
-/** \addtogroup chapter_special Special Functions And Utilities */
-/** \} */
+/** \addtogroup book_writing Writing Debug Output */
-/** \addtogroup chapter_allocations Memory Allocation Debug Support */
-/** \{ */
-/** \addtogroup chapter_allocations_intro Memory Allocation Debug Support: Introduction */
-/** \addtogroup chapter_validation De-Allocation Pointer Validation */
-/** \addtogroup chapter_magic_numbers Overflow/Underflow Protection (Red Zones) */
-/** \addtogroup chapter_annotation Allocation Annotation */
-/** \addtogroup chapter_overview Overview Of Allocated Memory */
-/** \{ */
-/** \addtogroup chapter_invisible */
-/** \} */
-/** \addtogroup chapter_finding Finding (Information About) Memory Allocations */
-/** \addtogroup chapter_markers Memory Allocation Markers: Memory Leak Checking */
-/** \} */
+/** \addtogroup book_allocations Memory Allocation Debug Support */
-/** \addtogroup chapter_symbols Program Symbols Access And Interpretation */
-/** \{ */
-/** \addtogroup chapter_symbols_intro Program Symbols Access And Interpretation: Introduction */
-/** \addtogroup chapter_locations Source File And Line Number Information */
-/** \addtogroup chapter_type_info Getting Type Information Of Types And Symbols */
-/** \} */
+/** \addtogroup book_symbols Program Symbols Access And Interpretation */
-/** \addtogroup chapter_start Configuration, Installation And Getting Started */
-/** \{ */
-/** \addtogroup group_configuration Configuration Options And Macros */
-/** \addtogroup chapter_alloc_locations */
-/** \} */
+/** \addtogroup book_start Configuration, Installation And Getting Started */
Index: src/libcwd/documentation/nested.dox
diff -u src/libcwd/documentation/nested.dox:1.1.2.3 src/libcwd/documentation/nested.dox:1.1.2.4
--- src/libcwd/documentation/nested.dox:1.1.2.3 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/nested.dox Wed Dec 5 22:01:16 2001
@@ -1,10 +1,15 @@
/*!
+\defgroup chapter_nesting Nesting Debug Output
+\ingroup book_writing
+*/
+/*!
+\page page_nesting
+\ingroup chapter_nesting
-\addtogroup chapter_nesting Nesting Debug Output
+\section section_nesting_calling Calling functions inside Dout
-\par Calling functions inside Dout
-\n
Consider the following code:
+
\code
int foobar(void) __attribute__ ((const));
@@ -22,37 +27,46 @@
return foobar();
}
\endcode
+
This code would start a new debug message before the previous debug message is finished.
Libcwd detects this and will output:
+
\exampleoutput <PRE>
NOTICE: Entering foobar()
NOTICE: Leaving foobar()
KERNEL: The value of foobar() = 2, aint that nice?</PRE>
\endexampleoutput
+
Note the indentation and the fact that the printing of the label KERNEL was delayed.
+
+\section using_continued Using continued_cf, dc::continued and dc::finish
-\anchor using_continued
-\par Using continued_cf, dc::continued and dc::finish
-\n
In the previous section <CODE>foobar()</CODE> was a const function: it didn't matter
whether or not it was called for the functionality of the application. But when
it does matter, then one might want to do something like this:
+
\code
Dout( dc::kernel|flush_cf|continued_cf, "Generating tables... " );
generate_tables();
Dout( dc::finish, "done" );
\endcode
+
If generate_tables() would not print debug messages, then the output will look like:
+
\exampleoutput <PRE>
KERNEL: Generating tables... done</PRE>
\endexampleoutput
+
When it does generated debug output, then the <unfinished> and <continued> labels are printed also:
+
\exampleoutput <PRE>
KERNEL: Generating tables... <unfinished>
NOTICE: Inside generate_tables()
KERNEL: <continued> done</PRE>
\endexampleoutput
+
Finally, it is also possible to split a debug line into more then two parts by using the special dc::continued debug channel.
+
\code
Dout( dc::notice|flush_cf|continued_cf, "Generating tables." );
for(int i = 0; i < 8; ++i)
@@ -62,16 +76,21 @@
}
Dout( dc::finish, " done" );
\endcode
+
When generate_table(i) doesn't print debug messages, then the output will look like:
+
\exampleoutput <PRE>
NOTICE: Generating tables......... done</PRE>
\endexampleoutput
+
When it does generate debug output, then each dot would be surrounded by a <continued> .<unfinished> :
+
\exampleoutput <PRE>
NOTICE: Generating tables.<unfinished>
TABLE : Inside generate_table(0)
NOTICE: <continued> .<unfinished></PRE>
\endexampleoutput
+
etc.
*/
Index: src/libcwd/documentation/preparation.dox
diff -u src/libcwd/documentation/preparation.dox:1.1.2.3 src/libcwd/documentation/preparation.dox:1.1.2.4
--- src/libcwd/documentation/preparation.dox:1.1.2.3 Sat Dec 1 17:01:31 2001
+++ src/libcwd/documentation/preparation.dox Wed Dec 5 22:01:16 2001
@@ -32,7 +32,7 @@
\htmlonly «<A HREF="../external/debug.h">download</A>»\endhtmlonly
This %debug.h file is for applications, for more detailed information and for information
-for library developers who want to use libbcwd, please also read \ref custom_debug_h.
+for library developers who want to use libbcwd, please also read \ref chapter_custom_debug_h.
\subsection custom_debug_cc Step 3: Creating the custom source file
Index: src/libcwd/documentation/reference.dox
diff -u /dev/null src/libcwd/documentation/reference.dox:1.1.2.3
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/reference.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,66 @@
+/*!
+
+\page reference Reference Manual: Table Of Contents
+
+<h2>Writing Debug Output</h2>
+<ul>
+ <li>\ref book_writing_intro
+ <li>\ref group_destination
+ <li>\ref chapter_debug_object
+ <ul>
+ <li>\ref chapter_custom_do
+ </ul>
+ <li>\ref chapter_debug_channels
+ <ul>
+ <li>\ref group_default_dc
+ </ul>
+ <li>\ref group_control_flags
+ <li>\ref group_formatting
+ <li>\ref chapter_fatal_output
+ <li>\ref chapter_nesting
+ <li>\ref group_special
+</ul>
+
+<h2>Memory Allocation Debug Support</h2>
+<ul>
+ <li>\ref book_allocations_intro
+ <li>\ref chapter_validation
+ <li>\ref chapter_magic_numbers
+ <li>\ref group_annotation
+ <li>\ref chapter_overview
+ <ul>
+ <li>\ref group_invisible
+ </ul>
+ <li>\ref group_finding
+ <li>\ref chapter_markers
+</ul>
+
+<h2>Program Symbols Access And Interpretation</h2>
+<ul>
+ <li>\ref chapter_symbols_intro
+ <li>\ref group_locations
+ <li>\ref group_type_info
+ <ul>
+ <li>\ref group_demangle
+ </ul>
+</ul>
+
+<h2>Configuration, Installation And Getting Started</h2>
+<ul>
+ <li>\ref chapter_custom_debug_h
+ <li>\ref chapter_alloc_locations
+ <li>\ref group_configuration
+ <ul>
+ <li>\ref enable_libcwd_alloc
+ <li>\ref enable_libcwd_magic
+ <li>\ref enable_libcwd_location
+ <li>\ref enable_libcwd_libbfd
+ <li>\ref enable_libcwd_debug
+ <li>\ref enable_libcwd_debugoutput
+ <li>\ref enable_libcwd_debugm
+ <li>\ref enable_libcwd_marker
+ </ul>
+</ul>
+
+*/
+
Index: src/libcwd/documentation/special.dox
diff -u /dev/null src/libcwd/documentation/special.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/special.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,9 @@
+/*!
+\addtogroup group_special Special Functions And Utilities
+\ingroup book_writing
+*/
+/*!
+\page page_special
+\ingroup group_special
+*/
+
Index: src/libcwd/documentation/symbols_intro.dox
diff -u /dev/null src/libcwd/documentation/symbols_intro.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/symbols_intro.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,12 @@
+/*!
+\addtogroup chapter_symbols_intro Program Symbols Access And Interpretation: Introduction
+\ingroup book_symbols
+*/
+/*!
+\page page_symbols_intro
+\ingroup chapter_symbols_intro
+
+Fix me: add text.
+
+*/
+
Index: src/libcwd/documentation/type_info.dox
diff -u /dev/null src/libcwd/documentation/type_info.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/type_info.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,9 @@
+/*!
+\addtogroup group_type_info Getting Type Information Of Types And Symbols
+\ingroup book_symbols
+*/
+/*!
+\page page_type_info
+\ingroup group_type_info
+*/
+
Index: src/libcwd/documentation/writing_intro.dox
diff -u /dev/null src/libcwd/documentation/writing_intro.dox:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/documentation/writing_intro.dox Wed Dec 5 22:01:16 2001
@@ -0,0 +1,37 @@
+/*!
+\defgroup book_writing_intro Writing Debug Output: Introduction
+\ingroup book_writing
+*/
+/*!
+\page page_writing_into
+\ingroup book_writing_intro
+
+\section section_writing_into_introduction Introduction
+
+Libcwd is an <code>ostream</code> oriented debug output facility.
+The class libcw::debug::debug_ct represents a single <code>ostream</code>.
+
+Libcwd defines and uses only one such object, called a \ref chapter_debug_object "debug object",
+being libcw::debug::libcw_do.
+
+Debug output is written using \ref page_why_macro "macros" (\ref Dout and \ref DoutFatal),
+both of which are defined to use libcw::debug::libcw_do.
+More general macros exist (\ref LibcwDout and \ref LibcwDoutFatal) that allow you
+to use a different (\ref chapter_custom_do "custom") debug object.
+
+Both macros take two arguments, the first argument is used to specify
+\ref chapter_debug_channels "debug channels" and \ref group_control_flags "control flags"
+while the second argument should be a series of objects seperated by <code><<</code>
+that you want to write to the <code>ostream</code>.
+
+For example,
+
+\code
+Dout(dc::notice|blank_label_cf|flush_cf, "Total count: " << count << "; Average: " << average);
+\endcode
+
+In this example <code>dc::notice</code> is one of the \ref group_default_dc "pre-defined" debug channels.
+Debug channels are intended to control to amount of output of your application by switching
+the channels on or off.
+
+*/
Index: src/libcwd/elf32.cc
diff -u src/libcwd/elf32.cc:1.20.2.20 src/libcwd/elf32.cc:1.20.2.21
--- src/libcwd/elf32.cc:1.20.2.20 Sat Oct 20 20:14:01 2001
+++ src/libcwd/elf32.cc Wed Dec 5 22:01:15 2001
@@ -1,4 +1,4 @@
-// $Header: /cvsroot/l/li/libcw/src/libcwd/elf32.cc,v 1.20.2.20 2001/10/21 03:14:01 libcw Exp $
+// $Header: /cvsroot/l/li/libcw/src/libcwd/elf32.cc,v 1.20.2.21 2001/12/06 06:01:15 libcw Exp $
//
// Copyright (C) 2001, by
//
@@ -30,7 +30,7 @@
#include <set>
#include <map>
#include <vector>
-#include "debug.h"
+#include "cwd_debug.h"
#include "elf32.h"
#include <libcw/private_assert.h>
Index: src/libcwd/include/cwd_debug.h
diff -u /dev/null src/libcwd/include/cwd_debug.h:1.1.2.1
--- /dev/null Wed Dec 5 22:01:28 2001
+++ src/libcwd/include/cwd_debug.h Wed Dec 5 22:01:16 2001
@@ -0,0 +1,244 @@
+// Generated automatically from sys.ho.in by configure.
+// $Header: /cvsroot/l/li/libcw/src/libcwd/include/Attic/cwd_debug.h,v 1.1.2.1 2001/12/06 06:01:16 libcw Exp $
+//
+// Copyright (C) 2001, by
+//
+// Carlo Wood, Run on IRC <ca...@al...>
+// RSA-1024 0x624ACAD5 1997-01-26 Sign & Encrypt
+// Fingerprint16 = 32 EC A7 B6 AC DB 65 A6 F6 F6 55 DD 1C DC FF 61
+//
+// This file may be distributed under the terms of the Q Public License
+// version 1.0 as appearing in the file LICENSE.QPL included in the
+// packaging of this file.
+//
+
+#ifndef DEBUG_H
+#define DEBUG_H
+
+#include <libcw/debug.h>
+#include <libcw/private_internal_string.h>
+#include <iostream>
+
+extern "C" size_t strlen(const char *s) throw();
+#ifdef DEBUGDEBUG
+extern "C" ssize_t write(int fd, const void *buf, size_t count) throw();
+#endif
+
+namespace libcw {
+ namespace debug {
+
+namespace _private_ {
+
+extern void no_alloc_print_int_to(std::ostream* os, unsigned long val, bool hexadecimal);
+
+//----------------------------------------------------------------------------------------------
+// struct no_alloc_ostream_ct
+//
+// A fake ostream that is used in DoutInternal and LIBCWD_Dout in order to write
+// to an ostream without allocating memory through std::__default_allocator<true, 0>
+// which could lead to a dead lock.
+
+struct no_alloc_ostream_ct {
+ std::ostream& M_os;
+ no_alloc_ostream_ct(std::ostream& os) : M_os(os) { }
+};
+
+} // namespace _private_
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, char const* data)
+{
+ os.M_os.write(data, strlen(data));
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, libcw::debug::_private_::internal_string const& data)
+{
+ os.M_os.write(data.data(), data.size());
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, char data)
+{
+ os.M_os.put(data);
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, int data)
+{
+ _private_::no_alloc_print_int_to(&os.M_os, data, false);
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, unsigned int data)
+{
+ _private_::no_alloc_print_int_to(&os.M_os, data, false);
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, long data)
+{
+ _private_:: no_alloc_print_int_to(&os.M_os, data, false);
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, unsigned long data)
+{
+ _private_::no_alloc_print_int_to(&os.M_os, data, false);
+ return os;
+}
+
+inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, void const* data)
+{
+ _private_::no_alloc_print_int_to(&os.M_os, reinterpret_cast<unsigned long>(data), true);
+ return os;
+}
+
+#define LIBCWD_Dout( cntrl, data ) \
+ do \
+ { \
+ if (libcw_do._off < 0) \
+ { \
+ bool on; \
+ { \
+ using namespace channels; \
+ on = (libcw_do|cntrl).on; \
+ } \
+ if (on) \
+ { \
+ libcw_do.start(LIBCWD_TSD); \
+ _private_::no_alloc_ostream_ct no_alloc_ostream(*libcw_do.current_oss); \
+ no_alloc_ostream << data; \
+ libcw_do.finish(LIBCWD_TSD); \
+ } \
+ } \
+ } while(0)
+
+#define LIBCWD_DoutFatal( cntrl, data ) \
+ do \
+ { \
+ { \
+ using namespace dc_namespace; \
+ libcw_do&cntrl; \
+ } \
+ libcw_do.start(LIBCWD_TSD); \
+ _private_::no_alloc_ostream_ct no_alloc_ostream(*libcw_do.current_oss); \
+ no_alloc_ostream << data; \
+ libcw_do.fatal_finish(LIBCWD_TSD); \
+ } while(0)
+
+#ifdef DEBUGDEBUG
+namespace _private_ {
+ static class non_allocating_fake_ostream_using_write_ct { } const raw_write = { };
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, char const* data)
+{
+ write(2, data, strlen(data));
+ return raw_write;
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, void const* data)
+{
+ size_t dat = (size_t)data;
+ write(2, "0x", 2);
+ char c[11];
+ char* p = &c[11];
+ do
+ {
+ int d = (dat % 16);
+ *--p = ((d < 10) ? '0' : ('a' - 10)) + d;
+ dat /= 16;
+ }
+ while(dat > 0);
+ write(2, p, &c[11] - p);
+ return raw_write;
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, bool data)
+{
+ if (data)
+ write(2, "true", 4);
+ else
+ write(2, "false", 5);
+ return raw_write;
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, char data)
+{
+ char c[1];
+ c[0] = data;
+ write(2, c, 1);
+ return raw_write;
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, unsigned long data)
+{
+ char c[11];
+ char* p = &c[11];
+ do
+ {
+ *--p = '0' + (data % 10);
+ data /= 10;
+ }
+ while(data > 0);
+ write(2, p, &c[11] - p);
+ return raw_write;
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, long data)
+{
+ if (data < 0)
+ {
+ write(2, "-", 1);
+ data = -data;
+ }
+ return operator<<(raw_write, (unsigned long)data);
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, int data)
+{
+ return operator<<(raw_write, (long)data);
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, unsigned int data)
+{
+ return operator<<(raw_write, static_cast<unsigned long>(data));
+}
+
+inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, libcw::debug::_private_::internal_string const& data)
+{
+ write(2, data.data(), data.size());
+ return raw_write;
+}
+
+#endif // DEBUGDEBUG
+
+ } // namespace debug
+} // namespace libcw
+
+#ifdef DEBUGDEBUG
+// The difference between DEBUGDEBUG_CERR and FATALDEBUGDEBUG_CERR is that the latter is not suppressed
+// when --disable-libcwd-debug-output is used because a fatal error occured anyway, so this can't
+// disturb the testsuite.
+#define FATALDEBUGDEBUG_CERR(x) \
+ do { \
+ if (1/*::libcw::debug::_private_::WST_ios_base_initialized FIXME: uncomment again*/) { \
+ ::write(2, "DEBUGDEBUG: ", 12); \
+ LIBCWD_TSD_DECLARATION \
+ /* __libcwd_lcwc means library_call write counter. Used to avoid the 'scope of for changed' warning. */ \
+ for (int __libcwd_lcwc = 0; __libcwd_lcwc < __libcwd_tsd.library_call; ++__libcwd_lcwc) \
+ ::write(2, " ", 4); \
+ ::libcw::debug::_private_::raw_write << x << '\n'; \
+ } \
+ } while(0)
+#else // !DEBUGDEBUG
+#define FATALDEBUGDEBUG_CERR(x)
+#endif // !DEBUGDEBUG
+
+#ifdef DEBUGDEBUGOUTPUT
+#define DEBUGDEBUG_CERR(x) FATALDEBUGDEBUG_CERR(x)
+#else // !DEBUGDEBUGOUTPUT
+#define DEBUGDEBUG_CERR(x)
+#endif // !DEBUGDEBUGOUTPUT
+
+#endif // DEBUG_H
Index: src/libcwd/include/debug.h
diff -u src/libcwd/include/debug.h:1.1.2.4 src/libcwd/include/debug.h:removed
--- src/libcwd/include/debug.h:1.1.2.4 Sat Oct 20 19:19:31 2001
+++ src/libcwd/include/debug.h Wed Dec 5 22:01:28 2001
@@ -1,244 +0,0 @@
-// Generated automatically from sys.ho.in by configure.
-// $Header: /cvsroot/l/li/libcw/src/libcwd/include/Attic/debug.h,v 1.1.2.4 2001/10/21 02:19:31 libcw Exp $
-//
-// Copyright (C) 2001, by
-//
-// Carlo Wood, Run on IRC <ca...@al...>
-// RSA-1024 0x624ACAD5 1997-01-26 Sign & Encrypt
-// Fingerprint16 = 32 EC A7 B6 AC DB 65 A6 F6 F6 55 DD 1C DC FF 61
-//
-// This file may be distributed under the terms of the Q Public License
-// version 1.0 as appearing in the file LICENSE.QPL included in the
-// packaging of this file.
-//
-
-#ifndef DEBUG_H
-#define DEBUG_H
-
-#include <libcw/debug.h>
-#include <libcw/private_internal_string.h>
-#include <iostream>
-
-extern "C" size_t strlen(const char *s) throw();
-#ifdef DEBUGDEBUG
-extern "C" ssize_t write(int fd, const void *buf, size_t count) throw();
-#endif
-
-namespace libcw {
- namespace debug {
-
-namespace _private_ {
-
-extern void no_alloc_print_int_to(std::ostream* os, unsigned long val, bool hexadecimal);
-
-//----------------------------------------------------------------------------------------------
-// struct no_alloc_ostream_ct
-//
-// A fake ostream that is used in DoutInternal and LIBCWD_Dout in order to write
-// to an ostream without allocating memory through std::__default_allocator<true, 0>
-// which could lead to a dead lock.
-
-struct no_alloc_ostream_ct {
- std::ostream& M_os;
- no_alloc_ostream_ct(std::ostream& os) : M_os(os) { }
-};
-
-} // namespace _private_
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, char const* data)
-{
- os.M_os.write(data, strlen(data));
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, libcw::debug::_private_::internal_string const& data)
-{
- os.M_os.write(data.data(), data.size());
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, char data)
-{
- os.M_os.put(data);
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, int data)
-{
- _private_::no_alloc_print_int_to(&os.M_os, data, false);
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, unsigned int data)
-{
- _private_::no_alloc_print_int_to(&os.M_os, data, false);
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, long data)
-{
- _private_:: no_alloc_print_int_to(&os.M_os, data, false);
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, unsigned long data)
-{
- _private_::no_alloc_print_int_to(&os.M_os, data, false);
- return os;
-}
-
-inline _private_::no_alloc_ostream_ct& operator<<(_private_::no_alloc_ostream_ct& os, void const* data)
-{
- _private_::no_alloc_print_int_to(&os.M_os, reinterpret_cast<unsigned long>(data), true);
- return os;
-}
-
-#define LIBCWD_Dout( cntrl, data ) \
- do \
- { \
- if (libcw_do._off < 0) \
- { \
- bool on; \
- { \
- using namespace channels; \
- on = (libcw_do|cntrl).on; \
- } \
- if (on) \
- { \
- libcw_do.start(LIBCWD_TSD); \
- _private_::no_alloc_ostream_ct no_alloc_ostream(*libcw_do.current_oss); \
- no_alloc_ostream << data; \
- libcw_do.finish(LIBCWD_TSD); \
- } \
- } \
- } while(0)
-
-#define LIBCWD_DoutFatal( cntrl, data ) \
- do \
- { \
- { \
- using namespace dc_namespace; \
- libcw_do&cntrl; \
- } \
- libcw_do.start(LIBCWD_TSD); \
- _private_::no_alloc_ostream_ct no_alloc_ostream(*libcw_do.current_oss); \
- no_alloc_ostream << data; \
- libcw_do.fatal_finish(LIBCWD_TSD); \
- } while(0)
-
-#ifdef DEBUGDEBUG
-namespace _private_ {
- static class non_allocating_fake_ostream_using_write_ct { } const raw_write = { };
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, char const* data)
-{
- write(2, data, strlen(data));
- return raw_write;
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, void const* data)
-{
- size_t dat = (size_t)data;
- write(2, "0x", 2);
- char c[11];
- char* p = &c[11];
- do
- {
- int d = (dat % 16);
- *--p = ((d < 10) ? '0' : ('a' - 10)) + d;
- dat /= 16;
- }
- while(dat > 0);
- write(2, p, &c[11] - p);
- return raw_write;
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, bool data)
-{
- if (data)
- write(2, "true", 4);
- else
- write(2, "false", 5);
- return raw_write;
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, char data)
-{
- char c[1];
- c[0] = data;
- write(2, c, 1);
- return raw_write;
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, unsigned long data)
-{
- char c[11];
- char* p = &c[11];
- do
- {
- *--p = '0' + (data % 10);
- data /= 10;
- }
- while(data > 0);
- write(2, p, &c[11] - p);
- return raw_write;
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, long data)
-{
- if (data < 0)
- {
- write(2, "-", 1);
- data = -data;
- }
- return operator<<(raw_write, (unsigned long)data);
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, int data)
-{
- return operator<<(raw_write, (long)data);
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, unsigned int data)
-{
- return operator<<(raw_write, static_cast<unsigned long>(data));
-}
-
-inline _private_::non_allocating_fake_ostream_using_write_ct const& operator<<(_private_::non_allocating_fake_ostream_using_write_ct const& raw_write, libcw::debug::_private_::internal_string const& data)
-{
- write(2, data.data(), data.size());
- return raw_write;
-}
-
-#endif // DEBUGDEBUG
-
- } // namespace debug
-} // namespace libcw
-
-#ifdef DEBUGDEBUG
-// The difference between DEBUGDEBUG_CERR and FATALDEBUGDEBUG_CERR is that the latter is not suppressed
-// when --disable-libcwd-debug-output is used because a fatal error occured anyway, so this can't
-// disturb the testsuite.
-#define FATALDEBUGDEBUG_CERR(x) \
- do { \
- if (1/*::libcw::debug::_private_::WST_ios_base_initialized FIXME: uncomment again*/) { \
- ::write(2, "DEBUGDEBUG: ", 12); \
- LIBCWD_TSD_DECLARATION \
- /* __libcwd_lcwc means library_call write counter. Used to avoid the 'scope of for changed' warning. */ \
- for (int __libcwd_lcwc = 0; __libcwd_lcwc < __libcwd_tsd.library_call; ++__libcwd_lcwc) \
- ::write(2, " "...
[truncated message content] |
