Debug.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2017 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 // XXX should be mem/forward.h once it removes dependencies on typedefs.h
15 #include "mem/AllocatorProxy.h"
16 
17 #include <iostream>
18 #undef assert
19 #include <sstream>
20 #include <iomanip>
21 #if defined(assert)
22 #undef assert
23 #endif
24 
25 #if PURIFY
26 #define assert(EX) ((void)0)
27 #elif defined(NODEBUG)
28 #define assert(EX) ((void)0)
29 #elif STDC_HEADERS
30 #define assert(EX) ((EX)?((void)0):xassert( # EX , __FILE__, __LINE__))
31 #else
32 #define assert(EX) ((EX)?((void)0):xassert("EX", __FILE__, __LINE__))
33 #endif
34 
35 /* context-based debugging, the actual type is subject to change */
36 typedef int Ctx;
37 Ctx ctx_enter(const char *descr);
38 void ctx_exit(Ctx ctx);
39 
40 /* defined debug section limits */
41 #define MAX_DEBUG_SECTIONS 100
42 
43 /* defined names for Debug Levels */
44 #define DBG_CRITICAL 0
45 #define DBG_IMPORTANT 1
46 /* levels 2-8 are still being discussed amongst the developers */
47 #define DBG_DATA 9
49 #define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
51 class Debug
52 {
53 
54 public:
56  class Context
57  {
58  public:
59  Context(const int aSectionLevel, const int aLevel);
60 
61  int level;
63 
64  private:
65  friend class Debug;
66  void rewind(const int aSection, const int aLevel);
67  void formatStream();
69  std::ostringstream buf;
70  };
71 
73  static bool Enabled(const int section, const int level)
74  {
75  return level <= Debug::Levels[section];
76  }
77 
78  static char *debugOptions;
79  static char *cache_log;
80  static int rotateNumber;
82  static int override_X;
83  static int log_stderr;
84  static bool log_syslog;
85 
86  static void parseOptions(char const *);
87 
89  static int Level() { return Current ? Current->level : 1; }
91  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
92 
94  static std::ostringstream &Start(const int section, const int level);
96  static void Finish();
97 
98 private:
99  static Context *Current;
100 };
101 
104 FILE *DebugStream();
106 #define debug_log DebugStream()
107 
109 void StopUsingDebugLog();
110 
112 void ResyncDebugLog(FILE *newDestination);
113 
114 size_t BuildPrefixInit();
115 const char * SkipBuildPrefix(const char* path);
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  << SkipBuildPrefix(__FILE__)<<"("<<__LINE__<<") "<<__FUNCTION__<<": "; \
131  } \
132  _dbo << CONTENT; \
133  Debug::Finish(); \
134  } \
135  } while (/*CONSTCOND*/ 0)
136 
146 inline std::ostream&
147 HERE(std::ostream& s)
148 {
149  return s;
150 }
151 
152 /*
153  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
154  *
155  * debugs(1,1, MYNAME << "WARNING: some message");
156  */
157 #ifdef __PRETTY_FUNCTION__
158 #define MYNAME __PRETTY_FUNCTION__ << " "
159 #else
160 #define MYNAME __FUNCTION__ << " "
161 #endif
162 
163 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
164 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
165 {
166  return (os << (int)d);
167 }
168 
169 /* Legacy debug function definitions */
170 void _db_init(const char *logfile, const char *options);
171 void _db_print(const char *,...) PRINTF_FORMAT_ARG1;
172 void _db_set_syslog(const char *facility);
173 void _db_rotate_log(void);
174 
180 {
181 public:
182  Raw(const char *label, const char *data, const size_t size):
183  level(-1), label_(label), data_(data), size_(size), useHex_(false) {}
184 
186  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
187 
189  Raw &hex() { useHex_ = true; return *this; }
190 
197  std::ostream &print(std::ostream &os) const;
198 
202  int level;
203 
204 private:
205  void printHex(std::ostream &os) const;
206 
207  const char *label_;
208  const char *data_;
209  size_t size_;
210  bool useHex_;
211 };
212 
213 inline
214 std::ostream &operator <<(std::ostream &os, const Raw &raw)
215 {
216  return raw.print(os);
217 }
218 
220 template <class Pointer>
221 class RawPointerT {
222 public:
223  RawPointerT(const char *aLabel, const Pointer &aPtr):
224  label(aLabel), ptr(aPtr) {}
225  const char *label;
226  const Pointer &ptr;
227 };
228 
230 template <class Pointer>
232 RawPointer(const char *label, const Pointer &ptr)
233 {
234  return RawPointerT<Pointer>(label, ptr);
235 }
236 
238 template <class Pointer>
239 inline std::ostream &
240 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
241 {
242  os << pd.label << '=';
243  if (pd.ptr)
244  return os << *pd.ptr;
245  else
246  return os << "[nil]";
247 }
248 
249 #endif /* SQUID_DEBUG_H */
250 
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:80
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:189
void _db_rotate_log(void)
Definition: debug.cc:499
static bool log_syslog
Definition: Debug.h:84
const char * SkipBuildPrefix(const char *path)
Definition: debug.cc:864
std::ostream & print(std::ostream &os) const
Definition: debug.cc:885
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:182
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:89
Definition: Debug.h:51
std::ostringstream buf
debugs() output sink
Definition: Debug.h:69
Ctx ctx_enter(const char *descr)
Definition: debug.cc:708
static int override_X
Definition: Debug.h:82
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:62
meta-information for debugs() or a similar debugging call
Definition: Debug.h:56
bool useHex_
whether hex() has been called
Definition: Debug.h:210
static int log_stderr
Definition: Debug.h:83
static char * debugOptions
Definition: Debug.h:78
size_t BuildPrefixInit()
Definition: debug.cc:849
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:99
static char * cache_log
Definition: Debug.h:79
size_t size_
data length
Definition: Debug.h:209
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:68
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:164
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:221
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:147
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:186
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
void ctx_exit(Ctx ctx)
Definition: debug.cc:724
const char * label
Definition: Debug.h:225
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:226
int level
Definition: Debug.h:202
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:81
Definition: Debug.h:179
#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:73
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:91
FILE * DebugStream()
Definition: debug.cc:77
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:223
int level
minimum debugging level required by the debugs() call
Definition: Debug.h:61
RawPointerT< Pointer > RawPointer(const char *label, const Pointer &ptr)
convenience wrapper for creating RawPointerT<> objects
Definition: Debug.h:232
char * class
Definition: smb-errors.c:146
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:207
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:36
#define MAX_DEBUG_SECTIONS
Definition: Debug.h:41
const char * data_
raw data to be printed
Definition: Debug.h:208

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors