Debug.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2019 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 private:
103  static Context *Current;
104 };
105 
108 FILE *DebugStream();
110 #define debug_log DebugStream()
111 
113 void StopUsingDebugLog();
114 
116 void ResyncDebugLog(FILE *newDestination);
117 
118 /* Debug stream
119  *
120  * Unit tests can enable full debugging to stderr for one
121  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
122  * section number before any header
123  */
124 #define debugs(SECTION, LEVEL, CONTENT) \
125  do { \
126  const int _dbg_level = (LEVEL); \
127  if (Debug::Enabled((SECTION), _dbg_level)) { \
128  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
129  if (_dbg_level > DBG_IMPORTANT) { \
130  _dbo << (SECTION) << ',' << _dbg_level << "| " \
131  << Here() << ": "; \
132  } \
133  _dbo << CONTENT; \
134  Debug::Finish(); \
135  } \
136  } while (/*CONSTCOND*/ 0)
137 
141 std::ostream& ForceAlert(std::ostream& s);
142 
152 inline std::ostream&
153 HERE(std::ostream& s)
154 {
155  return s;
156 }
157 
158 /*
159  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
160  *
161  * debugs(1,1, MYNAME << "WARNING: some message");
162  */
163 #ifdef __PRETTY_FUNCTION__
164 #define MYNAME __PRETTY_FUNCTION__ << " "
165 #else
166 #define MYNAME __FUNCTION__ << " "
167 #endif
168 
169 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
170 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
171 {
172  return (os << (int)d);
173 }
174 
175 /* Legacy debug function definitions */
176 void _db_init(const char *logfile, const char *options);
177 void _db_set_syslog(const char *facility);
178 void _db_rotate_log(void);
179 
184 class Raw
185 {
186 public:
187  Raw(const char *label, const char *data, const size_t size):
188  level(-1), label_(label), data_(data), size_(size), useHex_(false), useGap_(true) {}
189 
191  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
192 
194  Raw &hex() { useHex_ = true; return *this; }
195 
196  Raw &gap(bool useGap = true) { useGap_ = useGap; return *this; }
197 
204  std::ostream &print(std::ostream &os) const;
205 
209  int level;
210 
211 private:
212  void printHex(std::ostream &os) const;
213 
214  const char *label_;
215  const char *data_;
216  size_t size_;
217  bool useHex_;
218  bool useGap_;
219 };
220 
221 inline
222 std::ostream &operator <<(std::ostream &os, const Raw &raw)
223 {
224  return raw.print(os);
225 }
226 
228 template <class Pointer>
229 class RawPointerT {
230 public:
231  RawPointerT(const char *aLabel, const Pointer &aPtr):
232  label(aLabel), ptr(aPtr) {}
233  const char *label;
234  const Pointer &ptr;
235 };
236 
238 template <class Pointer>
240 RawPointer(const char *label, const Pointer &ptr)
241 {
242  return RawPointerT<Pointer>(label, ptr);
243 }
244 
246 template <class Pointer>
247 inline std::ostream &
248 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
249 {
250  os << pd.label << '=';
251  if (pd.ptr)
252  return os << *pd.ptr;
253  else
254  return os << "[nil]";
255 }
256 
258 template <class Integer>
259 class AsHex
260 {
261 public:
262  explicit AsHex(const Integer n): raw(n) {}
263  Integer raw;
264 };
265 
266 template <class Integer>
267 inline std::ostream &
268 operator <<(std::ostream &os, const AsHex<Integer> number)
269 {
270  const auto oldFlags = os.flags();
271  os << std::hex << std::showbase << number.raw;
272  os.setf(oldFlags);
273  return os;
274 }
275 
277 template <class Integer>
278 inline AsHex<Integer> asHex(const Integer n) { return AsHex<Integer>(n); }
279 
280 #endif /* SQUID_DEBUG_H */
281 
static void parseOptions(char const *)
Definition: debug.cc:459
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:844
static int rotateNumber
Definition: Debug.h:82
std::ostream manipulator to print integers as hex numbers prefixed by 0x
Definition: Debug.h:259
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:194
Integer raw
the integer to print
Definition: Debug.h:263
void _db_rotate_log(void)
Definition: debug.cc:502
static bool log_syslog
Definition: Debug.h:86
void _db_set_syslog(const char *facility)
Definition: stub_debug.cc:55
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:812
Raw(const char *label, const char *data, const size_t size)
Definition: Debug.h:187
AsHex(const Integer n)
Definition: Debug.h:262
void _db_init(const char *logfile, const char *options)
Definition: debug.cc:484
static int Level()
minimum level required by the current debugs() call
Definition: Debug.h:91
Definition: Debug.h:52
std::ostringstream buf
debugs() output sink
Definition: Debug.h:70
Ctx ctx_enter(const char *descr)
Definition: debug.cc:715
static int override_X
Definition: Debug.h:84
void const char HLPCB void * data
Definition: stub_helper.cc:16
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:88
int sectionLevel
maximum debugging level allowed during the call
Definition: Debug.h:63
bool useGap_
whether to print leading space if label is missing
Definition: Debug.h:218
meta-information for debugs() or a similar debugging call
Definition: Debug.h:57
bool useHex_
whether hex() has been called
Definition: Debug.h:217
static int log_stderr
Definition: Debug.h:85
#define true
Definition: GnuRegex.c:234
static char * debugOptions
Definition: Debug.h:80
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:103
static char * cache_log
Definition: Debug.h:81
size_t size_
data length
Definition: Debug.h:216
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:69
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Debug.h:170
AsHex< Integer > asHex(const Integer n)
a helper to ease AsHex object creation
Definition: Debug.h:278
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:229
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:153
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:866
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:191
static FILE * logfile
void StopUsingDebugLog()
start logging to stderr (instead of cache.log, if any)
Definition: debug.cc:82
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:797
number
Definition: testStatHist.cc:16
void ctx_exit(Ctx ctx)
Definition: debug.cc:731
const char * label
Definition: Debug.h:233
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:234
Raw & gap(bool useGap=true)
Definition: Debug.h:196
int level
Definition: Debug.h:209
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:83
std::ostream & print(std::ostream &os) const
Definition: debug.cc:886
Definition: Debug.h:184
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Debug.h:75
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:93
FILE * DebugStream()
Definition: debug.cc:77
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:231
int level
minimum debugging level required by the debugs() call
Definition: Debug.h:62
RawPointerT< Pointer > RawPointer(const char *label, const Pointer &ptr)
convenience wrapper for creating RawPointerT<> objects
Definition: Debug.h:240
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:214
void Start(const Comm::ConnectionPointer &conn, IDCB *callback, void *cbdata)
Definition: Ident.cc:237
int size
Definition: ModDevPoll.cc:77
#define false
Definition: GnuRegex.c:233
int Ctx
Definition: Debug.h:37
#define MAX_DEBUG_SECTIONS
Definition: Debug.h:42
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Debug.h:71
const char * data_
raw data to be printed
Definition: Debug.h:215

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors