/usr/include/x86_64-linux-gnu/qcc/Debug.h is in liballjoyn-common-dev-1604 16.04a+dfsg.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 | /**
* @file
*
* Define some convenience macros for debugging.
*/
/******************************************************************************
*
*
* Copyright AllSeen Alliance. All rights reserved.
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
******************************************************************************/
#ifndef _QCC_DEBUG_H
#define _QCC_DEBUG_H
#include <qcc/platform.h>
#include <stdio.h>
/** @cond ALLJOYN_DEV */
/** @internal DEBUG */
#define QCC_MODULE "DEBUG"
/** @endcond */
/**
* Some products using AllJoyn source code(e.g.Microsoft Windows) can override
* this macro to direct the log output to their product-specific log.
*/
#ifndef QCC_LogError
/**
* Macro for printing out error messagages.
*
* @param _status Status code related to the message.
* @param _msg Parenthesized arguments to be passed to printf
* [e.g. ("Disconnecting from %s", nodename)].
* String should not end with a new line.
*/
#if defined(NDEBUG)
#define QCC_LogError(_status, _msg) \
do { \
void* _ctx = _QCC_DbgPrintContext(" 0x%04x", _status); \
_QCC_DbgPrintProcess(_ctx, DBG_LOCAL_ERROR, QCC_MODULE, __FILE__, __LINE__); \
} while (0)
#else
#define QCC_LogError(_status, _msg) \
do { \
void* _ctx = _QCC_DbgPrintContext _msg; \
_QCC_DbgPrintAppend(_ctx, ": %s", QCC_StatusText(_status)); \
_QCC_DbgPrintProcess(_ctx, DBG_LOCAL_ERROR, QCC_MODULE, __FILE__, __LINE__); \
} while (0)
#endif
#endif
/**
* Some products using AllJoyn source code(e.g.Microsoft Windows) can override
* this macro to direct the log output to their product-specific log.
*/
#ifndef QCC_LogMsg
/**
* Macro for printing a log message. This will print its message even when
* NDEBUG is defined (depending on the log level setting).
* This macro is only intended for use in test applications where the
* timing of events needs to be record within an optimized build
* (release mode)
*
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#define QCC_LogMsg(_msg) \
do { \
if (_QCC_DbgPrintCheck((DBG_HIGH_LEVEL), QCC_MODULE)) { \
void* _ctx = _QCC_DbgPrintContext _msg; \
_QCC_DbgPrintProcess(_ctx, DBG_HIGH_LEVEL, QCC_MODULE, __FILE__, __LINE__); \
} \
} while (0)
#endif
/**
* Macro for high level debug prints. This is intended for high level summary
* debug information. Use QCC_DbgPrintf for more detailed debug information.
*
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#define QCC_DbgHLPrintf(_msg) _QCC_DbgPrint(DBG_HIGH_LEVEL, _msg)
/**
* Macro for general purpose debug prints.
*
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#define QCC_DbgPrintf(_msg) _QCC_DbgPrint(DBG_GEN_MESSAGE, _msg)
/**
* Macro for tracing the entrace to functions. This macro should be called
* first thing in a function.
*
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#define QCC_DbgTrace(_msg) _QCC_DbgPrint(DBG_API_TRACE, _msg)
/**
* Macro for dumping data received from remote connections.
*
* @param _data Pointer to the data to be dumped.
* @param _len Length of the data to be dumped.
*/
#define QCC_DbgRemoteData(_data, _len) _QCC_DbgDumpData(DBG_REMOTE_DATA, _data, _len)
/**
* Macro for dumping local data that will be sent to remote connections.
*
* @param _data Pointer to the data to be dumped.
* @param _len Length of the data to be dumped.
*/
#define QCC_DbgLocalData(_data, _len) _QCC_DbgDumpData(DBG_LOCAL_DATA, _data, _len)
/**
* Macro for reporting errors in received data from remote connections.
*
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#define QCC_DbgRemoteError(_msg) _QCC_DbgPrint(DBG_REMOTE_ERROR, _msg)
/**
* Macro to make conditional compilation of simple lines of code dependent on
* debug vs. release easier to read (and thus maintain). This should be used
* for single statements only. (Example: QCC_DEBUG_ONLY(printf("only print in
* debug mode\n"));)
*
* @param _cmd Single, simple, complete C statement to be compiled out in release mode.
*/
#if defined(NDEBUG)
#define QCC_DEBUG_ONLY(_cmd) do { } while (0)
#else
#define QCC_DEBUG_ONLY(_cmd) do { _cmd; } while (0)
#endif
/**
* Macro used to avoid the need for a local variable just for an assert. Using a local
* variable just for assert, instead of this macro, can cause compiler warnings on
* NDEBUG builds.
* Example: QCC_VERIFY(foo() == 0); instead of {int local = foo(); QCC_ASSERT(local == 0);}
*
* @param _cmd Statement to be executed on both types of builds, and asserted just
* on non-NDEBUG builds.
*/
#if defined(NDEBUG)
#define QCC_VERIFY(_cmd) ((void)(_cmd))
#else
#define QCC_VERIFY(_cmd) QCC_ASSERT(_cmd)
#endif
/**
* Some products using AllJoyn source code(e.g.Microsoft Windows) can override
* this macro to direct the log output to their product - specific log.
*/
#ifndef _QCC_DbgPrint
/**
* @cond ALLJOYN_DEV
* @internal
* Generalized macro for printing debug messages for code built in debug mode.
*
* @param _msgType Debug message mode defined in DbgMode enum.
* @param _msg "printf" parameters in parentheses.
* Example: ("value: %d", variable)
*/
#if defined(NDEBUG)
#define _QCC_DbgPrint(_msgType, _msg) do { } while (0)
#else
#define _QCC_DbgPrint(_msgType, _msg) \
do { \
if (_QCC_DbgPrintCheck((_msgType), QCC_MODULE)) { \
void* _ctx = _QCC_DbgPrintContext _msg; \
_QCC_DbgPrintProcess(_ctx, (_msgType), QCC_MODULE, __FILE__, __LINE__); \
} \
} while (0)
#endif
#endif
/** @endcond */
/**
* @cond ALLJOYN_DEV
* @internal
* Generalized macro for dumping arrays of data.
*
* @param _msgType Debug message mode defined in DbgMode enum.
* @param _data Pointer to data to dump.
* @param _len Length of data to dump.
*/
#if defined(NDEBUG)
#define _QCC_DbgDumpData(_msgType, _data, _len) do { } while (0)
#else
#define _QCC_DbgDumpData(_msgType, _data, _len) \
_QCC_DbgDumpHex((_msgType), QCC_MODULE, __FILE__, __LINE__, # _data, (_data), (_len))
#endif
/** @endcond */
#ifdef __cplusplus
extern "C" {
#endif
/**
* This function may be used by multi-threaded apps to print to STDOUT in a
* manner that prevents the output from one print statement from becomming
* interspersed with another print.
*
* @param fmt Format string.
* @param ... Arguments for filling out format string.
*
* @return Number of characters printed. Negative value indicates an error.
*/
int AJ_CALL QCC_SyncPrintf(const char* fmt, ...);
/**
* List of debug modes.
*/
typedef enum {
DBG_LOCAL_ERROR, /**< Error messages locally generated. (Should only
* be used by QCC_LogError().) */
DBG_REMOTE_ERROR, /**< Problem detected with data from remote host. */
DBG_HIGH_LEVEL, /**< High level debug information. */
DBG_GEN_MESSAGE, /**< General debug message. */
DBG_API_TRACE, /**< API trace. */
DBG_REMOTE_DATA, /**< Communicated data from remote host. */
DBG_LOCAL_DATA /**< Local data. */
} DbgMsgType;
/**
* Initialize the debug control.
* Calling this init method causes the debug control to re-read its environment
* settings and re-initialize accordingly.
*/
void QCC_InitializeDebugControl(void);
/**
* Prototype for the debug message callback. This callback allows application
* code to recieve debug message rather than the debug messages going to
* STDERR or a file.
*
* @param type Type of debug message. One of the DbgMsgType enumerations.
* @param module A C string identifying the module that the debug message is from.
* @param msg A C string containing the debug message.
* @param context An opaque pointer to context data provided by the application
* when registering the callback.
*/
typedef void (*QCC_DbgMsgCallback)(DbgMsgType type,
const char* module,
const char* msg,
void* context);
/**
* Allows the application to define its own debug and error message handler.
* This is intended for more generic handling of debug messages than what
* QCC_RegisterOutputFile() can provide.
*
* @param cb Callback to a function for handling debug messages.
* @param context Pointer to application data.
*/
void AJ_CALL QCC_RegisterOutputCallback(QCC_DbgMsgCallback cb, void* context);
/**
* Set the FILE stream where debug and error output should go. If not called then
* stderr is used as a default. This should only be called once at start up.
* See QCC_RegisterOutputCallback() for an alternate that is more generic.
*
* @param file Opened FILE pointer.
*/
void AJ_CALL QCC_RegisterOutputFile(FILE* file);
/**
* @cond ALLJOYN_DEV
* @internal
* Creates and prepares a debug context for printing debug output.
*
* @param fmt A printf() style format specification.
*/
void* AJ_CALL _QCC_DbgPrintContext(const char* fmt, ...);
/**
* @internal
* Appends the formatted string to the debug context.
*
* @param ctx Debug context created by _QCC_DbgPrintContext.
* @param fmt A printf() style format specification.
*/
void AJ_CALL _QCC_DbgPrintAppend(void* ctx, const char* fmt, ...);
/**
* @internal
* Prints the debug output.
*
* @param ctx Debug context created by _QCC_DbgPrintContext.
* @param type The debug type.
* @param module The module name.
* @param filename Filename where the debug message is.
* @param lineno Line number where the debug message is.
*/
void AJ_CALL _QCC_DbgPrintProcess(void* ctx, DbgMsgType type, const char* module, const char* filename, int lineno);
/**
* @internal
* Check if the module is set for printing debug of the specifed type.
*
* @param type The debug type.
* @param module The module name.
*
* @return 1 = print, 0 = don't print
*/
int AJ_CALL _QCC_DbgPrintCheck(DbgMsgType type, const char* module);
/**
* @internal
* Dumps data to the debug output.
*
* @param type The debug type.
* @param module The module name.
* @param filename Filename where the debug message is.
* @param lineno Line number where the debug message is.
* @param dataStr String representation of the data pointer 'name' to be dumped.
* @param data Pointer to the data to be dumped.
* @param dataLen Length of the data to be dumped.
*/
void AJ_CALL _QCC_DbgDumpHex(DbgMsgType type, const char* module, const char* filename, int lineno,
const char* dataStr, const void* data, size_t dataLen);
/**
* @internal
* Retrieves the internal message contained by the specified debug context
*
* @param ctx Debug context created by _QCC_DbgPrintContext.
*/
const char* AJ_CALL _QCC_DbgGetMsg(void* ctx);
/**
* @internal
* Frees memory occupied by the specified debug context object
*
* @param ctx Debug context created by _QCC_DbgPrintContext.
*/
void AJ_CALL _QCC_DbgDeleteCtx(void* ctx);
/**
* @internal
* Checks if any modules have been explicitly enabled for debug logging -
* by setting one or more ER_DEBUG_ModuleName environment variables, or by
* calling QCC_SetDebugLevel.
*
* @return true if there are any filters based on module name, false otherwise.
*/
bool AJ_CALL _QCC_DbgModulesSpecified();
/** @endcond */
#ifdef __cplusplus
}
#endif
#undef QCC_MODULE
#endif
|