libcsdbg
Contents
1. Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 5 Usage 17 1 Create a tcpsockbuf object for a peer IP address and TCP port 2 Connect to the peer 3 Append set text data in the buffer 4 Flush the buffer 5 Repeat steps 3 4 until completion 6 Disconnect 7 Repeat steps 2 6 until completion 8 Release the object Step 2 in this list can be inserted anywhere within steps 2 4 you don t need to connect the socket in order to process its buffer it must be connected before you flush the buffer The following is an example of using the tcpsockbuf class using namespace csdbg tracer iface tracer interface if unlikely iface NULL return tcpsockbuf client NULL chain lt string gt peer_info tracer getenv g_peer_env if likely peer_info NULL client new tcpsockbuf else i32 port g_ldp_port if likely peer_info gt size gt 1 port atoi peer_info gt at 1 gt cstr client new tcpsockbuf peer_info gt at 0 gt cstr port x Log a trace to a socket connected to an LDP server at port 4242 x client gt header client gt append r n iface gt trace client pthread_self client gt append r n client gt open client gt flush client gt close 1 5 5 3 Using csdbg sttybuf A csdbg sttybuf object is a buffered output stream used to output LDP Libcsdbg Debug Protocol data protocol headers and trac2. 1 root root 671 Feb 14 13 57 libcsdbg pc To validate that libcsdbg works correctly for your platform all you have to do is to execute the example executables csdbg_step or any of the tutorial executables csdbg_tut The examples utilize most of the library API so they provide best coverage but the third and sixth examples are also jTracer clients and you will need a running server to verify the API The installation directory PREFIX bin of these executables must be in PATH To see exact details about the usage of the examples and the output you should get read the Examples section of the documentation These programs will be dynamically linked with libcsdbg so and with the example DSO libcsdbg_ test so so their installation directories PREFIX lib and PREFIX lib modules libcsdbg must be in the Id path or in the LD_LIBRARY_PATH shell variable You may need to invoke the following line before you run any of the examples export LD_LIBRARY_PATH usr local lib usr local lib modules libcsdbg or in generic export LD_LIBRARY_PATH PREFIX lib SPREFIX lib modules libcsdbg The symbol table of the program is always loaded by libcsdbg The user can select which DSO symbol tables to load and which to discard by declaring the CSDBG_LIBS shell variable as a delimited list of POSIX extended regular expressions The absolute path of each DSO is matched against each regexp If CSDBG_LIBS is not set all linked DSO symbol tables will
3. at csdbg_extra level2 char const unsigned short csdbg_stepl cpp 121 at void csdbg_extra level3 lt csdbg string gt csdbg string amp unsigned int amp csdbg_stepl cpp 116 at csdbg_extra level4 char const unsigned long long volatile void double csdbg_stepl cpp 102 at csdbg_extra dso_main char constx csdbg_stepl cpp 89 at csdbg_extra dso_inner char constx libcsdbg_test cpp 53 1 1 2 Features This is a comprehensive albeit not complete list of libcsdbg features e Create sophisticated exception stack traces with addr2line support e Works with multi thread processes and with multi process programs Create detailed POSIX thread stack traces with addr2line support Full support for Position Independent Code PIC for DSO e Works with generic throwables and user defined exception types e Support for most of the objective code formats elf a out coff ecoff e t c e Support for both 32 and 64 bit systems e Support for both big and little endian CPUs e Compiled tested for x86 x86_64 ARM AVR32 Leon Project libcsdbg exports an extended well documented and reusable library API to provide Easy and minimal code interface transparent library integration Easy library runtime configuration Transparent but configurable loading of symbol tables of any executable DSO or other module Instrumentation algorithms add only minimal overhead and memory footprint e The high level API provid
4. unlikely iface NULL return Log a thread stack trace to a file with a unique trace describing name string nm filebuf unique_id e_ s nm gt append trace filebuf fout nm gt cstr Add a header that describes the trace x fout header fout append r n iface gt trace fout pthread_self fout append r n fout open fout flush fout close 1 5 5 2 Using csdbg tcpsockbuf A csdbg tcpsockbuf object is a buffered output stream than can be used to implement the client side of the LD P Libcsdbg Debug Protocol or a generic TCP IP client socket Nevertheless this class is optimized for LDP and generally for unidirectional protocols If you need to implement a bidirectional protocol you must subclass tcpsockbuf This class is not thread safe the caller must implement thread synchronization A tcpsockbuf object inherits all the csdbg string methods designed for text manipulation append clear set e t c You use these methods to process the buffer data or the csdbg tracer methods to store traces to the buffer Then you may connect the socket to its peer and flush clear the buffer You can re fill and re flush as many times as you wish before you close disconnect the tcpsockbuf Disconnecting closing or shutting down the socket is just the opposite of open connect it doesn t release the object and its buffer so you may re connect it The steps to use a tcpsockbuf object are
5. Added method string trim Fixed Makefile and header includes to reflect the Makefile 5DOPTS build configuration Added Makefile target distclean Added example and tutorial for the trace syntax highlighter Added utility script vt100_colors color sampler for highlighter customization Added dictionary source files for C keywords integral types and file extensions Version 1 21 Class highlighter renamed to parser Added thread names and all supporting infrastructure Added lookup mode to class dictionary Heavily reworked class style Added methods plugin destroy string insert and thread foreach Added method util header and COLOR_TERM support for debug text Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 26 Overview Added macros for the default syntax highlighter colors Added various code optimizations and beautifications Updated all examples to use demonstrate thread names Updated examples to make them more uniform Added Makefile target distclean clean the source tree from all generated files Added scripts vt100_bgcolors and vt100_fgcolors VT100 palette samplers Added parser and trace syntax highlighter documentation Added Makefile DOPTS documentation 1 7 10 Version 1 22 Changed LDP to support multiple messages through a unique session socket e Scripts vt100_fgcolors and vt100_bgcolors fused into vtcolors e Reconfigured the default syntax highlighter e Reworked examples
6. The user of a parser object can register a style for each type of token to create custom syntax highlighters The following is an example of using the predefined libcsdbg syntax highlighter using namespace csdbg tracer iface tracer interface if unlikely iface NULL return try catch exception parser p parser get_default p gt clear iface gt trace p std cerr lt lt x lt lt rin lt lt xp lt lt r n The following snippet shows how the default parser gets initialized as an example on how to clone and customize your own syntax highlighters Create the default parser m_default new parser Ir Equip the default parser with dictionaries for C keywords types and file extensions string path s etc keywords dict util prefix m_default gt add_dictionary keywords path cstr path set s etc types dict util prefix m_default gt add_dictionary types path cstr path set s etc extensions dict util prefix m_default gt add_dictionary extensions path cstr true Create the default fallback style When a highlighter can t determine or create obtain the correct style for a token it uses the fallback m_fallback new style fallback x Add styles for all kinds of trace tokens to the default parser style s m_fallback gt clone s gt set_name delimiter m_default gt add_style s
7. Using the stack trace parser syntax highlighter o o 19 158 Usimg the internal libcsdbg ARP ico a a E ee ee 20 16 Examples and lulonals acoso sra e A A de OR RA 21 LE AMAS coo be hohe a a A eee hed 22 LETRERO TID oee Ga ke A A Se AR Rw eee ee a 22 1 42 VERSION TT x ee a ae we KE OE a a A GS OW Gm a 23 CONTENTS 123 1 7 4 1 2 5 1 7 6 LES 1 7 8 1 7 9 1 7 10 NOTE he a id BADE aa y See a A a a En de a de de o 23 METIDO TIZ e a A ee Me RA A ee a E A a le 24 Ves Lido oc dra ee Swe a A ee 24 VeRO VS eas ee oe ee Gs Swe eG Pode RSP Agee A eG Rak Se ae A a a a 24 TODO WA A A ARA amp A te ak a ai 25 Version T20 ge oh ee heh e dd e done i 25 a TEET eao a Ete alte eR ER we Eh Ro SS 25 MOTION Ue sik p a Mp ee A a es es eek Uk a hm a ee we gee ee A 26 Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen Chapter 1 Overview 1 1 Introduction 1 1 1 Description Project libesdbg is a C exception and generic stack tracer When an exception is thrown caught and handled libcsdbg offers the tools to create process and output the exception stack trace the path the exception has propagated up the call stack unwinding it up to the section were it was handled The traces are fully detailed with demangled function signatures and additional addr2line information the source code file and line that each function was called Libcsdbg will perform flawlessly with single thread and multi thr
8. be detached dispose the node without deleting its data or removed dispose both node and data A chain can be traversed using simple callbacks and method csdbg chain foreach The stack supports shared data multiple stacks can point to the same data but it is not thread safe callers should synchronize thread access This implementation doesn t allow a node with a NULL or a duplicate data pointer A stack can be traversed using simple callbacks and method stack foreach Apart from the legacy push pop functions node data can be accessed using stack offsets Class csdbg symbol_table A symbol_table object can load code from executables or dynamic shared objects with absolute addressing or position independent It supports all the binary formats supported by the libbfd backends on the host or target machine elf coff ecoff e t c To optimize lookups the symbol table as structured in libbfd is parsed the non function symbols are discarded and function symbols are demangled once and stored in simpler data structures A symbol_table can be traversed using simple callbacks and method csdbg symbol_table foreach The access to a symbol_table is not thread safe the caller must implement thread synchronization Class csdbg name_space This class defines the way to group symbol tables of different objective code files executables and DSO libraries into a single object the namespace and perform batch symbol lookups on them Inverse look
9. files from your system make uninstall To clear the source directory from built binaries and all the compiled documentation files this target is not called from buila make distclean As said earlier no autotools support exists for the project but this is under way So currently all you can do is edit Makefile to change some options that may give you a headache The Makefile options you may want to alter are PREFIX Where to install libcsdbg copy changes to include config hpp PLATFORM The target prefix you need to cross compile the package for example mips linux It is used as the prefix for various binaries in the toolchain LPATHS Additional paths to search for DSO IPATHS Additional paths to search for header files DOPTS Define various preprocessor macros such as word size for the target machine achitecture the default is 64 bits the target machine endianity debug or release mode optimizations include or discard modules e t c GOPTS Various g options such as target machine architecture C standard used throughout compilation e t c The Makefile DOPTS variable defines the main build configuration Through this variable you can define which modules you want to include in the library and which features to support The directives in DOPTS are formatted as CSDBG_WITH_feature to add support for a module or feature or CSDBG_WITHOUT_feature to exclude it _REENTRANT Support thread safety CSDBG_WITH_DEBUG I
10. make e GNU binutils at least libbfd so v2 22 and addr2line e UNIX standard tools such as rm mkdir cp In Idconfig e t c Unpack the archive unless you already have done that tar xjpf x86_64 linux dbg libcsdbg 1 24 tar bz2 or tar xjpf x86_64 linux libcsdbg 1 24 tar bz2 Then install it cd x86_64 linux dbg libcsdbg 1 24 sudo sh install or cd x86_64 linux libcsdbg 1 24 sudo sh install If you install as a simple user not root use of sudo is essential if you want to keep the default prefix usr local Installing in another prefix doesn t need root privilege but the dynamic loader configuration file Id so conf will not be updated if sudo is not used Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 8 Overview The install script should flawlessly install libcsdbg library headers and other project files examples e t c using usr local as the prefix If you want to alter the installation prefix edit the Makefile and change PREFIX to a path of your choice For an overview of other install script options and modes of operation use sh install h Project libcsdbg installer Usage install u h install will install its target by default The following options change the default behaviour u Uninstall the package make uninstall h Show this message 1 3 3 Verify installation If all project components are correctly built and installed the directory used as
11. n Arn Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 5 Usage 15 The mandatory protocol headers are for executable absolute path process ID e thread ID e timestamp in microseconds The non mandatory protocol headers are for e exception data e other user and OEM headers The following is an LDP message created by example csdbg_step6 cpp path usr local bin csdbg_step6 pid 3b3 tid 7 9870ca8700 tstamp 4f264e66740f9 at child_1 thread 0x7f9870ca8700 at csdbg_extra pthread_main voidx at csdbg_extra levell char const unsigned char csdbg_step6 cpp 205 at csdbg_extra level2 char const unsigned short csdbg_step6 cpp 187 at void csdbg_extra level3 lt csdbg string gt csdbg string amp unsigned int amp csdbg_step6 cpp 182 at csdbg_extra level4 char const unsigned long long volatile void double csdbg_step6 cpp 169 Project jTracer is a libcsdbg sister project a portable LDP server implemented with Java Each application that uses the libcsdbg LDP API can implement a jTracer client This can be essential for cross platform development with embedded devices and development boards Most often target platforms such as these don t have a screen or other resources to visualize output and data collection during the development and debugging cycles is controlled ata workstation through ethernet or serial ports Instead of cluttering the IDE console or debugg
12. to call the interface tracer object to store it in a csdbg string buffer as in the following example using namespace csdbg tracer iface tracer interface if unlikely iface NULL return try 4 catch exception amp x try string buf iface gt trace buf eaten faist A iface gt unwind As you see in this last example creating a stack trace in this way may throw exceptions that are the caller s respon sibility to handle The call to csdbg tracer unwind is only mandatory when the exception stack trace is ignored in order to dispose that stored trace If you don t properly unwind the simulated stack the stored trace will mess with the next attempt to obtain a stack trace Nevertheless if the trace was actually created a call to unwind doesn t affect the tracer object state at all nothing to dispose so it is not an error to call it once or even more times even when the trace was produced Mind you all calls to csdbg tracer trace even from the sid ostream insertion operator unwind the stack on their own even if they fail to produce a trace due to some error A final point is if you code a function to do the trace creation and output this function must not be instrumented otherwise it will corrupt the exception stack trace Here s an example Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 5 Usage 13 using namespace csdbg void foo exception amp _
13. to make them compatible with the new LDP architecture Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen
14. 22 Feb 14 13 57 filebuf hpp rw r r root root 1899 Feb 14 13 57 name_space hpp rw r r root root 3347 Feb 14 13 57 node hpp rw r r root root 504 Feb 14 13 57 object hpp rw r r root root 2377 Feb 14 13 57 parser hpp rw r r 1 root root 2824 Feb 14 13 57 plugin hpp rw r r 1 root root 5742 Feb 14 13 57 stack hpp rw r r root root 1851 Feb 14 13 57 streambuf hpp rW ir root root 2929 Feb 14 13 57 string hpp rw r r root root 1258 Feb 14 13 57 sttybuf hpp rw r r root root 1999 Feb 14 13 57 style hpp rw r r root root 793 Feb 14 13 57 symbol hpp rw r r root root 1811 Feb 14 13 57 symbol_table hpp rw r r root root 2200 Feb 14 13 57 tcpsockbuf hpp rw Yr r root root 1770 Feb 14 13 57 thread hpp rw r r root root 3214 Feb 14 13 57 tracer hpp rw r r root root 1076 Feb 14 13 57 util hpp usr local lib Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 4 Troubleshooting 9 drwxr xr x 3 root root 4096 Feb 14 13 57 modules drwxr xr x 2 root root 4096 Feb 14 13 57 pkgconfig lrwxrwxrwx 1 root root 31 Feb 14 13 57 libcsdbg so gt usr local lib libcsdbg so 1 24 rwxr xr x 1 root root 229120 Feb 14 13 57 libcsdbg so 1 24 usr local lib modules libcsdbg rwxr xr x 1 root root 32158 Feb 14 13 57 libcsdbg_test so rwxr xr x 1 root root 51758 Feb 14 13 57 mod_callgraph so rwxr xr x 1 root root 13622 Feb 14 13 57 mod_test so usr local lib pkgconfig rw r r
15. Changelog 25 1 7 7 1 7 8 Version 1 16 Added a generic adaptive syntax parser tokenizer in class string method split This method is used for the plugin symbol mangler and is the base for the stack trace syntax highlighter Added support for the C ABI to class plugin and updated the class tracer plugin management API All typedefs where added to the csdbg namespace API reference and User Manual are brought up to date both HTML and PDF Added the full class plugin documentation to the User Manual under a new section Added the Changelog section to the User Manual Implemented a profiling module plugin mod_callgraph so that constructs and prints to console the complete call graph of any multi thread process This module was created both as an elaborate example of the plugin mechanism and as a demonstration and proof of the power of the libcsdbg API as a base for generic user instrumentation code Added an example step inserted as step 4 to demonstrate to the full the features of class plugin using mod_callgraph as the plugin module Tutorial plugin mod_null so renamed to mod_test so Finalized the code and documentation for all current example code Added three syntax highlighter vocabularies for C types and keywords and for source header assembler inline and other C C file extensions Version 1 20 Added class dictionary Added class highlighter Added class style Added case sensitivity flag in string cmp
16. WITH_PLUGIN or with support for stack trace syntax highlighting CSDBG_WITH_HIGHLIGH T a string object gets equipped with a method to tokenize it using POSIX extended regular expressions and other advanced text processing methods This class is not thread safe the caller must implement thread sychronization Data structure classes csdbg node csdbg chain and csdbg stack A node can be instantiated only through the public methods of a chain or stack object When a node is released it also calls delete not delete on its data pointer unless it s previously detached Therefore each node must point to a single T and not a T allocated with operator new not newJ If a node is constructed with a pointer to a TI memory leaks are bound to happen When a node is copied or assigned only its data are copied not the position in its container The data copy works for any type integral or user defined except arrays Data copying invokes T const T amp or T operator const T amp exceptions thrown from these methods are not handled by the node nor its container they are just propagated up the call stack The chain supports shared data multiple chains can point to the same data but it is not thread safe callers should Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 6 Examples and tutorials 21 synchronize thread access This implementation doesn t allow a node with a NULL or a duplicate data pointer A node can
17. _attribute no_instrument_function void foo exception amp x tracer iface tracer interface if unlikely iface NULL return tiy 1 string buf iface gt trace buf eaten f try catch exception amp x foo x iface gt unwind Due to C polymorfism all subclasses of csdbg string including the buffered output stream types of the library like csdbg filebuf csdbg tcpsockbuf and those to come work in the same way 1 5 3 2 Thread stack traces You can create a thread stack trace anywhere in your code at any moment of execution You can create a stack trace for the currently running thread or for any process thread running stopped resumed or blocked with a call at the two argument variant of csdbg tracer trace as in the next example using namespace csdbg tracer xiface tracer interface if unlikely iface NULL return string buf iface gt trace buf pthread_self In case you have stored the thread ID of any thread you then can obtain its stack trace from any other thread Although the libcdbg higher lever interface library calls are thread safe you should be vigilant for data races that you may create Another consideration is that the above code can throw some exceptions that of course you need to handle somewhere Libcsdbg maintains a list of all simulated threads There are four tracer methods to obtain the csdbg thread object descriptor fo
18. ation through ethernet or serial ports Instead of cluttering the IDE console or debugger with trace data LDP is designed to isolate these generated data collect them with Tracer even from multiple target hosts with diverse architectures and provide an easy way to navigate through them 1 1 3 Licence and details Libcsdbg is currently published as an Open Source project licenced under the GNU Library or Lesser General Public License version 3 0 LGPLv3 Tasos Parisinos develops and maintains libcsdbg and the project documentation while Antonis Kalamaras develops and maintains the build system Version numbering uses three numbers major minor and subminor The current library version is 1 24 Major library updates are related with multiple feature addition significant changes in the library interface major bug fixes or overall optimization Minor library updates usually add minor features or major features that were almost ready to be included in the major release but didn t minor bug fixes typos and documentation updates or entities that need to be tested to gather feedback Subminor releases are stable beta snapshots of the current code development status with the last additions since the last minor update The following are locations essential to the development of libcsdbg Homepage e libcsdbg sourceforge libcsdbg freecode Downloads Release News Forum Support e jTracer homepage jJTracer freecode Ge
19. be loaded If it is set with a void value all DSO are filtered out from instrumentation You should only load the DSO that are compiled with libcsdbg support see Usage Loading non instrumented DSO is not a problem except additional overhead For example to run the example programs you must execute something like export CSDBG_LIBS csdbg_test 1 4 Troubleshooting 1 4 1 Bug reports Bugs are tracked in the tickets section of the libcsdbg site at sourceforge net Before submitting a new bug first search through all the tickets open and closed if the same bug has already been submitted by others If you are unsure whether or not something is a bug you may ask help on the users forums first Subscription is not required the forums are moderated So you think you found a bug You should report it either on the user forums or by sending an email to the project admin tasos42 users sourceforge net If you send only a vague description of a bug you are usually not very helpful and it will cost much more time to figure out what you mean In the worst case your bug report may even be completely ignored so always try to include the following information in your bug report The version of libcsdbg you are using use pkg config modversion libcsdbg if you are not sure The name and version number of your operating system uname a The libcsdbg related shell and CLI variables Generated on Thu Feb 20 2014 18 25 02 for libcsdbg b
20. brary exports through its namespace csdbg a rich user API to create and process stack traces to store them to files or send them via ethernet or serial media to a remote debug workstation to track threads and lookup process symbols to process command line arguments and shell variables that configure the library at runtime and a host of other useful utility functions One of the most useful library tools is the csdbg plugin API Using the methods exported from this class the user can register multiple function profilers either inline or modular to be run by libcsdbg A g shortcoming is that the names of the default instrumentation functions are hard coded so only a unique implementation of these can exist at linkage time therefore only one profiler can be used at a time The plugin class is the solution to this problem The library is also equipped with a parser usable with generic automata POSIX extended regular expressions and grammars The default grammar specifies a C stack trace Using this default parser a trace can be tok enized processed and printed using custom syntax highlighters The library supports a default stack trace syntax highlighter for VT100 compatible terminals XTerm RXVT GNOME terminal e t c with configurable styles The following is one of the traces produced when you execute example csdbg_step1 cpp at thread 0x7 94d9c79740 at main at csdbg_extra levell char const unsigned char csdbg_stepl cpp 149
21. cope is correctly given and the callbacks are correctly coded exported and linked 1 5 7 Using the stack trace parser syntax highlighter Class csdbg parser is a string buffer that can parse its contents using any arbitrary grammar POSIX extended regular expressions The predefined default grammar defines a C stack trace as structured by libcsdbg both for exceptions and threads A parser object equipped with this grammar can be used to perform stack trace syntax highlighting for VT100 terminals XTerm RXVT GNOME terminal e t c Subclasses of the default parser can be implemented to create highlighted stack traces for any rich text format HTML XML e t c The default highlighter uses custom styles that describe how to render each type of token function name C keyword C integral type e t c This is implemented using the classes csdbg dictionary and csdbg style Class csdbg dictionary represents a named collection of words Its tokens can be loaded from a simple text file A parser may be equipped with multiple dictionaries and use them to lookup and identify tokens The default parser object loads three dictionary data files one for C keywords one for C integral types and one for C file extensions The contents of a dictionary can be looked up as literals or as POSIX extended regular expressions A csdbg style object is a named set of VT100 text style attributes foreground and background colors and text style indicators
22. ead or multi process programs with any dynamically linked shared object DSO Dynamic Shared Object and with any statically linked library Additionally libcsdbg helps the developer tester create sophisticated stack traces of any thread at any given moment during the execution of a process or create a dump of the call stacks of all threads as a snapshot of the runtime call graph This is useful in cases of fatal errors reception of terminating signals such as SIGSEGV or process abortion termination In an object oriented programming paradigm it s usually not enough to catch and handle an exception It s essential to know at runtime where in the code and under what circumstances the exception was thrown and also the path that the exception followed from the throw point up to the point where it was caught Although much of this information can be embedded inside the exception object this has several drawbacks namely e It s not a complete solution e It needs lots of code to keep track the exception objects must have small footprint e It can t function with STL exceptions and integral types It s difficult to make it generic and portable In Java method java lang throwable prinStackTrace can provide this additional exception information because the Java language is interpreted not native as C is To implement this with GNU g libcsdbg exploits the com piler code generation features to inject code for function instrume
23. ed methods to process the CLI arguments opt_count getopt_at to class tracer and made getenv public e Added function try blocks to fix potential memory leaks in the constructors of class symbol_table name_ space tracer streambuf filebuf and tcpsockbuf e Finalized the implementation of LDP filebuf unique_id now takes a printf style format argument and times tamps are given in microseconds Added the final optimizations fixes and beautifications to the code to the library API and the documentation for all current code Dropped class throwable Added assertions e Finalized the HTML documentation generation system Added the Usage section with its 10 subsections and an Examples and Tutorials section to the User Manual both for HTML and PDF e Removed all old examples and added the new Step examples 4 and the new Tutorial examples 4 all with their complete documentation 1 7 6 Version 1 15 Added class plugin Added a user API to register unregister and manage instrumentation plugins to class tracer two register_ plugin and unregister_plugin methods method plugin_count and plugin_at Dropped the PDF API reference manual and finalized the document generation system for the PDF User Manual Added a tutorial that demonstrates the use of the plugin API both for inline plugins and for DSO modules Added a tutorial plugin module DSO mod_null so Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 7
24. er with trace data LDP is designed to isolate these generated data collect them with Tracer even from multiple target hosts with diverse architectures and provide an easy way to navigate through them 1 5 5 Buffered output streams Subclassing the abstract class csdbg streambuf is the standard way to create objects that output traces and other data to various media A streambuf derived object is both a string buffer an object of class csdbg string and an output stream The media that are supported are those that can be handled with an integer descriptor files character devices terminals sockets pipes e t c The libcsdbg project is currently shipped with three streambuf subclasses csdbg filebuf is used to output traces to files csdbg tcpsockbuf is used to transmit traces through a TCP IP network and csdbg sttybuf is used to send traces to serial devices Other classes to support UDP IP and Unix sockets pipes FIFOs and other will be added in the future Class streambuf apart from providing the common base functionality it also implements a part of the Libcsdbg Debug Protocol LDP These classes are not thread safe the caller must implement thread synchronization 1 5 5 1 Using csdbg filebuf A csdbg filebuf object is a buffered output stream used to output LDP Libcsdbg Debug Protocol data protocol headers and traces or generic data to a file This class is not thread safe the caller must implement thread synchronization A f
25. ere only for the users to use but in the future the runtime configuration of libcsdbg will be affected by them and or a configuration file If you plan to develop and use any instrumentation plugin DSO modules the best practice is to store them in PR EFIX lib modules libcsdbg At runtime for the dynamic linker to be able to locate them you must add this path to the linker search path either by editing Id so conf or by adding the path to the LD_LIBRARY_PATH shell variable The examples and tutorials that demonstrate the plugin API work in exactly this way 1 5 3 Using the csdbg tracer API To be able to do anything with libcsdbg even when you use its higher level objects csdbg filebuf csdbg tcpsockbuf e t c you first need to obtain a csdbg tracer object The word is obtain not create because the class constructors destructor and assignment operator are not public The class itself provides you with interfacing tracer objects You must call the csdbg tracer interface static method as seen in the following snippet to obtain a pointer to an interfacing tracer object using namespace csdbg tracer iface tracer interface if unlikely iface NULL abort Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 12 Overview If this call returns NULL that means that library initialization failed to load at least one symbol table You should check the debug and generic output to see why this occured For
26. es or generic data to a serial device RS 282 RS 485 USB or other serial interfaces terminals pseudoterminals e t c This class is not thread safe the caller must implement thread synchronization An sttybuf object inherits all the csdbg string methods designed for text manipulation append clear set e t c You use these methods to process the buffer data or the csdbg tracer methods to store traces to the buffer Then you may open the device node and flush the buffer You can re fill and re flush as many times as you wish before you close the sttybuf Closing is just the opposite of open it doesn t release the object and its buffer so you may re open it The steps to use an sttybuf object are 1 Create an sttybuf object for a serial port and baud 8N1 configuration 2 Open the device 3 Append set text data in the buffer 4 Flush the buffer 5 Repeat steps 3 4 until completion 6 Close Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 18 Overview 7 Repeat steps 2 6 until completion 8 Release the object Step 2 in this list can be inserted anywhere within steps 2 4 you don t need to open the port in order to process its buffer it must be opened before you flush the buffer The following is an example of using the sttybuf class using namespace csdbg tracer iface tracer interface if unlikely iface NULL return sttybuf tty dev ttyS0 115200 tty header tty append MrI
27. es thread safety Smart API to output trace or generic data to files or to network peers with the use of LDP Libcsdbg Debug Protocol Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 1 Introduction 3 An evergrowing API to support multiple output interfaces through different media ethernet serial UNIX domain sockets pipes e t c e Support for multiple function profilers either inline or loaded from a DSO module plugin e Stack trace syntax highlighting for VT100 console output e Custom dictionaries and BNF grammars for the syntax highlighters Custom VT100 configurable styles e Library API can be used as the base for custom instrumentation code Libcsdbg is currently available for GNU Linux uClibc platforms There is development going on to provide a version for Windows 32 and 64 bit systems through MinGW and Unix FreeBSD OpenBSD NetBSD systems along with an GNU autotools based build system and plugins for various IDE Eclipse Code Blocks e t c Project j Tracer is a libcsdbg sister project a portable LDP server implemented with Java Each application that uses the libcsdbg LDP API can implement a jTracer client This can be essential for cross platform development with embedded devices and development boards Most often target platforms such as these don t have a screen or other resources to visualize output and data collection during the development and debugging cycles is controlled ata workst
28. example this can happen if all modules and the executable itself are stripped of symbols You don t need to release or otherwise clear the obtained interface object after you are done The library will take care of it internally Read the code and comments in the Examples section of the documentation This will help you understand how to use libcsdbg how to interface with it with code and use its facilities The interface is really very simple and usually it takes one or two lines of code to produce a trace 1 5 3 1 Exception stack traces The best place to create and output or process an exception stack trace is in the catch section that is handling it There are two ways to output such a trace The first is to feed the tracer object to an STL output stream using the insertion operator for example using namespace csdbg tracer xiface tracer interface if unlikely iface NULL return try 4 catch exception amp x std cout lt lt x lt lt r n lt lt xiface lt lt rin iface gt unwind This is the simplest way possible Although inside the tracer object lots of things are happening behind the scenes things that can throw exceptions you don t need to worry they are taken care of internally Moreover the output to an STL stream is atomic in the scope of the library no other library output method will interleave The other way to get the stack trace of the currently handled exception is
29. he original BFD tables discard non function symbols demangle the rest and store them in a chain This change allows the symbol_table to be copied assigned and cloned so these methods were made public and functional The same changes were propagated to class name_space Added an optional symbol lookup cache with its profiler to class namespace and defined a default name for unresolved symbols Added methods exception header node detach chain detach chain detach_node namespace get_table _ count call_flow enabled and various thread accessor methods Removed the debug enumerator from class chain stack thread symbol_table name_space and call_flow Inverse lookup was removed from class namespace and symbol_table Namespace symbol lookup and current thread lookup was moved from class util to class call_flow e Function simulation methods and simulated stack unwinding were moved from class call_flow to class thread e Document generation system updated Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 7 Changelog 23 e Various code comment and documentation typos corrected e Various minor bugs fixed e Script stats was reworked to collect objective code size only e Man page documentation was dropped Added a signal handler to demonstrate stack dumps to the examples Added user defined exceptions to the examples 1 7 2 Version 1 11 Removed class call_flow Added class call string and t
30. ication with third party DSO the DSO function calls will not appear in the trace by default You need to recompile those DSO to add libcsdbg support As a rule of thumb you should recompile code to add support for libcsdbg if that code throws exceptions and if it is essential to you to see how those exceptions propagated inside the module call graph Even if you don t call a single API method if libcsdbg is compiled with debug support it is easy to see if everything linked properly by just running your application libcsdbg will at least attempt to load its symbol table and it will print various debug messages 1 5 2 Configuring libcsdbg at runtime Before you run a program linked with libcsdbg there are some things you may want to configure apart from the dynamic linker path to help libcsdbg decide what to load and what to ignore as well as some other runtime config uration tokens The symbol table of the program is always loaded by libcsdbg The user can select which DSO symbol tables to load and which to discard by declaring the CSDBG_LIBS shell variable as a delimited list of POSIX extended regular expressions The absolute path of each DSO is matched against each regexp If one matches then the symbol table of the DSO is loaded to the libcsdbg namespace and the DSO functions are instrumented throughout execution If CSDBG_LIBS is not set all linked DSO symbol tables will be loaded If it is set with a void value all DSO are filte
31. ilebuf object inherits all the csdbg string methods designed for text manipulation append clear set e t c You use these methods to process the buffer data or the csdbg tracer methods to store traces to the buffer Then you may open the underlaying file stream and flush clear the buffer You can re fill and re flush as many times as you wish before you close the filebuf Closing is just the opposite of open it doesn t release the object and its buffer so you may re open it The steps to use a filebuf object are Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 16 Overview 1 Create a filebuf object for a path 2 Open the file 3 Append set text data in the buffer 4 Flush the buffer 5 Repeat steps 3 4 until completion 6 Close 7 Repeat steps 2 6 until completion 8 Release the object Step 2 in this list can be inserted anywhere within steps 2 4 you don t need to open the file in order to process its buffer it must be opened before you flush the buffer To name files in an unambiguous way method csdbg filebuf stunique_id can come in handy It takes a printf style format string the default format is e_ p_ t_ s and uses the following specifiers e executable name a executable absolute path p process ID t thread ID s timestamp in microseconds The following is an example of using the filebuf class using namespace csdbg tracer iface tracer interface if
32. in DSO example mod_callgraph cpp This example is compiled into a plu gin module As the name implies this module tracks function execution and constructs the call graph of each thread Before the process exits the module prints these graphs to the console in a human readable way First step example csdbg_step1 cpp Demonstrates the way to integrate and use libcsdbg with a single thread program a DSO and a user defined exception type Second step example csdbg_step2 cpp This example shows the way libcsdbg works with multi thread programs and a signal handler for fatal signals that generates process stack trace dumps Third step example csdbg_step3 cpp Demonstrates the use of multiple output interfaces to output traces to files and to sockets connected to LDP servers Fourth step example csdbg_step4 cpp This example demonstrates the plugin API using the mod_ callgraph plugin to create and print the call graph of a multi thread process Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 22 Overview e Fifth step example csdbg_step5 cpp This example demonstrates the stack trace C syntax parser highlighter with a multi thread program a DSO and an asynchronous stack trace dump e Sixth step example csdbg_step6 cpp This is the final all inclusive example It builds on all previous exam ples and demonstrates all libcsdbg tricks and features from working with multi thread programs and DSO to doing outpu
33. io The application setups and registers a handler for the SIGSEGV signal A thread execution creates a memory access violation The process receives a SIGSEGV because of the segmentation fault Po oN The registered handler creates a stack trace dump for all the threads and stores it in a file using a csdbg filebuf object 5 The process aborts There are additional methods in the csdbg tracer public API they are designed to be called by the instrumentation functions these functions are not part of the csdbg namespace so they too need to obtain a tracer interface and use its public methods These methods are used for thread management and symbol lookup and they may be called by the library user One of them csdbg tracer cleanup_thread is specifically for the library user This method should be called from thread cancellation handlers to release resources If you don t cleanup the thread descriptor though it becomes useless when the actual thread has exited it continues to occupy memory and will also inject junk empty traces in dumps or in explicit trace requests This method may also be called just before a thread exits If you don t call cleanup_thread it is not a bug it s just poor coding When you have called this method you should call no more methods for the deleted thread ID Again this will be handled by the library but again it is poor coding 1 5 4 The Libcsdbg Debug Protocol LDP Ok you have created so
34. le callback functions must be named mod_enter and mod_exit take two void arguments and return void for the plugin object to resolve them correctly All plugin functions as all libcsdbg functions must NOT be instrumented by libcsdbg as this will result in an infinite recurse and a stack overflow You don t really need to instantiate plugin objects yourself Just use the static plugin API exported by csdbg tracer to register or unregister plugins like in the following code example using namespace csdbg void init __attribute constructor no_instrument_function void init try string path path to module plugin so tracer register_plugin path cstr outer inner class catch exception amp x std cerr lt lt x catch std exception amp x std cerr lt lt x Like in this example by registering a plugin in a function marked with the constructor g attribute _ attribute constructor lets the plugin get called even before main and other compiler generated initialization functions to profile them as well Note if you register the plugin inside main the profiler mod_exit callback will be called for main when it returns As you see in this example the scope argument can be as complicated as you need Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 5 Usage 19 it to be The plugin object code will mangle the callback symbols and resolve them correctly as long as their s
35. libesdbg 1 24 Generated by Doxygen 1 8 5 Thu Feb 20 2014 18 25 02 Contents 1 Overview 1 Teh e AAA 1 LLT DESGMPNON 4 24440 58 b4e 8G a Pii ded he eee ew hee bade hw i 1 LAA FEANES cia Ge eee Rk ee oe Be we A A we eee es 2 143 LESA adele ihe ede eh Goede Ewe eck BOWER Pe eee eS 3 12 Coil MESES 05 e d ee Aa Bae AA RO em A a ee ed a a 4 A ae e ce es elec alk GU ee ce BO Be iene we A ol ae he Ee we ea ee a al a E R 4 1 3 1 Compile the sources Unix Linux aaa ee 4 13 2 Install a binary distribution Unix Linux lt s a me 7 Low VOMYPINSIOlIQUOA s oben a Bea de E a i 8 TA TROUDIESIOOUNG e e 02 ee OER ee Re n ae ee Oe Re be ee Ga e 9 LAT BOIS ONS ak ke Gc eo a A AA 9 142 HOW IOCRMINDUIG oi bal ak PRE ESRD EL GEER EERE bw 10 To Uige gk go Eda A eA ee ead do ele Geet A eR ae Qe Be 10 1 5 1 Compiling with libcsdbg support 2 eoe e a ee 10 1 5 2 Configuring libcsdbg atruntime oaoa ee 11 152 Weng ine esdbgitracerAPl ocios ais aa Re EA ee A a 11 1 5 3 1 Exception stack aces lt s scc raara darra dat eee ae ee 12 1 5 3 2 Thread stack traces 2 o eb ee 13 1 5 4 The Libesdbg Debug Protocol LDP eco cos ca ca ee ee 14 15 5 Buffered output streams 2 22 ee ee ee 15 155 1 e AI 15 1552 Using esdbgtepsockp f o s scat edom Pew pa ee 16 1553 Using esdboushyOul lt oi e aw Pe Ae ae bee ey Bee ee ea 17 1 5 6 Using the instrumentation plugin API 2 2 oce ee ee 18 1 5 7
36. me traces and learned how to output them to a console or store them in buffers LDP Libcsdbg Debug Protocol is an application level protocol designed to transmit trace data together with other process thread and exception descriptive data through any media and transport layer protocol TCP IP UDP IP e t c LDP is a unidirectional client server protocol Unidirectional because only the client sends trace data to the server the server need not aknowledge or reply in any way The only role that the server plays in LDP is to collect these data from multiple and possibly of variant architecture and OS client peers and store them or let a user collectively navigate through them and process them LDP is designed as a message oriented protocol like HTTP A single connection kept alive can be used to send multiple messages but this is not mandatory it is up to the implementation Nevertheless two LDP messages are not connected in any way and can be thought as two separate LDP sessions This is a pseudo BNF description of a message The message consists of a head and a body separated by an empty line r n e The head consists of a number of headers Each header is formatted as key value r n e Header numeric values are hexadecimal no Ox prefix e The message body is the whole trace The message is terminated by an empty line This is the generic layout keyl valuel r n key2 value2 r n keyN valueN r n r n trace data r
37. n iface gt trace tty pthread_self tty append r n tty open tty flush tty close 1 5 6 Using the instrumentation plugin API A plugin object is the way to declare a pair of instrumentation functions and register them with libcsdbg to be run upon function call and return A plugin can be created by passing it the addresses of the instrumentation functions inline plugin or by loading a plugin DSO module that implements and exports these two functions A plugin invokes the system dynamic linker Id to find load and link the module so it must reside in one of the linker search directories see Id so conf and the linker manual to understand its path search algorithm The names of the default profiling functions __cyg_profile_func_enter and __cyg_profile_func_exit are hard coded into g so only a unique implementation of these can exist at linkage time therefore only one profiler can be used at a time For example if a user needed to use libcsdbg he she could not use any other function profilers at the same time The plugin class is the fix to this g shortcoming Now you can use libcsdbg and let the library run the secondary profilers by registering to it the proper plugins The plugin class supports both C and C ABls To resolve C functions the user must pass the symbol name and its full scope as a separate argument in the form namespace class To resolve C functions omit the scope argument altogether The modu
38. nclude debugging code CSDBG_WITH_COLOR_TERM Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 3 Installation 7 Include support for color terminals for debug text only This coloring of debug messages makes it easy to discrim inate between the different debug levels CSDBG_WITH_STREAMBUF Include code for buffered output streams CSDBG_WITH_STREAMBUF_FILE Include code for buffered file output streams this is valid only if the CSDBG_WITH_STREAMBUF directive is also defined CSDBG_WITH_STREAMBUF_TCP Include code for buffered TCP IP socket output streams this is valid only if the CSDBG_WITH_STREAMBUF direc tive is also defined CSDBG_WITH_STREAMBUF_STTY Include code for buffered serial tty output streams this is valid only if the CSDBG_WITH_STREAMBUF directive is also defined CSDBG_WITH_PLUGIN Include code for instrumentation plugins CSDBG_WITH_HIGHLIGHT Include code for trace C syntax highlighting The complete library with all its features enabled has a memory footprint of approximately 223Kb The complete release library is marginally smaller 219Kb If you keep only the core library functions and exclude all advanced features buffered output streams instrumentation plugins trace syntax highlighter the release library shrinks down to 111Kb 1 3 2 Install a binary distribution Unix Linux If you downloaded the binary distribution you need the following to install and use libcsdbg GNU
39. nerated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 4 Overview 1 2 Obtaining the sources The latest version of libcsdbg is 1 24 release date February 21st 2014 This release optimizes the library data structures introducing doubly linked lists class chain The implementation is done using XOR linking so memory footprint is not increased Node indexing time and memory references are greatly optimized by this especially in large symbol table lookups dramatically minimizing library overhead This subversion is the first in a series that will introduce optimizations and code example and documentation cleanup maintenance and beautifications The target is to standardize and finalize all current features before porting libcsdbg to other platforms The latest source distribution is Libcsdbg 1 24 tar bz2 Alternatively if you ve already got the previous version 1 23 you can patch it to upgrade it to the latest release libesdbg 1 23 tar D22 upgrade 1 24 patch If you have both these files in the same directory to apply the patch execute tar xjpf libcsdbg 1 23 tar bz2 cd libcsdbg 1 23 patch p1 lt upgrade 1 24 patch There are also binary distributions for 64 bit Linux debug and release versions compiled on Ubuntu 13 04 TLS libbfd 2 22 86 64 Linux lLibesdbg 1 24 tar bz2 86_64 linux dbg libesdbg 1 24 tar b22 The project documentation exists in the binary distributions and can be recrea
40. nt indicated on the project site at sourceforge net or contact us for other payment methods 1 5 Usage 1 5 1 Compiling with libcsdbg support Integration with libcsdbg is transparent and simple just compile your code with some g mandatory flags and link with libcsdbg lcsdbg From these g flags the most prominent are finstrument functions and gfformat You may need to invoke pkg config cflags libcsdbg EPIC 9 finstrument functions finstrument functions exclude file 1ist usr include finstrument functions exclude file list iostream finstrument functions exclude file list ios finstrument functions exclude file list istream finstrument functions exclude file list ostream finstrument functions exclude file 1list usr local include csdbg I usr local include to see all the additional flags you must pass to the compiler Similarly pkg config libs libcsdbg L usr local lib L usr local lib modules libcsdbg lcsdbg ldl lbfd lpthread will print the flags you must pass to the linker You may need to add PREFIX lib pkgconfig to your pkg config path Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 5 Usage 11 Stack traces created with libcsdbg can only contain calls to functions that are instrumented by libcsdbg For example if you write code for an application and instrument that code with libcsdbg only these functions you instrument will appear in traces If you link your appl
41. nt to recreate the documentation you must unpack the tarball in devel or change the paths in the doxygen configuration files doc docgen_html and doc docgen_tex with a simple text editor or doxywizard mkdir p devel mv libcsdbg 1 24 tar bz2 devel cd devel tar xjpf libcsdbg 1 24 tar bz2 Then compile and install it cd libcsdbg 1 24 sudo sh build If you install as a simple user not root use of sudo is essential if you want to keep the default prefix usr local Installing in another prefix may not need root privilege but the dynamic loader configuration file Id so conf will not be updated if sudo is not used Currently GNU autotools are not supported but this is under development The build script should compile without problems and install libcsdbg library headers and other project files examples e t c with usr local as the prefix For an overview of all build script options and modes of operation use sh build h Project libcsdbg installer Usage build c u m s d h build will compile and install its target by default The following options change the default behaviour c Clear the source tree make clean u Uninstall the package make uninstall m Compile but don t install s Don t parallelize compilation on multicore systems d Create update the documentation make doc h Show this message Although the build script can do all that you may need to compile and install or
42. ntation Compiling code with the finstrument functions flag commands g to inject calls to the instrumentation functions __cyg_profile_func_enter _ cyg_ profile_func_exit at the beginning and end of all the instrumented user functions respectively The compiled code is then linked with libcsdbg that implements these two functions as csdbg instrument_enter and csdbg instrument exit At runtime libcsdbg uses these functions to transparently simulate the call stack of each thread of execution within the debugged process adding only minimum overhead When an exception is thrown the actual thread stack is unwound until a catch section is found or until the process aborts because of the unhandled exception The stack simulator detects there is an exception being thrown and does not unwind so the libcsdbg user can obtain the exception stack trace and print store or process the trace data any way seem fit Libcsdbg transparently loads the symbol tables of the executable and of any chosen dynamic shared objects demangles function symbols to complete signatures and binds function names to runtime addresses even for 2 Overview relocatable position independent DSO symbols Libcsdbg can use all the well known objective code file formats a out elf coff ecoff e t c works with 32 and 64 bit systems and with both big and little endian architectures The library API can easily be used as the base for your own instrumentation code The li
43. on This type is used internally by libcsdbg to propagate and process errors Itis also used by the library to report internal errors to the user Users may use it or even subclass it for their own needs An exception object can be constructed using printf style formatting and a variable argument list for its error message Inside the constructor copy constructor and assignment operator other formatting or allocation exceptions may be recursively thrown but they are internally caught and silently ignored In these cases the object is still safe to use by ignoring its error message The std ostream insertion operator implementation and all exception methods take this into account Although an exception object is not thread safe by itself all overloaded std ostream insertion operator implementations that output exceptions synchronize thread access Class csdbg string A string object is mainly used to create trace text Text is easily appended using printf style format strings ex panded with variable argument lists Memory is allocated in blocks aligning to reduce overhead when appending multiple small strings It is comparable against POSIX extended regular expressions By creating traces in string buffers it is easy to direct library output to any kind of stream console file serial network plugin device e t c Apart from traces a string can be used for generic dynamic text manipulation If the library is compiled with plugin support CSDBG_
44. prefix usr local by default will have something like the following layout usr local bin IWXYI XI X root root 51101 Feb 14 13 57 csdbg_stepl IWXYI XI X root root 57024 Feb 14 13 57 csdbg_step2 IWXYI XI X root root 57936 Feb 14 13 57 csdbg_step3 IWXYI XI X root root 37108 Feb 14 13 57 csdbg_step4 IWXYI XI X root root 58371 Feb 14 13 57 csdbg_step5 IWXYI XI X root root 67825 Feb 14 13 57 csdbg_step6 IWXYI XI X root root 37254 Feb 14 13 57 csdbg_tutl IWXYI XI X root root 36320 Feb 14 13 57 csdbg_tut2 IWXYI XI X root root 35784 Feb 14 13 57 csdbg_tut3 IWXYI XI X root root 41091 Feb 14 13 57 csdbg_tut4 IWXYI XI X root root 44138 Feb 14 13 57 csdbg_tut5 IWXYI XI X root root 37440 Feb 14 13 57 csdbg_tut6 IWXYI XI X root root 989 Feb 14 13 57 vtcolors usr local etc rw r r root root 183 Feb 14 13 57 extensions dict rw r r root root 512 Feb 14 13 57 keywords dict rw r r root root 86 Feb 14 13 57 types dict usr local include drwxr xr x 2 root root 4096 Feb 14 13 57 csdbg rw Yr r root root 1065 Feb 14 13 57 csdbg hpp usr local include csdbg rw r r root root 700 Feb 14 13 57 call hpp rw r r root root 7174 Feb 14 13 57 chain hpp rw r r root root 6525 Feb 14 13 57 config hpp rw r r root root 1804 Feb 14 13 57 dictionary hpp rw r r root root 1365 Feb 14 13 57 exception hpp rw Yr r root root 13
45. r a thread e csdbg tracer current_thread Get the current thread descriptor e csdbg tracer thread_by_id Get the thread descriptor for a specific ID csdbg tracer thread_by_ name Get the thread descriptor for a specific name Threads are anonymous by default libcsdbg adds a name attribute to thread handlers for easy identification You may set or retreive a thread s name using csdbg tracer set_name and csdbg tracer name methods respectively e csdbg tracer thread_at Get the thread descriptor at an offset in the thread enumerator This is an example of creating a stack trace for the third thread in the list using namespace csdbg tracer iface tracer interface if unlikely iface NULL return thread thr iface gt thread_at 2 string buf iface gt trace buf thr gt handle Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 14 Overview Another version of thread stack tracing is to create a batch trace for all the threads within a process This feature is delivered by calling the method csdbg tracer dump This can prove extremely helpful when you want to debug an application that has totally crashed Instead of loading and debugging the core dump if the OS supports this you can solve the problem quicker by taking a look at the thread stack traces to see what each was doing and what the then executing thread was doing before the program crashed Here s an example scenar
46. racer e Radically simplified beautified and optimized the whole internal and exported library API Now a global tracer object is used as the simple interface to the library for all its features from library construction and destruction to DSO filtering and symbol table loading and parsing and from symbol and thread lookup to trace creation in string buffers and output to std ostream objects using the insertion operator The sum of changes dramatically reduces the interfacing code from whole functions to a couple of lines Heavily optimized all code and removed all unused and obsolete code Added addr2line support and all needed infrastructure code in class name_space and symbol_table for inverse lookups Removed all RTT checks from class object util chain and stack e Class name_space cache made mandatory removed its profiler Fixed a common memory leak in class chain stack name_space and thread e Added CSDBG_LIBS shell variable for DSO filtering Overloaded std ostream insertion operator for std exception and csdbg exception objects e Heavily reworked the build system for portability dropped the stats script added support for the example DSOs for the new documentation system and to reflect the new classes and the new API interface Heavily reworked the documentation generation system in general and created the first draft of the documen tation overview and user manual pages e Started the LaTeX PDF API reference doc
47. red out from instrumentation You should only load DSO that are compiled with libcsdbg support Loading non instrumented DSO is not a problem apart from additional overhead For example to run the example programs you must execute something like export CSDBG_LIBS csdbg_test Another shell variable you may care to set is CSDBG_PEER In case you utilize any csdbg tcpsockbuf object to implement an LDP jTracer client this variable tells these objects the default server IP address and TCP port if not set programmatically as the constructor arguments It must be formatted as IPaddress TCPport If the port is omitted the default LDP port 4242 is assumed Generally to get the value of such shell variables parsed to their components you need to use the csdbg tracer getenv method instead of the equivalent libe function Libcsdbg can also accept command line arguments To avoid conflicts with the application and its command line arguments the ones for libcsdbg are prefixed with csdbg To feed those arguments to libcsdbg you must call early in your code the csdbg tracer init method This method parses the command line argument vector identifies the arguments for libcsdbg canonicalizes removes the csdbg prefix stores them internally and removes them from the vector so the application never knows they were there These arguments may just be flags or pass values to the library Currently no such argument is utilized and the mechanism is th
48. s m_fallback gt clone s gt set_name number s gt set_fgcolor HLT_NUMBER_FG s gt set_attr_enabled style BOLD true Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 20 Overview m_default gt add_style s s m_fallback gt clone s gt set_name keyword s gt set_fgcolor HLT_KEYWORD_FG m_default gt add_style s s m_fallback gt clone s gt set_name type s gt set_fgcolor HLT_TYPE_FG s gt set_attr_enabled style BOLD true m_default gt add_style s s m_fallback gt clone s gt set_name file s gt set_fgcolor HLT_FILE_FG m_default gt add_style s s m_fallback gt clone s gt set_name scope s gt set_fgcolor HLT_SCOPE_FG m_default gt add_style s s m_fallback gt clone s gt set_name function s gt set_fgcolor HLT_FUNCTION_FG s gt set_attr_enabled style BOLD true m_default gt add_style s 1 5 8 Using the internal libcsdbg API Although now you know everything you need to produce and process any kind of stack trace some libcsdbg types may still come in handy for other more generic purposes although these types are quite specific and optimized for the project This is why some of these classes have some rather tricky details so instead of getting lost in the code and comments to get an idea some of them are shortly described here with some of their most uncommon features Class csdbg excepti
49. t to files and LDP servers The tutorial are the simplest possible programs showing how to perform a simple single task using one of the libcsdbg interfaces e Tutorial instrumentation plugin DSO example mod_test cpp This example is compiled into a plugin module The plugin callbacks just output debug messages about the instrumented function that got called or returns e First tutorial example csdbg_tut1 cpp Tutorial on how to print an exception stack trace to the console Second tutorial example csdbg_tut2 cpp Tutorial on how to print a thread stack trace to the console Third tutorial example csdbg_tut3 cpp Tutorial on how to store a thread stack trace to a file Fourth tutorial example csdbg_tut4 cpp Tutorial on how to create an LDP client for an exception stack trace Fifth tutorial example csdbg_tut5 cpp Tutorial on how to use instrumentation plugins inline or modules e Sixth tutorial example csdbg_tut6 cpp Tutorial on how to print an exception stack trace to the console using the trace syntax highlighter 1 7 Changelog 1 7 1 Version 1 10 e Header limits h included to provide constants for library runtime configuration e Memory address bus default width was set to 64 bit e High level user API was made thread safe RTTI checks were reworked in class util chain and stack Added checks for chain and stack overlapping e Class symbol_table was almost rewritten and got fully optimized by parsing t
50. ted with doxygen in the source code distributions The doxygen version used to produce the documentation for this version is 1 8 5 It can also be separately downloaded in HTML or as a single hyperlinked PDF document api ref libcsdbg 1 24 tar bz2 user manual libcsdbg 1 24 pdf Finally if you want an overview of all project files check the libcsdbg repository at sourceforge net Click on any file s info icon and obtain its SHA1 or MD5 checksum to verify the file you ve downloaded Note After you download any project file remember to subscribe follow libcsdbg in order to receive notification about new releases updates news announcements and other libcsdbg related material in your mailbox The easiest way to do so is to visitthe Libcsdbg project page at freecode comand click on follow 1 3 Installation 1 3 1 Compile the sources Unix Linux If you downloaded the source distribution you need at least the following to build the library the example executables and the project documentation GNU g Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 1 3 Installation 5 GNU make e GNU binutils at least libbfd so strip and addr2line e UNIX standard tools such as rm echo touch mkdir cd cp In mv grep id tar ldconfig sudo e t c e You will need doxygen and graphviz to recreate the project documentation doxygen 1 8 5 Unpack the archive unless you already have done that If you wa
51. umentation Added complete example documentation Heavily reworked the examples to simplify them and accomodate the radical libcsdobg API changes Added an example DSO that throws demo exceptions and code in the examples to use the example DSO Moved all example code to a new namespace csdbg_ extra 1 7 3 Version 1 12 Added class streambuf and filebuf buffered output streams Added method tracer init to load the library runtime configuration from the command line arguments Added method tracer thread_by_id and tracer cleanup_thread Overloaded tracer trace to create thread stack tracer Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 24 Overview Added class throwable as a more transparent interface API Updated the user manual for PDF Added file documentation Added example for buffered output streams and throwables 1 7 4 Version 1 13 e Reworked the API of the buffered output streams Implemented the first draft version of LDP Libcsdbg Debug Protocol Added method filebuf unique_id and streambuf header Added class tcpsockbuf Added example code to test demonstrate the new output APIs e Minor changes to the documentation system upgraded to doxygen 1 8 5 1 7 5 Version 1 14 e This is a maintenance version Added an iterator method foreach to class chain stack symbol_table and name_space Added methods to the thread interface API thread_count thread_at of class tracer Add
52. uninstall recreate the documentation or clear the source tree by calling the equivalent Makefile targets in the right order it is essential to describe these individual targets First of all clear the source tree from built binaries make clean Compile the sources the result binaries are stored in build make Install the library header files miscellaneous resource files stack trace syntax highlighter dictionaries VT100 utility scripts e t c and pkg config file under usr local by default make install Generated on Thu Feb 20 2014 18 25 02 for libcsdbg by Doxygen 6 Overview Then if you want to compile and install the example executables and DSO even in order to verify your installation this is done by default by build you must invoke make example plugin make example dso make example Optionally generate the documentation This will create the API reference in HTML and the user manual in LaTex and in hyperlinked PDF all generated under doc To generate the PDF version of the manual you will need a running distribution of LaTex and pdflatex makeindex and egrep To see the HTML documentation just point a browser to index html in the doc api ref libcsdbg 1 24 folder The PDF manual refman paf will be located in the user manual directory of the distribution doc user manual libcsdbg 1 24 Just view and print it via the acrobat reader make doc Finally if you need to uninstall all libcsdbg related
53. ups are also sup ported given a resolved symbol find the module that defines it A lookup cache is used internally to optimize symbol resolving A name_space can be traversed its symbol tables using simple callbacks and method csdbg name_space foreach The access to a name_space is not thread safe the caller must implement thread synchro nization 1 6 Examples and tutorials The examples come in a series of six programs of incremental complexity to cover as many of the features as possible That s why the examples are treated as steps that the library user must follow to understand the various tricks needed to correctly integrate libcsdbg and exploit it to the maximum These programs will be dynamically linked with libcsdbg so and with the example DSO libcsdbg_test so so their installation directories PREFIX lib and PREFIX lib modules libcsdbg must be in the Id path or in the LD_LIBRARY_PATH shell variable You may need to invoke the following line before you run any of the examples export LD_LIBRARY_PATH usr local lib usr local lib modules libcsdbg or in generic export LD_LIBRARY_PATH PREFIX 1lib SPREFIX lib modules libcsdbg Example DSO example libcsdbg_test cpp This example is compiled into a DSO and linked with all of the example executables to demonstrate the flawless and easy integration of relocatable shared objects with libcsdbg with either single thread or multi thread programs Example instrumentation plug
54. y Doxygen 10 Overview All libcsdbg output to the console files network that is specific to the problematic scenario The easiest way for us to fix bugs is if you can attach a small example that demonstrates the problem you have to the bug report so we can reproduce it on our machines Please make sure the example is valid source code and that the problem is really captured by the example If you intend to send more than one file please zip or tar the files together into a single file for easier processing You can and are encouraged to add a patch for a bug If you do so please use PATCH as a keyword in the bug entry form or in the email subject If you have ideas how to fix existing bugs and limitations please discuss them on the users forums For patches please use diff uprN or include the files you modified 1 4 2 How to contribute Donate time You can contribute your time by helping with programming testing and filing bug reports improving documentation translations or by answering questions on the mailing list We always welcome users whose only contribution is simply using libcsdbg giving us feedback on how to improve it and telling others about it Thank you for supporting libcsdbg Donate money If you don t have time to help but do find libcsdbg useful then please consider making a financial donation This will help to pay the bills and motivate us to continue working on libcsdbg You can do so using the Paypal accou
Download Pdf Manuals
Related Search