doc/logflagsenv.txt

   1 HEAD~ Control what gets logged; NOBUG_ENV; environment variable for loging control
   2
   3 The `NOBUG_INIT_FLAG...` calls parsing the environment variable
   4 'NOBUG_LOG' to configure what gets logged at runtime. The syntax is as
   5 following:
   6
   7 .Formal Syntax for log control
   8 [source,prolog]
   9 ----
  10  logdecl_list --> logdecl, any( ',' logdecl_list).
  11
  12  logdecl --> flag, opt(limitdecl, any(targetdecl)).
  13
  14  flag --> "identifier of a flag".
  15
  16  limitdecl --> ':', "LIMITNAME".
  17
  18  targetdecl --> '@', "targetname", opt(targetopts).
  19
  20  targetopts --> '(', "options for target", ')', opt(targetopts).
  21 ----
  22
  23 Roughly speaking, 'NOBUG_LOG' contains a comma separated list of declarations for
  24 flags which are the name of the flag followed by a limit which is written in
  25 all uppercase letters and preceeded by a colon, followed by target declarations
  26 which are names of the targets, introduced by a at sign. Target declarations
  27 can have option, described in the next section. Limit and target
  28 declarations are optional and then choosen from the defaults table above. These
  29 defaults are currently just an guess what should be useable and might be
  30 redefined in future.
  31
  32 .Targets and Options
  33
  34 The Following options are available:
  35
  36  `@ringbuffer`::
  37    `(file=_filename_)`:: set filename backing the ringbuffer
  38    `(size=_nnn_)`::      set size of the ringbuffer
  39    `(append)`::          don't erase existing ringbuffer
  40    `(keep)`::            keep file after application end
  41    `(temp)`::            unlink file instantly at creation
  42
  43  `@console`::
  44    `(fd=n)`::            redirect console output to fd n
  45
  46  `@file`::
  47    `(name=_filename_)`:: log to filename
  48    `(append)`::          append to (existing) log
  49
  50  `@syslog`::
  51    `(ident=_name_)`::    global prefix for syslog
  52    `(cons)`::            log to system console if syslog is down
  53    `(pid)`::             include pid in log
  54    `(perror)`::          log to stderr as well
  55
  56
  57 .How the NOBUG_LOG is used
  58 [source,sh]
  59 ----
  60 # set the limit of the default target a default limit (see table above)
  61 NOBUG_LOG='flag,other'
  62
  63 # set the limit of the default target to DEBUG
  64 NOBUG_LOG='flag:DEBUG'
  65
  66 # set console and syslog limits for flag to DEBUG
  67 NOBUG_LOG='flag:DEBUG@console@syslog'
  68
  69 # trace 'other' to a persistent ringbuffer
  70 NOBUG_LOG='other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
  71 ----
  72
  73 .Using log flags (example.c)
  74 [source,c]
  75 ----
  76 #include "nobug.h"
  77
  78 NOBUG_DEFINE_FLAG (test);
  79
  80 int main()
  81 {
  82    /* NOBUG_INIT;  // not needed because of NOBUG_INIT_FLAG */
  83    NOBUG_INIT_FLAG (test);
  84
  85    TRACE (test, "Logging enabled");
  86    TRACE (NOBUG_ON, "Always on");
  87 }
  88 ----
  89
  90 .test it:
  91 [source,sh]
  92 ----
  93 $ cc -DEBUG_ALPHA -lnobug example.c
  94 $ ./a.out
  95 0000000002: TRACE: example.c:11: main: Always on
  96
  97 $ NOBUG_LOG=test:TRACE ./a.out
  98 0000000001: TRACE: example.c:10: main: Logging enabled
  99 0000000002: TRACE: example.c:11: main: Always on
 100 ----
 101