Debug.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2018 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  };
72 
74  static bool Enabled(const int section, const int level)
75  {
76  return level <= Debug::Levels[section];
77  }
78 
79  static char *debugOptions;
80  static char *cache_log;
81  static int rotateNumber;
83  static int override_X;
84  static int log_stderr;
85  static bool log_syslog;
86 
87  static void parseOptions(char const *);
88 
90  static int Level() { return Current ? Current->level : 1; }
92  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
93 
95  static std::ostringstream &Start(const int section, const int level);
97  static void Finish();
98 
99 private:
100  static Context *Current;
101 };
102 
105 FILE *DebugStream();
107 #define debug_log DebugStream()
108 
110 void StopUsingDebugLog();
111 
113 void ResyncDebugLog(FILE *newDestination);
114 
115 /* Debug stream
116  *
117  * Unit tests can enable full debugging to stderr for one
118  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
119  * section number before any header
120  */
121 #define debugs(SECTION, LEVEL, CONTENT) \
122  do { \
123  const int _dbg_level = (LEVEL); \
124  if (Debug::Enabled((SECTION), _dbg_level)) { \
125  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
126  if (_dbg_level > DBG_IMPORTANT) { \
127  _dbo << (SECTION) << ',' << _dbg_level << "| " \
128  << Here() << ": "; \
129  } \
130  _dbo << CONTENT; \
131  Debug::Finish(); \
132  } \
133  } while (/*CONSTCOND*/ 0)
134 
144 inline std::ostream&
145 HERE(std::ostream& s)
146 {
147  return s;
148 }
149 
150 /*
151  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
152  *
153  * debugs(1,1, MYNAME << "WARNING: some message");
154  */
155 #ifdef __PRETTY_FUNCTION__
156 #define MYNAME __PRETTY_FUNCTION__ << " "
157 #else
158 #define MYNAME __FUNCTION__ << " "
159 #endif
160 
161 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
162 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
163 {
164  return (os << (int)d);
165 }
166 
167 /* Legacy debug function definitions */
168 void _db_init(const char *logfile, const char *options);
169 void _db_print(const char *,...) PRINTF_FORMAT_ARG1;
170 void _db_set_syslog(const char *facility);
171 void _db_rotate_log(void);
172 
178 {
179 public:
180  Raw(const char *label, const char *data, const size_t size):
181  level(-1), label_(label), data_(data), size_(size), useHex_(false) {}
182 
184  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
185 
187  Raw &hex() { useHex_ = true; return *this; }
188 
195  std::ostream &print(std::ostream &os) const;
196 
200  int level;
201 
202 private:
203  void printHex(std::ostream &os) const;
204 
205  const char *label_;
206  const char *data_;
207  size_t size_;
208  bool useHex_;
209 };
210 
211 inline
212 std::ostream &operator <<(std::ostream &os, const Raw &raw)
213 {
214  return raw.print(os);
215 }
216 
218 template <class Pointer>
219 class RawPointerT {
220 public:
221  RawPointerT(const char *aLabel, const Pointer &aPtr):
222  label(aLabel), ptr(aPtr) {}
223  const char *label;
224  const Pointer &ptr;
225 };
226 
228 template <class Pointer>
230 RawPointer(const char *label, const Pointer &ptr)
231 {
232  return RawPointerT<Pointer>(label, ptr);
233 }
234 
236 template <class Pointer>
237 inline std::ostream &
238 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
239 {
240  os << pd.label << '=';
241  if (pd.ptr)
242  return os << *pd.ptr;
243  else
244  return os << "[nil]";
245 }
246 
248 template <class Integer>
249 class AsHex
250 {
251 public:
252  explicit AsHex(const Integer n): raw(n) {}
253  Integer raw;
254 };
255 
256 template <class Integer>
257 inline std::ostream &
258 operator <<(std::ostream &os, const AsHex<Integer> number)
259 {
260  const auto oldFlags = os.flags();
261  os << std::hex << std::showbase << number.raw;
262  os.setf(oldFlags);
263  return os;
264 }
265 
267 template <class Integer>
268 inline AsHex<Integer> asHex(const Integer n) { return AsHex<Integer>(n); }
269 
270 #endif /* SQUID_DEBUG_H */
271 
static void parseOptions(char const *)
Definition: debug.cc:456
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:836
static int rotateNumber
Definition: Debug.h:81
std::ostream manipulator to print integers as hex numbers prefixed by 0x
Definition: Debug.h:249
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:187
Integer raw
the integer to print
Definition: Debug.h:253
void _db_rotate_log(void)
Definition: debug.cc:499
static bool log_syslog
Definition: Debug.h:85
std::ostream & print(std::ostream &os) const
Definition: debug.cc:862
void _db_set_syslog(const char *facility)
Definition: stub_debug.cc:54
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:804
Raw(const char *label, const char *data, const size_t size)
Definition: Debug.h:180
AsHex(const Integer n)
Definition: Debug.h:252
void _db_init(const char *logfile, const char *options)
Definition: debug.cc:481
static int Level()
minimum level required by the current debugs() call
Definition: Debug.h:90
Definition: Debug.h:52
std::ostringstream buf
debugs() output sink
Definition: Debug.h:70
Ctx ctx_enter(const char *descr)
Definition: debug.cc:708
static int override_X
Definition: Debug.h:83
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
meta-information for debugs() or a similar debugging call
Definition: Debug.h:57
bool useHex_
whether hex() has been called
Definition: Debug.h:208
static int log_stderr
Definition: Debug.h:84
static char * debugOptions
Definition: Debug.h:79
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:100
static char * cache_log
Definition: Debug.h:80
size_t size_
data length
Definition: Debug.h:207
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:69
void _db_print(const char *,...) PRINTF_FORMAT_ARG1
Definition: debug.cc:112
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Debug.h:162
AsHex< Integer > asHex(const Integer n)
a helper to ease AsHex object creation
Definition: Debug.h:268
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:219
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:145
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:184
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:789
number
Definition: testStatHist.cc:16
void ctx_exit(Ctx ctx)
Definition: debug.cc:724
const char * label
Definition: Debug.h:223
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:224
int level
Definition: Debug.h:200
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:82
Definition: Debug.h:177
#define PRINTF_FORMAT_ARG1
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Debug.h:74
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:92
FILE * DebugStream()
Definition: debug.cc:77
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:221
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:230
char * class
Definition: smb-errors.c:146
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:205
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
const char * data_
raw data to be printed
Definition: Debug.h:206

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors