favicon test
[www_nobug/.git] / nobug_manual.txt
1 NoBug Reference Manual
2 ======================
3 Christian_Thäter,_Benny_Lyons
4
5 [abstract]
6 *****************************************************************
7 NoBug is a debugging library for instrumenting C and C++ programs
8 inspired by ideas originating from Design-by-Contract.
9 *****************************************************************
10
11 [quote]
12 __________________________________________________________________
13 Everyone makes mistakes, but with NoBug you won't make them twice!
14 __________________________________________________________________
15
16 ifdef::basebackend-latex[]
17 Contents
18 --------
19 endif::basebackend-latex[]
20
21 // doc/overview.txt:1 //
22 Overview
23 --------
24
25 The following features are provided by NoBug:
26
27   * Three different check levels: from detailed to final no-overhead
28   * Scope tags: tell whenever a function or loop is considered to be bug free
29   * Precondition, Postcondition and Invariant checks and generic assertions
30   * Data structures can be dumped
31   * Application activities can be logged
32   * Runtime customizable logging via an environment variable
33   * Different logging targets to stderr, syslog, debugger, ...
34   * Annotation of your sourcecode about known bugs, things to do, etc.
35   * Tracking resources (files, locks, etc.) used by your program; help in
36     detecting misuse
37   * Detecting potential deadlocks
38   * Simulate errors by injecting faults
39   * Coverage checking to find out if all (instrumentated) errors are properly handled
40   * Additionally, the NoBug project is used to maintain a script and
41     some tools to setup testsuites
42
43 In contrast to traditional debuggers, NoBug is a non-interactive debugger that
44 is linked to your application doing hard-coded tests in an efficient way
45 without much overhead. Depending on the build level you choose, NoBug features
46 will be an integral part of your application making it possible to gather
47 debugging data for each stage of the application development, including
48 collecting debugging info for finally deployed applications.
49
50
51 .What NoBug can't do
52
53 NoBug is a (macro-)library, it is not a C/C++ language extension. This
54 means that code must be called at runtime to benefit from the set up
55 contracts. What's not tested is likely slipping through the net. Being
56 part of the program itself, it is affected by memory corruption.
57 Certain kinds of misuse may introduce new bugs (assert expressions with
58 side effects for example).
59
60
61 Support
62 ~~~~~~~
63 anchor:mailinglist[]
64
65 When you need help with NoBug, have some ideas about potential features or
66 think you found a bug, then you can contact the NoBug community and developers
67 by sending mail to the NoBug mailinglist. Subscription is available at
68 http://lists.pipapo.org/cgi-bin/mailman/listinfo/nobug[].
69
70 // doc/buildinstall.txt:1 //
71 Building and Installing
72 -----------------------
73
74 Supported Platforms
75 ~~~~~~~~~~~~~~~~~~~
76
77 NoBug has been developed on Linux, using GCC. It should be possible to port
78 it to any other POSIX compliant operating system. Platform/compiler
79 specific things are kept optional. Currently Linux with a GCC that conforms to
80 C99 is supported for both 32 and 64 bit architectures. For non-GCC compilers,
81 some features are not available or degraded.
82
83 [frame="topbot",options="header", cols="<,<,<,<"]
84 |=================================================================================
85 |CPU    |OS          |Compiler    |State
86 |x86_64 |Debian      |gcc4        |supported footnote:[Reference Platform]
87 |x86    |other Linux |gcc4        |supported footnote:[Please report distro specific problems]
88 |armel  |maemo5      |gcc4        |supported footnote:[check fails in SDK (emulator bug)]
89 |x86*   |Mac OS X    |gcc4        |supported
90 |x86    |OpenSolaris |gcc4        |supported
91 |x86    |OpenSolaris |suncc       |mostly    footnote:[some features are not
92 available, needs more testing]
93 |       |*BSD        |            |planned   footnote:[Need volunteer for testing]
94 |=================================================================================
95
96 NoBug has few mandatory dependencies on other software and libraries,
97 some things such as valgrind support are optional and should be automatically
98 detected by `./configure`. Nevertheless it
99 requires 'pkg-config' to be installed or you'll get some weird errors at
100 bootstrapping (`autoreconf`) already.
101
102
103 Release Tarballs
104 ~~~~~~~~~~~~~~~~
105
106 Releases are available at:
107  http://www.pipapo.org/nobug-releases/[]
108
109 Gpg signed tarballs are being used for distribution. The first step involves
110 checking the signature:
111
112  $ gpg nobug-VERSION.tar.gz.gpg
113
114 This will produce a nobug-VERSION.tar.gz and report if the signature could be
115 validated.
116
117 Since they are built with GNU Autotools, the usual build and install procedure
118 will work:
119
120  $ tar xzvf nobug-VERSION.tar.gz
121  $ cd nobug-VERSION
122  $ mkdir -p build
123  $ cd build
124  $ ../configure
125  $ make
126  $ make check           # optional, runs the testsuite
127  $ make install         # to be done as root,
128                         # depending on distribution and setup
129
130
131 Development Version via Git
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
133
134 You can obtain a development version using Git.  The Git repository can be
135 cloned from `git://git.pipapo.org/nobug`.
136
137 Clone the Git repository with:
138
139  $ git clone git://git.pipapo.org/nobug
140
141 After cloning the repository, then bootstrap the Autotools:
142
143  $ cd nobug
144  $ autoreconf -i                # creates the configure file
145
146 Then the usual
147
148  $ cd build && ../configure && make && make install
149
150 (as above) will work. Careful users may run
151
152  $ make check
153
154 to run a testsuite before installing.
155
156
157 Keeping Git Up To Date
158 ^^^^^^^^^^^^^^^^^^^^^^
159
160 To update to any new revision, just enter the nobug dir and
161
162  $ git pull
163
164 After that you can build as above
165
166  $ cd build && ../configure && make && make install
167
168 This default pull will update from the 'master' branch which is meant to be an
169 on-going stable version (latest release and bugfixes).
170
171 Major new releases are assembled in the 'devel' branch, generally this is not
172 considered production ready.
173
174 All other branches are volatile and may be deleted or rebased anytime without
175 further notice.
176
177
178 What Is Installed
179 ~~~~~~~~~~~~~~~~~
180
181 Currently, NoBug installs the following:
182
183   * A single nobug.h headerfile. Include this in your code.
184   * Static libraries. Statically link these to your application:
185     - `libnobug.a` for singlethreaded programs.
186     - `libnobugmt.a` for multithreaded programs.
187   * Dynamic Libraries. Dynamically link these to your application:
188     - `libnobug.so` for singlethreaded programs.
189     - `libnobugmt.so` for multithreaded programs.
190     - associated libtool descriptors (`libnobug*.la`)
191   * Pkgconfig control files:
192     - `nobug.pc` for singlethreaded programs.
193     - `nobugmt.pc` for multithreaded programs.
194   * The `nobug_rbdump` utility to inspect NoBug ringbuffers.
195
196
197 Generating This Documentation
198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199
200 There are Makefile targets for generating the documentation, either one of the
201 following does what you might expect:
202
203  $ make nobug_manual.txt nobug_manual.html nobug_manual.pdf
204
205 Alternatively, you can generate all the documentation in one go as follows:
206
207   $ make doc
208
209 Building the documentation has quite some more dependencies than building
210 NoBug itself. Unless you are a packager you may prefer to refer to the online
211 documentation or the shipped 'README' which is the complete NoBug reference
212 manual in text form. Generating the documentation requires: gawk, asciidoc,
213 graphviz and LaTeX. Check the `[header]` section of doc/latex.conf for required
214 packages.
215
216 // doc/using.txt:1 //
217 Using NoBug
218 -----------
219
220 Your application will have to include the header file 'nobug.h' before NoBug
221 can be used. Prior including this, a Build-level has to be choosen,
222 Build-levels are discussed later, c.f., xref:buildlevel[buildlevel].
223 Build-levels are used to define the amount of information NoBug provides to
224 you. Maximum information is generally required while developing an application
225 and the ALPHA build-level is most apropriate during this phase; whereas the
226 released phase of an application will usually only require sparse information,
227 for which the RELEASE build-level has been conceived.
228
229 A build-level must always be specified, otherwise the compiler will complain
230 while attempting to compile your application.  You can specifiy a build level in
231 one of two ways: use a define statement in one of your modules, or pass the
232 build-level using the -D flag to your compiler.  Assuming we'd like to select
233 the ALPHA build-level in your application, then your module would assume the
234 following form:
235
236  #define EBUG_ALPHA
237  #include <nobug.h>
238
239 Subsequently you'll have to link the appropriate library to your application.
240
241 A number of different libraries are available to link depending on whether you
242 require to statically or dynamically link, or whether your application is multi
243 or single threaded.  The link order is important on your link line.  Link the NoBug
244 library 'after' your application's modules.  Here's how to statically link,
245 single-threaded applications:
246
247 [source,sh]
248 ----------------
249 gcc -o mybinary  $(WHATEVER_FLAGS) \
250        mymodules.o ... -lnobug
251 ----------------
252
253 However, for more flexibility in selecting a build-level, you might wish to
254 define various targets in your makefile, one for each build-level.  In such
255 cases, the -D flag in your makefile is most appropriate; so your link line for
256 an ALPHA build with multi-threaded support would look like the following:
257
258 [source,sh]
259 ----------------
260 gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
261        mymodules.o -lnobugmt
262 ----------------
263
264 The NoBug libraries must be initialised before they can be used. To initialise
265 it call the `NOBUG_INIT` macro, which must be used before any NoBug features
266 can be used or any thread is created. This is discussed in more detail in the
267 xref:multithreading[multithreading] chapter.
268
269 So putting all this together, our application using NoBug might look something
270 like the following:
271
272
273 [source,C]
274 ----------------
275 #define EBUG_ALPHA   /* If we don't use the -D Flag to cc */
276 #include <nobug.h>   /* Include the NoBug API */
277
278 int main()
279 {
280         NOBUG_INIT;  /* Initialise NoBug libs */
281
282         ...
283 }
284 ----------------
285
286
287
288 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
289 included.
290
291
292 Autotools Support
293 ~~~~~~~~~~~~~~~~~
294
295 A project using NoBug can use autoconf to check for execinfo and
296 valgrind:
297
298 [source,sh]
299 ----------------
300 AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
301 PKG_CHECK_MODULES(VALGRIND, [valgrind],
302                             [AC_DEFINE(HAVE_VALGRIND_H)])
303 ----------------
304
305 For Multithreaded programs, you should also check for the availability of pthreads
306 and flavour with the `ACX_PTHREAD` maxro, see:
307
308 +http://ac-archive.sourceforge.net/ac-archive/acx_pthread.html[]+
309
310 When the resulting `HAVE_PTHREAD`, `HAVE_EXECINFO_H` and
311 `HAVE_VALGRIND_H` are defined by the configure script, the
312 relevant features become available.
313
314 `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and `NOBUG_USE_EXECINFO` will be
315 defined depeding on the information gathered by configuration. If you do not
316 want to use any of these features in NoBug, you can override these macros by
317 setting them to `0` before including 'nobug.h'.
318
319 If `NVALGRIND` is defined, there will be no support for valgrind.
320
321 There are many other macros which can be set and overridden by the user to
322 control behavior. Your help would be appreciated in expanding this documentation
323 if you find some features useful; or simply contact any of the authors.
324
325
326 .Using Nobug from a Project using autoconf/automake
327
328 Here is a rather elaborate snippet how to put this all together into a
329 `configure.ac` file:
330
331 [source,sh]
332 ----------------
333 # define autoheader templates for the config macros
334 AH_TEMPLATE(EBUG_ALPHA,
335         [Define to 1 for selecting NoBug ALPHA build level])
336 AH_TEMPLATE(EBUG_BETA,
337         [Define to 1 for selecting NoBug BETA build level])
338 AH_TEMPLATE(NDEBUG,
339         [Define to 1 for selecting NoBug RELEASE build level])
340
341 # set configure options up
342 AC_ARG_ENABLE(alpha, AC_HELP_STRING([--enable-alpha],
343                 [select NoBug ALPHA build level]),
344         nobug_level=alpha
345         AC_DEFINE(EBUG_ALPHA),
346 [
347 AC_ARG_ENABLE(beta, AC_HELP_STRING([--enable-beta],
348                 [select NoBug BETA build level]),
349         nobug_level=beta
350         AC_DEFINE(EBUG_BETA),
351 [
352 AC_ARG_ENABLE(release, AC_HELP_STRING([--enable-release],
353                 [select NoBug RELEASE build level]),
354         nobug_level=release
355         AC_DEFINE(NDEBUG),
356
357 # default to ALPHA
358         nobug_level=alpha
359         AC_DEFINE(EBUG_ALPHA)
360 )])])
361
362 # check for required and optional packages
363 ACX_PTHREAD
364 AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
365 PKG_CHECK_MODULES(VALGRIND, [valgrind],
366         AC_DEFINE(HAVE_VALGRIND_H))
367
368 # finally check for nobug itself, multithreaded here
369 PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= 201006.1],
370         AC_DEFINE(HAVE_NOBUGMT_H),
371         AC_MSG_ERROR([NoBug pkg-config metadata missing])
372 )
373 ----------------
374
375 // doc/additional.txt:1 //
376 Additional Tools
377 ~~~~~~~~~~~~~~~~
378
379 Various peripheral tools can be used by NoBug depending on the requirements
380 of the application and the detail desired by the user.  Such tools can provide
381 additional, detailed information on the application and its behaviour.
382 However, some applications may not require such detail and the associated
383 overhead in information, and users may decide to omit excess information by
384 excluding such tools.
385
386 At the moment NoBug supports the optional inclusion of gdb, valgrind and support
387 for multi-threaded applications and the information that can be provided by
388 these tools.  However, support for other tools may be supplied in the future,
389 e.g. the dbx debugger on OpenSolaris.
390
391
392 // doc/whichlibrary.txt:1 //
393 Link Appropriate Library
394 ~~~~~~~~~~~~~~~~~~~~~~~~
395
396 Finally, the appropriate library (for either single or multi-threaded
397 applications) is linked to the project.
398
399    *libnobug*:: Link-in this library for single threaded applications.
400    *libnobugmt*:: Link with this library for multi-threaded applications.
401
402 NoBug installed static and dynamic libraries. When your application
403 uses multiple dynamic libraries which use NoBug or you build a dynamic
404 library, then you have to link against the dynamic library.
405
406 You can use the `pkg-config` tool to gather information about NoBug in
407 your build system. For example you can query the NoBug version which is
408 installed on your system:
409
410  $ pkg-config --modversion nobug
411  201006.1
412
413 // doc/initialization.txt:1 //
414 Initialization
415 --------------
416
417 Global Initialization
418 ~~~~~~~~~~~~~~~~~~~~~
419
420 Before anything from NoBug can be used, NoBug must be initialised. This
421 is archived by calling the `NOBUG_INIT()` macro before using any other of the
422 NoBug facilities.
423
424 `NOBUG_INIT` can be called more than once, subsequent calls will be a no-op,
425 thus initialising in main and in libraries won't interfere with one another.
426
427 Care must be taken when one already using NoBug features from dynamic
428 initialized things in C++, one has to ensure that NoBug gets initialized first
429 possibly by pulling up a singleton at very first.
430
431
432 Destroying NoBug
433 ~~~~~~~~~~~~~~~~
434
435 Since NoBug is intended to be available throughout its whole lifetime,
436 destroying it is not to be advised. Nevertheless, there is a destroy function
437
438  void nobug_destroy (void);
439
440 to shutdown NoBug, and this frees all resources associated with it.
441 This is mostly used in the NoBug testsuite itself to check for leaks,
442 and it might be useful for other programs which employ some kind of
443 leak checker.
444
445
446 Init logging Flags
447 ~~~~~~~~~~~~~~~~~~
448
449 If you want to use environment variable controlled debuging, then you have to
450 initialize each defined flag with
451
452   NOBUG_INIT_FLAG(flagname)
453
454 or
455
456   NOBUG_INIT_FLAG_LIMIT(flagname, default)
457
458 or one of the C++ compatibility macros.
459
460 This is documented later in the xref:logconfig[logging configuration] chapter.
461
462
463 Threads
464 ~~~~~~~
465
466 In Multithreaded programs you should assign an identifier to each
467 thread. A thread identifier is a string which will be automatically
468 appended with an underscore and an incrementing integer. It is is
469 created using the following:
470
471   NOBUG_THREAD_ID_SET(name)
472
473 For example, calling `NOBUG_THREAD_ID_SET("worker")` will result in a thread
474 identifier 'worker_1'.
475
476 If you don't set an identifier, then NoBug will automatically assign
477 one.  This is further documented in the xref:multithreading[multi threading]
478 section of this manual.
479
480
481 .Initialization example
482 anchor:initexample[]
483
484 Thus the boilerplate code to pulling up NoBug in a multithreaded program looks
485 like (omit `NOBUG_THREAD_ID_SET()` in single threaded programs):
486 [source,C]
487 -------------------------------------------------------
488 #include <nobug.h>
489 NOBUG_DEFINE_FLAG(example);
490
491 ...
492
493 int main()
494 {
495     NOBUG_INIT();
496     NOBUG_THREAD_ID_SET("main");
497     NOBUG_INIT_FLAG(example);
498
499     ...
500 }
501 -------------------------------------------------------
502
503 // doc/buildlevels.txt:1 //
504 Debugging Information Granularity: The Build Levels
505 ---------------------------------------------------
506 anchor:buildlevel[]
507
508 There are three different levels of debugging information available: alpha, beta
509 and release.  One of these levels must be specified before compiling, otherwise
510 an error while compiling will occur.
511
512
513   *ALPHA*::
514         This debugging level is envisaged for the development phase of a project
515         where exhaustive testing and logging are required. All NoBug features
516         are enabled.
517   *BETA*::
518         This debugging level is more appropriate for projects beyond the
519         development phase and ready for field-testing with users willing to
520         test the software. The most expensive debugging features are disabled
521         at this level.
522   *RELEASE*::
523         This level is for final, end-users. Logging is mostly retained but
524         assertions and other checking is disabled.
525
526 .Select a Build Level
527 A logging level can be selected by either using a define before including
528 `nobug.h`, or by passing the appropriate level using the -D switch
529 to the compiler:
530
531     *ALPHA*::
532        `-DEBUG_ALPHA` / `#define EBUG_ALPHA`
533
534     *BETA*::
535        `-DEBUG_BETA` / `#define EBUG_BETA`
536
537     *RELEASE*::
538        `-DNDEBUG` / `#define NDEBUG`
539
540 If a log level has not been selected, NoBug will abort the
541 compilation with an error.
542
543 // doc/logging.txt:1 //
544 Logging Concepts
545 ----------------
546 anchor:loggingconcepts[]
547
548 Nearly all NoBug Macros emit some xref:logformat[log message]. NoBug gives
549 the user fine grained control over these log messages to display only
550 interesting information without loosing details.
551
552 Log messages can be routed to various destinations.  The following destintaions
553 are available:
554
555   *RINGBUFFER*::
556         The underlying storage backend. Messages are appended to the
557         end of the buffer, overwriting older messages at the front of
558         the buffer. NoBug comes with a highly efficient ringbuffer
559         implementation. This ringbuffer is temporary by default but
560         can be made persistent on disk which can be inspected with the
561         'nobug_rbdump' tool.
562
563   *CONSOLE*::
564         This is either just stderr, or, if running under a supported
565         debugger, the debuggers facilities to print messages will be used.
566
567   *FILE*::
568         The user can open files for log messages.
569
570   *SYSLOG*::
571         Messages are sent to the standard system logging daemon.
572
573   *APPLICATION*::
574         There are hooks which allow the programmer to catch logmessages and
575         display them in an application which are defined by the application.
576
577 Each log message has a priority describing its severity in the same way as
578 syslog messages do.
579
580 All non-fatal messages are associated with a programmer defined flag
581 describing the source of the message (subsystem, module, ...). This is
582 referred to as 'channels' in other logging systems. xref:logflags[Flags] make
583 it possible to configure logging in much detail at runtime.
584
585 Putting this all together: A user can define which source/flag will be logged at
586 what priority level and to which destination. To make this all easier, NoBug
587 tries to provide reasonable defaults.
588
589 // doc/logconfiguration.txt:1 //
590 Configuration
591 ~~~~~~~~~~~~~
592 anchor:logconfig[]
593
594 .Log Levels
595
596 Each log macro has an explicit or implicit log-level which
597 correspondends to syslog levels. Logging is only emitted when the
598 message is more severe or the same as a defined limit.
599
600 INDEX Default levels for logging;loggingleveldefaults; table showing defaults log levels
601 [frame="topbot",options="header"]
602 |===============================================================================
603 |            |ALPHA    |BETA    |RELEASE
604 |ringbuffer footnote:[ringbuffer must always be most verbose] |TRACE    |INFO    |NOTICE
605 |console     |INFO     |NOTICE  |-1 footnote:[no log to console in release]
606 |file        |TRACE    |NOTICE  |WARNING
607 |syslog      |-1 footnote:[no syslog for test runs]      |NOTICE  |WARNING
608 |application |INFO     |WARNING |ERROR
609 |===============================================================================
610
611 Depending on the build level, there is a default logging target and a default
612 limit which is selected when the user doesn't specify one.
613
614 .The following default limits are
615 anchor:limitslogging[]
616
617   In *ALPHA* builds::
618      `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
619   In *BETA* builds::
620      `NOBUG_LOG_LIMIT_BETA` is used and defaults to `LOG_WARNING`
621   In *RELEASE* builds::
622      `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
623
624 .The default targets are
625 anchor:targetslogging[]
626
627   In *ALPHA* builds::
628     `NOBUG_LOG_TARGET_ALPHA` defaulting to `NOBUG_TARGET_CONSOLE`
629   In *BETA* builds::
630      `NOBUG_LOG_TARGET_BETA` defaulting to `NOBUG_TARGET_FILE`
631   In *RELEASE* builds::
632      `NOBUG_LOG_TARGET_RELEASE` defaulting to `NOBUG_TARGET_SYSLOG`
633
634 You can override all these values with other limits or targets before
635 including 'nobug.h'. As an alternative, `NOBUG_LOG_LIMIT` and
636 `NOBUG_LOG_TARGET` can be defined to override all defaults at once.
637
638 // doc/logflags.txt:1 //
639 Log Flags
640 ~~~~~~~~~
641 anchor:logflags[]
642
643 Flags are used to inform NoBug about subsystems/modules or even finer
644 grained sections of the code. These are referred to as 'channels' in other
645 logging libraries.
646
647 Flags are generally used as follows:
648
649     . Declare the flag.
650     . Define the flag.
651     . Initialise the flag.
652
653 To declare a flag, it is suggested to do so in a header file:
654 anchor:DECLAREFLAG[]
655
656  NOBUG_DECLARE_FLAG(flagname)
657
658 The flag should then be defined most appropriately in some implementation file
659 by using one of the following macros:
660 anchor:DEFINEFLAG[]
661
662  NOBUG_DEFINE_FLAG(flagname)
663
664 or:
665 anchor:DEFINEFLAGLIMIT[]
666
667  NOBUG_DEFINE_FLAG_LIMIT(flagname, limit)
668
669 Moreover, macros are available that accept a 'parent' flag as a parameter, which is then
670 used to initialize the defaults from another flag:
671 anchor:DEFINEFLAGPARENT[]
672
673  NOBUG_DEFINE_FLAG_PARENT(flagname, parent)
674
675 or
676 anchor:DEFINEFLAGPARENTLIMIT[]
677
678  NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)
679
680 This can be used to create hierarchies of flags.
681
682
683 C\++ support, C++ logflags
684 ^^^^^^^^^^^^^^^^^^^^^^^^^^
685 anchor:Cpluspluslogflags[]
686
687 Additional macros are available for applications written in C++:
688
689  NOBUG_CPP_DEFINE_FLAG(name)
690  NOBUG_CPP_DEFINE_FLAG_PARENT(name, parent)
691  NOBUG_CPP_DEFINE_FLAG_LIMIT(name, default)
692  NOBUG_CPP_DEFINE_FLAG_PARENT_LIMIT(name, parent, default)
693
694 These macros statically initialize the flags when they are defined, there is no
695 need to call `NOBUG_INIT_FLAG()` (see below).
696
697
698 Logging Flag Initialization
699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
700 anchor:INITFLAG[]
701
702 After a flag has been declared and defined, it has to be initialised:
703
704  NOBUG_INIT_FLAG(flagname)
705
706 or
707
708  NOBUG_INIT_FLAG_LIMIT(flagname, default)
709
710 Use either of these macros once at the begining your program for each flag.
711 This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
712 initializing the given flag dynamically.
713
714 For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
715 initialized as in the xref:loggingleveldefaults[table above], while
716 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
717 target (depending on build level) to `level`.
718
719
720 Force declarations only
721 ^^^^^^^^^^^^^^^^^^^^^^^
722 anchor:NOBUGDECLAREONLY[]
723
724 When `NOBUG_DECLARE_ONLY` defined to be `1` then all flag definitions here become
725 declarations only. When this is defined to be `0` (which is the default) then
726 all definitions behave as described. This can be used to construct a
727 headerfile which only contains definitions, but, by default, yield only
728 declarations. This provides one convenient single point to maintain flag
729 configurations.
730
731 .flags.h
732 [source,c]
733 ----
734 #include <nobug.h>
735
736 /*
737  if not included from flags.c then declare the flags,
738  else define them
739  */
740 #ifndef FLAGS_C
741 #define NOBUG_DECLARE_ONLY 1
742 #endif
743
744 /* use only DEFINE_FLAG here */
745 NOBUG_DEFINE_FLAG(example);
746
747 /*
748  Reset it to 0 to cause no trouble
749  */
750 #ifndef FLAGS_C
751 #undef NOBUG_DECLARE_ONLY
752 #define NOBUG_DECLARE_ONLY 0
753 #endif
754 ----
755
756 .flags.c
757 [source,C]
758 ----
759 #define FLAGS_C
760 #include "flags.h"
761 ...
762 ----
763
764 // doc/logflagsenv.txt:1 //
765 Controlling what gets logged
766 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
767 anchor:NOBUGENV[]
768
769 The `NOBUG_INIT_FLAG...` series of macros parse the environment variable
770 '$NOBUG_LOG'. This enviromnet variable is thus used to configure what is
771 logged at runtime. Its syntax is as following:
772
773 [source,prolog]
774 ----
775 logdecl_list --> logdecl, any( ',' logdecl_list).
776
777 logdecl --> flag, opt(limitdecl, any(targetdecl)).
778
779 flag --> "identifier of a flag".
780
781 limitdecl --> ':', "LIMITNAME".
782
783 targetdecl --> '@', "targetname", opt(targetopts).
784
785 targetopts --> '(', "options for target", ')', opt(targetopts).
786 ----
787
788 Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations
789 for flags, which is the name of the flag followed by a limit which is all
790 written in uppercase letters and preceeded by a colon, followed by target
791 declarations which are the names of targets, introduced by an at sign. Target
792 declarations can have options, which are described in the next section. Limit
793 and target declarations are optional and defaults are selected from the
794 xref:loggingleveldefaults[table above]. The defaults presented here are
795 currently an approximation of what might be viable. The default values used
796 here may be redefined in a future release.
797
798 Targets and Options
799 ^^^^^^^^^^^^^^^^^^^
800 anchor:loggingoptions[]
801
802 The Following options are available:
803
804 `@ringbuffer`::
805   `(file=`'filename'`)`:::
806     set 'filename' for the backing ringbuffer
807   `(size=`'nnn'`)`:::
808     set size of the ringbuffer to 'nnn' bytes, rounded-off up to the next page
809     boudary
810   `(append)`:::
811     don't erase existing ringbuffer, start where it left off
812   `(keep)`:::
813     keep file after application ends
814   `(temp)`:::
815     unlink file instantly at creation
816
817 The default ringbuffer is a temporary file in '/tmp' with the `temp` option.
818 This means it will not be available and accessible for inspection, but it also
819 won't leave any stale data behind when the application ends.
820
821
822 `@console`::
823   `(fd=`'n'`)`:::
824     redirect console output to fd 'n'
825
826 When running under a debugger, NoBug tries to use debugger facilities
827 to print console messages.
828
829 `@file`::
830   `(name=`'filename'`)`:::
831     log to 'filename'
832   `(append)`:::
833     append to (existing) logfile
834
835 `@syslog`::
836   `(ident=`'name'`)`:::
837     global prefix for syslog
838   `(cons)`:::
839     log to system console if syslog is down
840   `(pid)`:::
841     include the process identifier in the log
842   `(perror)`:::
843     log to stderr as well (Not available on all systems)
844
845
846 .How $NOBUG_LOG is used
847 [source,sh]
848 ----
849 # set limit to the default target and default limit
850 # (see table above)
851 NOBUG_LOG='flag,other'
852
853 # set the limit of the default target to DEBUG
854 NOBUG_LOG='flag:DEBUG'
855
856 # set console and syslog limits for flag to DEBUG
857 NOBUG_LOG='flag:DEBUG@console@syslog'
858
859 # trace 'other' to a persistent ringbuffer
860 NOBUG_LOG=\
861  'other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
862 ----
863 // src/nobug.c:38 //
864 Predefined Flags
865 ~~~~~~~~~~~~~~~~
866
867 There are some debugging flags which are predefined by NoBug.
868
869 .NOBUG_ON
870 anchor:NOBUGON[]
871
872 The flag `NOBUG_ON` is always enabled at LOG_DEBUG level. This is
873 static and can not be changed.
874
875 .NOBUG_ANN
876 anchor:NOBUGANN[]
877
878 The flag `NOBUG_ANN` is used for the source annotations. This is
879 static and can not be changed. It differs from `NOBUG_ON` as in
880 never logging to syslog and only define a LOG_WARNING limit for the
881 application callback.
882
883 .nobug
884 anchor:nobugflag[]
885
886 Actions on NoBug itself will be logged under the `nobug` flag itself.
887 To see whats going on you can enable it with `NOBUG_LOG=nobug:TRACE`.
888 This is particulary useful to check if `NOBUG_INIT_FLAG()` is called on all flags.
889
890 // doc/logflagsexample.txt:1 //
891
892 .Using log flags (example.c)
893 [source,c]
894 ----
895 #include <nobug.h>
896
897 NOBUG_DEFINE_FLAG (test);
898
899 int main()
900 {
901    NOBUG_INIT;
902    NOBUG_INIT_FLAG (test);
903
904    TRACE (test, "Logging enabled");
905    TRACE (NOBUG_ON, "Always on");
906    return 0;
907 }
908 ----
909
910 .test it:
911 [source,sh]
912 ----
913 $ cc -DEBUG_ALPHA -lnobug example.c
914 $ ./a.out
915 0000000003: TRACE: example.c:11: -: main: Always on
916
917 $ NOBUG_LOG=test:TRACE ./a.out
918 0000000003: TRACE: example.c:10: -: main: Logging enabled
919 0000000004: TRACE: example.c:11: -: main: Always on
920 ----
921
922 // doc/logformat.txt:1 //
923 Log Line Format
924 ~~~~~~~~~~~~~~~
925 anchor:logformat[]
926
927 Logging follows a rather rigid format and is not configurable. This is
928 intentional to make it easier to compare and process logs afterwards. NoBug is
929 designed with the goal to effectively do very fine grained logging and then
930 analyze this logs later, either manually or with further tools.
931
932 A typical log looks like:
933
934  0000000003: TRACE: test.c:10: thread_1: main: message
935  0000000003! TRACE: test.c:10: thread_1: main: continued
936  0000000005: NOTICE: test.c:15: thread_1: main: next
937
938 The components are delimited by ": " or in one case by "! " are as following:
939
940  . *Sequence Number* +
941    Each logging event increments a counter, for preformance (and privacy)
942    reasons we do not use timestamps here. The sequence number is represented by
943    ten decimal digits, overflows are not specially handled. There is a special
944    case that when the final message (see below) spans more log lines, then the
945    delimiter after the sequence number is a "! " and not ": ". The sequence
946    numbers in a log can be sparse because not every event is send to the log,
947    the left out lines are still available in the ringbuffer.
948
949  . *NoBug Facility* +
950    Describes what NoBug macro produced the output. This can be a simple
951    annotation or logging as well as assertions or one of the more complex
952    NoBug facilities.
953
954  . *File and Linenumber* +
955    The filename is only printed without it's path. This is important for some
956    reasons. First it makes the log vastly more readable and second depending
957    on source location and build system and configuration thereof paths are not
958    easily reproducible, this makes it hard to use simple tools like grep or
959    diff on logs generated on different systems. For some messages the filename
960    and/or the linenumber is not available or meaningless, a "-" is used then.
961
962  . *Thread Identifier* +
963    Shows which thread generated this message. The single threaded version of
964    NoBug uses always "-".
965
966  . *Function Name* +
967    Gives the function in which the logging occured. For a lot macros it is
968    possible to pass a context (file, line and function name) around to make it
969    possible to delegate validation and logging to some special functions while
970    still being able to present the context where the call originated. NoBug
971    only uses the function name as identifier here no pretty printed prototype
972    or demangled C++ method. The reason for this is that neither is well
973    specified an may yield to non unique results which may even interfere with
974    the logging format syntax and thus make it very unreliable to write tools
975    to process logs. Some contexts dont provide a function name, a "-" is used
976    then.
977
978  . *Message* +
979    The rest of the log line is the user-defined and optional message part.
980    There are no constraints on the format and one should constrain himself to
981    print only meaningful textual information. Embedded newlines will always be
982    translated into a new logging line as shown in the example above.
983
984 // doc/macros.txt:1 //
985 Macros Overview
986 ---------------
987 anchor:macros[]
988
989 The NoBug interface is almost completely implemented using
990 preprocessor macros. This is required because NoBug uses the
991 +$$__FILE__$$+, +$$__LINE__$$+ and +$$__func__$$+ macros to
992 log information on the current file, line number and function.
993 Moreover, all the flat namespace uppercase identifiers make it easy
994 to recognise the macros in source code.
995 anchor:DISABLESHORTNAMES[]
996
997 All macros are available without condition with a `NOBUG_...` prefix. Many
998 macros (the common cases) are also available without this prefix as a
999 convenience, however macros without this prefix must not have been previously
1000 defined. When `NOBUG_DISABLE_SHORTNAMES` is defined before including
1001 'nobug.h', then only the `NOBUG_` prefixed macros are available and the short
1002 forms will never be defined.
1003
1004 A set of macros are provided by NoBug that are postfixed by `..._IF`. These
1005 macros have the following form:
1006
1007   * `..._IF(when, ...)`
1008
1009 They perform the desired action only if `when` is true. For example:
1010
1011   * `REQUIRE_IF(foo != NULL, foo->something == constrained)`
1012
1013 The assertion will only be performed if `foo` is non `NULL`.
1014
1015 NoBug also contains a facility to pass the xref:NOBUGCONTEXT[source context]
1016 (file, line, function) around, this can be used to write functions which
1017 handle things where one is more interested in the context of the caller rather
1018 than the location where the macro appears.
1019
1020 These macros are postfixed with `..._CTX` and take an extra context
1021 parameter (usually at last but before the logging format specifier and
1022 any variable argument list). The context parameter must be of type
1023 `const struct nobug_context`.
1024
1025 When the `_CTX` context form is used together with the conditional `_IF`
1026 form then the suffix of the macros is always `..._IF_CTX`.
1027
1028 Macros that can accept a context have no short form and must always be
1029 prefixed with `NOBUG_...`.
1030
1031 // doc/parametertable.txt:1 //
1032 Parameters types
1033 ~~~~~~~~~~~~~~~~
1034
1035 We use names for parameters which describe their type. These names are
1036 orthogonal through all macro definitions.
1037
1038 [cols="1,5",frame="topbot"]
1039 |==============================================================================
1040 |`when`    |Assertion is only performed if expression `when` is true at runtime
1041 |`expr`    |Test without side effects
1042 |`flag`    |Destination flag for control logging at runtime
1043 |`type`    |Data type to be checked as a single identifier name
1044 |`pointer` |Pointer to type
1045 |`lvl`     |Log level
1046 |`depth`   |Depth for invariants and dumps
1047 |`context` |Source context of type `struct nobug_context`
1048 |`...`     |printf-like format string followed by its arguments
1049 |==============================================================================
1050
1051 // src/nobug.h:716 //
1052 Source Contexts
1053 ~~~~~~~~~~~~~~~
1054 anchor:NOBUGCONTEXT[]
1055
1056  NOBUG_CONTEXT
1057  NOBUG_CONTEXT_NOFUNC
1058
1059 NoBug passes information about the source location of a given statement in
1060 `const struct nobug_context` structures. These can be generated with
1061 `NOBUG_CONTEXT` or `NOBUG_CONTEXT_NOFUNC`. The later one doesn't define a
1062 function name and must be used when the function context is not available
1063 like in static initialization etc..
1064
1065 // src/nobug.h:146 //
1066 Macros for Assertions
1067 ---------------------
1068 anchor:assertions[]
1069
1070 The assertion set of macros provide a convenient status check on whether
1071 to continue running, or abort execution as some condition was not fulfilled.
1072 Assertion failures are fatal and must abort the application immediately by
1073 calling the xref:ABORT[NOBUG_ABORT] macro which in turn may call a user defined
1074 xref:abortcallback[abort hook].
1075
1076 .CHECK
1077 anchor:CHECK[]
1078
1079  CHECK(expr, ...)
1080  CHECK_IF(when, expr, ...)
1081
1082 This assertion is never optimized out. Its main purpose is in implementing
1083 test suites where one would like to assert tests independent of the build level.
1084
1085 .REQUIRE
1086 anchor:REQUIRE[]
1087
1088  REQUIRE(expr, ...)
1089  REQUIRE_IF(when, expr, ...)
1090  NOBUG_REQUIRE_CTX(expr, context,...)
1091  NOBUG_REQUIRE_IF_CTX(when, expr, context, ...)
1092
1093 Precondition (input) check. Use these macros to validate the input a
1094 function receives. The checks are enabled in *ALPHA* and *BETA* builds,
1095 but have not effect in *RELEASE* builds.
1096
1097 .ENSURE
1098 anchor:ENSURE[]
1099
1100  ENSURE(expr, ...)
1101  ENSURE_IF(when, expr, ...)
1102  NOBUG_ENSURE_CTX(expr, context, ...)
1103  NOBUG_ENSURE_IF_CTX(when, expr, context, ...)
1104
1105 Postcondition (progress/output) check. Use these macros to validate the
1106 data a function produces (example: return value). `ENSURE` is enabled
1107 unconditionally in *ALPHA* builds and have no effect in *BETA* builds for
1108 scopes which are tagged as `CHECKED`.
1109
1110 The `ENSURE_IF` variants are enabled in *ALPHA* and *BETA* builds.
1111
1112 In *RELEASE* builds these checks are optimized out.
1113
1114 .ASSERT
1115 anchor:ASSERT[]
1116
1117  ASSERT(expr, ...)
1118  ASSERT_IF(when, expr, ...)
1119  NOBUG_ASSERT_CTX(expr, context, ...)
1120  NOBUG_ASSERT_IF_CTX(when, expr, context, ...)
1121
1122 Generic check. Use these macros when you want to validate something
1123 which doesn't fall into one of the above categories. Generally to be
1124 avoided! The checks are enabled in *ALPHA* and *BETA* builds and
1125 have no effect in *RELEASE* builds.
1126
1127 .assert
1128 anchor:assert[]
1129
1130  assert(expr)
1131
1132 NoBug overrides the standard `assert` macro, using `NOBUG_ASSERT`.
1133 This is just a compatibility feature, its use is not suggested.
1134
1135 .INVARIANT
1136 anchor:INVARIANT[]
1137
1138  INVARIANT(type, pointer, depth)
1139  INVARIANT_IF(when,type, pointer, depth)
1140  INVARIANT_ASSERT(expr, ...)
1141
1142 Checking invariants. You can provide more complex checking functions
1143 which test the validity of datastructures. Invariants are only enabled
1144 in *ALPHA* builds for scopes which are not tagged as `CHECKED` and
1145 otherwise optimized out.
1146
1147  TODO: describe how to create invariant checks
1148
1149 // src/nobug.h:426 //
1150 Macros That Log Information
1151 ---------------------------
1152 anchor:logging[]
1153
1154 Logging targets a flag (except for `ECHO`) and is done at a log-level related to syslog levels.
1155
1156 .ECHO
1157 anchor:ECHO[]
1158
1159  ECHO(...)
1160
1161 Never optimized out, logs at LOG_NOTICE level. Its main purpose is for implementing
1162 testsuites where one would like to print and log messages independent of the build level
1163
1164 .ALERT
1165 anchor:ALERT[]
1166
1167  ALERT(flag, ...)
1168  ALERT_IF(when, flag, ...)
1169  NOBUG_ALERT_CTX(flag, context, ...)
1170  NOBUG_ALERT_IF_CTX(when, flag, context, ...)
1171
1172 This is the most critical condition that might be registered by
1173 an application. Situations might arise when the application
1174 encounters such a serious error that can only be adequately treated
1175 by, for example, safely shutting down the application.
1176
1177 .CRITICAL
1178 anchor:CRITICAL[]
1179
1180  CRITICAL(flag, ...)
1181  CRITICAL_IF(when, flag, ...)
1182  NOBUG_CRITICAL_CTX(flag, context, ...)
1183  NOBUG_CRITICAL_IF_CTX(when, flag, context, ...)
1184
1185 An error which can not be handled occured but the application does not need to be
1186 shutdowen, perhaps waiting for an operator to fix the cause.
1187
1188 .ERROR
1189 anchor:ERROR[]
1190
1191  ERROR(flag, ...)
1192  ERROR_IF(when, flag, ...)
1193  NOBUG_ERROR_CTX(flag, context, ...)
1194  NOBUG_ERROR_IF_CTX(when, flag, context, ...)
1195
1196 This is used when an application registers an error
1197 and appropriate action will have to be taken.
1198
1199 .WARN
1200 anchor:WARN[]
1201
1202  WARN(flag, ...)
1203  WARN_IF(when, flag, ...)
1204  NOBUG_WARN_CTX(flag, context, ...)
1205  NOBUG_WARN_IF_CTX(when, flag, context, ...)
1206
1207 When an application encounters a rare and unexpected
1208 situation, these macros can be used.
1209
1210 .INFO
1211 anchor:INFO[]
1212
1213  INFO(flag, ...)
1214  INFO_IF(when, flag, ...)
1215  NOBUG_INFO_CTX(flag, context, ...)
1216  NOBUG_INFO_IF_CTX(when, flag, context, ...)
1217
1218 It may be benificial to output information at various
1219 locations throughout the code, e.g., messages on programm
1220 progress.
1221
1222 .NOTICE
1223 anchor:NOTICE[]
1224
1225  NOTICE(flag, ...)
1226  NOTICE_IF(when, flag, ...)
1227  NOBUG_NOTICE_CTX(flag, context, ...)
1228  NOBUG_NOTICE_IF_CTX(when, flag, context, ...)
1229
1230 Same as the INFO() macros, except more verbose.
1231
1232 .TRACE
1233 anchor:TRACE[]
1234
1235  TRACE(flag, ...)
1236  TRACE_IF(when, flag, ...)
1237  NOBUG_TRACE_CTX(flag, context, ...)
1238  NOBUG_TRACE_IF_CTX(when, flag, context, ...)
1239
1240 The same as the NOTICE() macros, except very fine-grained information.
1241 a common use case is to put just `TRACE(debugflag)` just at the begin of every
1242 non-trivial function. This allows to watch fine grained application progress in the log.
1243
1244 NOTE: `TRACE` corresponds to `LOG_DEBUG`, because using `DEBUG` could be ambiguous.
1245
1246 .LOG
1247 anchor:LOG[]
1248
1249  NOBUG_LOG_CTX(flag, lvl, context, ...)
1250  NOBUG_LOG_IF_CTX(when, flag, lvl, context, ...)
1251
1252 Generic logging macro which takes the level explicitly.
1253 Avoid this, unless you implement your own logging facilities.
1254
1255 anchor:LOGEMERG[]
1256
1257 NOTE: there is no logging macro for `LOG_EMERG`, this is only used by the assertions as a fatal message
1258
1259 .LOG_BASELIMIT
1260 anchor:LOGBASELIMIT[]
1261
1262  NOBUG_LOG_BASELIMIT_ALPHA
1263  NOBUG_LOG_BASELIMIT_BETA
1264  NOBUG_LOG_BASELIMIT_RELEASE
1265  NOBUG_LOG_BASELIMIT
1266
1267 Anything more detailed than this base limits will be optimized out.
1268 This is used to reduce the logging overhead for *RELEASE* builds.
1269 By default the limit is set to `LOG_DEBUG` for *ALPHA* and *BETA*
1270 builds, so all logging is retained and `LOG_NOTICE` in *RELEASE*
1271 builds to log the application progress only coarsely.
1272
1273 These macros can be defined before including 'nobug.h' to some other
1274 log level (as defined in 'syslog.h').
1275
1276 // doc/dumping.txt:1 //
1277 Dumping Data Structures
1278 -----------------------
1279 anchor:dumping[]
1280
1281 One can write functions to dump complex data structures using the NoBug
1282 facilities. This is done by writing a custom function for each
1283 data structure to be dumped, which may recursively call other dumping
1284 functions. There are macros that can log within such a dumper function
1285 and to initialise a dump of a given data structure.
1286
1287 A dump function has the prototype:
1288
1289 [source,c]
1290 -------------------------------------------------------
1291 void
1292 nobug_NAME_dump (const struct NAME* POINTER,
1293                  const int DEPTH,
1294                  const struct nobug_context context,
1295                  void* EXTRA);
1296 -------------------------------------------------------
1297
1298 where 'NAME' is the identifier for what you want to dump, 'POINTER' is a pointer
1299 to the data to be dumped, 'DEPTH' is an integer which will be decremented when
1300 recursing into the data structure dumper (your dump function does that, see
1301 below) to limit the recursion depth, 'context' is a source context generated by
1302 nobug when you call DUMP() and 'EXTRA' is a pointer transparently passed around
1303 that you can use to store some additional state. The 'context' variable must
1304 be named `context` because the `DUMP_LOG()` macro relies on this.
1305
1306 // src/nobug.h:363 //
1307 .DUMP
1308 anchor:DUMP[]
1309
1310  DUMP(flag, type, pointer, depth, extra)
1311  DUMP_IF(when, flag, type, pointer, depth, extra)
1312
1313 These macros call a data structure dump of the object (`pointer`) in question.
1314 `DUMP` has only effect in *ALPHA* and *BETA* builds, `DUMP_IF` is also
1315 enabled for RELEASE builds.
1316
1317 `extra` is a void* which is transparently passed around and can be used to
1318 pass a particular state around. NoBug does not alter this.
1319
1320 .DUMP_LOG
1321 anchor:DUMPLOG[]
1322
1323  DUMP_LOG(...)
1324  DUMP_LOG_IF(when, ...)
1325
1326 Any output from `DUMP` handlers should be done by these macros.
1327
1328 .DUMP_LEVEL
1329 anchor:DUMPLEVEL[]
1330
1331  #define NOBUG_DUMP_LEVEL ...
1332
1333 Dumping is by default done at `LOG_DEBUG` level, this can be overridden by
1334 defining `NOBUG_DUMP_LEVEL` to some other logging level.
1335
1336 // doc/dumpexample.txt:1 //
1337 .How to use the DUMP facilities
1338
1339 [source,c]
1340 -------------------------------------------------------
1341 struct STRUCTNAME
1342 {
1343   int INTEGER_MEMBER;
1344   char * STRING_MEMBER;
1345   struct STRUCTNAME* next;
1346 }
1347 -------------------------------------------------------
1348
1349 Thereafter, define a funcion as follows:
1350
1351 [source,c]
1352 -------------------------------------------------------
1353 void
1354 nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
1355                        const int depth,
1356                        const struct nobug_context context,
1357                        void* extra)
1358 {
1359   /* check for self != NULL and that the depth limit
1360      was not exceeded in recursive data structures */
1361   if (self && depth)
1362   {
1363     /* you may or may not do something with the extra
1364        parameter here, extra is transparently
1365        passed around */
1366     (void) extra;
1367
1368     /* use DUMP_LOG not LOG to print the data */
1369     DUMP_LOG("STRUCTNAME %p: int is %d, string is %s", self,
1370                              self->INTEGER_MEMBER,
1371                              self->STRING_MEMBER);
1372
1373     /* now recurse while decrementing depth */
1374     nobug_STRUCTNAME_dump (self->next,
1375                            depth-1,
1376                            context,
1377                            extra);
1378   }
1379 }
1380 -------------------------------------------------------
1381
1382 Now you can use the DUMP() macros within the code
1383
1384 [source,c]
1385 -------------------------------------------------------
1386 example()
1387 {
1388   struct STRUCTNAME foo;
1389   init(&foo);
1390
1391   /* extra can be anything,
1392      NULL is suggested when you don't use it */
1393   DUMP (my_flag, STRUCTNAME, &foo, 2, NULL);
1394 }
1395 -------------------------------------------------------
1396
1397 // src/nobug.h:745 //
1398 Source Code Annotations
1399 -----------------------
1400
1401 Obsolete, buggy or precarious code can be marked in the code itself in
1402 comments at the location where the code occurs.  However these code
1403 locations can be easily overlooked, especially in large projects. NoBug
1404 provides macros to tag code with such annotations. This provides an additional
1405 instrument to alert or remind the programmer that there is still dubious
1406 code embedded in the application. This tagging scheme not only informs
1407 the programmer at compile time that there is code in the application
1408 that needs attending to, but long after compilitation a test team
1409 might become aware of dubious code due to runtime messages.
1410
1411
1412 .DEPRECATED
1413 anchor:DEPRECATED[]
1414
1415  DEPRECATED(...)
1416
1417 Use this macro to identify code that is depreciated
1418 and should not be used in future or productive code.
1419
1420 .UNIMPLEMENTED
1421 anchor:UNIMPLEMENTED[]
1422
1423  UNIMPLEMENTED(...)
1424
1425 Use this macro to identify code that is functionally
1426 not yet complete and should not be used. This is convenient
1427 for code under development or being reviewed.
1428
1429 .FIXME
1430 anchor:FIXME[]
1431
1432  FIXME(...)
1433
1434 Use this macro to mark a known and unfixed bug.
1435
1436 .TODO
1437 anchor:TODO[]
1438
1439  TODO(...)
1440
1441 Enhancement or non-critical bug to be done soon.
1442
1443 .PLANNED
1444 anchor:PLANNED[]
1445
1446  PLANNED(...)
1447
1448 Future enhancement, optimization to similar which has no side effect on the current program.
1449
1450 .NOTREACHED
1451 anchor:NOTREACHED[]
1452
1453  NOTREACHED(...)
1454
1455 Code which must never be reached.
1456
1457 .ELSE_NOTREACHED
1458 anchor:ELSENOTREACHED[]
1459
1460  ELSE_NOTREACHED(...)
1461
1462 This macro is the same as `else NOTREACHED()`, but completely
1463 optimized out in release builds.
1464
1465 // doc/annotationtable.txt:1 //
1466
1467 Annotation Semantics
1468 ~~~~~~~~~~~~~~~~~~~~
1469 anchor:annotationsemantics[]
1470
1471 The action that should be taken when an annotated source line is reached
1472 depends on the build level.
1473
1474 [frame="topbot",options="header"]
1475 |================================================
1476 |              |ALPHA |BETA         |RELEASE
1477 |DEPRECATED    |
1478 log footnote:[will only log once for each source line (not on each hit)] |
1479 nothing footnote:[optimized out, irrelevant] |
1480 won't compile footnote:[aborts compilation with an error message]
1481
1482 |UNIMPLEMENTED |abort footnote:[spew a log message, then abort the program] |
1483 abort |won't compile
1484
1485 |FIXME         |log   |won't compile |won't compile
1486 |TODO          |log   |log          |won't compile
1487 |PLANNED       |log   |nothing      |nothing
1488 |NOTREACHED    |abort |abort        |removed footnote:[optmized out, size]
1489 |================================================
1490
1491 // doc/scopechecks.txt:1 //
1492 Scope Checks
1493 ------------
1494 anchor:CHECKED[]
1495 anchor:UNCHECKED[]
1496
1497 The programmer can tag any scope as `UNCHECKED` or `CHECKED`. In *ALPHA* and *BETA*
1498 builds, a global `UNCHECKED` is implied. In *RELEASE* builds, `UNCHECKED` scopes are
1499 not allowed.
1500
1501 [source,C]
1502 -------
1503 int
1504 myfunc()
1505 {
1506    /* the outer scope of this function is not validated yet*/
1507    UNCHECKED;
1508
1509    if (...)
1510    {
1511       /* everything in this scope is considered ok */
1512       CHECKED;
1513       ...
1514    }
1515    return ...;
1516 }
1517 -------
1518
1519 // doc/assertiontable.txt:1 //
1520 .Assertions active depending on Build level and Scope
1521
1522 [cols="2h,3*3",frame="topbot",options="header",autowidth="something"]
1523 |============================================================================================
1524 |          |ALPHA                                     |BETA                          |RELEASE
1525 |UNCHECKED |Preconditions, Postconditions, Invariants |Preconditions, Postconditions |compiling will abort
1526 |CHECKED   |Preconditions, Postconditions             |Preconditions                 |
1527 |============================================================================================
1528
1529 // src/nobug.h:892 //
1530 Fault injection
1531 ---------------
1532
1533 NoBug has some macros which can be used to simulate erroneous behaviour,
1534 in other words, we can inject errors, or faults, into the code
1535 using NoBug.
1536
1537 .INJECT_GOODBAD
1538 anchor:INJECTGOODBAD[]
1539
1540  INJECT_GOODBAD(expr, good, bad)
1541
1542 Substitutes to an expression and returns 'good' when expr is false and
1543 'bad' when expr is true. In BETA and RELEASE builds 'good' is always returned.
1544
1545 .INJECT_FAULT
1546 anchor:INJECTFAULT[]
1547
1548  INJECT_FAULT(expr, bad)
1549
1550 Substitutes to a statement which executes 'bad'
1551 when expr is true. This is only available in ALPHA builds and
1552 is optimitsed out in BETA and RELEASE builds.
1553
1554 .Setting the logging level for fault injections
1555 anchor:INJECTLEVEL[]
1556 In both cases, when a fault is injected, it will be logged at
1557 `NOBUG_INJECT_LEVEL` (default: `LOG_NOTICE`). This can be defined
1558 before including 'nobug.h' to override it.
1559
1560 // doc/coverageintro.txt:1 //
1561 Fault coverage checking
1562 -----------------------
1563
1564 CAUTION: Fault coverage checking is an experimental feature!
1565
1566 NoBug can automatically inject faults at instrumented points and permute
1567 through all potential error paths of an application by restarting it with the
1568 state from a former run. It can be used to provide information on whether a
1569 particular error is adequately treated in an application. Fault coverage
1570 checking is only available in ALPHA builds; it is optimized out in all other
1571 builds.
1572
1573 NOTE: This kind of testing is very expensive on performance.
1574
1575 How Does Automatic Fault Injection Work?
1576 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1577
1578 First, NoBug checks if the `NOBUG_COVERAGE` environment variable is set. If it
1579 is set, it must contain a space, comma or a semicolon separated list of
1580 filenames which are the logs from a previous run. These logs are then parsed
1581 storing the old state in a lookup tree.
1582
1583 The application will then proceed to run as usual. When an instrumented
1584 coverage point is hit, its status is checked against all states that have been
1585 recorded previously. Any failure point that is encountered for a first time
1586 causes a fault to be injected; the last seen but previously failed point will
1587 now be passed, all other fault injection points behave as in their previous
1588 run. This ensures that each successive run of the application changes only one
1589 injection point and, thus, permutes through all possible code paths.
1590
1591 Fault injection points are identified by a 64bit hash over the backtrace
1592 (return addresses on the stack) leading to it. This means each unique way to
1593 reach an injection point is recorded. Parameters and threads are intentionally
1594 not considered in this calculation.
1595
1596
1597 How to Invoke Fault-Coverage Checking
1598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1599
1600 Each fault-injection point emits a logging message about its identity and
1601 state, this logging uses the normal NoBug logging facilities. Thus, one can
1602 control logging with the `NOBUG_LOG` environment variable. Furthermore, fault
1603 coverage checking is only active when the `NOBUG_COVERAGE` environment
1604 variable has been set to point to log files which are the results from a
1605 previous run. NoBug comes with a `tests/coverage.sh` example script which
1606 permutes through all possible error paths.
1607
1608 // src/nobug.h:944 //
1609 Coverage checking Macros
1610 ~~~~~~~~~~~~~~~~~~~~~~~~
1611
1612 .COVERAGE_FAULT
1613 anchor:COVERAGEFAULT[]
1614
1615  COVERAGE_FAULT(flag, ...)
1616
1617 Injects the statement at `...` when simulating a failure. Only active in
1618 ALPHA builds.
1619
1620 .COVERAGE_GOODBAD
1621 anchor:COVERAGEGOODBAD[]
1622
1623  COVERAGE_GOODBAD(flag, good, bad)
1624
1625 Substitutes to an expression and injects `bad` when simulating a failure and `good`
1626 otherwise. Only active in ALPHA builds.
1627
1628 .COVERAGE_LEVEL
1629 anchor:COVERAGELEVEL[]
1630
1631  #define NOBUG_COVERAGE_LEVEL ...
1632
1633 Define the logging level in which fault-coverage logging is emitted.
1634
1635 NOTE: Supressing log output with this level will not supress fault injection,
1636       actually the opposite is true since every newly seen failure path gets injected.
1637       This might be changed in future releases.
1638
1639 .Disabling and enabling fault-coverage checks
1640 anchor:COVERAGEDISABLE[]
1641
1642  NOBUG_COVERAGE_DISABLE
1643  NOBUG_COVERAGE_ENABLE
1644
1645 Sometimes fault injection yields false positives, errors which may never happen in real life
1646 (and are possibly enforced with an ENSURE afterwards). For this cases coverage fault injection can be
1647 disabled temporarly and reenabled later. Disabling/enabling may nest and must properly match.
1648
1649 // doc/resourcetracking.txt:1 //
1650 Resource Tracking
1651 -----------------
1652
1653 With little effort, NoBug can watch all kinds of resources a program uses. This
1654 becomes useful for resources which are distributed over a multithreaded
1655 program. Resource tracking includes logging actions on resource and checking
1656 locking policies over acquired resources. Resource logging is active in ALPHA
1657 and BETA builds when NOBUG_RESOURCE_LOGGING is defined to 1 (the default).
1658 The resource tracker which supervises locking policies is only enabled in
1659 ALPHA builds.
1660
1661 Concepts
1662 ~~~~~~~~
1663
1664 Resources are an abstract entity for NoBug, which has little knowledge about the
1665 kinds of resources; it only keeps records of resources and the code using
1666 these resources and ensures basic constraints. More detailed checks on resource
1667 usage have to be done with other NoBug facilities.
1668
1669 Resources are identified by an arbitrary identifier which is just a
1670 pointer. Additionally a name, the type and the source locations which
1671 registered the resource are stored.
1672
1673 Code which requiring to use a resource, calls an 'ENTER' macro, supplying
1674 an identifier and state. The state can be altered. Thereafter a 'LEAVE' macro is
1675 used when the the code is finished with the resources.
1676
1677 When a resource is used, one has to pass one of these states:
1678
1679   `NOBUG_RESOURCE_WAITING`::
1680         For resources which might need to be blocked (locks),  enter with a
1681         WAITING state first, as soon at the resource is acquired, change the
1682         state to one of the following.
1683   `NOBUG_RESOURCE_EXCLUSIVE`::
1684         Acquired the resource exclusively. The resource must not be acquired
1685         again, not even from the same thread.
1686   `NOBUG_RESOURCE_RECURSIVE`::
1687         The resource might be entered multiple times from the same
1688         thread with this state.
1689   `NOBUG_RESOURCE_SHARED`::
1690         The resource might be entered multiple times from any thread
1691         with this state.
1692
1693 ["graphviz", "resource-transitions.eps"]
1694 ---------------------------------------------------------------------
1695 strict digraph G
1696 {
1697         edge [fontname=Courier fontsize=10]
1698
1699         start [shape=ellipse]
1700
1701         node [shape=box]
1702
1703         start -> Waiting [label="ENTER()"]
1704         start -> Exclusive [label="ENTER()"]
1705         start -> Recursive [label="ENTER()"]
1706
1707         Waiting -> Exclusive [label="STATE()"]
1708         Waiting -> Recursive [label="STATE()"]
1709
1710         Recursive -> Recursive [label="ENTER()\nSTATE()"]
1711
1712         Waiting -> end [label="LEAVE()"]
1713         Exclusive -> end [label="LEAVE()"]
1714         Recursive -> end [label="LEAVE()"]
1715
1716         end [shape=ellipse]
1717 }
1718 ---------------------------------------------------------------------
1719
1720 Notes
1721 ~~~~~
1722
1723 The Resource Tracker relies on proper announce/forget and enter/leave
1724 are properly paired. The programmer should ensure that this is correctly 
1725 done, otherwise the results are unpredictable.
1726
1727 // src/nobug.h:1229 //
1728 Resource tracking macros
1729 ~~~~~~~~~~~~~~~~~~~~~~~~
1730 anchor:RESOURCELOGGING[]
1731 anchor:RESOURCELOGLEVEL[]
1732
1733 Unless the user defines `NOBUG_RESOURCE_LOGGING` to 0 each of the above macros
1734 will emit a log message at `NOBUG_RESOURCE_LOG_LEVEL` which defaults to
1735 `LOG_DEBUG`.
1736
1737 .RESOURCE_HANDLE
1738 anchor:RESOURCEHANDLE[]
1739
1740  RESOURCE_HANDLE(name)
1741  RESOURCE_HANDLE_INIT(name)
1742  RESOURCE_USER(name)
1743  RESOURCE_USER_INIT(name)
1744
1745 Define and initialize handles for to track resources.
1746
1747  `name`::
1748      identifer to be used for the handle
1749
1750 There are two kinds of handles. Resource themself are abstracted with a
1751 `RESOURCE_HANDLE` while uses of a resources are tracked by `RESOURCE_USER`
1752 handle. These macros takes care that the declaration is optimized out
1753 in the same manner as the rest of the resource tracker would be disabled.
1754 You can still instantiate handles as `struct nobug_resource_record*` or
1755 `struct nobug_resource_user*` in structures which must have a constant size
1756 unconditional of the build level. The two `*_INIT` macros can be used to initialize
1757 resource handles and are optimized out when the resource tracker gets disabled.
1758
1759 .RESOURCE_ANNOUNCE
1760 anchor:RESOURCEANNOUNCE[]
1761
1762  RESOURCE_ANNOUNCE(flag, type, name, identifier, handle){}
1763  NOBUG_RESOURCE_ANNOUNCE_RAW(flagptr, type, name, ptr, handle){}
1764  NOBUG_RESOURCE_ANNOUNCE_RAW_CTX(flagptr, type, name,
1765                                  ptr, handle, context){}
1766
1767 Publishes resources.
1768
1769  `flag`::
1770      the NoBug flag name which turns logging on for this macro
1771  `type`::
1772      a string which should denote the domain of the resource,
1773      examples are "file", "mutex", "lock", "database" and so on
1774  `name`::
1775      the actual name of a named resource this as string. `type` and
1776      `name` must be available through the entire lifetime of the resource, using
1777      literal strings is recommended
1778  `identifier`::
1779      a pointer which must be unique for this resource, any
1780      kind of pointer will suffice, it is only used for identification. In
1781      multithreaded applications the thread identifier becomes an additional
1782      identifier
1783  `handle`::
1784      a `NOBUG_RESOURCE_HANDLE` which will be initialized to point to
1785      the newly created resource.
1786
1787 Resources must be unique, it is a fatal error when a resource it tried to be
1788 announced more than one time.
1789
1790 `RESOURCE_ANNOUNCE()` acts like the head of a C loop statement, it ties to the following
1791 (block-) statement which will be handled atomic.
1792 This statement must not be left by break, return or any other kind of jump.
1793
1794 .RESOURCE_FORGET
1795 anchor:RESOURCEFORGET[]
1796
1797  RESOURCE_FORGET(flag, handle){}
1798  NOBUG_RESOURCE_FORGET_RAW(flagptr, handle){}
1799  NOBUG_RESOURCE_FORGET_RAW_CTX(flagptr, handle, context){}
1800
1801 Removes resources that have become unavailable from the registry.
1802
1803 `flag`::
1804     the NoBug flag which turns logging on for this macro
1805 `handle`::
1806     the `NOBUG_RESOURCE_HANDLE` used to track this resource
1807
1808 The resource must still exist and no users must be attached to it, else a fatal
1809 error is raised.
1810
1811 `RESOURCE_FORGET()` acts like the head of a C loop statement, it ties to the following
1812 (block-) statement which will be handled atomic.
1813 This statement must not be left by break, return or any other kind of jump.
1814
1815 .RESOURCE_RESETALL
1816 anchor:RESOURCERESETALL[]
1817
1818  RESOURCE_RESETALL(flag)
1819  NOBUG_RESOURCE_RESETALL_RAW(flagptr)
1820  NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, context)
1821
1822 Sometimes the resource tracker can give false positives when it finds a locking order violation
1823 while the programmer knows that this will never happen in the real program, because for example
1824 this is only used at initialization or shutdown and never overlaps. This macro can then be used
1825 to reset all whats learnt about all resources and start over.
1826
1827 `flag`::
1828     the NoBug flag which turns logging on for this macro
1829
1830 .RESOURCE_RESET
1831 anchor:RESOURCERESET[]
1832
1833  RESOURCE_RESET(flag, handle)
1834  NOBUG_RESOURCE_RESET_RAW(flagptr, handle)
1835  NOBUG_RESOURCE_RESET_RAW_CTX(flagptr, handle, context)
1836
1837 Sometimes the resource tracker can give false positives when it finds a locking order violation
1838 while the programmer knows that this will never happen in the real program, because for example
1839 this is only used at initialization or shutdown and never overlaps. This macro can then be used
1840 to reset all whats learnt about a single resources and start over.
1841
1842 `flag`::
1843     the NoBug flag which turns logging on for this macro
1844 `handle`::
1845     the `NOBUG_RESOURCE_HANDLE` used to track this resource
1846
1847 .RESOURCE_ENTER
1848 anchor:RESOURCEENTER[]
1849
1850  RESOURCE_ENTER(flag, announced, user, state, handle){}
1851  NOBUG_RESOURCE_ENTER_CTX(flag, resource, user, state,
1852                           handle, context){}
1853
1854 Acquire a resource.
1855
1856 `flag`::
1857     nobug flag which turns logging on for this macro
1858 `announced`::
1859     the handle set by `RESOURCE_ANNOUNCE`
1860 `user`::
1861     a literal string defining the purpose
1862 `state`::
1863     the state to enter
1864 `handle`::
1865     a `NOBUG_RESOURCE_HANDLE` which will be initialized to the
1866     entering node
1867
1868 `RESOURCE_ENTER()` acts like the head of a C loop statement, it ties to the following
1869 (block-) statement which will be handled atomic.
1870 This statement must not be left by break, return or any other kind of jump.
1871
1872 .RESOURCE_WAIT
1873 anchor:RESOURCEWAIT[]
1874
1875  RESOURCE_WAIT(flag, resource, user, handle){}
1876  NOBUG_RESOURCE_WAIT_CTX(flag, resource, user, handle, context){}
1877
1878 This is just an alias for
1879
1880  RESOURCE_ENTER(flag, resource, user,
1881                 NOBUG_RESOURCE_WAITING, handle)
1882
1883 .How to use it
1884 [source,c]
1885 ----
1886 RESOURCE_WAIT(flag, resource, user, handle);
1887 if (lock_my_resource() == ERROR)
1888   NOBUG_RESOURCE_LEAVE(flag, handle);
1889 else
1890   RESOURCE_STATE(flag, NOBUG_RESOURCE_EXCLUSIVE, handle);
1891 ----
1892
1893 .RESOURCE_TRY
1894 anchor:RESOURCETRY[]
1895
1896  RESOURCE_TRY(flag, resource, user, handle){}
1897  NOBUG_RESOURCE_TRY_CTX(flag, resource, user, handle, context){}
1898
1899 This is just an alias for
1900
1901  RESOURCE_ENTER(flag, resource, user,
1902                 NOBUG_RESOURCE_TRYING, handle)
1903
1904 Trying on a resource is similar to waiting but will not trigger a deadlock check. This can be used
1905 when a deadlock is expected at runtime and one handles this otherwise (by a timed wait or something like that).
1906
1907 .RESOURCE_STATE
1908 anchor:RESOURCESTATE[]
1909
1910  RESOURCE_STATE(flag, entered, state){}
1911  NOBUG_RESOURCE_STATE_CTX(flag, state, entered, context){}
1912  NOBUG_RESOURCE_STATE_RAW(flagptr, state, entered){}
1913  NOBUG_RESOURCE_STATE_RAW_CTX(flagptr, state, entered, context){}
1914
1915 Changes resource's state.
1916
1917 `flag`::
1918     is nobug flag which turns logging on for this macro
1919 `state`::
1920     the new state Note that only certain state transitions are
1921     allowed, see discussion/diagram above
1922 `entered`::
1923     the handle set by `RESOURCE_ENTER`
1924
1925 `RESOURCE_STATE()` acts like the head of a C loop statement, it ties to the following
1926 (block-) statement which will be handled atomic.
1927 This statement must not be left by break, return or any other kind of jump.
1928
1929 .RESOURCE_LEAVE
1930 anchor:RESOURCELEAVE[]
1931
1932  RESOURCE_LEAVE(flag, handle){}
1933  NOBUG_RESOURCE_LEAVE_RAW(flagptr, handle){}
1934  NOBUG_RESOURCE_LEAVE_RAW_CTX(flagptr, handle, context){}
1935
1936 Disconnect from a resource identified with its handle.
1937
1938 `flag`::
1939     nobug flag which turns logging on for this macro
1940 `handle`::
1941     the handle you got while entering the resource
1942
1943 `RESOURCE_LEAVE()` acts like the head of a C loop statement, it ties to the following
1944 (block-) statement which will be handled atomic.
1945 This statement must not be left by break, return or any other kind of jump.
1946
1947 .How to use it
1948 [source,c]
1949 ----
1950 NOBUG_RESOURCE_LEAVE(flag, handle)
1951   {
1952     unlock_my_resource();
1953   }
1954 ----
1955
1956 .RESOURCE_ASSERT_STATE
1957 anchor:RESOURCEASSERTSTATE[]
1958
1959  RESOURCE_ASSERT_STATE(resource, state)
1960  RESOURCE_ASSERT_STATE_IF(when, resource, state)
1961  NOBUG_RESOURCE_ASSERT_STATE_CTX(resource, state, context)
1962  NOBUG_RESOURCE_ASSERT_STATE_IF_CTX(when, resource,
1963                                     state, context)
1964
1965 Assert that we have a resource in a given state. For multithreaded programms the topmost
1966 state of the calling thread is checked, for non threadeded programs the most recent state on
1967 resource is used.
1968
1969 `when`::
1970     Condition which must be true for testing the assertion
1971 `resource`::
1972     Resource handle
1973 `state`::
1974     The expected state
1975
1976 .RESOURCE_DUMP
1977 anchor:RESOURCEDUMP[]
1978
1979  NOBUG_RESOURCE_DUMP(flag, handle)
1980  NOBUG_RESOURCE_DUMP_IF(when, flag, handle)
1981
1982 Dump the state of a single resource.
1983
1984 `when`::
1985     Condition which must be true to dump the resource
1986 `flag`::
1987     Nobug flag for the log channel
1988 `handle`::
1989     handle of the resource to be dumped
1990
1991 .RESOURCE_DUMPALL
1992 anchor:RESOURCEDUMPALL[]
1993
1994  NOBUG_RESOURCE_DUMPALL(flag)
1995  NOBUG_RESOURCE_DUMPALL_IF(when, flag)
1996
1997 Dump the state of all resources.
1998
1999 `when`::
2000     Condition which must be true to dump the resources
2001 `flag`::
2002     Nobug flag for the log channel
2003
2004 .RESOURCE_LIST
2005 anchor:RESOURCELIST[]
2006
2007  NOBUG_RESOURCE_LIST(flag)
2008  NOBUG_RESOURCE_LIST_IF(when, flag)
2009
2010 List all registered resources.
2011
2012 `when`::
2013     Condition which must be true to list the resources
2014 `flag`::
2015     Nobug flag for the log channel
2016
2017 // doc/resourceexample.txt:1 //
2018 .How to use the Resourcetracker
2019 [source,c]
2020 ----
2021 NOBUG_DEFINE_FLAG_LIMIT(test, LOG_DEBUG);
2022
2023 void example()
2024 {
2025   /* define a mutex and announce it */
2026   pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
2027   RESOURCE_HANDLE(resource);
2028
2029   /* 'example' is just a pointer to this function
2030      which suffices as unique identifier */
2031   RESOURCE_ANNOUNCE(test, "mutex", "my_mutex",
2032                     example, resource);
2033
2034   /* the following would be done in a
2035      different thread in a real program */
2036
2037   /* define a handle */
2038   RESOURCE_HANDLE(enter);
2039
2040   /* announce that we want to use the resource
2041      &enter also suffices as unique pointer,
2042      which is all we need as identifer here */
2043   RESOURCE_WAIT(flag, resource, &enter, enter)
2044     {
2045       /* lock() might block */
2046       pthread_mutex_lock (&my_mutex);
2047       /* assume no errors, got it, change the state */
2048       RESOURCE_STATE(test, NOBUG_RESOURCE_EXCLUSIVE, enter);
2049     }
2050
2051   /***************************************
2052   ** program does something useful here **
2053   ***************************************/
2054
2055   /* we don't need it anymore */
2056   RESOURCE_LEAVE(test, enter)  /* << no semicolon! */
2057     pthread_mutex_unlock (&my_mutex);
2058
2059   /* back in the main thread */
2060
2061   /* remove the resource from the public registry */
2062   RESOURCE_FORGET(test, resource);
2063 }
2064 ----
2065
2066 // doc/resourcedeadlock.txt:1 //
2067 Deadlock Detection
2068 ~~~~~~~~~~~~~~~~~~
2069
2070 The Resource Tracker is able to detect potential deadlocks. This is done by
2071 learning the relations between locks (precedence) and watching the order in
2072 which resources are acquired. It has some heuristics to detect certain
2073 patterns which are deadlock free. A possible deadlock results in a log message
2074 and a fatal abort. Note that only waiting on resources can lead to a deadlock.
2075 Deadlock detection is implemented in the Resource Tracker and active in ALPHA
2076 builds and optimized out on any other build level.
2077
2078 For details about the deadlock detection algorithm see
2079 xref:deadlockdetection[Appendix: Resource Tracking Alorithm].
2080
2081 // src/nobug.h:2753 //
2082 Callbacks
2083 ---------
2084 anchor:callbacks[]
2085
2086 NoBug provides callbacks, applications can use these
2087 to present logging information in some custom way or hook some special processing in.
2088 The callbacks are initialized to NULL and never modified by NoBug, it is the sole responsibility
2089 of the user to manage them.
2090
2091 CAUTION: There are certain constraints what and what not can be done in callbacks
2092          documented below which must be followed.
2093
2094 .logging callback prototype
2095 anchor:loggingcb[]
2096
2097  typedef void (*nobug_logging_cb)(const struct nobug_flag* flag,
2098                                   int priority,
2099                                   const char *log,
2100                                   void* data)
2101
2102  `flag`::
2103     Flag structure which defines the logging configuration for this event
2104  `priority`::
2105     Log level of the current event
2106  `log`::
2107     Pointing to the current log line in the ringbuffer or `NULL`
2108  `data`::
2109     Global pointer defined by the user, passed arround (see below)
2110
2111 .abort callback prototype
2112 anchor:abortcb[]
2113
2114  typedef void (*nobug_abort_cb)(void* data)
2115
2116  `data`::
2117     Global data defined by the user, passed arround (see below)
2118
2119 .passing data to callbacks
2120 anchor:callbackdata[]
2121
2122  void* nobug_callback_data
2123
2124 This global variable is initialized to `NULL` and will never be touched by NoBug. One can use it
2125 to pass extra data to the callback functions.
2126
2127 .callback when logging
2128 anchor:loggingcallback[]
2129
2130  nobug_logging_cb nobug_logging_callback
2131
2132 This callback gets called when something gets logged.
2133 NoBug will still hold its mutexes when calling this hook, calling NoBug logging or resource tracking
2134 functions from here recursively will deadlock and must be avoided.
2135 The `log` parameter points to the logging message in the ringbuffer.
2136 Unlike other logging targets it is not automatically limited to the log level configured
2137 in the flag but called unconditionally. The callback should implement its own limiting.
2138
2139 When one wants to do complex calls which may include recursion into logging and resource tracking
2140 functions, the intended way is to pass contextual information possibly including a __copy__ of the
2141 `log` parameter in xref:THREADDATA[NOBUG_THREAD_DATA] to the postlogging callback (see below).
2142 Other internal NoBug facilties, like the ringbuffer etc, are protected by the mutexes and may be accessed
2143 from this function.
2144
2145 .callback after logging
2146 anchor:postloggingcallback[]
2147
2148  nobug_logging_cb nobug_postlogging_callback
2149
2150 This callback gets called after something got logged. The `log` parameter is always NULL and all
2151 NoBug mutexes are released. This means that this function may call any complex things, including
2152 calling logging and resource tracking, but may not call internal NoBug facilities.
2153 Contextual created in the `nobug_logging_callback` and stored in xref:THREADDATA[NOBUG_THREAD_DATA] can be
2154 retrieved here and may need to be cleaned up here.
2155
2156 .callback for aborting
2157 anchor:abortcallback[]
2158
2159  nobug_abort_cb nobug_abort_callback
2160
2161 This callback gets called when the application shall be terminated due an error.
2162 It can be used to hook exceptions or similar things in. When it returns, `abort()`
2163 is called.
2164
2165 IMPORTANT: Errors detected by NoBug are always fatal. If one handles and possible
2166            throws an exception here, the application must shut down as soon as possible.
2167            Most causes for aborts are optimitzed out in `RELEASE` builds.
2168
2169 // src/nobug.h:1914 //
2170 Tool Macros
2171 -----------
2172
2173 .NOBUG_FLAG_RAW
2174 anchor:NOBUGFLAGRAW[]
2175
2176  NOBUG_FLAG_RAW(ptr)
2177
2178 Using this macro one can pass a direct pointer to a flag where a name would
2179 be expected. This is sometimes convinient when flag pointers are passed around
2180 in management strutures and one wants to tie logging to dynamic targets.
2181
2182 [source,c]
2183 ----
2184 NOBUG_DEFINE_FLAG(myflag);
2185 ...
2186 struct nobug_flag* ptr = &NOBUG_FLAG(myflag);
2187 TRACE(NOBUG_FLAG_RAW(ptr), "Passed flag by pointer")
2188 ----
2189
2190 .Backtraces
2191 anchor:BACKTRACE[]
2192
2193  BACKTRACE
2194  NOBUG_BACKTRACE_CTX(context)
2195
2196 The backtrace macro logs a stacktrace using the NoBug facilities.
2197 This is automatically called when NoBug finds an error and is due
2198 to abort. But one might call it manually too.
2199
2200 .Aborting
2201 anchor:ABORT[]
2202
2203  NOBUG_ABORT_
2204
2205 This is the default implementation for aborting the program, it first syncs all ringbuffers to disk, then
2206 calls the abort callback if defined and then `abort()`.
2207
2208  NOBUG_ABORT
2209
2210 If not overridden, evaluates to `NOBUG_ABORT_`. One can override this before including
2211 `nobug.h` to customize abortion behaviour. This will be local to the translation unit then.
2212
2213 .NOBUG_ALPHA_COMMA
2214 anchor:NOBUGALPHACOMMA[]
2215
2216  NOBUG_ALPHA_COMMA(something)
2217  NOBUG_ALPHA_COMMA_NULL
2218
2219 Sometimes it is useful to have initializer code only in *ALPHA* builds, for example when you
2220 conditionally include resource handles only in *ALPHA* versions. An initializer can then
2221 use this macros to append a comma and something else only in *ALPHA* builds as in:
2222
2223 [source,C]
2224 ----
2225 struct foo = {"foo", "bar" NOBUG_ALPHA_COMMA_NULL };
2226 ----
2227
2228 Becomes the following in *ALPHA* builds
2229
2230 [source,C]
2231 ----
2232 struct foo = {"foo", "bar", NULL};
2233 ----
2234
2235 and
2236
2237 [source,C]
2238 ----
2239 struct foo = {"foo", "bar"};
2240 ----
2241
2242 in *BETA* and *RELEASE* builds.
2243
2244 .NOBUG_IF_*
2245 anchor:NOBUGIF[]
2246
2247  NOBUG_IF_ALPHA(...)
2248  NOBUG_IF_NOT_ALPHA(...)
2249  NOBUG_IF_BETA(...)
2250  NOBUG_IF_NOT_BETA(...)
2251  NOBUG_IF_RELEASE(...)
2252  NOBUG_IF_NOT_RELEASE(...)
2253
2254 This macros allow one to conditionally include the code in '(...)' only if the
2255 criteria on the build level is met. If not, nothing gets substituted. Mostly used
2256 internally, but can also be used for custom things.
2257
2258 // doc/multithreading.txt:1 //
2259 Multithreading
2260 --------------
2261 anchor:multithreading[]
2262
2263 It is important that NoBug protects certain operations with locks in
2264 multithreaded programs. You have to ensure that 'HAVE_PTHREAD_H' is defined by
2265 the configuration system and use the 'libnobugmt' library for linking. It is
2266 particular important that libraries using NoBug are compiled with
2267 'HAVE_PTHREAD_H' enabled when they are intended to be used in multithreaded
2268 programs.
2269
2270 When Multithreading is used, log messages contain a identifier of the
2271 originating thread. This identifier should be set by
2272
2273 .NOBUG_THREAD_ID_SET
2274 anchor:THREADIDSET[]
2275
2276  NOBUG_THREAD_ID_SET(name)
2277
2278 `name`::
2279         New name for the thread
2280
2281 Nobug will assemble a unique identifier by appending a underscore and a
2282 number to name, for example `NOBUG_THREAD_ID_SET("gui")` will result in a
2283 identifier like 'gui_5'. When you don't set a thread identifier, then NoBug
2284 assigns one automatically with the name 'thread' preprended if needed. Thread
2285 identifiers may be reset with a new call to this macro.
2286
2287 .NOBUG_THREAD_ID_GET
2288 anchor:THREADIDGET[]
2289
2290  NOBUG_THREAD_ID_GET
2291
2292 Will return a const char* of the thread id in multithreaded programs and
2293 a pointer to a literal empty string in singlethreaded programs.
2294
2295 .NOBUG_THREAD_DATA
2296 anchor:THREADDATA[]
2297
2298  NOBUG_THREAD_DATA
2299
2300 Evaluates to a variable of type `void*` which can be used to store
2301 thread local information. This is useable for xref:callbacks[callbacks] which may
2302 prepare context information to be reused later.
2303
2304 This macro is also available in singlethreaded programs, refering to a
2305 single global variable.
2306
2307 Nobug initializes this variable to `NULL` and then touches it never again.
2308
2309 // src/nobug_rbdump.c:33 //
2310 Dumping Persistent Ringbuffers
2311 ------------------------------
2312 anchor:rbdump[]
2313
2314 NoBug installs the `nobug_rbdump` tool for dumping the content of a persistent
2315 ringbuffer. It is invoked with the filename of the ringbuffer, the content is then
2316 printed to stdout.
2317
2318  $ NOBUG_LOG='test:TRACE@ringbuffer(file=test.rb)(keep)' ./a.out
2319  0000000004: TRACE: example.c:11: -: main: Always on
2320  $ nobug_rbdump test.rb
2321  0000000003: TRACE: example.c:10: -: main: Logging
2322  0000000003! TRACE: example.c:10: -: main:  enabled
2323
2324 include::test_inc.txt[]
2325 // doc/bestpractices.txt:1 //
2326 Best Practices
2327 --------------
2328
2329 NOTE: this section is very work in progress
2330
2331 .Workflow
2332
2333  1. Development
2334       * Write a testsuite, build your program with -O0 -g -DEBUG_ALPHA and run
2335         the testsuite under valgrind control. Hack until the program meets the
2336         specifications defined by the testsuite.
2337  2. Beta Test
2338       * Build with desired optimization level and -g -DEBUG_BETA and give the
2339         program to your beta testers.
2340  3. Release
2341       * Build it with optimization and without -g -DEBUG_*
2342
2343 .What and when to check
2344
2345   * Add REQUIRE checks on your interfaces (incoming parameters). Especially if
2346     an argument might not cover the whole range of the underlying type.
2347   * Don't waste your and your CPU's time with unnecessary checks. The testsuite
2348     should validate your program. NoBug aids in debugging. You can add
2349     Postconditions (ENSURE) and Invariants when you have a bug somewhere and
2350     want to nail it down.
2351   * Added checks don't need to be removed.
2352   * When you use the CHECKED/UNCHECKED features then don't forget C scoping
2353     rules, tag things as CHECKED from the leaves to the root.
2354
2355 .Tips & Tricks
2356
2357   * TRACE(flagname) at the begin of every nontrivial function will easily log
2358     the progress of your application.
2359   * Trying a RELEASE build will abort on certain conditions (known BUG, TODO's,
2360     UNCHECKED code), you can use this to find these spots.
2361
2362 Appendix
2363 --------
2364
2365 // src/nobug_resources.c:380 //
2366 The Resource Tracking Algorithm
2367 -------------------------------
2368 anchor:deadlockdetection[]
2369
2370 Each resource registers a global 'resource_record'.
2371
2372 Every new locking path discovered is stored as 'resource_node' structures which refer to the associated
2373 'resource_record'.
2374
2375 Threads keep a trail of 'resource_user' structures for each resource entered. This 'resource_user' struct
2376 refer to the 'resource_nodes' and thus indirectly to the associated 'resource_record'.
2377
2378 The deadlock checker uses this information to test if the acqusition of a new resource would yield a
2379 potential deadlock.
2380
2381 Entering Resources
2382 ~~~~~~~~~~~~~~~~~~
2383 anchor:nobugresourceenter[]
2384
2385 In multithreaded programs, whenever a thread wants to wait for a 'resource_record'
2386 the deadlock checker jumps in.
2387
2388 The deadlock checking algorithm is anticipatory as it will find and abort on conditions which may lead
2389 to a potential deadlock by violating the locking order learned earlier.
2390
2391 Each thread holds a stack (list) of each 'resource_user' it created. Leaving
2392 a resource will remove it from this stacklist.
2393
2394 Each 'resource_record' stores the trail which other 'resource_records' are already entered. This relations
2395 are implemented with the 'resource_node' helper structure.
2396
2397 ////
2398 TODO: insert diagram here
2399   2-3
2400 1
2401   3-4-2
2402
2403 1-3-2-4
2404
2405 3-4-2
2406
2407 1-4-2
2408
2409 ////
2410
2411 First we find out if there is already a node from the to be acquired resource back to
2412 the topmost node of the current threads user stack.
2413
2414 [source,c]
2415 ---------------------------------------------------------------------
2416 struct nobug_resource_user* user = NULL;
2417 struct nobug_resource_node* node = NULL;
2418
2419 if (!llist_is_empty (&tls->res_stack))
2420  {
2421   user = LLIST_TO_STRUCTP (llist_tail (&tls->res_stack),
2422                            struct nobug_resource_user,
2423                            res_stack);
2424
2425   struct nobug_resource_node templ =
2426    {
2427     ...
2428     user->current->resource,
2429     ...
2430    };
2431
2432   node = (struct nobug_resource_node*)
2433    llist_ufind (&resource->nodes,
2434                 &templ.node,
2435                 nobug_resource_node_resource_cmpfn,
2436                 NULL);
2437  }
2438 ...
2439 ---------------------------------------------------------------------
2440
2441 Deadlock checking is only done when the node is entered in `WAITING` state and only
2442 available in multithreaded programs.
2443
2444 [source,c]
2445 ---------------------------------------------------------------------
2446 if (state == NOBUG_RESOURCE_WAITING)
2447  {
2448 #if NOBUG_USE_PTHREAD
2449   ...
2450 ---------------------------------------------------------------------
2451
2452 If node was found above, then this locking path is already validated and no deadlock can happen,
2453 else, if this stack already holds a resource (user is set) we have to go on with checking.
2454
2455 [source,c]
2456 ---------------------------------------------------------------------
2457 if (!node && user)
2458  {
2459   ...
2460 ---------------------------------------------------------------------
2461
2462 If not then its checked that the resource to be entered is not on any parent trail of the current topmost resource,
2463 if it is then this could be a deadlock which needs to be further investigated.
2464
2465 [source,c]
2466 ---------------------------------------------------------------------
2467 LLIST_FOREACH (&user->current->resource->nodes, n)
2468  {
2469   for (struct nobug_resource_node* itr =
2470          ((struct nobug_resource_node*)n)->parent;
2471        itr;
2472        itr = itr->parent)
2473    {
2474     if (itr->resource == resource)
2475      {
2476        ...
2477 ---------------------------------------------------------------------
2478
2479 if the resource was on the trail, we search if there is a common ancestor before the resource
2480 on the trail and the threads current chain,
2481 if yes then this ancestor protects against deadlocks and we can continue.
2482
2483 [source,c]
2484 ---------------------------------------------------------------------
2485 for (struct nobug_resource_node* itr2 = itr->parent;
2486      itr2;
2487      itr2 = itr2->parent)
2488  {
2489   LLIST_FOREACH_REV (&tls->res_stack, p)
2490    {
2491     struct nobug_resource_user* user =
2492      LLIST_TO_STRUCTP (p,
2493                        struct nobug_resource_user,
2494                        res_stack);
2495     if (user->current->resource == itr2->resource)
2496      goto done;
2497    }
2498   ...
2499 ---------------------------------------------------------------------
2500
2501 If no ancestor found, we finally abort with a potential deadlock condition.
2502
2503 [source,c]
2504 ---------------------------------------------------------------------
2505 nobug_resource_error = "possible deadlock detected";
2506 return NULL;
2507 ---------------------------------------------------------------------
2508
2509
2510 Leaving Resources
2511 ~~~~~~~~~~~~~~~~~
2512 anchor:nobugresourceleave[]
2513
2514 store the tail and next aside, we need it later
2515
2516 [source,c]
2517 ---------------------------------------------------------------------
2518 #if NOBUG_USE_PTHREAD
2519 struct nobug_resource_user* tail =
2520  LLIST_TO_STRUCTP (llist_tail (&user->thread->res_stack),
2521                    struct nobug_resource_user,
2522                    res_stack);
2523 struct nobug_resource_user* next =
2524  LLIST_TO_STRUCTP (llist_next (&user->res_stack),
2525                    struct nobug_resource_user,
2526                    res_stack);
2527 ...
2528 ---------------------------------------------------------------------
2529
2530 remove user struct from thread stack
2531 The res_stack is now like it is supposed to look like with the 'user' removed.
2532 We now need to fix the node tree up to match this list.
2533
2534 [source,c]
2535 ---------------------------------------------------------------------
2536 llist_unlink_fast_ (&user->res_stack);
2537 ...
2538 ---------------------------------------------------------------------
2539
2540 When the the user node was not the tail or only node of the thread stack, we have to check
2541 (and possibly construct) a new node chain for it. No valdation of this chain needs to be done,
2542 since it was already validated when entering the resources first.
2543
2544 [source,c]
2545 ---------------------------------------------------------------------
2546 if (user != tail && !llist_is_empty (&user->thread->res_stack))
2547  {
2548   struct nobug_resource_user* parent = NULL;
2549   if (llist_head (&user->thread->res_stack)!= &next->res_stack)
2550    {
2551     parent =
2552      LLIST_TO_STRUCTP (llist_prev (&next->res_stack),
2553                        struct nobug_resource_user,
2554                        res_stack);
2555    }
2556   ...
2557 ---------------------------------------------------------------------
2558
2559 iterate over all users following the removed node, finding nodes pointing to this users or
2560 create new nodes.
2561
2562 [source,c]
2563 ---------------------------------------------------------------------
2564 LLIST_FORRANGE (&next->res_stack, &user->thread->res_stack, n)
2565  {
2566   struct nobug_resource_user* cur =
2567    LLIST_TO_STRUCTP (n,
2568                      struct nobug_resource_user,
2569                      res_stack);
2570
2571   struct nobug_resource_record* resource =
2572    cur->current->resource;
2573   ...
2574 ---------------------------------------------------------------------
2575 // src/nobug_resources.c:745 //
2576
2577 find the node pointing back to parent, create a new one if not found, rinse repeat
2578
2579 [source,c]
2580 ---------------------------------------------------------------------
2581 struct nobug_resource_node templ =
2582  {
2583   ...
2584   parent?parent->current:NULL,
2585   ...
2586  };
2587
2588 struct nobug_resource_node* node =
2589  (struct nobug_resource_node*)
2590  llist_ufind (&resource->nodes,
2591               &templ.node,
2592               nobug_resource_node_parent_cmpfn,
2593               NULL);
2594
2595 if (!node)
2596  {
2597   node = nobug_resource_node_new (resource,
2598                                   parent?parent->current:NULL);
2599   if (!node)
2600    {
2601     nobug_resource_error = "internal allocation error";
2602     return 0;
2603    }
2604  }
2605
2606 parent = cur;
2607 ---------------------------------------------------------------------
2608
2609
2610 Reference Index
2611 ---------------
2612
2613 [dotted]
2614 xref:ABORT[Aborting]:: abort the program
2615 xref:abortcallback[callback for aborting]:: hook to handle a termination
2616 xref:abortcb[abort callback prototype]:: type of a abort callback function
2617 xref:ALERT[ALERT]:: about to die
2618 xref:annotationsemantics[Annotation Semantics]:: actions taken on annotations
2619 xref:ASSERT[ASSERT]:: generic assertion
2620 xref:assert[assert]:: C standard assertion
2621 xref:assertions[Macros for Assertions]:: assert the state of the application
2622 xref:BACKTRACE[Backtraces]:: generate a backtrace
2623 xref:buildlevel[Build Levels]:: selecting the build level
2624 xref:callbackdata[passing data to callbacks]:: data to be passed to callbacks
2625 xref:callbacks[Callbacks]:: function hooks to catch nobug actions
2626 xref:CHECK[CHECK]:: unnconditional assertion for test suites
2627 xref:CHECKED[CHECKED, Scope]:: tag scope as reviewed
2628 xref:COVERAGEDISABLE[Disabling and enabling fault-coverage checks]:: handle false positives
2629 xref:COVERAGEFAULT[COVERAGE_FAULT]:: coverage fault injection, statement
2630 xref:COVERAGEGOODBAD[COVERAGE_GOODBAD]:: coverage fault injection, expression
2631 xref:COVERAGELEVEL[COVERAGE_LEVEL]:: coverage fault injection log level
2632 xref:Cpluspluslogflags[C\++ support, C++ logflags]:: C\++ support for log flags
2633 xref:CRITICAL[CRITICAL]:: can not continue
2634 xref:deadlockdetection[The Resource Tracking Algorithm]:: how resources are tracked
2635 xref:DECLAREFLAG[DECLARE_FLAG]:: declaring a flag
2636 xref:DEFINEFLAG[DEFINE_FLAG]:: defining a flag
2637 xref:DEFINEFLAGLIMIT[DEFINE_FLAG_LIMIT]:: defining a flag w/ log limit
2638 xref:DEFINEFLAGPARENT[DEFINE_FLAG_PARENT]:: defining a flag hierarchy
2639 xref:DEFINEFLAGPARENTLIMIT[DEFINE_FLAG_PARENT_LIMIT]:: defining a flag hierarchy, w/ log limit
2640 xref:DEPRECATED[DEPRECATED]:: to be discarded in future
2641 xref:DISABLESHORTNAMES[DISABLE_SHORTNAMES]:: require NOBUG_ prefix everywhere
2642 xref:DUMP[DUMP]:: dumping datastructures
2643 xref:DUMPLEVEL[DUMP_LEVEL]:: logging level at which DUMPs are done
2644 xref:DUMPLOG[DUMP_LOG]:: logging helper for dumping
2645 xref:dumping[Dumping Data Structures]:: dump complete datastructures
2646 xref:ECHO[ECHO]:: unconditional logging for tests
2647 xref:ELSENOTREACHED[ELSE_NOTREACHED]:: alternative never taken
2648 xref:ENSURE[ENSURE]:: postconditions (computation outcomes)
2649 xref:ERROR[ERROR]:: something gone wrong
2650 xref:FIXME[FIXME]:: known bug
2651 xref:INFO[INFO]:: progress message
2652 xref:INITFLAG[Logging Flag Initialization]:: initialize log flags from environment
2653 xref:initexample[Initialization example]:: initialize NoBug, example
2654 xref:INJECTFAULT[INJECT_FAULT]:: fault injection statement
2655 xref:INJECTGOODBAD[INJECT_GOODBAD]:: fault injection expression
2656 xref:INJECTLEVEL[Setting the logging level for fault injections]:: log level for fault injection
2657 xref:INVARIANT[INVARIANT]:: validate invariant state
2658 xref:limitslogging[The following default limits are]:: default logging limits
2659 xref:LOG[LOG]:: generic logging
2660 xref:LOGBASELIMIT[LOG_BASELIMIT]:: minimum compliled-in logging limit
2661 xref:LOGEMERG[LOG_EMERG]:: no logging macro for emergency logging
2662 xref:logflags[Log Flags]:: define hierarchies for logging output
2663 xref:logformat[Log Line Format]:: format of a log line
2664 xref:logging[Macros That Log Information]:: generate logging messages
2665 xref:loggingcallback[callback when logging]:: hook when something get logged
2666 xref:loggingcb[logging callback prototype]:: type of a logging callback function
2667 xref:loggingconcepts[Logging Concepts]:: destinations for logging output
2668 xref:loggingoptions[Targets and Options]:: configure what gets logged
2669 xref:macros[Macros Overview]:: concepts and parameters for macros
2670 xref:mailinglist[Support]:: how to reach the NoBug developers
2671 xref:multithreading[Multithreading]:: using NoBug in multithreaded programs
2672 xref:NOBUGALPHACOMMA[NOBUG_ALPHA_COMMA]:: append something after a comma in *ALPHA* builds
2673 xref:NOBUGANN[NOBUG_ANN]:: log flag for annotations
2674 xref:NOBUGCONTEXT[Source Contexts]:: pass information about the source location
2675 xref:NOBUGDECLAREONLY[Force declarations only]:: force flag declarations
2676 xref:NOBUGENV[Controlling what gets logged]:: environment variable for loging control
2677 xref:NOBUGFLAGRAW[NOBUG_FLAG_RAW]:: pass direct flag pointer
2678 xref:NOBUGIF[NOBUG_IF_*]:: include code conditionally on build level
2679 xref:NOBUGON[NOBUG_ON]:: log flag which is always enabled
2680 xref:nobugresourceenter[Entering Resources]:: deadlock check on enter
2681 xref:nobugresourceleave[Leaving Resources]:: fix resource lists
2682 xref:nobugflag[nobug]:: log flag used to show nobug actions
2683 xref:NOTICE[NOTICE]:: detailed progress message
2684 xref:NOTREACHED[NOTREACHED]:: code path never taken
2685 xref:PLANNED[PLANNED]:: ideas for future
2686 xref:postloggingcallback[callback after logging]:: hook after something get logged
2687 xref:rbdump[Dumping Persistent Ringbuffers]:: dumping persistent ringbuffers
2688 xref:REQUIRE[REQUIRE]:: preconditions (input parameters)
2689 xref:RESOURCEANNOUNCE[RESOURCE_ANNOUNCE]:: publish new resources
2690 xref:RESOURCEASSERTSTATE[RESOURCE_ASSERT_STATE]:: assert the state of a resource
2691 xref:RESOURCEDUMP[RESOURCE_DUMP]:: dump the state of a single resource
2692 xref:RESOURCEDUMPALL[RESOURCE_DUMPALL]:: dump the state of all resources
2693 xref:RESOURCEENTER[RESOURCE_ENTER]:: claim a resource
2694 xref:RESOURCEFORGET[RESOURCE_FORGET]:: remove resources
2695 xref:RESOURCEHANDLE[RESOURCE_HANDLE]:: define resource handles
2696 xref:RESOURCELEAVE[RESOURCE_LEAVE]:: relinquish a claimed resource
2697 xref:RESOURCELIST[RESOURCE_LIST]:: enumerate all registered resources
2698 xref:RESOURCELOGLEVEL[RESOURCE_LOG_LEVEL]:: select the log level for resource logging
2699 xref:RESOURCELOGGING[RESOURCE_LOGGING]:: switch resource logging on and off
2700 xref:RESOURCERESET[RESOURCE_RESET]:: reset a single resource to a pristine state
2701 xref:RESOURCERESETALL[RESOURCE_RESETALL]:: reset the resource tracker to a pristine state
2702 xref:RESOURCESTATE[RESOURCE_STATE]:: change the state of a resource
2703 xref:RESOURCETRY[RESOURCE_TRY]:: wait for a resource to become available
2704 xref:RESOURCEWAIT[RESOURCE_WAIT]:: wait for a resource to become available
2705 xref:targetslogging[The default targets are]:: default logging targets
2706 xref:THREADDATA[NOBUG_THREAD_DATA]:: thread local data for application use
2707 xref:THREADIDGET[NOBUG_THREAD_ID_GET]:: query thread id
2708 xref:THREADIDSET[NOBUG_THREAD_ID_SET]:: set or reset thread id
2709 xref:TODO[TODO]:: things to be done
2710 xref:TRACE[TRACE]:: debugging level message
2711 xref:UNCHECKED[UNCHECKED, Scope]:: tag scope as unreviewed
2712 xref:UNIMPLEMENTED[UNIMPLEMENTED]:: not yet implemented
2713 xref:WARN[WARN]:: unexpected fixable error
2714
2715 // doc/license.txt:1 //
2716 License
2717 -------
2718
2719  NoBug
2720  Copyright (C)
2721  2006, 2007, 2008, 2009, 2010   Christian Thäter <ct@pipapo.org>
2722
2723  This program is free software; you can redistribute it and/or
2724  modify it under the terms of the GNU General Public License
2725  as published by the Free Software Foundation; either version 2
2726  of the License, or (at your option) any later version.
2727
2728  This program is distributed in the hope that it will be useful,
2729  but WITHOUT ANY WARRANTY; without even the implied warranty of
2730  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2731  GNU General Public License for more details.
2732
2733  You should have received a copy of the GNU General Public
2734  License along with this program; if not, write to the Free
2735  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
2736  Boston, MA 02110-1301 USA.
2737
2738 .License Rationale
2739
2740 NoBug is released under the "GNU General Public License version 2 or
2741 any later" to protect its freedom. If one wants to use NoBug in a
2742 propietary program, please contact the main author for
2743 acknowledging relicensing terms.
2744
2745 For BSD license style Free Software, this means you can not distribute
2746 binaries linking NoBug without making its source available. To make
2747 this compatible, it is suggested that you dual-license your software
2748 with your prefered BSD like license and the GPL. As long as it uses
2749 NoBug, the GPL will take over and you have to make the source
2750 available, while one can ship a BSD or LGPL Licensed headerfile which
2751 defines all NoBug macros as empty macros and remove libnobug from the
2752 linking, then NoBug isn't used anymore and you may apply BSD license
2753 terms for resulting binaries.
2754
2755
2756 .Contributor Agreement
2757
2758 Improvements and patches must be licensed as "GPL v2 or any later" to
2759 be acceptable. Further a contributor must either assign his copyright
2760 to the main NoBug author or agree with the possibility that NoBug can
2761 be relicensed for propietary use:
2762
2763  Independent of the GPL license as stated above, The main author
2764  of NoBug explicitly reserve the right to relicense NoBug under
2765  different, even propietary terms. Any contributor agrees to
2766  such a possiblility by sending his contribution to be included
2767  into the official releases.
2768
2769  This agreement is bilateral, every contributor who worked on a
2770  substantial part of NoBug has the right to relicense it after
2771  negotiation with the NoBug main author. Exact terms of such
2772  relicensing are worked out on a per case base.
2773
2774 The intention is that anyone who worked on NoBug should be able to
2775 benefit from his work. This means one should be able to use it at his
2776 workplace, to gain a job or as well as relicense it for a customer.
2777 Unlike other projects which simply ask for transfering the copyright
2778 to the main author, NoBug tries to make it possible to retain the
2779 copyright by anyone who helped the project.
2780
2781 This additional agreement has no impact on the GPL, it's sole purpose
2782 is to define relicensing policies between the NoBug main author and
2783 contributors. When you recieve NoBug it will be licensed under
2784 GPL unless you personally acknowledged other terms with the NoBug main
2785 author (or any other main contributor).
2786
2787 If anyone feels he is not credited in the 'AUTHORS' file or in any
2788 copyright notice, please contact the main author for inclusion.
2789
2790 Credits
2791 -------
2792
2793 // doc/credits.txt:1 //
2794 Design, implementation::
2795  Christian Thaeter $$<ct@pipapo.org>$$ +
2796
2797 Testsuite::
2798  Christian Thaeter $$<ct@pipapo.org>$$ +
2799
2800 Documentation::
2801  Christian Thaeter $$<ct@pipapo.org>$$ +
2802  Benny Lyons $$<benny.lyons@uniserv.com>$$ +
2803  François KUBLER $$<ih8tehuman@free.fr>$$ +
2804  Andreas Hermann Braml $$<andreas@braml.org>$$ +
2805
2806 Autoconf build system improvements::
2807  Peter Simons $$<simons@cryp.to>$$ +
2808  Luca Barbato $$<lu_zero@gentoo.org>$$ +
2809  Michael Ploujnikov $$<ploujj@gmail.com>$$ +
2810
2811 Ringbuffer dump tool::
2812  Simeon Voelkel $$<simeon_voelkel@arcor.de>$$ +
2813
2814 Logo::
2815  Pablo Lizardo $$<pablo_lizardo@yahoo.com.ar>$$ +
2816
2817