MRW C++ Library Reference Manual

Transcription

1 MRW C++ Library Reference Manual Version Generated by Doxygen Mon Aug 20 21:44:

2 CONTENTS 1 Contents 1 MRW C++ Library Main Page 1 2 MRW C++ Library Module Index 2 3 MRW C++ Library Namespace Index 3 4 MRW C++ Library Hierarchical Index 3 5 MRW C++ Library Class Index 5 6 MRW C++ Library File Index 8 7 MRW C++ Library Page Index 9 8 MRW C++ Library Module Documentation 10 9 MRW C++ Library Namespace Documentation MRW C++ Library Class Documentation MRW C++ Library File Documentation MRW C++ Library Example Documentation MRW C++ Library Page Documentation MRW C++ Library Main Page The official homepage is on: The minimal runtime package (for use with VideoreKorder): Minimalpaket (für den VideoreKorder): mrw-c++-minimal i586.rpm More downloads see Download and Installation of the MRW-C++ Library. All features are listed on the "Modules" page.

3 1.1 Introduction Introduction Featureful C++ Library containing a lot of needful things. Everything, I often need, but it s missing in C++ standard libraries and other common 3rd party libraries, such as log4cxx, cppunit and boost. I have paid attention to define simple and a nice to use interfaces. The library makes use of object orientation, operator overload and templates, where it makes sense. The library passes several module tests before each delivery. It is therefore stable and tested. 1.2 Supported Platforms The library is generic UNIX, but should also work on Windows. It is sporadically tested on Windows in Cygwin. Stack trace works on Linux only, it could theoretically work on Sun Solaris too, but this is untested. Stack trace without symbol resolution, just getting the raw addresses, only depends on GNU gcc and should work on all platforms. Feedback is welcome! 1.3 Missing a Feature, Found a Bug? You are missing a feature, or an implementation is too incomplete for the purpose you need it? Or you even found a bug? Just ask me and I ll try to help you! My address is in the file AUTHORS and on my website: Additional Information See the "Related Pages". Download and Installation of the MRW-C++ Library Readme Usage of the Library: Include and Link Thread Safety Library Versioning License Installation News Change Log

4 2 MRW C++ Library Module Index 3 2 MRW C++ Library Module Index 2.1 MRW C++ Library Modules Here is a list of all modules: C++ Evaluation of Command Line Arguments 10 Classes for Automated Resource Handling 11 Configuration File Handler 21 Dynamic Library Loading (ltdl) 25 Execute UNIX Commands 30 File and System Utilities 31 Regular Expressions 44 Regular Expressions 45 Tokenizer 68 Debug Utilities 47 Function Tracing (using log4cxx) 31 Automatic Function Trace for GNU g++ 14 Automatic Function Trace to standard out for GNU g++ 16 Automatically initialize log4cxx 38 Collect and Format a Stack Trace 47 Automated Unexpected and Terminate Handler 16 Exceptions with Stack Trace 26 Suggested Exception Handling Rules 29 Extensions for C++ Standard Libraries 52 STL extensions 36 deque 24 list 36 map 39 multimap 41

5 3 MRW C++ Library Namespace Index 4 multiset 43 set 45 vector 68 Useful Global Functions 50 String extensions 54 3 MRW C++ Library Namespace Index 3.1 MRW C++ Library Namespace List Here is a list of all documented namespaces with brief descriptions: mrw (Namespace for this library ) 70 4 MRW C++ Library Hierarchical Index 4.1 MRW C++ Library Class Hierarchy This inheritance list is sorted roughly, but not completely, alphabetically: mrw::args 74 mrw::auto< T > 82 mrw::autoptr< T > 82 mrw::autoptrary< T > 84 mrw::autoresource< RESOURCE_TYPE, FUNCTION_PTR, FREE_- FUNCTION, INITIAL_VALUE_TYPE, INITIAL_VALUE, FREE_- TYPE > 87 mrw::cmd 91 mrw::configfilereader 95 mrw::configfilewriter 100 mrw::configfilereader::value 98 mrw::dir 102 mrw::dir::entry 104 mrw::dynamiclibrary 106

6 4.1 MRW C++ Library Class Hierarchy 5 mrw::errno 112 mrw::exec 114 mrw::partialexec 133 mrw::file 120 mrw::fntrace 123 mrw::mmaphandle 125 mrw::opt 125 mrw::param 129 mrw::param::value 131 mrw::pipe 138 mrw::pointercounter 140 mrw::regexp 141 mrw::smartpointerparent 146 mrw::smartpointer< TYPE > 144 mrw::stacktrace 146 mrw::stacktrace::codepos 150 exception mrw::exception 112 mrw::bad_alloc 89 mrw::bad_cast 90 mrw::bad_exception 90 mrw::bad_typeid 91 mrw::executionfailedexc 119 mrw::logic_error 124 mrw::domain_error 105 mrw::invalid_argument 123 mrw::length_error 124 mrw::out_of_range 128

7 5 MRW C++ Library Class Index 6 mrw::runtime_error 144 mrw::dynamiclibrary::failure 111 mrw::overflow_error 128 mrw::range_error 141 mrw::underflow_error 154 mrw::unix_error 154 mrw::tokenizer MRW C++ Library Class Index 5.1 MRW C++ Library Class List Here are the classes, structs, unions and interfaces with brief descriptions: mrw::args (Handle command line arguments ) 74 mrw::auto< T > (Automatically calls free for malloc allocated memory. Instanciate it as mrw::auto<type >::Free ) 82 mrw::autoptr< T > (Automatically deletes a pointer when destructed ) 82 mrw::autoptrary< T > (Automatically deletes an array pointer when destructed ) 84 mrw::autoresource< RESOURCE_TYPE, FUNCTION_PTR, FREE_- FUNCTION, INITIAL_VALUE_TYPE, INITIAL_VALUE, FREE_- TYPE > (Automatically frees a resource when destructed ) 87 mrw::bad_alloc (Replacement for std::bad_alloc, but with stack trace ) 89 mrw::bad_cast (Replacement for std::bad_cast, but with stack trace ) 90 mrw::bad_exception (Replacement for std::bad_exception, but with stack trace ) 90 mrw::bad_typeid (Replacement for std::bad_typeid, but with stack trace ) 91 mrw::cmd (A system command to be executed ) 91 mrw::configfilereader (Parse configuration file and access the contents ) 95 mrw::configfilereader::value (A configuration file value ) 98

8 5.1 MRW C++ Library Class List 7 mrw::configfilewriter (Parse configuration file and offer read / write access to the contents ) 100 mrw::dir (Directory access ) 102 mrw::dir::entry (Directory entry ) 104 mrw::domain_error (Replacement for std::domain_error, but with stack trace ) 105 mrw::dynamiclibrary (Dynamic Library loaded from the filesystem at runtime ) 106 mrw::dynamiclibrary::failure (Failure in access to shared libraries ) 111 mrw::errno (Stores a UNIX errno error number and converts it to string )112 mrw::exception (Replacement for std::exception, that collects a stack trace ) 112 mrw::exec (Execute a command in a new process ) 114 mrw::executionfailedexc (Exception: Execution of command failed ) 119 mrw::file (File handling utilities ) 120 mrw::fntrace 123 mrw::invalid_argument (Replacement for std::invalid_argument, but with stack trace ) 123 mrw::length_error (Replacement for std::length_error, but with stack trace ) 124 mrw::logic_error (Replacement for std::logic_error, but with stack trace ) 124 mrw::mmaphandle (Resource handle for mmap ) 125 mrw::opt (This class represents one command line option ) 125 mrw::out_of_range (Replacement for std::out_of_range, but with stack trace ) 128 mrw::overflow_error (Replacement for std::overflow_error, but with stack trace ) 128 mrw::param (List of additional (mandatory) parameter to one command line argument ) 129 mrw::param::value (Abstract base class to represent one single parameter value ) 131

9 6 MRW C++ Library File Index 8 mrw::partialexec (Execute a UNIX program in non blocking parts ) 133 mrw::pipe (Class that implements an unnamed UNIX pipe ) 138 mrw::pointercounter 140 mrw::range_error (Replacement for std::range_error, but with stack trace ) 141 mrw::regexp (Regular expression ) 141 mrw::runtime_error (Replacement for std::runtime_error, but with stack trace ) 144 mrw::smartpointer< TYPE > (Smart Pointer Implementation ) 144 mrw::smartpointerparent 146 mrw::stacktrace (Store and print a stack trace of the actual position in code ) 146 mrw::stacktrace::codepos (Structure to store all evaluated information )150 mrw::tokenizer (Split strings into parts separated by delimiters ) 151 mrw::underflow_error (Replacement for std::underflow_error, but with stack trace ) 154 mrw::unix_error (To be thrown when a unix system call fails, evaluates errno ) MRW C++ Library File Index 6.1 MRW C++ Library File List Here is a list of all documented files with brief descriptions: mrw/arg.cpp 156 mrw/arg.hpp 157 mrw/auto.hpp 158 mrw/autofunctiontracelog4cxx.cpp 160 mrw/autofunctiontracestdlog.cpp 161 mrw/autostacktracelog4cxx.cpp 162 mrw/autostacktracestderr.cpp 163

10 6.1 MRW C++ Library File List 9 mrw/configfile.cpp 163 mrw/configfile.hpp 164 mrw/deque.hpp 165 mrw/dynamiclibrary.hpp 166 mrw/errno.cpp 167 mrw/errno.hpp 167 mrw/exception.cpp 169 mrw/exception.hpp 170 mrw/exec.cpp 172 mrw/exec.hpp 174 mrw/file.hpp 175 mrw/functiontrace.cpp 176 mrw/functiontrace.hpp 177 mrw/list.hpp 178 mrw/log4cxxconfiguration.cpp 179 mrw/map.hpp 180 mrw/mrw.hpp?? mrw/multimap.hpp 180 mrw/multiset.hpp 181 mrw/regexp.cpp 182 mrw/regexp.hpp 183 mrw/set.hpp 184 mrw/smartpointer.hpp 185 mrw/stacktrace.cpp 185 mrw/stacktrace.hpp 186 mrw/stdext.cpp 187 mrw/stdext.hpp 188

11 7 MRW C++ Library Page Index 10 mrw/string.hpp 189 mrw/tokenizer.hpp 192 mrw/unistd.hpp 192 mrw/vector.hpp 194 mrw/version.cpp MRW C++ Library Page Index 7.1 MRW C++ Library Related Pages Here is a list of all related documentation pages: Download and Installation of the MRW-C++ Library 197 Usage of the Library: Include and Link 199 Thread Safety 199 Library Versioning 200 License 200 Readme 209 Installation 210 News 213 Change Log 215 Todo List MRW C++ Library Module Documentation 8.1 C++ Evaluation of Command Line Arguments Detailed Description These classes do simple and easy command line argment evaluation in C++. Features: every argument has a long and a short option all arguments are optional and provide a default value

12 8.1 C++ Evaluation of Command Line Arguments 11 the order of options is not important every option can take any (fixed) number of additional parameter of type string integer boolean ("yes", "on", "true" evaluates to true) short options can be combined, instead of -a -b -c 15 you can simply write -abc 15 automated help display (support for option -h) mrw::args is the main user interface class that represents all command line options with their arguments. It is implemented as singleton, so the same instance can be accessed from everywhere in the code. It mst be setup just in the beginning of the main() function. The other important class for the end user is mrw::opt, one possible option with additional parameter. The end user needs mrw::opt to setup all allowed command line options in the beginning, bevore evaluation of the user given command line is done (before argc and argv is shifted into mrw::args. The third class a user should know is mrw::param. It represents the arguments to one option. Every instance of mrw::opt owns one instance of mrw::param that is either empty or list of (mandatory) arguments of type std::string, int or bool. The classes are normally used this way: // this program may be called e.g. with the following arguments: //./a.out --coordinates vo out.txt -n MyName int main(int argv, char const*const*const argv) { try { mrw::args::instance() // setup the possible options <<mrw::opt( h, "--help", "Show this help text") <<mrw::opt( v, "--verbose", "print more information") <<mrw::opt( q, "--quiet", "be quiet") <<mrw::opt( n, "--name", mrw::param()<<"mrw", "name of the user") <<mrw::opt( o, "--output-file", mrw::param()<<"", "file to load") <<mrw::opt( c, "--coordinates", mrw::param()<<0<<0, "X, Y coordinate") // set a description text for help <<"This is a testprogram for argument evaluation in C++" // define the help option << h // shift in the command line arguments <<argc<<argv;... // example usage of simple option if (mrw::args::instance().find( v )) // be verbose here if (mrw::args::have( v )) // the same, simpler: be verbose here... // example usage of option with one parameter ifstream file(mrw::args::tostring( o ).c_str());... // example usage of option with two parameter int x = mrw::args::instance().find( c )[0]->toInt(); // first integer int y = mrw::args::toint( c, 1); // second; alternative, simpler access

13 8.2 Classes for Automated Resource Handling 12 }... return 0 } } catch (mrw::exception& x) { // trace error, print help or mention option -h } Classes class mrw::param List of additional (mandatory) parameter to one command line argument. class mrw::opt this class represents one command line option class mrw::args handle command line arguments 8.2 Classes for Automated Resource Handling Detailed Description For pointers that have been allocated with new, you can use std::auto_ptr to automatically free them when you leave the context. Unfortunately there is no such thing for malloc (except malloca that only works for a subset of problems: if you and not a system call allocates memory), open and so on. These classes can take over the resource ownership. The following ressource handler are predefined: mrw::autoptr<> is the same as std::auto_ptr, but can be stored in STL containers mrw::autoptr<classname> xyz(new ClassName(a, b, c)); mrw::mmaphandle frees an mmap handle with munmap mrw::auto<>::free frees malloc allocated memory with free mrw::auto<char*>::free xxx((char*)malloc(15)); mrw::smartpointer<> is a shared pointer that deletes memory when all owners have died mrw::smartpointer<classname> xyz(new ClassName(a, b, c)); mrw::pipe handles UNIX pipes and closes them on exit

14 8.2 Classes for Automated Resource Handling 13 mrw::autofile automatically closes open files mrw::automapper calls munmap on memory mapped files mrw::autobfd automatically calls bfd_close If this is not enough, you can typedef your own ressource handler from the template class mrw::autoresource<>. For example, mrw::autofile is defined as: typedef mrw::autoresource<int, int(*)(int), &close, int, -1> mrw::autofile; Classes class mrw::autoresource< RESOURCE_TYPE, FUNCTION_PTR, FREE_- FUNCTION, INITIAL_VALUE_TYPE, INITIAL_VALUE, FREE_TYPE > Automatically frees a resource when destructed. class mrw::autoptr< T > Automatically deletes a pointer when destructed. class mrw::autoptrary< T > Automatically deletes an array pointer when destructed. class mrw::mmaphandle Resource handle for mmap. class mrw::auto< T > Automatically calls free for malloc allocated memory. mrw::auto<type >::Free. Instanciate it as class mrw::smartpointer< TYPE > Smart Pointer Implementation. class mrw::pipe class that implements an unnamed UNIX pipe Typedefs typedef mrw::autoresource< int, int( )(int),&close, int,-1 > mrw::autofile Automatically closes a file when destructed. typedef mrw::autoresource< MMapHandle, void( )(MMapHandle &),&mrw::munmap, int > mrw::automapper Automatically calls munmap on destruction for mmaped files.

15 8.2 Classes for Automated Resource Handling 14 typedef mrw::autoresource< bfd, int( )(bfd ),&bfd_close, int > mrw::auto- Bfd Automatically calls bfd_close for bfd. Functions void mrw::munmap (MMapHandle &res) throw (std::bad_exception) Typedef Documentation typedef mrw::autoresource<bfd, int( )(bfd ), &bfd_close, int> mrw::autobfd Automatically calls bfd_close for bfd. Precondition: #include <mrw/auto.hpp> It acts like a std::auto_ptr, but for bfd, that means it calls bfd_close whenever the context is left. Definition at line 401 of file auto.hpp typedef mrw::autoresource<int, int( )(int), &close, int, -1> mrw::autofile Automatically closes a file when destructed. Precondition: #include <mrw/auto.hpp> AutoFile works exactly like std::auto_ptr, but for files instead of pointers. Whenever the context of AutoFile is left, the opened file is close. This way, resources are freed even in case of exceptions. Definition at line 356 of file auto.hpp typedef mrw::autoresource<mmaphandle, void( )(MMapHandle&), &mrw::munmap, int> mrw::automapper Automatically calls munmap on destruction for mmaped files. Precondition: #include <mrw/auto.hpp> It s the same as std::auto_ptr, but for mmap instead of new. When the context of AutoMapper is left, munmap is called. Definition at line 393 of file auto.hpp.

16 8.3 Automatic Function Trace for GNU g Automatic Function Trace for GNU g++ Collaboration diagram for Automatic Function Trace for GNU g++: Funct i on Tr aci ng ( usi ng l og4cxx) Aut omat i c Funct i on Tr ace f or GNU g Detailed Description If you compile your program with GNU g++ / gcc, and you want to add function tracing without changing a single line of your code, here s the solution: If you link to the library libmrwautofunctiontracelog4cxx using a linker option such as: -lmrwautofunctiontracelog4cxx and you must enable the GNU Compiler Collection specific function trace feature with compile and link option -finstrument-functions then you get an automatical function trace, that traces to level DEBUG using the log4cxx library. You don t need to change a single line in your code! This feature depends on: the GNU C++ compiler gcc mrw::stacktrace log4cxx optional: boost for thread support The logger hiararchy name is: "mrw.fn.<full-method-name>" where <full-method-name> is the full name of the method, including namespace and class name, seperated not by double colon :: but by single dots. as it is common use in log4cxx. This way, you can enable or disable the function trace per namespace, per class or even per method. The function trace does not start, before the program main is reached! Only the calls within the main are traced, but not during the initialisation and destruction of static members. This is necessary, because otherwise access the incompletely initialized MRW-C++ library itself may cause a crash. A good default configuration is given in Automatically initialize log4cxx. Depending on your log4cxx configuration, a function trace may look e.g. like this (very simple configuration with very few additional information): mrw.fn.anotherfunction mrw.fn.hallowelt.fn1 mrw.fn.hallowelt.fn mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.fn mrw.fn.hallowelt.fn \ anotherfunction() \ HalloWelt::fn1() \ HalloWelt::fn() \ HalloWelt::A::method() / HalloWelt::A::method() \ HalloWelt::A::method() / HalloWelt::A::method() / HalloWelt::fn() \ HalloWelt::fn()

17 8.4 Automatic Function Trace to standard out for GNU g++ 16 mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.a.method mrw.fn.hallowelt.fn mrw.fn.hallowelt.fn1 mrw.fn.anotherfunction \ HalloWelt::A::method() / HalloWelt::A::method() \ HalloWelt::A::method() / HalloWelt::A::method() / HalloWelt::fn() / HalloWelt::fn1() / anotherfunction() Note: The configurator is not installed automatically. If you want to trace e.g. on the console, you have to call log4cxx::basicconfigurator::configure(); as first statement in your main(). See also: Automatically initialize log4cxx if you also want to automatically configure log4cxx Multithreading Multithreading is also supported, then you need to link to the thread safe compilat of the library libmrwautofunctiontracelog4cxx-mt with option -libmrwautofunctiontracelog4cxx-mt and you need the option -pthread in addition to -finstrument-functions which is still required. Thread support requires the boost thread library. See for details. Functions void cyg_profile_func_enter (void, void ) attribute ((no_instrument_- function)) void cyg_profile_func_exit (void, void ) attribute ((no_instrument_- function)) 8.4 Automatic Function Trace to standard out for GNU g++ Collaboration diagram for Automatic Function Trace to standard out for GNU g++: Funct i on Tr aci ng ( usi ng l og4cxx) Aut omat i c Funct i on Tr ace t o st andar d out f or GNU g++ Same as Automatic Function Trace for GNU g++, but traces to stdlog. If you link to the library libmrwautofunctiontracestdlog using a linker option such as: -lmrwautofunctiontracestdlog and you must enable the GNU Compiler Collection specific function trace feature with compile and link option -finstrument-functions then you get an automatical function trace, that traces to stdlog. You don t need to change a single line in your code!

18 8.5 Automated Unexpected and Terminate Handler Automated Unexpected and Terminate Handler Collaboration diagram for Automated Unexpected and Terminate Handler: Col l ect and Format a St ack Trace Aut omat ed Unexpect ed and Ter mi nat e Handl er Detailed Description Don t care about the unexpected handler, don t care about a try-catch in the main, let the library do all the repetitive work for you. with Stack Trace For all your programs it is recommended to implement an identical unexpected handler, that rethrows, catches the mrw::exception, std::exception and all unknown exceptions, traces them and finally quits with a throw of a std::bad_exception. You are also required to write a try catch block around all in your main, so that you don t miss any exception. The only thing that may be different from project to project is, how tracing is done. The MRW C++ Class Library provides you with additional libraries you can link to. By linking to the library, you get an unexpected handler and an exception trace in the main for free: You don t need to add a single line of code, just link to one more library! The libraries differ in how tracing is done. The Implementation is done with a static instance of a class that sets the unexpected handler in the constructor Trace using std::cerr If you link to the library libmrwexcstderr using a linker option such as: -lmrwexcstderr, then an unexpected and a terminate handler are registered, that trace to the standard error stream std::cerr. Also for all know signals there s a signal handler to trace the stack before termination (except in case of a SIGTRAP, wehere the program is not terminated). You don t need to change a single line in your code! Trace using the log4cxx Library If you link to the library libmrwexclog4cxx using a linker option such as: -lmrwexclog4cxx, then an unexpected and a terminate handler are registered, that trace a fatal error using the log4cxx library. Also for all know signals there s a signal handler to trace the stack before termination (except in case of a SIGTRAP, wehere the program is not terminated). You don t need to change a single line in your code! The log4cxx library is located at: Note: The configurator is not installed automatically. If you want to trace e.g. on the con-

19 8.5 Automated Unexpected and Terminate Handler 18 sole, you have to call log4cxx::basicconfigurator::configure(); as first statement in your main(). See also: Automatically initialize log4cxx if you also want to automatically configure log4cxx. Functions void mrw::unexpected_log4cxx () unexpected handler, that traces using log4cxx void mrw::terminate_log4cxx () terminate handler, that traces using log4cxx void mrw::signal_log4cxx (int sig) segmentation-fault handler, that traces using log4cxx void mrw::unexpected_stderr () unexpected handler, that traces to std::cerr void mrw::terminate_stderr () terminate handler, that traces to std::cerr void mrw::signal_stderr (int sig) segmentation-fault handler, that traces using stderr Function Documentation void mrw::signal_log4cxx (int sig) segmentation-fault handler, that traces using log4cxx The segmentation-fault handler is installed automatically when you link to -lmrwexclog4cxx. The implementation of this handler is as follows: void signal_log4cxx(int sig) { std::string txt; bool abort(true); switch sig { case SIGFPE: txt="sigfpe: Arithmetic error."; break; case SIGILL: txt="sigill: Illegal instruction."; break; case SIGSEGV: txt="sigsegv: Segmentation fault" " (invalid access to valid memory)."; break; case SIGBUS: txt="sigbus: Invalid pointer dereference" " (access to an invalid memory address)."; break; case SIGABRT: txt="sigabrt: Funktion abort was called."; break; case SIGIOT: txt="sigiot: PDP-11 iot instruction"; break; case SIGTRAP: txt="sigtrap: Breakpoint instruction."; abort=false; break;

20 8.5 Automated Unexpected and Terminate Handler 19 } case SIGEMT: txt="sigemt: Emulator trap."; break; case SIGSYS: txt="sigsys: Bad system call."; break; default: txt="unknown Signal Nr. "+sig; break; } StackTrace::createSymtable(); std::string st((std::string)stacktrace()); log4cxx::loggerptr logger(log4cxx::logger::getlogger("mrw.stacktrace")); logger->fatal("aborted by signal: "+txt+"\nstack:\n"+st); if (abort) exit(1); Definition at line 206 of file autostacktracelog4cxx.cpp. References mrw::stacktrace::createsymtable(), and mrw::string() void mrw::signal_stderr (int sig) segmentation-fault handler, that traces using stderr The segmentation-fault handler is installed automatically when you link to -lmrwexcstderr. The implementation of this handler is as follows: void signal_stderr(int sig) { std::cerr<<"signal RECEIVED: "<<std::endl; std::string txt; bool abort(true); switch (sig) { case SIGFPE: txt="sigfpe: Arithmetic error."; break; case SIGILL: txt="sigill: Illegal instruction."; break; case SIGSEGV: txt="sigsegv: Segmentation fault" " (invalid access to valid memory)."; break; case SIGBUS: txt="sigbus: Invalid pointer dereference" " (access to an invalid memory address)."; break; case SIGABRT: txt="sigabrt: Funktion abort was called."; break; case SIGTRAP: txt="sigtrap: Breakpoint instruction."; abort=false; break; case SIGSYS: txt="sigsys: Bad system call."; break; default: txt="unknown Signal Nr. "+sig; break; } StackTrace::createSymtable(); std::string st((std::string)stacktrace()); stderr::loggerptr logger(stderr::logger::getlogger(_t("mrw.stacktrace"))); std::cerr<<" Reason:"<<std::endl <<"Aborted by signal: "<<txt<<std::endl <<" Stack:"<<std::endl <<st<<std::endl <<" "<<std::endl; if (abort) exit(1); } Definition at line 204 of file autostacktracestderr.cpp. References mrw::stacktrace::createsymtable(), and mrw::string() void mrw::terminate_log4cxx () terminate handler, that traces using log4cxx

21 8.5 Automated Unexpected and Terminate Handler 20 The terminate handler is installed automatically when you link to -lmrwexclog4cxx. The implementation of this terminate handler is as follows: void terminate_log4cxx() { log4cxx::loggerptr logger(log4cxx::logger::getlogger("mrw.stacktrace")); logger->fatal("uncaught Exception", FILE, LINE ); StackTrace::createSymtable(); std::string st((std::string)stacktrace()); try { throw; exit(0); } catch (const mrw::exception& x) { logger->fatal(std::string("reason:\n")+x.what() +"\nstack:+\n"+x.stacktrace()); } catch (const std::exception& x) { logger->fatal(std::string("reason:\n")+x.what() +"\nstack:\n"+st); } catch (...) { logger->fatal(std::string("reason: **** not available ****") +"\nstack:\n"+st); } exit(1); } Definition at line 148 of file autostacktracelog4cxx.cpp. References mrw::stacktrace::createsymtable(), MRW_LOG4CXX_LOCATION, mrw::exception::stacktrace(), mrw::string(), and mrw::exception::what() void mrw::terminate_stderr () terminate handler, that traces to std::cerr The terminate handler is installed automatically when you link to -lmrwexcstderr. The implementation of this terminate handler is as follows: void terminate_stderr() { std::cerr<<"uncaught EXCEPTION: "<<std::endl; try { throw; } catch (const mrw::exception& x) { StackTrace::createSymtable(); std::cerr<<" Reason:"<<std::endl <<x.what()<<std::endl <<" Stack:"<<std::endl <<x.stacktrace(); } catch (const std::exception& x) { std::cerr<<" Reason:"<<std::endl <<x.what()<<std::endl <<" Stack: **** not available ****"<<std::endl; } catch (...) { std::cerr<<" Reason: **** not available ****"<<std::endl <<" Stack: **** not available ****"<<std::endl; } std::cerr<<" "<<std::endl; exit(1); }

22 8.5 Automated Unexpected and Terminate Handler 21 Definition at line 147 of file autostacktracestderr.cpp. References mrw::stacktrace::createsymtable(), mrw::exception::stacktrace(), and mrw::exception::what() void mrw::unexpected_log4cxx () unexpected handler, that traces using log4cxx The unexpected handler is installed automatically when you link to -lmrwexclog4cxx. The implementation of this unexpected handler is as follows: void unexpected_log4cxx() { log4cxx::loggerptr logger(log4cxx::logger::getlogger("mrw.stacktrace")); logger->fatal("unexpected Exception", FILE, LINE ); StackTrace::createSymtable(); std::string st((std::string)stacktrace()); try { throw; } catch (const mrw::exception& x) { logger->fatal(std::string("reason:\n")+x.what() +"\nstack:+\n"+x.stacktrace()); } catch (const std::exception& x) { logger->fatal(std::string("reason:\n")+x.what() +"\nstack:\n"+st); } catch (...) { logger->fatal(std::string("reason: **** not available ****") +"\nstack:\n"+st); } throw std::bad_exception(); } Definition at line 92 of file autostacktracelog4cxx.cpp. References mrw::stacktrace::createsymtable(), MRW_LOG4CXX_LOCATION, mrw::exception::stacktrace(), mrw::string(), and mrw::exception::what() void mrw::unexpected_stderr () unexpected handler, that traces to std::cerr The unexpected handler is installed automatically when you link to -lmrwexcstderr. The implementation of this unexpected handler is as follows: void unexpected_stderr() { std::cerr<<"unexpected EXCEPTION: "<<std::endl; try { StackTrace::createSymtable(); throw; } catch (const mrw::exception& x) { std::cerr<<" Reason:"<<std::endl <<x.what()<<std::endl <<" Stack:"<<std::endl <<x.stacktrace(); } catch (const std::exception& x) {

23 8.6 Configuration File Handler 22 std::string st((std::string)stacktrace()); std::cerr<<" Reason:"<<std::endl <<x.what()<<std::endl <<" Stack: "<<std::endl<<st; } catch (...) { std::string st((std::string)stacktrace()); std::cerr<<" Reason: **** not available ****"<<std::endl <<" Stack:"<<std::endl<<st; } std::cerr<<" "<<std::endl; throw std::bad_exception(); } Definition at line 92 of file autostacktracestderr.cpp. References mrw::stacktrace::createsymtable(), mrw::exception::stacktrace(), mrw::string(), and mrw::exception::what(). 8.6 Configuration File Handler Detailed Description Precondition: #include <mrw/configfile.hpp> Read configuration parameters from a file Configuration File Syntax Sections: [Section] Syntax (regular expression): \[([ [=#] )\] A configuration file consists of none or more sections. The sections start with tag [Section Name], where Section Name is the name of the section. The default section has an empty name Variables: name = value Syntax (regular expression): [ [\n\t ] ([ [=#\n]]+)[\n\t ] =[\n\t ] ([ [=#]] )[\n\t ] or [ [\n\t ] ([ [=#\n]]+)[\n\t ] =[\n\t ] ("[ "]] ")[\n\t ] or [ [\n\t ] ([ [=#\n]]+)[\n\t ] =[\n\t ] ( [ ]] )[\n\t ] In the section, there are variable definitions in the form of name=value, where name is the name of the variable and value is it s contents. White spaces at the begin or end of the name and the value are stripped. Whitespaces inside a name or value remain unchanged. Please note that a variable name starts at the begoin of line and ends before the equal sign, while the contents starts after the equal sign and ends before the next token starts. If you need a token inside a value, or a variable must start or end with white spaces, you can enclose it in either " or quotes. If a value is quoted and the quoting is not terminated, then the contents is taken up to the end of file. Please note that the same quote must not occur inside the value. All possible tokens are: [, # and =. All other characters are not treated in a special way.

24 8.6 Configuration File Handler Comments: # Comments start with # and end at the end of the line Special Characters \n, [, ], #, =, ", I have chosen a syntax that is downwards compatible with the common Unix configuration file syntax, but with a grammar as loose as possible and with as few restrictions as possible. Special characters have only special meanings in certain contexts. In other contexts, they can be used with no restrictions. The following characters are treated in a special way: [ and ] enclose a section name. A section name may contain any arbitrary character, including new line and white spaces, except a ]. \n (begin of line or file) and = enclose a variable name. In other circumstances (except in comments), a new line has no special meaning. A = inside a value is allowed only if the value is quoted. A variable name may contain any arbitrary character, including white spaces, except a new line or =. = and one out of [, # and the begin of a line that contains = enclose a variable contents if the contents is not quoted. A variable s contents may contain any arbitrary character, including new line and white spaces, except a ], # or the begin of a line that contains =. " or may enclose a variables contents. These characters have only a special meaning, if a variable s contents starts with one of them. Then the variable s contents may contain any arbitrary character, except the same quote itself, which marks the end of the contents. # and \n (end of line or file) enclose a comment. A variable name may contain any arbitrary character, including white spaces, except a new line Restrictions Attention: Due to the actual syntax, it is impossible that a variable s contents contains the following combination: " and and one out of [, = and # If a variable s contents contains heading or trailing white spaces or one out of [, = and #, then it must be quoted either with " or with Example File Nice Example [Section 1] name1 = value1 name2 = value2 [Section 2] name1 = value1 name2 = value2

25 8.7 deque Enhanced Example # this is in the global section, named "" this is a variable name = this is a variable contents [Global] # start of section "Global" multi line text = this is a text that is longer than one line! 1234 = "var=17" # if you need an equal inside a text, enclose it # either in " or in Code Sample try { const char* home(getenv("home")); mrw::configfilereader config(home?home+"/.myprogram":".myprogram"); std::string username(config("user Info", "Name")); } catch (...) { // file read or evaluation error } Classes class mrw::configfilereader Parse configuration file and access the contents. class mrw::configfilewriter Parse configuration file and offer read / write access to the contents. 8.7 deque Collaboration diagram for deque: STL ext ensi ons deque Functions template<typename T, typename A> std::deque< T, A > & operator<< (std::deque< T, A > &l, const T &o) throw (std::bad_exception) push a value to a deque template<typename T, typename A> std::deque< T, A > & operator>> (std::deque< T, A > &l, T &o) throw (std::exception) extract the first value of a deque

26 8.7 deque Function Documentation template<typename T, typename A> std::deque<t, A>& operator<< (std::deque< T, A > & l, const T & o) throw (std::bad_exception) push a value to a deque std::deque<int> test; test<<1<<2<<3<<4<<5<<6<<7<<8; Parameters: l a deque of values o a value to be inserted into deque l Precondition: #include <mrw/deque.hpp> Definition at line 52 of file deque.hpp template<typename T, typename A> std::deque<t, A>& operator>> (std::deque< T, A > & l, T & o) throw (std::exception) extract the first value of a deque std::deque<int> test; test<<1<<2<<3<<4<<5<<6<<7<<8; int i1(0), i2(0), i3(0), i4(0); test>>i1>>i2>>i3>>i4; // now: i1==1 i2==2 i3==3 i4==4 test=={5, 6, 7, 8} Parameters: l a deque of values o a value to be extracted from deque l Exceptions: Note: mrw::length_error,if deque was empty on entry when something is extracted from a deque, it is removed from the deque, that means after every shift the deque is shortened by the shifted element Precondition: #include <mrw/deque.hpp> Definition at line 76 of file deque.hpp. References mrw::string().

27 8.8 Dynamic Library Loading (ltdl) Dynamic Library Loading (ltdl) Detailed Description Implements a C++ wrapper around the Libtool s platform independent dynamic library loading library named libltdl. See info libtool for more information. Loading a symbol from a shared library: void fn() throw(mrw::dynamiclibrary::failure) { static DynamicLibrary lib("libsomething"); static void(*therealfunction)() = (void(*)())lib.symbol("therealfunction"); (*therealfunction)(); // call the loaded function } Precondition: #include <mrw/dynamiclibrary.hpp> Files that use this wrapper must be linked with libltdl, with GNU g++ on UNIX, this is link option: -lltdl Classes class mrw::dynamiclibrary Dynamic Library loaded from the filesystem at runtime. 8.9 Exceptions with Stack Trace Collaboration diagram for Exceptions with Stack Trace: Except i ons wi t h St ack Trace mr w: : except i on Col l ect and Format a St ack Trace Detailed Description The following diagram shows the inheritance of the MRW exception classes and how they are related to the C++ standard exceptions. mrw::exception inherits std::exception, then a inheritance corresponding to the standard is implemented below mrw::exception. To prevent diamond-shaped inheritance, the MRW exceptions below the mrw::exception base class do not inherit from their corresponding standard exception. The exception classes are meant as a replacement to the standard exceptions that provide stack trace information. I suggest exception handling according to Suggested Exception Handling Rules.

28 8.9 Exceptions with Stack Trace 27 std::domain_error std::bad_alloc std::invalid_argument std::bad_cast std::length_error std::logic_error std::out_of_range std::exception std::runtime_error std::overflow_error std::bad_exception std::range_error std::bad_typeid std::underflow_error mrw::domain_error mrw::bad_alloc mrw::invalid_argument mrw::bad_cast mrw::length_error mrw::logic_error mrw::out_of_range mrw::exception mrw::runtime_error mrw::overflow_error mrw::bad_exception mrw::range_error mrw::bad_typeid mrw::underflow_error mrw::unix_error

29 8.9 Exceptions with Stack Trace 28 In addition to the reimplementation of the standard exceptions, There is also a class mrw::errno to handle UNIX C library errno and an exception class mrw::unix_error to that uses mrw::errno to convert errno into a meaningful string and that offers facilities to handle failed UNIX C library calls. Classes class mrw::errno Stores a UNIX errno error number and converts it to string. class mrw::unix_error to be thrown when a unix system call fails, evaluates errno class mrw::exception replacement for std::exception, that collects a stack trace class mrw::bad_alloc Replacement for std::bad_alloc, but with stack trace. class mrw::bad_cast Replacement for std::bad_cast, but with stack trace. class mrw::bad_exception Replacement for std::bad_exception, but with stack trace. class mrw::bad_typeid Replacement for std::bad_typeid, but with stack trace. class mrw::logic_error Replacement for std::logic_error, but with stack trace. class mrw::domain_error Replacement for std::domain_error, but with stack trace. class mrw::invalid_argument Replacement for std::invalid_argument, but with stack trace. class mrw::length_error Replacement for std::length_error, but with stack trace. class mrw::out_of_range Replacement for std::out_of_range, but with stack trace. class mrw::runtime_error Replacement for std::runtime_error, but with stack trace.

30 8.10 Suggested Exception Handling Rules 29 class mrw::overflow_error Replacement for std::overflow_error, but with stack trace. class mrw::range_error Replacement for std::range_error, but with stack trace. class mrw::underflow_error Replacement for std::underflow_error, but with stack trace Suggested Exception Handling Rules Collaboration diagram for Suggested Exception Handling Rules: Col l ect and Format a St ack Trace Suggest ed Except i on Handl i ng Rul es 1. derieve all your exceptions from mrw::exception 2. write exception specifications as follows: (this specification is "binary", it only declares whether an exception is thrown or not, but it does not specify which exact exception can be thrown) if no exception is thrown, specify throw(std::bad_exception) instead of throw() as you would normally specify if any exception is thrown specify throw(std::exception) (Note: If you need a more specific declaration, you must also declare std::bad_exception in addition to your exceptions!) only declare throw() if you are 100% sure, that it is absolutely impossible that this method ever throws an exception, that means this method calls no other function or method (not even from a system library) that does not declare throw() 3. document the exact exception thrown with Doxygen tag 4. write an unexpected handler as follows (or link to a library): void unexpectedhandler() { try { throw; } catch (mrw::exception& x) { // trace x.stacktrace() and x.what() } catch (std::exception& x) { // trace x.what() } catch (...) { // trace unknown unexpected } throw std::bad_exception(); // try to recover }

31 8.11 Execute UNIX Commands 30 What happens: If you throw an exception in a method that declares not to throw an exception, the unexpected handler is called. It writes a stack trace for you to be able to find your bug. Then it throws a std::bad_exception, which is allowed to pass. Your program does not abort, but continues running. If higher in the stack you catch the exception, you may be able to recover. If you throw an exception where you are allowed to, you only need to catch mrw::exception and you can access what() and stacktrace(). For a proof of concept refer to the example exceptionhandling.cpp. The unexpected handler is implemented ready to use in a separate library Execute UNIX Commands Detailed Description There is no easy way to safely execute UNIX commands and to return the output of the callee to the caller. system ist first of all known to be unsafe, because it opens a shell, and second there is no way to transfer the output back to the caller. On the other hand, starting a new process with fork and exec and passing the output of the callee to the caller using pipes is quite complex and needs much more than one simple line of code. This is the gap that is filled with this command execution classes. There s a class for the command to be executed and a class for the execution of the command. Forking a subprocess and evaluating the result becomes so easy: try { // execute the command: /bin/ls -l /tmp mrw::exec ls = (mrw::cmd("/bin/ls"), "-l", "/tmp").execute(false); // evaluate the result if (ls.success()) std::cout<<"execution successful, result was:"<<std::endl; else std::cerr<<"error in execution, error was:"<<std::endl; std::cout<<ls.result()<<std::endl; std::cerr<<ls.error()<<std::endl; } catch (ExecutionFailedExc& x) { // a fatal execution error occurred // you can trace x.what() and x.stacktrace() } It is also possible to pass an stdin input argument to the subprocess called: try { mrw::exec cat = mrw::cmd("/bin/cat").execute("this is passed to stdin"); // "cat" passes all from stdin to stdout, therefore: assert(cat.result()=="this is passed to stdin"); } catch (...) {} // ignore

32 8.12 File and System Utilities 31 Classes class mrw::executionfailedexc Exception: Execution of command failed. class mrw::exec Execute a command in a new process. class mrw::partialexec Execute a UNIX program in non blocking parts. class mrw::cmd A system command to be executed File and System Utilities Detailed Description By now, some utilies for file handling, i.e. a copy command. Some file and system specific utilities are missing in C++ and often there is even no good alternative in C libraries. Classes class mrw::file File handling utilities. class mrw::dir Directory access Function Tracing (using log4cxx) Collaboration diagram for Function Tracing (using log4cxx): Debug Ut i l i t i es Funct i on Traci ng ( usi ng l og4cxx) Aut omat i c Funct i on Tr ace t o st andar d out f or GNU g++ Aut omat i c Funct i on Tr ace f or GNU g Detailed Description Precondition: #include <mrw/functiontrace.hpp>

33 8.13 Function Tracing (using log4cxx) 32 Place the macro MRW_METHOD as first line of all methods you want to trace, and macro MRW_FUNCTION as first line of all functions to be traced. There are alternative macros MRW_METHOD2 and MRW_FUNCTION2, that allow you to also specify the logging hierarchy. The default for the hierarchy string is "mrw.fntrace". The logging level is always DEBUG and cannot be changed. Attention: Be careful when you copy paste the declarations from one method to the other! Don t forget to correctly change the method s name! I recommend to use a tool like OpenC++ ( to automatically place function trace statements into classes, so that the coder does not have to care about. I have already partly written such a module and I will provide it for free (GPL) when it is good enough. The trace of the following code: \#include <mrw/functiontrace.hpp> \#include <log4cxx/basicconfigurator.h> void fn(int i=0) { MRW_FUNCTION("fn(int)"); // trace entry and exit if (i<4) fn(++i); } class A { public: A() { // not traced method(); } void method() { MRW_METHOD("A::method()"); // trace entry and exit fn(); } }; int main(int, char**) { log4cxx::basicconfigurator::configure(); MRW_FUNCTION("main(int, char**)"); A().method(); return 0; } Produces this output: 1 [ ] DEBUG mrw.fntrace - \ main(int, char**) 1 [ ] DEBUG mrw.fntrace - 0xbfffef3f: \ A::method() 1 [ ] DEBUG mrw.fntrace - \ fn(int) 2 [ ] DEBUG mrw.fntrace - \ fn(int) 2 [ ] DEBUG mrw.fntrace - \ fn(int) 2 [ ] DEBUG mrw.fntrace - \ fn(int) 2 [ ] DEBUG mrw.fntrace - \ fn(int) 2 [ ] DEBUG mrw.fntrace - / fn(int) 2 [ ] DEBUG mrw.fntrace - / fn(int) 2 [ ] DEBUG mrw.fntrace - / fn(int) 3 [ ] DEBUG mrw.fntrace - / fn(int) 3 [ ] DEBUG mrw.fntrace - / fn(int) 3 [ ] DEBUG mrw.fntrace - 0xbfffef3f: / A::method() 3 [ ] DEBUG mrw.fntrace - 0xbfffef3f: \ A::method()

34 8.13 Function Tracing (using log4cxx) 33 3 [ ] DEBUG mrw.fntrace - \ fn(int) 3 [ ] DEBUG mrw.fntrace - \ fn(int) 3 [ ] DEBUG mrw.fntrace - \ fn(int) 4 [ ] DEBUG mrw.fntrace - \ fn(int) 4 [ ] DEBUG mrw.fntrace - \ fn(int) 4 [ ] DEBUG mrw.fntrace - / fn(int) 4 [ ] DEBUG mrw.fntrace - / fn(int) 4 [ ] DEBUG mrw.fntrace - / fn(int) 4 [ ] DEBUG mrw.fntrace - / fn(int) 4 [ ] DEBUG mrw.fntrace - / fn(int) 4 [ ] DEBUG mrw.fntrace - 0xbfffef3f: / A::method() 5 [ ] DEBUG mrw.fntrace - / main(int, char**) The indentation is according to the call stack depth level, the name is preceded by a \ on entry and by a / on exit. The methods are preceded by the address of this, so that different instances can be distinguished. All before and including the dash - is configurable through the normal log4cxx trace patterns. Note: There is also a fully automagic function trace, similar to Automated Unexpected and Terminate Handler. It is described in Automatic Function Trace for GNU g++ and requires the GNU Compiler Collection gcc, because it makes use of a proprietary compiler feature. Modules Automatic Function Trace for GNU g++ Automatic Function Trace to standard out for GNU g++ Classes class mrw::fntrace Defines #define MRW_METHOD(name) mrw::fntrace fntrace(this, name, FILE, LINE ) Declare method entrance, place as first line in method. #define MRW_FUNCTION(name) mrw::fntrace fntrace(name, FILE, _- _LINE ) Declare function entrance, place as first line in functions. #define MRW_METHOD2(name, tracer) mrw::fntrace fntrace(this, name, - FILE, LINE, tracer) Declare method entrance, place as first line in method.

35 8.13 Function Tracing (using log4cxx) 34 #define MRW_FUNCTION2(name, tracer) mrw::fntrace fntrace(name, - FILE, LINE, tracer) Declare function entrance, place as first line in functions. Functions void cyg_profile_func_enter (void, void ) attribute ((no_instrument_- function)) Define Documentation #define MRW_FUNCTION(name) mrw::fntrace fntrace(name, - FILE, LINE ) Declare function entrance, place as first line in functions. Place this macro as first statement in each function that should write a function trace. Example: Parameters: namespace xxx { namespace yyy { void doit(int, char) { MRW_FUNCTION("xxx::yyy::doIt(int, char)"); [...] } } } name the full name of the function, including namespaces Definition at line 190 of file functiontrace.hpp #define MRW_FUNCTION2(name, tracer) mrw::fntrace fn- Trace(name, FILE, LINE, tracer) Declare function entrance, place as first line in functions. Place this macro as first statement in each function that should write a function trace. This macro allows you to define a logging hierarchy string. Example: namespace xxx { namespace yyy { void doit(int, char) { MRW_FUNCTION2("xxx::yyy::doIt(int, char)", "fn.xxx.yyy"); [...] } } }

36 8.13 Function Tracing (using log4cxx) 35 Parameters: name the full name of the function, including namespaces tracer the tracer hierarchy Definition at line 244 of file functiontrace.hpp #define MRW_METHOD(name) mrw::fntrace fntrace(this, name, _- _FILE, LINE ) Declare method entrance, place as first line in method. Place this macro as first statement in each method that should write a function trace. Example: Parameters: namespace xxx { namespace yyy { class Zzz { public: void doit(int, char) { MRW_METHOD("xxx::yyy::Zzz::doIt(int, char)"); [...] } }; } } name the full name of the method, including namespaces and class name Definition at line 168 of file functiontrace.hpp #define MRW_METHOD2(name, tracer) mrw::fntrace fntrace(this, name, FILE, LINE, tracer) Declare method entrance, place as first line in method. Place this macro as first statement in each method that should write a function trace. This macro allows you to define a logging hierarchy string. Example: Parameters: namespace xxx { namespace yyy { class Zzz { public: void doit(int, char) { MRW_METHOD2("xxx::yyy::Zzz::doIt(int, char)", "fn.xxx.yyy.zzz"); [...] } }; } } name the full name of the method, including namespaces and class name