Debug.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
3  *
4  * Squid software is distributed under GPLv2+ license and includes
5  * contributions from numerous individuals and organizations.
6  * Please see the COPYING and CONTRIBUTORS files for details.
7  */
8 
9 /* DEBUG: section 00 Debug Routines */
10 
11 #ifndef SQUID_DEBUG_H
12 #define SQUID_DEBUG_H
13 
14 #include "base/Here.h"
15 // XXX should be mem/forward.h once it removes dependencies on typedefs.h
16 #include "mem/AllocatorProxy.h"
17 
18 #include <iostream>
19 #undef assert
20 #include <sstream>
21 #include <iomanip>
22 #if defined(assert)
23 #undef assert
24 #endif
25 
26 #if PURIFY
27 #define assert(EX) ((void)0)
28 #elif defined(NODEBUG)
29 #define assert(EX) ((void)0)
30 #elif STDC_HEADERS
31 #define assert(EX) ((EX)?((void)0):xassert( # EX , __FILE__, __LINE__))
32 #else
33 #define assert(EX) ((EX)?((void)0):xassert("EX", __FILE__, __LINE__))
34 #endif
35 
36 /* defined debug section limits */
37 #define MAX_DEBUG_SECTIONS 100
38 
39 /* defined names for Debug Levels */
40 #define DBG_CRITICAL 0
41 #define DBG_IMPORTANT 1
42 /* levels 2-8 are still being discussed amongst the developers */
43 #define DBG_DATA 9
45 #define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
47 class Debug
48 {
49 
50 public:
52  class Context
53  {
54  public:
55  Context(const int aSectionLevel, const int aLevel);
56 
57  int level;
59 
60  private:
61  friend class Debug;
62  void rewind(const int aSection, const int aLevel);
63  void formatStream();
65  std::ostringstream buf;
66  bool forceAlert;
67  };
68 
70  static bool Enabled(const int section, const int level)
71  {
72  return level <= Debug::Levels[section];
73  }
74 
75  static char *debugOptions;
76  static char *cache_log;
77  static int rotateNumber;
79  static int override_X;
80  static int log_stderr;
81  static bool log_syslog;
82 
83  static void parseOptions(char const *);
84 
86  static int Level() { return Current ? Current->level : 1; }
88  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
89 
91  static std::ostringstream &Start(const int section, const int level);
93  static void Finish();
94 
96  static void ForceAlert();
97 
99  static std::ostream& Extra(std::ostream &os) { return os << "\n "; }
100 
101 private:
102  static Context *Current;
103 };
104 
107 FILE *DebugStream();
109 #define debug_log DebugStream()
110 
112 void StopUsingDebugLog();
113 
115 void ResyncDebugLog(FILE *newDestination);
116 
117 /* Debug stream
118  *
119  * Unit tests can enable full debugging to stderr for one
120  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
121  * section number before any header
122  */
123 #define debugs(SECTION, LEVEL, CONTENT) \
124  do { \
125  const int _dbg_level = (LEVEL); \
126  if (Debug::Enabled((SECTION), _dbg_level)) { \
127  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
128  if (_dbg_level > DBG_IMPORTANT) { \
129  _dbo << (SECTION) << ',' << _dbg_level << "| " \
130  << Here() << ": "; \
131  } \
132  _dbo << CONTENT; \
133  Debug::Finish(); \
134  } \
135  } while (/*CONSTCOND*/ 0)
136 
140 std::ostream& ForceAlert(std::ostream& s);
141 
151 inline std::ostream&
152 HERE(std::ostream& s)
153 {
154  return s;
155 }
156 
157 /*
158  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
159  *
160  * debugs(1,1, MYNAME << "WARNING: some message");
161  */
162 #ifdef __PRETTY_FUNCTION__
163 #define MYNAME __PRETTY_FUNCTION__ << " "
164 #else
165 #define MYNAME __FUNCTION__ << " "
166 #endif
167 
168 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
169 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
170 {
171  return (os << (int)d);
172 }
173 
174 /* Legacy debug function definitions */
175 void _db_init(const char *logfile, const char *options);
176 void _db_set_syslog(const char *facility);
177 void _db_rotate_log(void);
178 
183 class Raw
184 {
185 public:
186  Raw(const char *label, const char *data, const size_t size):
187  level(-1), label_(label), data_(data), size_(size), useHex_(false), useGap_(true) {}
188 
190  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
191 
193  Raw &hex() { useHex_ = true; return *this; }
194 
195  Raw &gap(bool useGap = true) { useGap_ = useGap; return *this; }
196 
203  std::ostream &print(std::ostream &os) const;
204 
208  int level;
209 
210 private:
211  void printHex(std::ostream &os) const;
212 
213  const char *label_;
214  const char *data_;
215  size_t size_;
216  bool useHex_;
217  bool useGap_;
218 };
219 
220 inline
221 std::ostream &operator <<(std::ostream &os, const Raw &raw)
222 {
223  return raw.print(os);
224 }
225 
227 template <class Pointer>
228 class RawPointerT {
229 public:
230  RawPointerT(const char *aLabel, const Pointer &aPtr):
231  label(aLabel), ptr(aPtr) {}
232  const char *label;
233  const Pointer &ptr;
234 };
235 
237 template <class Pointer>
239 RawPointer(const char *label, const Pointer &ptr)
240 {
241  return RawPointerT<Pointer>(label, ptr);
242 }
243 
245 template <class Pointer>
246 inline std::ostream &
247 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
248 {
249  os << pd.label << '=';
250  if (pd.ptr)
251  return os << *pd.ptr;
252  else
253  return os << "[nil]";
254 }
255 
257 template <class Integer>
258 class AsHex
259 {
260 public:
261  explicit AsHex(const Integer n): raw(n) {}
262  Integer raw;
263 };
264 
265 template <class Integer>
266 inline std::ostream &
267 operator <<(std::ostream &os, const AsHex<Integer> number)
268 {
269  const auto oldFlags = os.flags();
270  os << std::hex << std::showbase << number.raw;
271  os.setf(oldFlags);
272  return os;
273 }
274 
276 template <class Integer>
277 inline AsHex<Integer> asHex(const Integer n) { return AsHex<Integer>(n); }
278 
280 void PrintHex(std::ostream &, const char *data, size_t n);
281 
282 #endif /* SQUID_DEBUG_H */
283 
static char * debugOptions
Definition: Debug.h:75
int level
Definition: Debug.h:208
static char * cache_log
Definition: Debug.h:76
Definition: Debug.h:48
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:190
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Debug.h:66
void _db_rotate_log(void)
Definition: debug.cc:511
std::ostringstream buf
debugs() output sink
Definition: Debug.h:65
static std::ostream & Extra(std::ostream &os)
prefixes each grouped debugs() line after the first one in the group
Definition: Debug.h:99
void PrintHex(std::ostream &, const char *data, size_t n)
Prints the first n data bytes using hex notation. Does nothing if n is 0.
Definition: debug.cc:724
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:228
Raw(const char *label, const char *data, const size_t size)
Definition: Debug.h:186
const char * label
Definition: Debug.h:232
const char * data_
raw data to be printed
Definition: Debug.h:214
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:90
void _db_init(const char *logfile, const char *options)
Definition: debug.cc:493
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:233
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:88
#define MAX_DEBUG_SECTIONS
Definition: Debug.h:37
number
Definition: testStatHist.cc:16
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Debug.h:70
int level
minimum debugging level required by the debugs() call
Definition: Debug.h:57
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:230
static FILE * logfile
Definition: Debug.h:184
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:78
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Debug.h:169
int size
Definition: ModDevPoll.cc:76
int sectionLevel
maximum debugging level allowed during the call
Definition: Debug.h:58
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:213
meta-information for debugs() or a similar debugging call
Definition: Debug.h:53
bool useHex_
whether hex() has been called
Definition: Debug.h:216
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:690
#define true
Definition: GnuRegex.c:234
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:64
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:152
void _db_set_syslog(const char *facility)
Definition: debug.cc:460
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:658
std::ostream & print(std::ostream &os) const
Definition: debug.cc:740
RawPointerT< Pointer > RawPointer(const char *label, const Pointer &ptr)
convenience wrapper for creating RawPointerT<> objects
Definition: Debug.h:239
static void parseOptions(char const *)
Definition: debug.cc:468
static int rotateNumber
Definition: Debug.h:77
AsHex< Integer > asHex(const Integer n)
a helper to ease AsHex object creation
Definition: Debug.h:277
Integer raw
the integer to print
Definition: Debug.h:262
static bool log_syslog
Definition: Debug.h:81
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:643
void printHex(std::ostream &os) const
void StopUsingDebugLog()
start logging to stderr (instead of cache.log, if any)
Definition: debug.cc:84
AsHex(const Integer n)
Definition: Debug.h:261
static int Level()
minimum level required by the current debugs() call
Definition: Debug.h:86
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:193
static int override_X
Definition: Debug.h:79
void Start(const Comm::ConnectionPointer &conn, IDCB *callback, void *cbdata)
Definition: Ident.cc:264
FILE * DebugStream()
Definition: debug.cc:79
std::ostream manipulator to print integers as hex numbers prefixed by 0x
Definition: Debug.h:259
static int log_stderr
Definition: Debug.h:80
bool useGap_
whether to print leading space if label is missing
Definition: Debug.h:217
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:717
static StatHist s
#define false
Definition: GnuRegex.c:233
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:102
Raw & gap(bool useGap=true)
Definition: Debug.h:195
size_t size_
data length
Definition: Debug.h:215

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors