VirtualBox

source: vbox/trunk/include/iprt/log.h@ 75155

Last change on this file since 75155 was 73977, checked in by vboxsync, 6 years ago

IPRT/rest: More request array and map setter methods. Fixed string defaults. Safer copying and resetToDefaults. bugref:9167

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 88.0 KB
Line 
1/** @file
2 * IPRT - Logging.
3 */
4
5/*
6 * Copyright (C) 2006-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_log_h
27#define ___iprt_log_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/stdarg.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_log RTLog - Logging
36 * @ingroup grp_rt
37 * @{
38 */
39
40/**
41 * IPRT Logging Groups.
42 * (Remember to update RT_LOGGROUP_NAMES!)
43 *
44 * @remark It should be pretty obvious, but just to have
45 * mentioned it, the values are sorted alphabetically (using the
46 * english alphabet) except for _DEFAULT which is always first.
47 *
48 * If anyone might be wondering what the alphabet looks like:
49 * a b c d e f g h i j k l m n o p q r s t u v w x y z
50 */
51typedef enum RTLOGGROUP
52{
53 /** Default logging group. */
54 RTLOGGROUP_DEFAULT,
55 RTLOGGROUP_CRYPTO,
56 RTLOGGROUP_DBG,
57 RTLOGGROUP_DBG_DWARF,
58 RTLOGGROUP_DIR,
59 RTLOGGROUP_FILE,
60 RTLOGGROUP_FS,
61 RTLOGGROUP_HTTP,
62 RTLOGGROUP_LDR,
63 RTLOGGROUP_LOCALIPC,
64 RTLOGGROUP_PATH,
65 RTLOGGROUP_PROCESS,
66 RTLOGGROUP_REST,
67 RTLOGGROUP_SYMLINK,
68 RTLOGGROUP_THREAD,
69 RTLOGGROUP_TIME,
70 RTLOGGROUP_TIMER,
71 RTLOGGROUP_VFS,
72 RTLOGGROUP_ZIP = 31,
73 RTLOGGROUP_FIRST_USER = 32
74} RTLOGGROUP;
75
76/** @def RT_LOGGROUP_NAMES
77 * IPRT Logging group names.
78 *
79 * Must correspond 100% to RTLOGGROUP!
80 * Don't forget commas!
81 *
82 * @remark It should be pretty obvious, but just to have
83 * mentioned it, the values are sorted alphabetically (using the
84 * english alphabet) except for _DEFAULT which is always first.
85 *
86 * If anyone might be wondering what the alphabet looks like:
87 * a b c d e f g h i j k l m n o p q r s t u v w x y z
88 */
89#define RT_LOGGROUP_NAMES \
90 "DEFAULT", \
91 "RT_CRYPTO", \
92 "RT_DBG", \
93 "RT_DBG_DWARF", \
94 "RT_DIR", \
95 "RT_FILE", \
96 "RT_FS", \
97 "RT_HTTP", \
98 "RT_LDR", \
99 "RT_LOCALIPC", \
100 "RT_PATH", \
101 "RT_PROCESS", \
102 "RT_REST", \
103 "RT_SYMLINK", \
104 "RT_THREAD", \
105 "RT_TIME", \
106 "RT_TIMER", \
107 "RT_VFS", \
108 "RT_18", \
109 "RT_19", \
110 "RT_20", \
111 "RT_21", \
112 "RT_22", \
113 "RT_23", \
114 "RT_24", \
115 "RT_25", \
116 "RT_26", \
117 "RT_27", \
118 "RT_28", \
119 "RT_29", \
120 "RT_30", \
121 "RT_ZIP" \
122
123
124/** @def LOG_GROUP
125 * Active logging group.
126 */
127#ifndef LOG_GROUP
128# define LOG_GROUP RTLOGGROUP_DEFAULT
129#endif
130
131/** @def LOG_FN_FMT
132 * You can use this to specify your desired way of printing __PRETTY_FUNCTION__
133 * if you dislike the default one.
134 */
135#ifndef LOG_FN_FMT
136# define LOG_FN_FMT "%Rfn"
137#endif
138
139#ifdef LOG_INSTANCE
140# error "LOG_INSTANCE is no longer supported."
141#endif
142#ifdef LOG_REL_INSTANCE
143# error "LOG_REL_INSTANCE is no longer supported."
144#endif
145
146/** Logger structure. */
147#ifdef IN_RC
148typedef struct RTLOGGERRC RTLOGGER;
149#else
150typedef struct RTLOGGER RTLOGGER;
151#endif
152/** Pointer to logger structure. */
153typedef RTLOGGER *PRTLOGGER;
154/** Pointer to const logger structure. */
155typedef const RTLOGGER *PCRTLOGGER;
156
157
158/** Guest context logger structure. */
159typedef struct RTLOGGERRC RTLOGGERRC;
160/** Pointer to guest context logger structure. */
161typedef RTLOGGERRC *PRTLOGGERRC;
162/** Pointer to const guest context logger structure. */
163typedef const RTLOGGERRC *PCRTLOGGERRC;
164
165
166/**
167 * Logger phase.
168 *
169 * Used for signalling the log header/footer callback what to do.
170 */
171typedef enum RTLOGPHASE
172{
173 /** Begin of the logging. */
174 RTLOGPHASE_BEGIN = 0,
175 /** End of the logging. */
176 RTLOGPHASE_END,
177 /** Before rotating the log file. */
178 RTLOGPHASE_PREROTATE,
179 /** After rotating the log file. */
180 RTLOGPHASE_POSTROTATE,
181 /** 32-bit type blow up hack. */
182 RTLOGPHASE_32BIT_HACK = 0x7fffffff
183} RTLOGPHASE;
184
185
186/**
187 * Logger function.
188 *
189 * @param pszFormat Format string.
190 * @param ... Optional arguments as specified in the format string.
191 */
192typedef DECLCALLBACK(void) FNRTLOGGER(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
193/** Pointer to logger function. */
194typedef FNRTLOGGER *PFNRTLOGGER;
195
196/**
197 * Flush function.
198 *
199 * @param pLogger Pointer to the logger instance which is to be flushed.
200 */
201typedef DECLCALLBACK(void) FNRTLOGFLUSH(PRTLOGGER pLogger);
202/** Pointer to flush function. */
203typedef FNRTLOGFLUSH *PFNRTLOGFLUSH;
204
205/**
206 * Flush function.
207 *
208 * @param pLogger Pointer to the logger instance which is to be flushed.
209 */
210typedef DECLCALLBACK(void) FNRTLOGFLUSHGC(PRTLOGGERRC pLogger);
211/** Pointer to logger function. */
212typedef RCPTRTYPE(FNRTLOGFLUSHGC *) PFNRTLOGFLUSHGC;
213
214/**
215 * Header/footer message callback.
216 *
217 * @param pLogger Pointer to the logger instance.
218 * @param pszFormat Format string.
219 * @param ... Optional arguments specified in the format string.
220 */
221typedef DECLCALLBACK(void) FNRTLOGPHASEMSG(PRTLOGGER pLogger, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
222/** Pointer to header/footer message callback function. */
223typedef FNRTLOGPHASEMSG *PFNRTLOGPHASEMSG;
224
225/**
226 * Log file header/footer callback.
227 *
228 * @param pLogger Pointer to the logger instance.
229 * @param enmLogPhase Indicates at what time the callback is invoked.
230 * @param pfnLogPhaseMsg Callback for writing the header/footer (RTLogPrintf
231 * and others are out of bounds).
232 */
233typedef DECLCALLBACK(void) FNRTLOGPHASE(PRTLOGGER pLogger, RTLOGPHASE enmLogPhase, PFNRTLOGPHASEMSG pfnLogPhaseMsg);
234/** Pointer to log header/footer callback function. */
235typedef FNRTLOGPHASE *PFNRTLOGPHASE;
236
237/**
238 * Custom log prefix callback.
239 *
240 *
241 * @returns The number of chars written.
242 *
243 * @param pLogger Pointer to the logger instance.
244 * @param pchBuf Output buffer pointer.
245 * No need to terminate the output.
246 * @param cchBuf The size of the output buffer.
247 * @param pvUser The user argument.
248 */
249typedef DECLCALLBACK(size_t) FNRTLOGPREFIX(PRTLOGGER pLogger, char *pchBuf, size_t cchBuf, void *pvUser);
250/** Pointer to prefix callback function. */
251typedef FNRTLOGPREFIX *PFNRTLOGPREFIX;
252
253
254
255/**
256 * Logger instance structure for raw-mode context (RC).
257 */
258struct RTLOGGERRC
259{
260 /** Pointer to temporary scratch buffer.
261 * This is used to format the log messages. */
262 char achScratch[32768];
263 /** Current scratch buffer position. */
264 uint32_t offScratch;
265 /** This is set if a prefix is pending. */
266 bool fPendingPrefix;
267 bool afAlignment[3];
268 /** Pointer to the logger function.
269 * This is actually pointer to a wrapper which will push a pointer to the
270 * instance pointer onto the stack before jumping to the real logger function.
271 * A very unfortunate hack to work around the missing variadic macro support in C++. */
272 RCPTRTYPE(PFNRTLOGGER) pfnLogger;
273 /** Pointer to the flush function. */
274 PFNRTLOGFLUSHGC pfnFlush;
275 /** Magic number (RTLOGGERRC_MAGIC). */
276 uint32_t u32Magic;
277 /** Logger instance flags - RTLOGFLAGS. */
278 uint32_t fFlags;
279 /** Number of groups in the afGroups member. */
280 uint32_t cGroups;
281 /** Group flags array - RTLOGGRPFLAGS.
282 * This member have variable length and may extend way beyond
283 * the declared size of 1 entry. */
284 uint32_t afGroups[1];
285};
286
287/** RTLOGGERRC::u32Magic value. (John Rogers Searle) */
288#define RTLOGGERRC_MAGIC 0x19320731
289
290
291
292#ifndef IN_RC
293
294/** Pointer to internal logger bits. */
295typedef struct RTLOGGERINTERNAL *PRTLOGGERINTERNAL;
296
297/**
298 * Logger instance structure.
299 */
300struct RTLOGGER
301{
302 /** Pointer to temporary scratch buffer.
303 * This is used to format the log messages. */
304 char achScratch[49152];
305 /** Current scratch buffer position. */
306 uint32_t offScratch;
307 /** Magic number. */
308 uint32_t u32Magic;
309 /** Logger instance flags - RTLOGFLAGS. */
310 uint32_t fFlags;
311 /** Destination flags - RTLOGDEST. */
312 uint32_t fDestFlags;
313 /** Pointer to the internal bits of the logger.
314 * (The memory is allocated in the same block as RTLOGGER.) */
315 PRTLOGGERINTERNAL pInt;
316 /** Pointer to the logger function (used in non-C99 mode only).
317 *
318 * This is actually pointer to a wrapper which will push a pointer to the
319 * instance pointer onto the stack before jumping to the real logger function.
320 * A very unfortunate hack to work around the missing variadic macro
321 * support in older C++/C standards. (The memory is allocated using
322 * RTMemExecAlloc(), except for agnostic R0 code.) */
323 PFNRTLOGGER pfnLogger;
324 /** Number of groups in the afGroups and papszGroups members. */
325 uint32_t cGroups;
326 /** Group flags array - RTLOGGRPFLAGS.
327 * This member have variable length and may extend way beyond
328 * the declared size of 1 entry. */
329 uint32_t afGroups[1];
330};
331
332/** RTLOGGER::u32Magic value. (Avram Noam Chomsky) */
333# define RTLOGGER_MAGIC UINT32_C(0x19281207)
334
335#endif /* !IN_RC */
336
337
338/**
339 * Logger flags.
340 */
341typedef enum RTLOGFLAGS
342{
343 /** The logger instance is disabled for normal output. */
344 RTLOGFLAGS_DISABLED = 0x00000001,
345 /** The logger instance is using buffered output. */
346 RTLOGFLAGS_BUFFERED = 0x00000002,
347 /** The logger instance expands LF to CR/LF. */
348 RTLOGFLAGS_USECRLF = 0x00000010,
349 /** Append to the log destination where applicable. */
350 RTLOGFLAGS_APPEND = 0x00000020,
351 /** Show relative timestamps with PREFIX_TSC and PREFIX_TS */
352 RTLOGFLAGS_REL_TS = 0x00000040,
353 /** Show decimal timestamps with PREFIX_TSC and PREFIX_TS */
354 RTLOGFLAGS_DECIMAL_TS = 0x00000080,
355 /** Open the file in write through mode. */
356 RTLOGFLAGS_WRITE_THROUGH = 0x00000100,
357 /** Flush the file to disk when flushing the buffer. */
358 RTLOGFLAGS_FLUSH = 0x00000200,
359 /** Restrict the number of log entries per group. */
360 RTLOGFLAGS_RESTRICT_GROUPS = 0x00000400,
361 /** New lines should be prefixed with the write and read lock counts. */
362 RTLOGFLAGS_PREFIX_LOCK_COUNTS = 0x00008000,
363 /** New lines should be prefixed with the CPU id (ApicID on intel/amd). */
364 RTLOGFLAGS_PREFIX_CPUID = 0x00010000,
365 /** New lines should be prefixed with the native process id. */
366 RTLOGFLAGS_PREFIX_PID = 0x00020000,
367 /** New lines should be prefixed with group flag number causing the output. */
368 RTLOGFLAGS_PREFIX_FLAG_NO = 0x00040000,
369 /** New lines should be prefixed with group flag name causing the output. */
370 RTLOGFLAGS_PREFIX_FLAG = 0x00080000,
371 /** New lines should be prefixed with group number. */
372 RTLOGFLAGS_PREFIX_GROUP_NO = 0x00100000,
373 /** New lines should be prefixed with group name. */
374 RTLOGFLAGS_PREFIX_GROUP = 0x00200000,
375 /** New lines should be prefixed with the native thread id. */
376 RTLOGFLAGS_PREFIX_TID = 0x00400000,
377 /** New lines should be prefixed with thread name. */
378 RTLOGFLAGS_PREFIX_THREAD = 0x00800000,
379 /** New lines should be prefixed with data from a custom callback. */
380 RTLOGFLAGS_PREFIX_CUSTOM = 0x01000000,
381 /** New lines should be prefixed with formatted timestamp since program start. */
382 RTLOGFLAGS_PREFIX_TIME_PROG = 0x04000000,
383 /** New lines should be prefixed with formatted timestamp (UCT). */
384 RTLOGFLAGS_PREFIX_TIME = 0x08000000,
385 /** New lines should be prefixed with milliseconds since program start. */
386 RTLOGFLAGS_PREFIX_MS_PROG = 0x10000000,
387 /** New lines should be prefixed with timestamp. */
388 RTLOGFLAGS_PREFIX_TSC = 0x20000000,
389 /** New lines should be prefixed with timestamp. */
390 RTLOGFLAGS_PREFIX_TS = 0x40000000,
391 /** The prefix mask. */
392 RTLOGFLAGS_PREFIX_MASK = 0x7dff8000
393} RTLOGFLAGS;
394
395/**
396 * Logger per group flags.
397 *
398 * @remarks We only use the lower 16 bits here. We'll be combining it with the
399 * group number in a few places.
400 */
401typedef enum RTLOGGRPFLAGS
402{
403 /** Enabled. */
404 RTLOGGRPFLAGS_ENABLED = 0x0001,
405 /** Flow logging. */
406 RTLOGGRPFLAGS_FLOW = 0x0002,
407 /** Warnings logging. */
408 RTLOGGRPFLAGS_WARN = 0x0004,
409 /* 0x0008 for later. */
410 /** Level 1 logging. */
411 RTLOGGRPFLAGS_LEVEL_1 = 0x0010,
412 /** Level 2 logging. */
413 RTLOGGRPFLAGS_LEVEL_2 = 0x0020,
414 /** Level 3 logging. */
415 RTLOGGRPFLAGS_LEVEL_3 = 0x0040,
416 /** Level 4 logging. */
417 RTLOGGRPFLAGS_LEVEL_4 = 0x0080,
418 /** Level 5 logging. */
419 RTLOGGRPFLAGS_LEVEL_5 = 0x0100,
420 /** Level 6 logging. */
421 RTLOGGRPFLAGS_LEVEL_6 = 0x0200,
422 /** Level 7 logging. */
423 RTLOGGRPFLAGS_LEVEL_7 = 0x0400,
424 /** Level 8 logging. */
425 RTLOGGRPFLAGS_LEVEL_8 = 0x0800,
426 /** Level 9 logging. */
427 RTLOGGRPFLAGS_LEVEL_9 = 0x1000,
428 /** Level 10 logging. */
429 RTLOGGRPFLAGS_LEVEL_10 = 0x2000,
430 /** Level 11 logging. */
431 RTLOGGRPFLAGS_LEVEL_11 = 0x4000,
432 /** Level 12 logging. */
433 RTLOGGRPFLAGS_LEVEL_12 = 0x8000,
434
435 /** Restrict the number of log entries. */
436 RTLOGGRPFLAGS_RESTRICT = 0x40000000,
437 /** Blow up the type. */
438 RTLOGGRPFLAGS_32BIT_HACK = 0x7fffffff
439} RTLOGGRPFLAGS;
440
441/**
442 * Logger destination types and flags.
443 */
444typedef enum RTLOGDEST
445{
446 /** Log to file. */
447 RTLOGDEST_FILE = 0x00000001,
448 /** Log to stdout. */
449 RTLOGDEST_STDOUT = 0x00000002,
450 /** Log to stderr. */
451 RTLOGDEST_STDERR = 0x00000004,
452 /** Log to debugger (win32 only). */
453 RTLOGDEST_DEBUGGER = 0x00000008,
454 /** Log to com port. */
455 RTLOGDEST_COM = 0x00000010,
456 /** Log a memory ring buffer. */
457 RTLOGDEST_RINGBUF = 0x00000020,
458 /** Open files with no deny (share read, write, delete) on Windows. */
459 RTLOGDEST_F_NO_DENY = 0x00010000,
460 /** Delay opening the log file, logging to the buffer untill
461 * RTLogClearFileDelayFlag is called. */
462 RTLOGDEST_F_DELAY_FILE = 0x00020000,
463 /** Just a dummy flag to be used when no other flag applies. */
464 RTLOGDEST_DUMMY = 0x20000000,
465 /** Log to a user defined output stream. */
466 RTLOGDEST_USER = 0x40000000
467} RTLOGDEST;
468
469
470RTDECL(void) RTLogPrintfEx(void *pvInstance, unsigned fFlags, unsigned iGroup,
471 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
472
473
474#ifdef DOXYGEN_RUNNING
475# define LOG_DISABLED
476# define LOG_ENABLED
477# define LOG_ENABLE_FLOW
478#endif
479
480/** @def LOG_DISABLED
481 * Use this compile time define to disable all logging macros. It can
482 * be overridden for each of the logging macros by the LOG_ENABLE*
483 * compile time defines.
484 */
485
486/** @def LOG_ENABLED
487 * Use this compile time define to enable logging when not in debug mode
488 * or LOG_DISABLED is set.
489 * This will enabled Log() only.
490 */
491
492/** @def LOG_ENABLE_FLOW
493 * Use this compile time define to enable flow logging when not in
494 * debug mode or LOG_DISABLED is defined.
495 * This will enable LogFlow() only.
496 */
497
498/*
499 * Determine whether logging is enabled and forcefully normalize the indicators.
500 */
501#if (defined(DEBUG) || defined(LOG_ENABLED)) && !defined(LOG_DISABLED)
502# undef LOG_DISABLED
503# undef LOG_ENABLED
504# define LOG_ENABLED
505#else
506# undef LOG_ENABLED
507# undef LOG_DISABLED
508# define LOG_DISABLED
509#endif
510
511
512/** @def LOG_USE_C99
513 * Governs the use of variadic macros.
514 */
515#ifndef LOG_USE_C99
516# if defined(RT_ARCH_AMD64) || defined(RT_OS_DARWIN) || defined(RT_ARCH_SPARC) || defined(RT_ARCH_SPARC64)
517# define LOG_USE_C99
518# endif
519#endif
520
521
522/** @name Macros for checking whether a log level is enabled.
523 * @{ */
524/** @def LogIsItEnabled
525 * Checks whether the specified logging group is enabled or not.
526 */
527#ifdef LOG_ENABLED
528# define LogIsItEnabled(a_fFlags, a_iGroup) ( RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)) != NULL )
529#else
530# define LogIsItEnabled(a_fFlags, a_iGroup) (false)
531#endif
532
533/** @def LogIsEnabled
534 * Checks whether level 1 logging is enabled.
535 */
536#define LogIsEnabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
537
538/** @def LogIs2Enabled
539 * Checks whether level 2 logging is enabled.
540 */
541#define LogIs2Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
542
543/** @def LogIs3Enabled
544 * Checks whether level 3 logging is enabled.
545 */
546#define LogIs3Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
547
548/** @def LogIs4Enabled
549 * Checks whether level 4 logging is enabled.
550 */
551#define LogIs4Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
552
553/** @def LogIs5Enabled
554 * Checks whether level 5 logging is enabled.
555 */
556#define LogIs5Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
557
558/** @def LogIs6Enabled
559 * Checks whether level 6 logging is enabled.
560 */
561#define LogIs6Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
562
563/** @def LogIs7Enabled
564 * Checks whether level 7 logging is enabled.
565 */
566#define LogIs7Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP)
567
568/** @def LogIs8Enabled
569 * Checks whether level 8 logging is enabled.
570 */
571#define LogIs8Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP)
572
573/** @def LogIs9Enabled
574 * Checks whether level 9 logging is enabled.
575 */
576#define LogIs9Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP)
577
578/** @def LogIs10Enabled
579 * Checks whether level 10 logging is enabled.
580 */
581#define LogIs10Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP)
582
583/** @def LogIs11Enabled
584 * Checks whether level 11 logging is enabled.
585 */
586#define LogIs11Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP)
587
588/** @def LogIs12Enabled
589 * Checks whether level 12 logging is enabled.
590 */
591#define LogIs12Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP)
592
593/** @def LogIsFlowEnabled
594 * Checks whether execution flow logging is enabled.
595 */
596#define LogIsFlowEnabled() LogIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
597
598/** @def LogIsWarnEnabled
599 * Checks whether execution flow logging is enabled.
600 */
601#define LogIsWarnEnabled() LogIsItEnabled(RTLOGGRPFLAGS_WARN, LOG_GROUP)
602/** @} */
603
604
605/** @def LogIt
606 * Write to specific logger if group enabled.
607 */
608#ifdef LOG_ENABLED
609# if defined(LOG_USE_C99)
610# define _LogRemoveParentheseis(...) __VA_ARGS__
611# define _LogIt(a_fFlags, a_iGroup, ...) \
612 do \
613 { \
614 register PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
615 if (RT_LIKELY(!LogIt_pLogger)) \
616 { /* likely */ } \
617 else \
618 RTLogLoggerEx(LogIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
619 } while (0)
620# define LogIt(a_fFlags, a_iGroup, fmtargs) _LogIt(a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
621# define _LogItAlways(a_fFlags, a_iGroup, ...) RTLogLoggerEx(NULL, a_fFlags, UINT32_MAX, __VA_ARGS__)
622# define LogItAlways(a_fFlags, a_iGroup, fmtargs) _LogItAlways(a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
623 /** @todo invent a flag or something for skipping the group check so we can pass iGroup. LogItAlways. */
624# else
625# define LogIt(a_fFlags, a_iGroup, fmtargs) \
626 do \
627 { \
628 register PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
629 if (RT_LIKELY(!LogIt_pLogger)) \
630 { /* likely */ } \
631 else \
632 { \
633 LogIt_pLogger->pfnLogger fmtargs; \
634 } \
635 } while (0)
636# define LogItAlways(a_fFlags, a_iGroup, fmtargs) \
637 do \
638 { \
639 register PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(0, UINT16_MAX)); \
640 if (LogIt_pLogger) \
641 LogIt_pLogger->pfnLogger fmtargs; \
642 } while (0)
643# endif
644#else
645# define LogIt(a_fFlags, a_iGroup, fmtargs) do { } while (0)
646# define LogItAlways(a_fFlags, a_iGroup, fmtargs) do { } while (0)
647# if defined(LOG_USE_C99)
648# define _LogRemoveParentheseis(...) __VA_ARGS__
649# define _LogIt(a_fFlags, a_iGroup, ...) do { } while (0)
650# define _LogItAlways(a_fFlags, a_iGroup, ...) do { } while (0)
651# endif
652#endif
653
654
655/** @name Basic logging macros
656 * @{ */
657/** @def Log
658 * Level 1 logging that works regardless of the group settings.
659 */
660#define LogAlways(a) LogItAlways(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
661
662/** @def Log
663 * Level 1 logging.
664 */
665#define Log(a) LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
666
667/** @def Log2
668 * Level 2 logging.
669 */
670#define Log2(a) LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
671
672/** @def Log3
673 * Level 3 logging.
674 */
675#define Log3(a) LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
676
677/** @def Log4
678 * Level 4 logging.
679 */
680#define Log4(a) LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
681
682/** @def Log5
683 * Level 5 logging.
684 */
685#define Log5(a) LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
686
687/** @def Log6
688 * Level 6 logging.
689 */
690#define Log6(a) LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
691
692/** @def Log7
693 * Level 7 logging.
694 */
695#define Log7(a) LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
696
697/** @def Log8
698 * Level 8 logging.
699 */
700#define Log8(a) LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
701
702/** @def Log9
703 * Level 9 logging.
704 */
705#define Log9(a) LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
706
707/** @def Log10
708 * Level 10 logging.
709 */
710#define Log10(a) LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
711
712/** @def Log11
713 * Level 11 logging.
714 */
715#define Log11(a) LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
716
717/** @def Log12
718 * Level 12 logging.
719 */
720#define Log12(a) LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
721
722/** @def LogFlow
723 * Logging of execution flow.
724 */
725#define LogFlow(a) LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
726
727/** @def LogWarn
728 * Logging of warnings.
729 */
730#define LogWarn(a) LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, a)
731/** @} */
732
733
734/** @name Logging macros prefixing the current function name.
735 * @{ */
736/** @def LogFunc
737 * Level 1 logging inside C/C++ functions.
738 *
739 * Prepends the given log message with the function name followed by a
740 * semicolon and space.
741 *
742 * @param a Log message in format <tt>("string\n" [, args])</tt>.
743 */
744#ifdef LOG_USE_C99
745# define LogFunc(a) _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
746#else
747# define LogFunc(a) do { Log((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log(a); } while (0)
748#endif
749
750/** @def Log2Func
751 * Level 2 logging inside C/C++ functions.
752 *
753 * Prepends the given log message with the function name followed by a
754 * semicolon and space.
755 *
756 * @param a Log message in format <tt>("string\n" [, args])</tt>.
757 */
758#ifdef LOG_USE_C99
759# define Log2Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
760#else
761# define Log2Func(a) do { Log2((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log2(a); } while (0)
762#endif
763
764/** @def Log3Func
765 * Level 3 logging inside C/C++ functions.
766 *
767 * Prepends the given log message with the function name followed by a
768 * semicolon and space.
769 *
770 * @param a Log message in format <tt>("string\n" [, args])</tt>.
771 */
772#ifdef LOG_USE_C99
773# define Log3Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
774#else
775# define Log3Func(a) do { Log3((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log3(a); } while (0)
776#endif
777
778/** @def Log4Func
779 * Level 4 logging inside C/C++ functions.
780 *
781 * Prepends the given log message with the function name followed by a
782 * semicolon and space.
783 *
784 * @param a Log message in format <tt>("string\n" [, args])</tt>.
785 */
786#ifdef LOG_USE_C99
787# define Log4Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
788#else
789# define Log4Func(a) do { Log4((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log4(a); } while (0)
790#endif
791
792/** @def Log5Func
793 * Level 5 logging inside C/C++ functions.
794 *
795 * Prepends the given log message with the function name followed by a
796 * semicolon and space.
797 *
798 * @param a Log message in format <tt>("string\n" [, args])</tt>.
799 */
800#ifdef LOG_USE_C99
801# define Log5Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
802#else
803# define Log5Func(a) do { Log5((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log5(a); } while (0)
804#endif
805
806/** @def Log6Func
807 * Level 6 logging inside C/C++ functions.
808 *
809 * Prepends the given log message with the function name followed by a
810 * semicolon and space.
811 *
812 * @param a Log message in format <tt>("string\n" [, args])</tt>.
813 */
814#ifdef LOG_USE_C99
815# define Log6Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
816#else
817# define Log6Func(a) do { Log6((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log6(a); } while (0)
818#endif
819
820/** @def Log7Func
821 * Level 7 logging inside C/C++ functions.
822 *
823 * Prepends the given log message with the function name followed by a
824 * semicolon and space.
825 *
826 * @param a Log message in format <tt>("string\n" [, args])</tt>.
827 */
828#ifdef LOG_USE_C99
829# define Log7Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
830#else
831# define Log7Func(a) do { Log7((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log7(a); } while (0)
832#endif
833
834/** @def Log8Func
835 * Level 8 logging inside C/C++ functions.
836 *
837 * Prepends the given log message with the function name followed by a
838 * semicolon and space.
839 *
840 * @param a Log message in format <tt>("string\n" [, args])</tt>.
841 */
842#ifdef LOG_USE_C99
843# define Log8Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
844#else
845# define Log8Func(a) do { Log8((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log8(a); } while (0)
846#endif
847
848/** @def Log9Func
849 * Level 9 logging inside C/C++ functions.
850 *
851 * Prepends the given log message with the function name followed by a
852 * semicolon and space.
853 *
854 * @param a Log message in format <tt>("string\n" [, args])</tt>.
855 */
856#ifdef LOG_USE_C99
857# define Log9Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
858#else
859# define Log9Func(a) do { Log9((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log9(a); } while (0)
860#endif
861
862/** @def Log10Func
863 * Level 10 logging inside C/C++ functions.
864 *
865 * Prepends the given log message with the function name followed by a
866 * semicolon and space.
867 *
868 * @param a Log message in format <tt>("string\n" [, args])</tt>.
869 */
870#ifdef LOG_USE_C99
871# define Log10Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
872#else
873# define Log10Func(a) do { Log10((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log10(a); } while (0)
874#endif
875
876/** @def Log11Func
877 * Level 11 logging inside C/C++ functions.
878 *
879 * Prepends the given log message with the function name followed by a
880 * semicolon and space.
881 *
882 * @param a Log message in format <tt>("string\n" [, args])</tt>.
883 */
884#ifdef LOG_USE_C99
885# define Log11Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
886#else
887# define Log11Func(a) do { Log11((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log11(a); } while (0)
888#endif
889
890/** @def Log12Func
891 * Level 12 logging inside C/C++ functions.
892 *
893 * Prepends the given log message with the function name followed by a
894 * semicolon and space.
895 *
896 * @param a Log message in format <tt>("string\n" [, args])</tt>.
897 */
898#ifdef LOG_USE_C99
899# define Log12Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
900#else
901# define Log12Func(a) do { Log12((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log12(a); } while (0)
902#endif
903
904/** @def LogFlowFunc
905 * Macro to log the execution flow inside C/C++ functions.
906 *
907 * Prepends the given log message with the function name followed by
908 * a semicolon and space.
909 *
910 * @param a Log message in format <tt>("string\n" [, args])</tt>.
911 */
912#ifdef LOG_USE_C99
913# define LogFlowFunc(a) \
914 _LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
915#else
916# define LogFlowFunc(a) \
917 do { LogFlow((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
918#endif
919
920/** @def LogWarnFunc
921 * Macro to log a warning inside C/C++ functions.
922 *
923 * Prepends the given log message with the function name followed by
924 * a semicolon and space.
925 *
926 * @param a Log message in format <tt>("string\n" [, args])</tt>.
927 */
928#ifdef LOG_USE_C99
929# define LogWarnFunc(a) \
930 _LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
931#else
932# define LogWarnFunc(a) \
933 do { LogFlow((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
934#endif
935/** @} */
936
937
938/** @name Logging macros prefixing the this pointer value and method name.
939 * @{ */
940
941/** @def LogThisFunc
942 * Level 1 logging inside a C++ non-static method, with object pointer and
943 * method name prefixed to the given message.
944 * @param a Log message in format <tt>("string\n" [, args])</tt>.
945 */
946#ifdef LOG_USE_C99
947# define LogThisFunc(a) \
948 _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
949#else
950# define LogThisFunc(a) do { Log(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
951#endif
952
953/** @def Log2ThisFunc
954 * Level 2 logging inside a C++ non-static method, with object pointer and
955 * method name prefixed to the given message.
956 * @param a Log message in format <tt>("string\n" [, args])</tt>.
957 */
958#ifdef LOG_USE_C99
959# define Log2ThisFunc(a) \
960 _LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
961#else
962# define Log2ThisFunc(a) do { Log2(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log2(a); } while (0)
963#endif
964
965/** @def Log3ThisFunc
966 * Level 3 logging inside a C++ non-static method, with object pointer and
967 * method name prefixed to the given message.
968 * @param a Log message in format <tt>("string\n" [, args])</tt>.
969 */
970#ifdef LOG_USE_C99
971# define Log3ThisFunc(a) \
972 _LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
973#else
974# define Log3ThisFunc(a) do { Log3(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log3(a); } while (0)
975#endif
976
977/** @def Log4ThisFunc
978 * Level 4 logging inside a C++ non-static method, with object pointer and
979 * method name prefixed to the given message.
980 * @param a Log message in format <tt>("string\n" [, args])</tt>.
981 */
982#ifdef LOG_USE_C99
983# define Log4ThisFunc(a) \
984 _LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
985#else
986# define Log4ThisFunc(a) do { Log4(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log4(a); } while (0)
987#endif
988
989/** @def Log5ThisFunc
990 * Level 5 logging inside a C++ non-static method, with object pointer and
991 * method name prefixed to the given message.
992 * @param a Log message in format <tt>("string\n" [, args])</tt>.
993 */
994#ifdef LOG_USE_C99
995# define Log5ThisFunc(a) \
996 _LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
997#else
998# define Log5ThisFunc(a) do { Log5(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log5(a); } while (0)
999#endif
1000
1001/** @def Log6ThisFunc
1002 * Level 6 logging inside a C++ non-static method, with object pointer and
1003 * method name prefixed to the given message.
1004 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1005 */
1006#ifdef LOG_USE_C99
1007# define Log6ThisFunc(a) \
1008 _LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1009#else
1010# define Log6ThisFunc(a) do { Log6(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log6(a); } while (0)
1011#endif
1012
1013/** @def Log7ThisFunc
1014 * Level 7 logging inside a C++ non-static method, with object pointer and
1015 * method name prefixed to the given message.
1016 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1017 */
1018#ifdef LOG_USE_C99
1019# define Log7ThisFunc(a) \
1020 _LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1021#else
1022# define Log7ThisFunc(a) do { Log7(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log7(a); } while (0)
1023#endif
1024
1025/** @def Log8ThisFunc
1026 * Level 8 logging inside a C++ non-static method, with object pointer and
1027 * method name prefixed to the given message.
1028 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1029 */
1030#ifdef LOG_USE_C99
1031# define Log8ThisFunc(a) \
1032 _LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1033#else
1034# define Log8ThisFunc(a) do { Log8(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log8(a); } while (0)
1035#endif
1036
1037/** @def Log9ThisFunc
1038 * Level 9 logging inside a C++ non-static method, with object pointer and
1039 * method name prefixed to the given message.
1040 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1041 */
1042#ifdef LOG_USE_C99
1043# define Log9ThisFunc(a) \
1044 _LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1045#else
1046# define Log9ThisFunc(a) do { Log9(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log9(a); } while (0)
1047#endif
1048
1049/** @def Log10ThisFunc
1050 * Level 10 logging inside a C++ non-static method, with object pointer and
1051 * method name prefixed to the given message.
1052 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1053 */
1054#ifdef LOG_USE_C99
1055# define Log10ThisFunc(a) \
1056 _LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1057#else
1058# define Log10ThisFunc(a) do { Log10(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log10(a); } while (0)
1059#endif
1060
1061/** @def Log11ThisFunc
1062 * Level 11 logging inside a C++ non-static method, with object pointer and
1063 * method name prefixed to the given message.
1064 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1065 */
1066#ifdef LOG_USE_C99
1067# define Log11ThisFunc(a) \
1068 _LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1069#else
1070# define Log11ThisFunc(a) do { Log11(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log11(a); } while (0)
1071#endif
1072
1073/** @def Log12ThisFunc
1074 * Level 12 logging inside a C++ non-static method, with object pointer and
1075 * method name prefixed to the given message.
1076 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1077 */
1078#ifdef LOG_USE_C99
1079# define Log12ThisFunc(a) \
1080 _LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1081#else
1082# define Log12ThisFunc(a) do { Log12(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log12(a); } while (0)
1083#endif
1084
1085/** @def LogFlowThisFunc
1086 * Flow level logging inside a C++ non-static method, with object pointer and
1087 * method name prefixed to the given message.
1088 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1089 */
1090#ifdef LOG_USE_C99
1091# define LogFlowThisFunc(a) \
1092 _LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1093#else
1094# define LogFlowThisFunc(a) do { LogFlow(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
1095#endif
1096
1097/** @def LogWarnThisFunc
1098 * Warning level logging inside a C++ non-static method, with object pointer and
1099 * method name prefixed to the given message.
1100 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1101 */
1102#ifdef LOG_USE_C99
1103# define LogWarnThisFunc(a) \
1104 _LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1105#else
1106# define LogWarnThisFunc(a) do { LogWarn(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogWarn(a); } while (0)
1107#endif
1108/** @} */
1109
1110
1111/** @name Misc Logging Macros
1112 * @{ */
1113
1114/** @def Log1Warning
1115 * The same as Log(), but prepents a <tt>"WARNING! "</tt> string to the message.
1116 *
1117 * @param a Custom log message in format <tt>("string\n" [, args])</tt>.
1118 */
1119#if defined(LOG_USE_C99)
1120# define Log1Warning(a) _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "WARNING! %M", _LogRemoveParentheseis a )
1121#else
1122# define Log1Warning(a) do { Log(("WARNING! ")); Log(a); } while (0)
1123#endif
1124
1125/** @def Log1WarningFunc
1126 * The same as LogWarning(), but prepents the log message with the function name.
1127 *
1128 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1129 */
1130#ifdef LOG_USE_C99
1131# define Log1WarningFunc(a) \
1132 _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": WARNING! %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1133#else
1134# define Log1WarningFunc(a) \
1135 do { Log((LOG_FN_FMT ": WARNING! ", __PRETTY_FUNCTION__)); Log(a); } while (0)
1136#endif
1137
1138/** @def Log1WarningThisFunc
1139 * The same as LogWarningFunc() but for class functions (methods): the resulting
1140 * log line is additionally prepended with a hex value of |this| pointer.
1141 *
1142 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1143 */
1144#ifdef LOG_USE_C99
1145# define Log1WarningThisFunc(a) \
1146 _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": WARNING! %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1147#else
1148# define Log1WarningThisFunc(a) \
1149 do { Log(("{%p} " LOG_FN_FMT ": WARNING! ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
1150#endif
1151
1152
1153/** Shortcut to |LogFlowFunc ("ENTER\n")|, marks the beginnig of the function. */
1154#define LogFlowFuncEnter() LogFlowFunc(("ENTER\n"))
1155
1156/** Shortcut to |LogFlowFunc ("LEAVE\n")|, marks the end of the function. */
1157#define LogFlowFuncLeave() LogFlowFunc(("LEAVE\n"))
1158
1159/** Shortcut to |LogFlowFunc ("LEAVE: %Rrc\n")|, marks the end of the function. */
1160#define LogFlowFuncLeaveRC(rc) LogFlowFunc(("LEAVE: %Rrc\n", (rc)))
1161
1162/** Shortcut to |LogFlowThisFunc ("ENTER\n")|, marks the beginnig of the function. */
1163#define LogFlowThisFuncEnter() LogFlowThisFunc(("ENTER\n"))
1164
1165/** Shortcut to |LogFlowThisFunc ("LEAVE\n")|, marks the end of the function. */
1166#define LogFlowThisFuncLeave() LogFlowThisFunc(("LEAVE\n"))
1167
1168
1169/** @def LogObjRefCnt
1170 * Helper macro to print the current reference count of the given COM object
1171 * to the log file.
1172 *
1173 * @param pObj Pointer to the object in question (must be a pointer to an
1174 * IUnknown subclass or simply define COM-style AddRef() and
1175 * Release() methods)
1176 */
1177#define LogObjRefCnt(pObj) \
1178 do { \
1179 if (LogIsFlowEnabled()) \
1180 { \
1181 int cRefsForLog = (pObj)->AddRef(); \
1182 LogFlow((#pObj "{%p}.refCnt=%d\n", (pObj), cRefsForLog - 1)); \
1183 (pObj)->Release(); \
1184 } \
1185 } while (0)
1186/** @} */
1187
1188
1189
1190/** @name Passing Function Call Position When Logging.
1191 *
1192 * This is a little bit ugly as we have to omit the comma before the
1193 * position parameters so that we don't inccur any overhead in non-logging
1194 * builds (!defined(LOG_ENABLED).
1195 *
1196 * @{ */
1197/** Source position for passing to a function call. */
1198#ifdef LOG_ENABLED
1199# define RTLOG_COMMA_SRC_POS , __FILE__, __LINE__, __PRETTY_FUNCTION__
1200#else
1201# define RTLOG_COMMA_SRC_POS RT_NOTHING
1202#endif
1203/** Source position declaration. */
1204#ifdef LOG_ENABLED
1205# define RTLOG_COMMA_SRC_POS_DECL , const char *pszFile, unsigned iLine, const char *pszFunction
1206#else
1207# define RTLOG_COMMA_SRC_POS_DECL RT_NOTHING
1208#endif
1209/** Source position arguments. */
1210#ifdef LOG_ENABLED
1211# define RTLOG_COMMA_SRC_POS_ARGS , pszFile, iLine, pszFunction
1212#else
1213# define RTLOG_COMMA_SRC_POS_ARGS RT_NOTHING
1214#endif
1215/** Applies NOREF() to the source position arguments. */
1216#ifdef LOG_ENABLED
1217# define RTLOG_SRC_POS_NOREF() do { NOREF(pszFile); NOREF(iLine); NOREF(pszFunction); } while (0)
1218#else
1219# define RTLOG_SRC_POS_NOREF() do { } while (0)
1220#endif
1221/** @} */
1222
1223
1224
1225/** @name Release Logging
1226 * @{
1227 */
1228
1229#ifdef DOXYGEN_RUNNING
1230# define RTLOG_REL_DISABLED
1231# define RTLOG_REL_ENABLED
1232#endif
1233
1234/** @def RTLOG_REL_DISABLED
1235 * Use this compile time define to disable all release logging
1236 * macros.
1237 */
1238
1239/** @def RTLOG_REL_ENABLED
1240 * Use this compile time define to override RTLOG_REL_DISABLE.
1241 */
1242
1243/*
1244 * Determine whether release logging is enabled and forcefully normalize the indicators.
1245 */
1246#if !defined(RTLOG_REL_DISABLED) || defined(RTLOG_REL_ENABLED)
1247# undef RTLOG_REL_DISABLED
1248# undef RTLOG_REL_ENABLED
1249# define RTLOG_REL_ENABLED
1250#else
1251# undef RTLOG_REL_ENABLED
1252# undef RTLOG_REL_DISABLED
1253# define RTLOG_REL_DISABLED
1254#endif
1255
1256/** @name Macros for checking whether a release log level is enabled.
1257 * @{ */
1258/** @def LogRelIsItEnabled
1259 * Checks whether the specified release logging group is enabled or not.
1260 */
1261#define LogRelIsItEnabled(a_fFlags, a_iGroup) ( RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)) != NULL )
1262
1263/** @def LogRelIsEnabled
1264 * Checks whether level 1 release logging is enabled.
1265 */
1266#define LogRelIsEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
1267
1268/** @def LogRelIs2Enabled
1269 * Checks whether level 2 release logging is enabled.
1270 */
1271#define LogRelIs2Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
1272
1273/** @def LogRelIs3Enabled
1274 * Checks whether level 3 release logging is enabled.
1275 */
1276#define LogRelIs3Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
1277
1278/** @def LogRelIs4Enabled
1279 * Checks whether level 4 release logging is enabled.
1280 */
1281#define LogRelIs4Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
1282
1283/** @def LogRelIs5Enabled
1284 * Checks whether level 5 release logging is enabled.
1285 */
1286#define LogRelIs5Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
1287
1288/** @def LogRelIs6Enabled
1289 * Checks whether level 6 release logging is enabled.
1290 */
1291#define LogRelIs6Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
1292
1293/** @def LogRelIs7Enabled
1294 * Checks whether level 7 release logging is enabled.
1295 */
1296#define LogRelIs7Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP)
1297
1298/** @def LogRelIs8Enabled
1299 * Checks whether level 8 release logging is enabled.
1300 */
1301#define LogRelIs8Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP)
1302
1303/** @def LogRelIs2Enabled
1304 * Checks whether level 9 release logging is enabled.
1305 */
1306#define LogRelIs9Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP)
1307
1308/** @def LogRelIs10Enabled
1309 * Checks whether level 10 release logging is enabled.
1310 */
1311#define LogRelIs10Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP)
1312
1313/** @def LogRelIs11Enabled
1314 * Checks whether level 10 release logging is enabled.
1315 */
1316#define LogRelIs11Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP)
1317
1318/** @def LogRelIs12Enabled
1319 * Checks whether level 12 release logging is enabled.
1320 */
1321#define LogRelIs12Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP)
1322
1323/** @def LogRelIsFlowEnabled
1324 * Checks whether execution flow release logging is enabled.
1325 */
1326#define LogRelIsFlowEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
1327
1328/** @def LogRelIsWarnEnabled
1329 * Checks whether warning level release logging is enabled.
1330 */
1331#define LogRelIsWarnEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
1332/** @} */
1333
1334
1335/** @def LogRelIt
1336 * Write to specific logger if group enabled.
1337 */
1338/** @def LogRelItLikely
1339 * Write to specific logger if group enabled, assuming it likely it is enabled.
1340 */
1341/** @def LogRelMaxIt
1342 * Write to specific logger if group enabled and at less than a_cMax messages
1343 * have hit the log. Uses a static variable to count.
1344 */
1345#ifdef RTLOG_REL_ENABLED
1346# if defined(LOG_USE_C99)
1347# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1348# define _LogRelIt(a_fFlags, a_iGroup, ...) \
1349 do \
1350 { \
1351 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1352 if (RT_LIKELY(!LogRelIt_pLogger)) \
1353 { /* likely */ } \
1354 else \
1355 RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1356 _LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1357 } while (0)
1358# define LogRelIt(a_fFlags, a_iGroup, fmtargs) \
1359 _LogRelIt(a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1360# define _LogRelItLikely(a_fFlags, a_iGroup, ...) \
1361 do \
1362 { \
1363 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1364 if (LogRelIt_pLogger) \
1365 RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1366 _LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1367 } while (0)
1368# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) \
1369 _LogRelItLikely(a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1370# define _LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, ...) \
1371 do \
1372 { \
1373 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1374 if (LogRelIt_pLogger) \
1375 { \
1376 static uint32_t s_LogRelMaxIt_cLogged = 0; \
1377 if (s_LogRelMaxIt_cLogged < (a_cMax)) \
1378 { \
1379 s_LogRelMaxIt_cLogged++; \
1380 RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1381 } \
1382 } \
1383 _LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1384 } while (0)
1385# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) \
1386 _LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1387# else
1388# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) \
1389 do \
1390 { \
1391 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1392 if (LogRelIt_pLogger) \
1393 { \
1394 LogRelIt_pLogger->pfnLogger fmtargs; \
1395 } \
1396 LogIt(a_fFlags, a_iGroup, fmtargs); \
1397 } while (0)
1398# define LogRelIt(a_fFlags, a_iGroup, fmtargs) \
1399 do \
1400 { \
1401 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1402 if (RT_LIKELY(!LogRelIt_pLogger)) \
1403 { /* likely */ } \
1404 else \
1405 { \
1406 LogRelIt_pLogger->pfnLogger fmtargs; \
1407 } \
1408 LogIt(a_fFlags, a_iGroup, fmtargs); \
1409 } while (0)
1410# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) \
1411 do \
1412 { \
1413 PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1414 if (LogRelIt_pLogger) \
1415 { \
1416 static uint32_t s_LogRelMaxIt_cLogged = 0; \
1417 if (s_LogRelMaxIt_cLogged < (a_cMax)) \
1418 { \
1419 s_LogRelMaxIt_cLogged++; \
1420 LogRelIt_pLogger->pfnLogger fmtargs; \
1421 } \
1422 } \
1423 LogIt(a_fFlags, a_iGroup, fmtargs); \
1424 } while (0)
1425# endif
1426#else /* !RTLOG_REL_ENABLED */
1427# define LogRelIt(a_fFlags, a_iGroup, fmtargs) do { } while (0)
1428# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) do { } while (0)
1429# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) do { } while (0)
1430# if defined(LOG_USE_C99)
1431# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1432# define _LogRelIt(a_fFlags, a_iGroup, ...) do { } while (0)
1433# define _LogRelItLikely(a_fFlags, a_iGroup, ...) do { } while (0)
1434# define _LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, ...) do { } while (0)
1435# endif
1436#endif /* !RTLOG_REL_ENABLED */
1437
1438
1439/** @name Basic release logging macros
1440 * @{ */
1441/** @def LogRel
1442 * Level 1 release logging.
1443 */
1444#define LogRel(a) LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
1445
1446/** @def LogRel2
1447 * Level 2 release logging.
1448 */
1449#define LogRel2(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
1450
1451/** @def LogRel3
1452 * Level 3 release logging.
1453 */
1454#define LogRel3(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
1455
1456/** @def LogRel4
1457 * Level 4 release logging.
1458 */
1459#define LogRel4(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
1460
1461/** @def LogRel5
1462 * Level 5 release logging.
1463 */
1464#define LogRel5(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
1465
1466/** @def LogRel6
1467 * Level 6 release logging.
1468 */
1469#define LogRel6(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
1470
1471/** @def LogRel7
1472 * Level 7 release logging.
1473 */
1474#define LogRel7(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
1475
1476/** @def LogRel8
1477 * Level 8 release logging.
1478 */
1479#define LogRel8(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
1480
1481/** @def LogRel9
1482 * Level 9 release logging.
1483 */
1484#define LogRel9(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
1485
1486/** @def LogRel10
1487 * Level 10 release logging.
1488 */
1489#define LogRel10(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
1490
1491/** @def LogRel11
1492 * Level 11 release logging.
1493 */
1494#define LogRel11(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
1495
1496/** @def LogRel12
1497 * Level 12 release logging.
1498 */
1499#define LogRel12(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
1500
1501/** @def LogRelFlow
1502 * Logging of execution flow.
1503 */
1504#define LogRelFlow(a) LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
1505
1506/** @def LogRelWarn
1507 * Warning level release logging.
1508 */
1509#define LogRelWarn(a) LogRelIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, a)
1510/** @} */
1511
1512
1513
1514/** @name Basic release logging macros with local max
1515 * @{ */
1516/** @def LogRelMax
1517 * Level 1 release logging with a max number of log entries.
1518 */
1519#define LogRelMax(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
1520
1521/** @def LogRelMax2
1522 * Level 2 release logging with a max number of log entries.
1523 */
1524#define LogRelMax2(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
1525
1526/** @def LogRelMax3
1527 * Level 3 release logging with a max number of log entries.
1528 */
1529#define LogRelMax3(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
1530
1531/** @def LogRelMax4
1532 * Level 4 release logging with a max number of log entries.
1533 */
1534#define LogRelMax4(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
1535
1536/** @def LogRelMax5
1537 * Level 5 release logging with a max number of log entries.
1538 */
1539#define LogRelMax5(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
1540
1541/** @def LogRelMax6
1542 * Level 6 release logging with a max number of log entries.
1543 */
1544#define LogRelMax6(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
1545
1546/** @def LogRelMax7
1547 * Level 7 release logging with a max number of log entries.
1548 */
1549#define LogRelMax7(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
1550
1551/** @def LogRelMax8
1552 * Level 8 release logging with a max number of log entries.
1553 */
1554#define LogRelMax8(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
1555
1556/** @def LogRelMax9
1557 * Level 9 release logging with a max number of log entries.
1558 */
1559#define LogRelMax9(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
1560
1561/** @def LogRelMax10
1562 * Level 10 release logging with a max number of log entries.
1563 */
1564#define LogRelMax10(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
1565
1566/** @def LogRelMax11
1567 * Level 11 release logging with a max number of log entries.
1568 */
1569#define LogRelMax11(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
1570
1571/** @def LogRelMax12
1572 * Level 12 release logging with a max number of log entries.
1573 */
1574#define LogRelMax12(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
1575
1576/** @def LogRelMaxFlow
1577 * Logging of execution flow with a max number of log entries.
1578 */
1579#define LogRelMaxFlow(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
1580/** @} */
1581
1582
1583/** @name Release logging macros prefixing the current function name.
1584 * @{ */
1585
1586/** @def LogRelFunc
1587 * Release logging. Prepends the given log message with the function name
1588 * followed by a semicolon and space.
1589 */
1590#ifdef LOG_USE_C99
1591# define LogRelFunc(a) \
1592 _LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1593#else
1594# define LogRelFunc(a) do { LogRel((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1595#endif
1596
1597/** @def LogRelFlowFunc
1598 * Release logging. Macro to log the execution flow inside C/C++ functions.
1599 *
1600 * Prepends the given log message with the function name followed by
1601 * a semicolon and space.
1602 *
1603 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1604 */
1605#ifdef LOG_USE_C99
1606# define LogRelFlowFunc(a) _LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1607#else
1608# define LogRelFlowFunc(a) do { LogRelFlow((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRelFlow(a); } while (0)
1609#endif
1610
1611/** @def LogRelMaxFunc
1612 * Release logging. Prepends the given log message with the function name
1613 * followed by a semicolon and space.
1614 */
1615#ifdef LOG_USE_C99
1616# define LogRelMaxFunc(a_cMax, a) \
1617 _LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1618#else
1619# define LogRelMaxFunc(a_cMax, a) \
1620 do { LogRelMax(a_cMax, (LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRelMax(a_cMax, a); } while (0)
1621#endif
1622
1623/** @def LogRelMaxFlowFunc
1624 * Release logging. Macro to log the execution flow inside C/C++ functions.
1625 *
1626 * Prepends the given log message with the function name followed by
1627 * a semicolon and space.
1628 *
1629 * @param a_cMax Max number of times this should hit the log.
1630 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1631 */
1632#ifdef LOG_USE_C99
1633# define LogRelMaxFlowFunc(a_cMax, a) \
1634 _LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1635#else
1636# define LogRelMaxFlowFunc(a_cMax, a) \
1637 do { LogRelMaxFlow(a_cMax, (LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRelFlow(a_cMax, a); } while (0)
1638#endif
1639
1640/** @} */
1641
1642
1643/** @name Release Logging macros prefixing the this pointer value and method name.
1644 * @{ */
1645
1646/** @def LogRelThisFunc
1647 * The same as LogRelFunc but for class functions (methods): the resulting log
1648 * line is additionally prepended with a hex value of |this| pointer.
1649 */
1650#ifdef LOG_USE_C99
1651# define LogRelThisFunc(a) \
1652 _LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1653#else
1654# define LogRelThisFunc(a) \
1655 do { LogRel(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1656#endif
1657
1658/** @def LogRelMaxThisFunc
1659 * The same as LogRelFunc but for class functions (methods): the resulting log
1660 * line is additionally prepended with a hex value of |this| pointer.
1661 * @param a_cMax Max number of times this should hit the log.
1662 * @param a Log message in format <tt>("string\n" [, args])</tt>.
1663 */
1664#ifdef LOG_USE_C99
1665# define LogRelMaxThisFunc(a_cMax, a) \
1666 _LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1667#else
1668# define LogRelMaxThisFunc(a_cMax, a) \
1669 do { LogRelMax(a_cMax, ("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogRelMax(a_cMax, a); } while (0)
1670#endif
1671
1672/** @def LogRelFlowThisFunc
1673 * The same as LogRelFlowFunc but for class functions (methods): the resulting
1674 * log line is additionally prepended with a hex value of |this| pointer.
1675 */
1676#ifdef LOG_USE_C99
1677# define LogRelFlowThisFunc(a) \
1678 _LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1679#else
1680# define LogRelFlowThisFunc(a) do { LogRelFlow(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogRelFlow(a); } while (0)
1681#endif
1682
1683
1684/** Shortcut to |LogRelFlowFunc ("ENTER\n")|, marks the beginnig of the function. */
1685#define LogRelFlowFuncEnter() LogRelFlowFunc(("ENTER\n"))
1686
1687/** Shortcut to |LogRelFlowFunc ("LEAVE\n")|, marks the end of the function. */
1688#define LogRelFlowFuncLeave() LogRelFlowFunc(("LEAVE\n"))
1689
1690/** Shortcut to |LogRelFlowFunc ("LEAVE: %Rrc\n")|, marks the end of the function. */
1691#define LogRelFlowFuncLeaveRC(rc) LogRelFlowFunc(("LEAVE: %Rrc\n", (rc)))
1692
1693/** Shortcut to |LogRelFlowThisFunc ("ENTER\n")|, marks the beginnig of the function. */
1694#define LogRelFlowThisFuncEnter() LogRelFlowThisFunc(("ENTER\n"))
1695
1696/** Shortcut to |LogRelFlowThisFunc ("LEAVE\n")|, marks the end of the function. */
1697#define LogRelFlowThisFuncLeave() LogRelFlowThisFunc(("LEAVE\n"))
1698
1699/** @} */
1700
1701
1702#ifndef IN_RC
1703/**
1704 * Sets the default release logger instance.
1705 *
1706 * @returns The old default instance.
1707 * @param pLogger The new default release logger instance.
1708 */
1709RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger);
1710#endif /* !IN_RC */
1711
1712/**
1713 * Gets the default release logger instance.
1714 *
1715 * @returns Pointer to default release logger instance if availble, otherwise NULL.
1716 */
1717RTDECL(PRTLOGGER) RTLogRelGetDefaultInstance(void);
1718
1719/**
1720 * Gets the default release logger instance.
1721 *
1722 * @returns Pointer to default release logger instance if availble, otherwise NULL.
1723 * @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1724 * the high 16 bits.
1725 */
1726RTDECL(PRTLOGGER) RTLogRelGetDefaultInstanceEx(uint32_t fFlagsAndGroup);
1727
1728/**
1729 * Write to a logger instance, defaulting to the release one.
1730 *
1731 * This function will check whether the instance, group and flags makes up a
1732 * logging kind which is currently enabled before writing anything to the log.
1733 *
1734 * @param pLogger Pointer to logger instance.
1735 * @param fFlags The logging flags.
1736 * @param iGroup The group.
1737 * The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1738 * only for internal usage!
1739 * @param pszFormat Format string.
1740 * @param ... Format arguments.
1741 * @remark This is a worker function for LogRelIt.
1742 */
1743RTDECL(void) RTLogRelLogger(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
1744 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
1745
1746/**
1747 * Write to a logger instance, defaulting to the release one.
1748 *
1749 * This function will check whether the instance, group and flags makes up a
1750 * logging kind which is currently enabled before writing anything to the log.
1751 *
1752 * @param pLogger Pointer to logger instance. If NULL the default release instance is attempted.
1753 * @param fFlags The logging flags.
1754 * @param iGroup The group.
1755 * The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1756 * only for internal usage!
1757 * @param pszFormat Format string.
1758 * @param args Format arguments.
1759 */
1760RTDECL(void) RTLogRelLoggerV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
1761 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(4, 0);
1762
1763/**
1764 * printf like function for writing to the default release log.
1765 *
1766 * @param pszFormat Printf like format string.
1767 * @param ... Optional arguments as specified in pszFormat.
1768 *
1769 * @remark The API doesn't support formatting of floating point numbers at the moment.
1770 */
1771RTDECL(void) RTLogRelPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1772
1773/**
1774 * vprintf like function for writing to the default release log.
1775 *
1776 * @param pszFormat Printf like format string.
1777 * @param args Optional arguments as specified in pszFormat.
1778 *
1779 * @remark The API doesn't support formatting of floating point numbers at the moment.
1780 */
1781RTDECL(void) RTLogRelPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
1782
1783/**
1784 * Changes the buffering setting of the default release logger.
1785 *
1786 * This can be used for optimizing longish logging sequences.
1787 *
1788 * @returns The old state.
1789 * @param fBuffered The new state.
1790 */
1791RTDECL(bool) RTLogRelSetBuffering(bool fBuffered);
1792
1793/** @} */
1794
1795
1796
1797/** @name COM port logging
1798 * {
1799 */
1800
1801#ifdef DOXYGEN_RUNNING
1802# define LOG_TO_COM
1803# define LOG_NO_COM
1804#endif
1805
1806/** @def LOG_TO_COM
1807 * Redirects the normal logging macros to the serial versions.
1808 */
1809
1810/** @def LOG_NO_COM
1811 * Disables all LogCom* macros.
1812 */
1813
1814/** @def LogCom
1815 * Generic logging to serial port.
1816 */
1817#if defined(LOG_ENABLED) && !defined(LOG_NO_COM)
1818# define LogCom(a) RTLogComPrintf a
1819#else
1820# define LogCom(a) do { } while (0)
1821#endif
1822
1823/** @def LogComFlow
1824 * Logging to serial port of execution flow.
1825 */
1826#if defined(LOG_ENABLED) && defined(LOG_ENABLE_FLOW) && !defined(LOG_NO_COM)
1827# define LogComFlow(a) RTLogComPrintf a
1828#else
1829# define LogComFlow(a) do { } while (0)
1830#endif
1831
1832#ifdef LOG_TO_COM
1833# undef Log
1834# define Log(a) LogCom(a)
1835# undef LogFlow
1836# define LogFlow(a) LogComFlow(a)
1837#endif
1838
1839/** @} */
1840
1841
1842/** @name Backdoor Logging
1843 * @{
1844 */
1845
1846#ifdef DOXYGEN_RUNNING
1847# define LOG_TO_BACKDOOR
1848# define LOG_NO_BACKDOOR
1849#endif
1850
1851/** @def LOG_TO_BACKDOOR
1852 * Redirects the normal logging macros to the backdoor versions.
1853 */
1854
1855/** @def LOG_NO_BACKDOOR
1856 * Disables all LogBackdoor* macros.
1857 */
1858
1859/** @def LogBackdoor
1860 * Generic logging to the VBox backdoor via port I/O.
1861 */
1862#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1863# define LogBackdoor(a) RTLogBackdoorPrintf a
1864#else
1865# define LogBackdoor(a) do { } while (0)
1866#endif
1867
1868/** @def LogBackdoorFlow
1869 * Logging of execution flow messages to the backdoor I/O port.
1870 */
1871#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1872# define LogBackdoorFlow(a) RTLogBackdoorPrintf a
1873#else
1874# define LogBackdoorFlow(a) do { } while (0)
1875#endif
1876
1877/** @def LogRelBackdoor
1878 * Release logging to the VBox backdoor via port I/O.
1879 */
1880#if !defined(LOG_NO_BACKDOOR)
1881# define LogRelBackdoor(a) RTLogBackdoorPrintf a
1882#else
1883# define LogRelBackdoor(a) do { } while (0)
1884#endif
1885
1886#ifdef LOG_TO_BACKDOOR
1887# undef Log
1888# define Log(a) LogBackdoor(a)
1889# undef LogFlow
1890# define LogFlow(a) LogBackdoorFlow(a)
1891# undef LogRel
1892# define LogRel(a) LogRelBackdoor(a)
1893# if defined(LOG_USE_C99)
1894# undef _LogIt
1895# define _LogIt(a_fFlags, a_iGroup, ...) LogBackdoor((__VA_ARGS__))
1896# endif
1897#endif
1898
1899/** @} */
1900
1901
1902
1903/**
1904 * Gets the default logger instance, creating it if necessary.
1905 *
1906 * @returns Pointer to default logger instance if availble, otherwise NULL.
1907 */
1908RTDECL(PRTLOGGER) RTLogDefaultInstance(void);
1909
1910/**
1911 * Gets the logger instance if enabled, creating it if necessary.
1912 *
1913 * @returns Pointer to default logger instance, if group has the specified
1914 * flags enabled. Otherwise NULL is returned.
1915 * @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1916 * the high 16 bits.
1917 */
1918RTDECL(PRTLOGGER) RTLogDefaultInstanceEx(uint32_t fFlagsAndGroup);
1919
1920/**
1921 * Gets the default logger instance.
1922 *
1923 * @returns Pointer to default logger instance if availble, otherwise NULL.
1924 */
1925RTDECL(PRTLOGGER) RTLogGetDefaultInstance(void);
1926
1927/**
1928 * Gets the default logger instance if enabled.
1929 *
1930 * @returns Pointer to default logger instance, if group has the specified
1931 * flags enabled. Otherwise NULL is returned.
1932 * @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1933 * the high 16 bits.
1934 */
1935RTDECL(PRTLOGGER) RTLogGetDefaultInstanceEx(uint32_t fFlagsAndGroup);
1936
1937#ifndef IN_RC
1938/**
1939 * Sets the default logger instance.
1940 *
1941 * @returns The old default instance.
1942 * @param pLogger The new default logger instance.
1943 */
1944RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger);
1945#endif /* !IN_RC */
1946
1947#ifdef IN_RING0
1948/**
1949 * Changes the default logger instance for the current thread.
1950 *
1951 * @returns IPRT status code.
1952 * @param pLogger The logger instance. Pass NULL for deregistration.
1953 * @param uKey Associated key for cleanup purposes. If pLogger is NULL,
1954 * all instances with this key will be deregistered. So in
1955 * order to only deregister the instance associated with the
1956 * current thread use 0.
1957 */
1958RTDECL(int) RTLogSetDefaultInstanceThread(PRTLOGGER pLogger, uintptr_t uKey);
1959#endif /* IN_RING0 */
1960
1961
1962#ifndef IN_RC
1963/**
1964 * Creates the default logger instance for a iprt users.
1965 *
1966 * Any user of the logging features will need to implement
1967 * this or use the generic dummy.
1968 *
1969 * @returns Pointer to the logger instance.
1970 */
1971RTDECL(PRTLOGGER) RTLogDefaultInit(void);
1972
1973/**
1974 * Create a logger instance.
1975 *
1976 * @returns iprt status code.
1977 *
1978 * @param ppLogger Where to store the logger instance.
1979 * @param fFlags Logger instance flags, a combination of the
1980 * RTLOGFLAGS_* values.
1981 * @param pszGroupSettings The initial group settings.
1982 * @param pszEnvVarBase Base name for the environment variables for
1983 * this instance.
1984 * @param cGroups Number of groups in the array.
1985 * @param papszGroups Pointer to array of groups. This must stick
1986 * around for the life of the logger instance.
1987 * @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
1988 * if pszFilenameFmt specified.
1989 * @param pszFilenameFmt Log filename format string. Standard
1990 * RTStrFormat().
1991 * @param ... Format arguments.
1992 */
1993RTDECL(int) RTLogCreate(PRTLOGGER *ppLogger, uint32_t fFlags, const char *pszGroupSettings,
1994 const char *pszEnvVarBase, unsigned cGroups, const char * const * papszGroups,
1995 uint32_t fDestFlags, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(8, 9);
1996
1997/**
1998 * Create a logger instance.
1999 *
2000 * @returns iprt status code.
2001 *
2002 * @param ppLogger Where to store the logger instance.
2003 * @param fFlags Logger instance flags, a combination of the
2004 * RTLOGFLAGS_* values.
2005 * @param pszGroupSettings The initial group settings.
2006 * @param pszEnvVarBase Base name for the environment variables for
2007 * this instance.
2008 * @param cGroups Number of groups in the array.
2009 * @param papszGroups Pointer to array of groups. This must stick
2010 * around for the life of the logger instance.
2011 * @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
2012 * if pszFilenameFmt specified.
2013 * @param pfnPhase Callback function for starting logging and for
2014 * ending or starting a new file for log history
2015 * rotation. NULL is OK.
2016 * @param cHistory Number of old log files to keep when performing
2017 * log history rotation. 0 means no history.
2018 * @param cbHistoryFileMax Maximum size of log file when performing
2019 * history rotation. 0 means no size limit.
2020 * @param cSecsHistoryTimeSlot Maximum time interval per log file when
2021 * performing history rotation, in seconds.
2022 * 0 means time limit.
2023 * @param pErrInfo Where to return extended error information.
2024 * Optional.
2025 * @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
2026 * @param ... Format arguments.
2027 */
2028RTDECL(int) RTLogCreateEx(PRTLOGGER *ppLogger, uint32_t fFlags, const char *pszGroupSettings,
2029 const char *pszEnvVarBase, unsigned cGroups, const char * const * papszGroups,
2030 uint32_t fDestFlags, PFNRTLOGPHASE pfnPhase, uint32_t cHistory,
2031 uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot, PRTERRINFO pErrInfo,
2032 const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(13, 14);
2033
2034/**
2035 * Create a logger instance.
2036 *
2037 * @returns iprt status code.
2038 *
2039 * @param ppLogger Where to store the logger instance.
2040 * @param fFlags Logger instance flags, a combination of the
2041 * RTLOGFLAGS_* values.
2042 * @param pszGroupSettings The initial group settings.
2043 * @param pszEnvVarBase Base name for the environment variables for
2044 * this instance.
2045 * @param cGroups Number of groups in the array.
2046 * @param papszGroups Pointer to array of groups. This must stick
2047 * around for the life of the logger instance.
2048 * @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
2049 * if pszFilenameFmt specified.
2050 * @param pfnPhase Callback function for starting logging and for
2051 * ending or starting a new file for log history
2052 * rotation.
2053 * @param cHistory Number of old log files to keep when performing
2054 * log history rotation. 0 means no history.
2055 * @param cbHistoryFileMax Maximum size of log file when performing
2056 * history rotation. 0 means no size limit.
2057 * @param cSecsHistoryTimeSlot Maximum time interval per log file when
2058 * performing history rotation, in seconds.
2059 * 0 means no time limit.
2060 * @param pErrInfo Where to return extended error information.
2061 * Optional.
2062 * @param pszFilenameFmt Log filename format string. Standard
2063 * RTStrFormat().
2064 * @param args Format arguments.
2065 */
2066RTDECL(int) RTLogCreateExV(PRTLOGGER *ppLogger, uint32_t fFlags, const char *pszGroupSettings,
2067 const char *pszEnvVarBase, unsigned cGroups, const char * const * papszGroups,
2068 uint32_t fDestFlags, PFNRTLOGPHASE pfnPhase, uint32_t cHistory,
2069 uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot, PRTERRINFO pErrInfo,
2070 const char *pszFilenameFmt, va_list args) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(13, 0);
2071
2072/**
2073 * Create a logger instance for singled threaded ring-0 usage.
2074 *
2075 * @returns iprt status code.
2076 *
2077 * @param pLogger Where to create the logger instance.
2078 * @param cbLogger The amount of memory available for the logger instance.
2079 * @param pLoggerR0Ptr The ring-0 address corresponding to @a pLogger.
2080 * @param pfnLoggerR0Ptr Pointer to logger wrapper function.
2081 * @param pfnFlushR0Ptr Pointer to flush function.
2082 * @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
2083 * @param fDestFlags The destination flags.
2084 * @param pszThreadName The thread name to report in ring-0 when
2085 * RTLOGFLAGS_PREFIX_THREAD is set.
2086 */
2087RTDECL(int) RTLogCreateForR0(PRTLOGGER pLogger, size_t cbLogger,
2088 RTR0PTR pLoggerR0Ptr, RTR0PTR pfnLoggerR0Ptr, RTR0PTR pfnFlushR0Ptr,
2089 uint32_t fFlags, uint32_t fDestFlags, char const *pszThreadName);
2090
2091/**
2092 * Calculates the minimum size of a ring-0 logger instance.
2093 *
2094 * @returns The minimum size.
2095 * @param cGroups The number of groups.
2096 * @param fFlags Relevant flags.
2097 */
2098RTDECL(size_t) RTLogCalcSizeForR0(uint32_t cGroups, uint32_t fFlags);
2099
2100/**
2101 * Destroys a logger instance.
2102 *
2103 * The instance is flushed and all output destinations closed (where applicable).
2104 *
2105 * @returns iprt status code.
2106 * @param pLogger The logger instance which close destroyed. NULL is fine.
2107 */
2108RTDECL(int) RTLogDestroy(PRTLOGGER pLogger);
2109
2110/**
2111 * Create a logger instance clone for RC usage.
2112 *
2113 * @returns iprt status code.
2114 *
2115 * @param pLogger The logger instance to be cloned.
2116 * @param pLoggerRC Where to create the RC logger instance.
2117 * @param cbLoggerRC Amount of memory allocated to for the RC logger
2118 * instance clone.
2119 * @param pfnLoggerRCPtr Pointer to logger wrapper function for this
2120 * instance (RC Ptr).
2121 * @param pfnFlushRCPtr Pointer to flush function (RC Ptr).
2122 * @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
2123 */
2124RTDECL(int) RTLogCloneRC(PRTLOGGER pLogger, PRTLOGGERRC pLoggerRC, size_t cbLoggerRC,
2125 RTRCPTR pfnLoggerRCPtr, RTRCPTR pfnFlushRCPtr, uint32_t fFlags);
2126
2127/**
2128 * Flushes a RC logger instance to a R3 logger.
2129 *
2130 * @returns iprt status code.
2131 * @param pLogger The R3 logger instance to flush pLoggerRC to. If NULL
2132 * the default logger is used.
2133 * @param pLoggerRC The RC logger instance to flush.
2134 */
2135RTDECL(void) RTLogFlushRC(PRTLOGGER pLogger, PRTLOGGERRC pLoggerRC);
2136
2137/**
2138 * Flushes the buffer in one logger instance onto another logger.
2139 *
2140 * @returns iprt status code.
2141 *
2142 * @param pSrcLogger The logger instance to flush.
2143 * @param pDstLogger The logger instance to flush onto.
2144 * If NULL the default logger will be used.
2145 */
2146RTDECL(void) RTLogFlushToLogger(PRTLOGGER pSrcLogger, PRTLOGGER pDstLogger);
2147
2148/**
2149 * Flushes a R0 logger instance to a R3 logger.
2150 *
2151 * @returns iprt status code.
2152 * @param pLogger The R3 logger instance to flush pLoggerR0 to. If NULL
2153 * the default logger is used.
2154 * @param pLoggerR0 The R0 logger instance to flush.
2155 */
2156RTDECL(void) RTLogFlushR0(PRTLOGGER pLogger, PRTLOGGER pLoggerR0);
2157
2158/**
2159 * Sets the custom prefix callback.
2160 *
2161 * @returns IPRT status code.
2162 * @param pLogger The logger instance.
2163 * @param pfnCallback The callback.
2164 * @param pvUser The user argument for the callback.
2165 * */
2166RTDECL(int) RTLogSetCustomPrefixCallback(PRTLOGGER pLogger, PFNRTLOGPREFIX pfnCallback, void *pvUser);
2167
2168/**
2169 * Same as RTLogSetCustomPrefixCallback for loggers created by
2170 * RTLogCreateForR0.
2171 *
2172 * @returns IPRT status code.
2173 * @param pLogger The logger instance.
2174 * @param pLoggerR0Ptr The ring-0 address corresponding to @a pLogger.
2175 * @param pfnCallbackR0Ptr The callback.
2176 * @param pvUserR0Ptr The user argument for the callback.
2177 * */
2178RTDECL(int) RTLogSetCustomPrefixCallbackForR0(PRTLOGGER pLogger, RTR0PTR pLoggerR0Ptr,
2179 RTR0PTR pfnCallbackR0Ptr, RTR0PTR pvUserR0Ptr);
2180
2181/**
2182 * Copies the group settings and flags from logger instance to another.
2183 *
2184 * @returns IPRT status code.
2185 * @param pDstLogger The destination logger instance.
2186 * @param pDstLoggerR0Ptr The ring-0 address corresponding to @a pDstLogger.
2187 * @param pSrcLogger The source logger instance. If NULL the default one is used.
2188 * @param fFlagsOr OR mask for the flags.
2189 * @param fFlagsAnd AND mask for the flags.
2190 */
2191RTDECL(int) RTLogCopyGroupsAndFlagsForR0(PRTLOGGER pDstLogger, RTR0PTR pDstLoggerR0Ptr,
2192 PCRTLOGGER pSrcLogger, uint32_t fFlagsOr, uint32_t fFlagsAnd);
2193
2194/**
2195 * Get the current log group settings as a string.
2196 *
2197 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2198 * @param pLogger Logger instance (NULL for default logger).
2199 * @param pszBuf The output buffer.
2200 * @param cchBuf The size of the output buffer. Must be greater
2201 * than zero.
2202 */
2203RTDECL(int) RTLogGetGroupSettings(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2204
2205/**
2206 * Updates the group settings for the logger instance using the specified
2207 * specification string.
2208 *
2209 * @returns iprt status code.
2210 * Failures can safely be ignored.
2211 * @param pLogger Logger instance (NULL for default logger).
2212 * @param pszValue Value to parse.
2213 */
2214RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszValue);
2215#endif /* !IN_RC */
2216
2217/**
2218 * Updates the flags for the logger instance using the specified
2219 * specification string.
2220 *
2221 * @returns iprt status code.
2222 * Failures can safely be ignored.
2223 * @param pLogger Logger instance (NULL for default logger).
2224 * @param pszValue Value to parse.
2225 */
2226RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszValue);
2227
2228/**
2229 * Changes the buffering setting of the specified logger.
2230 *
2231 * This can be used for optimizing longish logging sequences.
2232 *
2233 * @returns The old state.
2234 * @param pLogger The logger instance (NULL is an alias for the
2235 * default logger).
2236 * @param fBuffered The new state.
2237 */
2238RTDECL(bool) RTLogSetBuffering(PRTLOGGER pLogger, bool fBuffered);
2239
2240/**
2241 * Sets the max number of entries per group.
2242 *
2243 * @returns Old restriction.
2244 *
2245 * @param pLogger The logger instance (NULL is an alias for the
2246 * default logger).
2247 * @param cMaxEntriesPerGroup The max number of entries per group.
2248 *
2249 * @remarks Lowering the limit of an active logger may quietly mute groups.
2250 * Raising it may reactive already muted groups.
2251 */
2252RTDECL(uint32_t) RTLogSetGroupLimit(PRTLOGGER pLogger, uint32_t cMaxEntriesPerGroup);
2253
2254#ifndef IN_RC
2255/**
2256 * Get the current log flags as a string.
2257 *
2258 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2259 * @param pLogger Logger instance (NULL for default logger).
2260 * @param pszBuf The output buffer.
2261 * @param cchBuf The size of the output buffer. Must be greater
2262 * than zero.
2263 */
2264RTDECL(int) RTLogGetFlags(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2265
2266/**
2267 * Updates the logger destination using the specified string.
2268 *
2269 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2270 * @param pLogger Logger instance (NULL for default logger).
2271 * @param pszValue The value to parse.
2272 */
2273RTDECL(int) RTLogDestinations(PRTLOGGER pLogger, char const *pszValue);
2274
2275/**
2276 * Clear the file delay flag if set, opening the destination and flushing.
2277 *
2278 * @returns IPRT status code.
2279 * @param pLogger Logger instance (NULL for default logger).
2280 * @param pszValue The value to parse.
2281 * @param pErrInfo Where to return extended error info. Optional.
2282 */
2283RTDECL(int) RTLogClearFileDelayFlag(PRTLOGGER pLogger, PRTERRINFO pErrInfo);
2284
2285/**
2286 * Get the current log destinations as a string.
2287 *
2288 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2289 * @param pLogger Logger instance (NULL for default logger).
2290 * @param pszBuf The output buffer.
2291 * @param cchBuf The size of the output buffer. Must be greater
2292 * than 0.
2293 */
2294RTDECL(int) RTLogGetDestinations(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2295#endif /* !IN_RC */
2296
2297/**
2298 * Flushes the specified logger.
2299 *
2300 * @param pLogger The logger instance to flush.
2301 * If NULL the default instance is used. The default instance
2302 * will not be initialized by this call.
2303 */
2304RTDECL(void) RTLogFlush(PRTLOGGER pLogger);
2305
2306/**
2307 * Write to a logger instance.
2308 *
2309 * @param pLogger Pointer to logger instance.
2310 * @param pvCallerRet Ignored.
2311 * @param pszFormat Format string.
2312 * @param ... Format arguments.
2313 */
2314RTDECL(void) RTLogLogger(PRTLOGGER pLogger, void *pvCallerRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
2315
2316/**
2317 * Write to a logger instance.
2318 *
2319 * @param pLogger Pointer to logger instance.
2320 * @param pszFormat Format string.
2321 * @param args Format arguments.
2322 */
2323RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2324
2325/**
2326 * Write to a logger instance.
2327 *
2328 * This function will check whether the instance, group and flags makes up a
2329 * logging kind which is currently enabled before writing anything to the log.
2330 *
2331 * @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
2332 * @param fFlags The logging flags.
2333 * @param iGroup The group.
2334 * The value ~0U is reserved for compatibility with RTLogLogger[V] and is
2335 * only for internal usage!
2336 * @param pszFormat Format string.
2337 * @param ... Format arguments.
2338 * @remark This is a worker function of LogIt.
2339 */
2340RTDECL(void) RTLogLoggerEx(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
2341 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
2342
2343/**
2344 * Write to a logger instance.
2345 *
2346 * This function will check whether the instance, group and flags makes up a
2347 * logging kind which is currently enabled before writing anything to the log.
2348 *
2349 * @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
2350 * @param fFlags The logging flags.
2351 * @param iGroup The group.
2352 * The value ~0U is reserved for compatibility with RTLogLogger[V] and is
2353 * only for internal usage!
2354 * @param pszFormat Format string.
2355 * @param args Format arguments.
2356 */
2357RTDECL(void) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
2358 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(4, 0);
2359
2360/**
2361 * printf like function for writing to the default log.
2362 *
2363 * @param pszFormat Printf like format string.
2364 * @param ... Optional arguments as specified in pszFormat.
2365 *
2366 * @remark The API doesn't support formatting of floating point numbers at the moment.
2367 */
2368RTDECL(void) RTLogPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2369
2370/**
2371 * vprintf like function for writing to the default log.
2372 *
2373 * @param pszFormat Printf like format string.
2374 * @param va Optional arguments as specified in pszFormat.
2375 *
2376 * @remark The API doesn't support formatting of floating point numbers at the moment.
2377 */
2378RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
2379
2380/**
2381 * Dumper vprintf-like function outputting to a logger.
2382 *
2383 * @param pvUser Pointer to the logger instance to use, NULL for
2384 * default instance.
2385 * @param pszFormat Format string.
2386 * @param va Format arguments.
2387 */
2388RTDECL(void) RTLogDumpPrintfV(void *pvUser, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
2389
2390
2391#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h */
2392#define DECLARED_FNRTSTROUTPUT
2393/**
2394 * Output callback.
2395 *
2396 * @returns number of bytes written.
2397 * @param pvArg User argument.
2398 * @param pachChars Pointer to an array of utf-8 characters.
2399 * @param cbChars Number of bytes in the character array pointed to by pachChars.
2400 */
2401typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
2402/** Pointer to callback function. */
2403typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
2404#endif
2405
2406/**
2407 * Partial vsprintf worker implementation.
2408 *
2409 * @returns number of bytes formatted.
2410 * @param pfnOutput Output worker.
2411 * Called in two ways. Normally with a string an it's length.
2412 * For termination, it's called with NULL for string, 0 for length.
2413 * @param pvArg Argument to output worker.
2414 * @param pszFormat Format string.
2415 * @param args Argument list.
2416 */
2417RTDECL(size_t) RTLogFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArg, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2418
2419/**
2420 * Write log buffer to COM port.
2421 *
2422 * @param pach Pointer to the buffer to write.
2423 * @param cb Number of bytes to write.
2424 */
2425RTDECL(void) RTLogWriteCom(const char *pach, size_t cb);
2426
2427/**
2428 * Prints a formatted string to the serial port used for logging.
2429 *
2430 * @returns Number of bytes written.
2431 * @param pszFormat Format string.
2432 * @param ... Optional arguments specified in the format string.
2433 */
2434RTDECL(size_t) RTLogComPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2435
2436/**
2437 * Prints a formatted string to the serial port used for logging.
2438 *
2439 * @returns Number of bytes written.
2440 * @param pszFormat Format string.
2441 * @param args Optional arguments specified in the format string.
2442 */
2443RTDECL(size_t) RTLogComPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
2444
2445
2446#if 0 /* not implemented yet */
2447
2448/** Indicates that the semaphores shall be used to notify the other
2449 * part about buffer changes. */
2450#define LOGHOOKBUFFER_FLAGS_SEMAPHORED 1
2451
2452/**
2453 * Log Hook Buffer.
2454 * Use to communicate between the logger and a log consumer.
2455 */
2456typedef struct RTLOGHOOKBUFFER
2457{
2458 /** Write pointer. */
2459 volatile void *pvWrite;
2460 /** Read pointer. */
2461 volatile void *pvRead;
2462 /** Buffer start. */
2463 void *pvStart;
2464 /** Buffer end (exclusive). */
2465 void *pvEnd;
2466 /** Signaling semaphore used by the writer to wait on a full buffer.
2467 * Only used when indicated in flags. */
2468 void *pvSemWriter;
2469 /** Signaling semaphore used by the read to wait on an empty buffer.
2470 * Only used when indicated in flags. */
2471 void *pvSemReader;
2472 /** Buffer flags. Current reserved and set to zero. */
2473 volatile unsigned fFlags;
2474} RTLOGHOOKBUFFER;
2475/** Pointer to a log hook buffer. */
2476typedef RTLOGHOOKBUFFER *PRTLOGHOOKBUFFER;
2477
2478
2479/**
2480 * Register a logging hook.
2481 *
2482 * This type of logging hooks are expecting different threads acting
2483 * producer and consumer. They share a circular buffer which have two
2484 * pointers one for each end. When the buffer is full there are two
2485 * alternatives (indicated by a buffer flag), either wait for the
2486 * consumer to get it's job done, or to write a generic message saying
2487 * buffer overflow.
2488 *
2489 * Since the waiting would need a signal semaphore, we'll skip that for now.
2490 *
2491 * @returns iprt status code.
2492 * @param pBuffer Pointer to a logger hook buffer.
2493 */
2494RTDECL(int) RTLogRegisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
2495
2496/**
2497 * Deregister a logging hook registered with RTLogRegisterHook().
2498 *
2499 * @returns iprt status code.
2500 * @param pBuffer Pointer to a logger hook buffer.
2501 */
2502RTDECL(int) RTLogDeregisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
2503
2504#endif /* not implemented yet */
2505
2506
2507
2508/**
2509 * Write log buffer to a debugger (RTLOGDEST_DEBUGGER).
2510 *
2511 * @param pach What to write.
2512 * @param cb How much to write.
2513 * @remark When linking statically, this function can be replaced by defining your own.
2514 */
2515RTDECL(void) RTLogWriteDebugger(const char *pach, size_t cb);
2516
2517/**
2518 * Write log buffer to a user defined output stream (RTLOGDEST_USER).
2519 *
2520 * @param pach What to write.
2521 * @param cb How much to write.
2522 * @remark When linking statically, this function can be replaced by defining your own.
2523 */
2524RTDECL(void) RTLogWriteUser(const char *pach, size_t cb);
2525
2526/**
2527 * Write log buffer to stdout (RTLOGDEST_STDOUT).
2528 *
2529 * @param pach What to write.
2530 * @param cb How much to write.
2531 * @remark When linking statically, this function can be replaced by defining your own.
2532 */
2533RTDECL(void) RTLogWriteStdOut(const char *pach, size_t cb);
2534
2535/**
2536 * Write log buffer to stdout (RTLOGDEST_STDERR).
2537 *
2538 * @param pach What to write.
2539 * @param cb How much to write.
2540 * @remark When linking statically, this function can be replaced by defining your own.
2541 */
2542RTDECL(void) RTLogWriteStdErr(const char *pach, size_t cb);
2543
2544#ifdef VBOX
2545
2546/**
2547 * Prints a formatted string to the backdoor port.
2548 *
2549 * @returns Number of bytes written.
2550 * @param pszFormat Format string.
2551 * @param ... Optional arguments specified in the format string.
2552 */
2553RTDECL(size_t) RTLogBackdoorPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2554
2555/**
2556 * Prints a formatted string to the backdoor port.
2557 *
2558 * @returns Number of bytes written.
2559 * @param pszFormat Format string.
2560 * @param args Optional arguments specified in the format string.
2561 */
2562RTDECL(size_t) RTLogBackdoorPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
2563
2564#endif /* VBOX */
2565
2566RT_C_DECLS_END
2567
2568/** @} */
2569
2570#endif
2571
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette