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 /* context-based debugging, the actual type is subject to change */
37 typedef int Ctx;
38 Ctx ctx_enter(const char *descr);
39 void ctx_exit(Ctx ctx);
40 
41 /* defined debug section limits */
42 #define MAX_DEBUG_SECTIONS 100
43 
44 /* defined names for Debug Levels */
45 #define DBG_CRITICAL 0
46 #define DBG_IMPORTANT 1
47 /* levels 2-8 are still being discussed amongst the developers */
48 #define DBG_DATA 9
50 #define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
52 class Debug
53 {
54 
55 public:
57  class Context
58  {
59  public:
60  Context(const int aSectionLevel, const int aLevel);
61 
62  int level;
64 
65  private:
66  friend class Debug;
67  void rewind(const int aSection, const int aLevel);
68  void formatStream();
70  std::ostringstream buf;
71  bool forceAlert;
72  };
73 
75  static bool Enabled(const int section, const int level)
76  {
77  return level <= Debug::Levels[section];
78  }
79 
80  static char *debugOptions;
81  static char *cache_log;
82  static int rotateNumber;
84  static int override_X;
85  static int log_stderr;
86  static bool log_syslog;
87 
88  static void parseOptions(char const *);
89 
91  static int Level() { return Current ? Current->level : 1; }
93  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
94 
96  static std::ostringstream &Start(const int section, const int level);
98  static void Finish();
99 
101  static void ForceAlert();
102 
104  static std::ostream& Extra(std::ostream &os) { return os << "\n "; }
105 
106 private:
107  static Context *Current;
108 };
109 
112 FILE *DebugStream();
114 #define debug_log DebugStream()
115 
117 void StopUsingDebugLog();
118 
120 void ResyncDebugLog(FILE *newDestination);
121 
122 /* Debug stream
123  *
124  * Unit tests can enable full debugging to stderr for one
125  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
126  * section number before any header
127  */
128 #define debugs(SECTION, LEVEL, CONTENT) \
129  do { \
130  const int _dbg_level = (LEVEL); \
131  if (Debug::Enabled((SECTION), _dbg_level)) { \
132  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
133  if (_dbg_level > DBG_IMPORTANT) { \
134  _dbo << (SECTION) << ',' << _dbg_level << "| " \
135  << Here() << ": "; \
136  } \
137  _dbo << CONTENT; \
138  Debug::Finish(); \
139  } \
140  } while (/*CONSTCOND*/ 0)
141 
145 std::ostream& ForceAlert(std::ostream& s);
146 
156 inline std::ostream&
157 HERE(std::ostream& s)
158 {
159  return s;
160 }
161 
162 /*
163  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
164  *
165  * debugs(1,1, MYNAME << "WARNING: some message");
166  */
167 #ifdef __PRETTY_FUNCTION__
168 #define MYNAME __PRETTY_FUNCTION__ << " "
169 #else
170 #define MYNAME __FUNCTION__ << " "
171 #endif
172 
173 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
174 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
175 {
176  return (os << (int)d);
177 }
178 
179 /* Legacy debug function definitions */
180 void _db_init(const char *logfile, const char *options);
181 void _db_set_syslog(const char *facility);
182 void _db_rotate_log(void);
183 
188 class Raw
189 {
190 public:
191  Raw(const char *label, const char *data, const size_t size):
192  level(-1), label_(label), data_(data), size_(size), useHex_(false), useGap_(true) {}
193 
195  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
196 
198  Raw &hex() { useHex_ = true; return *this; }
199 
200  Raw &gap(bool useGap = true) { useGap_ = useGap; return *this; }
201 
208  std::ostream &print(std::ostream &os) const;
209 
213  int level;
214 
215 private:
216  void printHex(std::ostream &os) const;
217 
218  const char *label_;
219  const char *data_;
220  size_t size_;
221  bool useHex_;
222  bool useGap_;
223 };
224 
225 inline
226 std::ostream &operator <<(std::ostream &os, const Raw &raw)
227 {
228  return raw.print(os);
229 }
230 
232 template <class Pointer>
233 class RawPointerT {
234 public:
235  RawPointerT(const char *aLabel, const Pointer &aPtr):
236  label(aLabel), ptr(aPtr) {}
237  const char *label;
238  const Pointer &ptr;
239 };
240 
242 template <class Pointer>
244 RawPointer(const char *label, const Pointer &ptr)
245 {
246  return RawPointerT<Pointer>(label, ptr);
247 }
248 
250 template <class Pointer>
251 inline std::ostream &
252 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
253 {
254  os << pd.label << '=';
255  if (pd.ptr)
256  return os << *pd.ptr;
257  else
258  return os << "[nil]";
259 }
260 
262 template <class Integer>
263 class AsHex
264 {
265 public:
266  explicit AsHex(const Integer n): raw(n) {}
267  Integer raw;
268 };
269 
270 template <class Integer>
271 inline std::ostream &
272 operator <<(std::ostream &os, const AsHex<Integer> number)
273 {
274  const auto oldFlags = os.flags();
275  os << std::hex << std::showbase << number.raw;
276  os.setf(oldFlags);
277  return os;
278 }
279 
281 template <class Integer>
282 inline AsHex<Integer> asHex(const Integer n) { return AsHex<Integer>(n); }
283 
284 #endif /* SQUID_DEBUG_H */
285 
static char * debugOptions
Definition: Debug.h:80
int level
Definition: Debug.h:213
static char * cache_log
Definition: Debug.h:81
Definition: Debug.h:53
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:195
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Debug.h:71
void _db_rotate_log(void)
Definition: debug.cc:508
int Ctx
Definition: Debug.h:37
std::ostringstream buf
debugs() output sink
Definition: Debug.h:70
static std::ostream & Extra(std::ostream &os)
prefixes each grouped debugs() line after the first one in the group
Definition: Debug.h:104
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:233
Raw(const char *label, const char *data, const size_t size)
Definition: Debug.h:191
const char * label
Definition: Debug.h:237
const char * data_
raw data to be printed
Definition: Debug.h:219
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:89
void _db_init(const char *logfile, const char *options)
Definition: debug.cc:490
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:238
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:93
#define MAX_DEBUG_SECTIONS
Definition: Debug.h:42
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:75
int level
minimum debugging level required by the debugs() call
Definition: Debug.h:62
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:235
static FILE * logfile
Definition: Debug.h:189
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:83
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Debug.h:174
int size
Definition: ModDevPoll.cc:77
int sectionLevel
maximum debugging level allowed during the call
Definition: Debug.h:63
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:218
meta-information for debugs() or a similar debugging call
Definition: Debug.h:58
bool useHex_
whether hex() has been called
Definition: Debug.h:221
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:850
#define true
Definition: GnuRegex.c:234
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:69
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:157
void _db_set_syslog(const char *facility)
Definition: stub_debug.cc:55
void const char HLPCB void * data
Definition: stub_helper.cc:16
Ctx ctx_enter(const char *descr)
Definition: debug.cc:721
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:818
std::ostream & print(std::ostream &os) const
Definition: debug.cc:897
RawPointerT< Pointer > RawPointer(const char *label, const Pointer &ptr)
convenience wrapper for creating RawPointerT<> objects
Definition: Debug.h:244
static void parseOptions(char const *)
Definition: debug.cc:465
static int rotateNumber
Definition: Debug.h:82
AsHex< Integer > asHex(const Integer n)
a helper to ease AsHex object creation
Definition: Debug.h:282
Integer raw
the integer to print
Definition: Debug.h:267
static bool log_syslog
Definition: Debug.h:86
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:803
void printHex(std::ostream &os) const
print data bytes using hex notation
Definition: debug.cc:885
void StopUsingDebugLog()
start logging to stderr (instead of cache.log, if any)
Definition: debug.cc:83
AsHex(const Integer n)
Definition: Debug.h:266
static int Level()
minimum level required by the current debugs() call
Definition: Debug.h:91
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:198
static int override_X
Definition: Debug.h:84
void Start(const Comm::ConnectionPointer &conn, IDCB *callback, void *cbdata)
Definition: Ident.cc:237
void ctx_exit(Ctx ctx)
Definition: debug.cc:737
FILE * DebugStream()
Definition: debug.cc:78
std::ostream manipulator to print integers as hex numbers prefixed by 0x
Definition: Debug.h:264
static int log_stderr
Definition: Debug.h:85
bool useGap_
whether to print leading space if label is missing
Definition: Debug.h:222
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:877
#define false
Definition: GnuRegex.c:233
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:107
Raw & gap(bool useGap=true)
Definition: Debug.h:200
size_t size_
data length
Definition: Debug.h:220

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors