log.h@ 53411

Last change on this file since 53411 was 53173, checked in by vboxsync, 10 years ago
IPRT,SUPDrv: Added new 'ringbuf[=size]' log destination for cases where only the last bit of the log is interesting and we can save space and time by not writing the whole log to disk/wherever. Since it changes the internal logger structure, it'll require a major SUPDrv version bump.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 69.5 KB

Line
1	/** @file
2	* IPRT - Logging.
3	*/
4
5	/*
6	* Copyright (C) 2006-2012 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
33	RT_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	*/
51	typedef enum RTLOGGROUP
52	{
53	/** Default logging group. */
54	RTLOGGROUP_DEFAULT,
55	RTLOGGROUP_DBG,
56	RTLOGGROUP_DBG_DWARF,
57	RTLOGGROUP_DIR,
58	RTLOGGROUP_FILE,
59	RTLOGGROUP_FS,
60	RTLOGGROUP_LDR,
61	RTLOGGROUP_PATH,
62	RTLOGGROUP_PROCESS,
63	RTLOGGROUP_SYMLINK,
64	RTLOGGROUP_THREAD,
65	RTLOGGROUP_TIME,
66	RTLOGGROUP_TIMER,
67	RTLOGGROUP_ZIP = 31,
68	RTLOGGROUP_FIRST_USER = 32
69	} RTLOGGROUP;
70
71	/** @def RT_LOGGROUP_NAMES
72	* IPRT Logging group names.
73	*
74	* Must correspond 100% to RTLOGGROUP!
75	* Don't forget commas!
76	*
77	* @remark It should be pretty obvious, but just to have
78	* mentioned it, the values are sorted alphabetically (using the
79	* english alphabet) except for _DEFAULT which is always first.
80	*
81	* If anyone might be wondering what the alphabet looks like:
82	* 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
83	*/
84	#define RT_LOGGROUP_NAMES \
85	"DEFAULT", \
86	"RT_DBG", \
87	"RT_DBG_DWARF", \
88	"RT_DIR", \
89	"RT_FILE", \
90	"RT_FS", \
91	"RT_LDR", \
92	"RT_PATH", \
93	"RT_PROCESS", \
94	"RT_SYMLINK", \
95	"RT_THREAD", \
96	"RT_TIME", \
97	"RT_TIMER", \
98	"RT_13", \
99	"RT_14", \
100	"RT_15", \
101	"RT_16", \
102	"RT_17", \
103	"RT_18", \
104	"RT_19", \
105	"RT_20", \
106	"RT_21", \
107	"RT_22", \
108	"RT_23", \
109	"RT_24", \
110	"RT_25", \
111	"RT_26", \
112	"RT_27", \
113	"RT_28", \
114	"RT_29", \
115	"RT_30", \
116	"RT_ZIP" \
117
118
119	/** @def LOG_GROUP
120	* Active logging group.
121	*/
122	#ifndef LOG_GROUP
123	# define LOG_GROUP RTLOGGROUP_DEFAULT
124	#endif
125
126	/** @def LOG_INSTANCE
127	* Active logging instance.
128	*/
129	#ifndef LOG_INSTANCE
130	# define LOG_INSTANCE NULL
131	#endif
132
133	/** @def LOG_REL_INSTANCE
134	* Active release logging instance.
135	*/
136	#ifndef LOG_REL_INSTANCE
137	# define LOG_REL_INSTANCE NULL
138	#endif
139
140	/** @def LOG_FN_FMT
141	* You can use this to specify you desired way of printing __PRETTY_FUNCTION__
142	* if you dislike the default one.
143	*/
144	#ifndef LOG_FN_FMT
145	# define LOG_FN_FMT "%Rfn"
146	#endif
147
148	/** Logger structure. */
149	#ifdef IN_RC
150	typedef struct RTLOGGERRC RTLOGGER;
151	#else
152	typedef struct RTLOGGER RTLOGGER;
153	#endif
154	/** Pointer to logger structure. */
155	typedef RTLOGGER *PRTLOGGER;
156	/** Pointer to const logger structure. */
157	typedef const RTLOGGER *PCRTLOGGER;
158
159
160	/** Guest context logger structure. */
161	typedef struct RTLOGGERRC RTLOGGERRC;
162	/** Pointer to guest context logger structure. */
163	typedef RTLOGGERRC *PRTLOGGERRC;
164	/** Pointer to const guest context logger structure. */
165	typedef const RTLOGGERRC *PCRTLOGGERRC;
166
167
168	/**
169	* Logger phase.
170	*
171	* Used for signalling the log header/footer callback what to do.
172	*/
173	typedef enum RTLOGPHASE
174	{
175	/** Begin of the logging. */
176	RTLOGPHASE_BEGIN = 0,
177	/** End of the logging. */
178	RTLOGPHASE_END,
179	/** Before rotating the log file. */
180	RTLOGPHASE_PREROTATE,
181	/** After rotating the log file. */
182	RTLOGPHASE_POSTROTATE,
183	/** 32-bit type blow up hack. */
184	RTLOGPHASE_32BIT_HACK = 0x7fffffff
185	} RTLOGPHASE;
186
187
188	/**
189	* Logger function.
190	*
191	* @param pszFormat Format string.
192	* @param ... Optional arguments as specified in the format string.
193	*/
194	typedef DECLCALLBACK(void) FNRTLOGGER(const char *pszFormat, ...);
195	/** Pointer to logger function. */
196	typedef FNRTLOGGER *PFNRTLOGGER;
197
198	/**
199	* Flush function.
200	*
201	* @param pLogger Pointer to the logger instance which is to be flushed.
202	*/
203	typedef DECLCALLBACK(void) FNRTLOGFLUSH(PRTLOGGER pLogger);
204	/** Pointer to flush function. */
205	typedef FNRTLOGFLUSH *PFNRTLOGFLUSH;
206
207	/**
208	* Flush function.
209	*
210	* @param pLogger Pointer to the logger instance which is to be flushed.
211	*/
212	typedef DECLCALLBACK(void) FNRTLOGFLUSHGC(PRTLOGGERRC pLogger);
213	/** Pointer to logger function. */
214	typedef RCPTRTYPE(FNRTLOGFLUSHGC *) PFNRTLOGFLUSHGC;
215
216	/**
217	* Header/footer message callback.
218	*
219	* @param pLogger Pointer to the logger instance.
220	* @param pszFormat Format string.
221	* @param ... Optional arguments specified in the format string.
222	*/
223	typedef DECLCALLBACK(void) FNRTLOGPHASEMSG(PRTLOGGER pLogger, const char *pszFormat, ...);
224	/** Pointer to header/footer message callback function. */
225	typedef FNRTLOGPHASEMSG *PFNRTLOGPHASEMSG;
226
227	/**
228	* Log file header/footer callback.
229	*
230	* @param pLogger Pointer to the logger instance.
231	* @param enmLogPhase Indicates at what time the callback is invoked.
232	* @param pfnLogPhaseMsg Callback for writing the header/footer (RTLogPrintf
233	* and others are out of bounds).
234	*/
235	typedef DECLCALLBACK(void) FNRTLOGPHASE(PRTLOGGER pLogger, RTLOGPHASE enmLogPhase, PFNRTLOGPHASEMSG pfnLogPhaseMsg);
236	/** Pointer to log header/footer callback function. */
237	typedef FNRTLOGPHASE *PFNRTLOGPHASE;
238
239	/**
240	* Custom log prefix callback.
241	*
242	*
243	* @returns The number of chars written.
244	*
245	* @param pLogger Pointer to the logger instance.
246	* @param pchBuf Output buffer pointer.
247	* No need to terminate the output.
248	* @param cchBuf The size of the output buffer.
249	* @param pvUser The user argument.
250	*/
251	typedef DECLCALLBACK(size_t) FNRTLOGPREFIX(PRTLOGGER pLogger, char pchBuf, size_t cchBuf, void pvUser);
252	/** Pointer to prefix callback function. */
253	typedef FNRTLOGPREFIX *PFNRTLOGPREFIX;
254
255
256
257	/**
258	* Logger instance structure for raw-mode context (RC).
259	*/
260	struct RTLOGGERRC
261	{
262	/** Pointer to temporary scratch buffer.
263	* This is used to format the log messages. */
264	char achScratch[32768];
265	/** Current scratch buffer position. */
266	uint32_t offScratch;
267	/** This is set if a prefix is pending. */
268	bool fPendingPrefix;
269	bool afAlignment[3];
270	/** Pointer to the logger function.
271	* This is actually pointer to a wrapper which will push a pointer to the
272	* instance pointer onto the stack before jumping to the real logger function.
273	* A very unfortunate hack to work around the missing variadic macro support in C++. */
274	RCPTRTYPE(PFNRTLOGGER) pfnLogger;
275	/** Pointer to the flush function. */
276	PFNRTLOGFLUSHGC pfnFlush;
277	/** Magic number (RTLOGGERRC_MAGIC). */
278	uint32_t u32Magic;
279	/** Logger instance flags - RTLOGFLAGS. */
280	uint32_t fFlags;
281	/** Number of groups in the afGroups member. */
282	uint32_t cGroups;
283	/** Group flags array - RTLOGGRPFLAGS.
284	* This member have variable length and may extend way beyond
285	* the declared size of 1 entry. */
286	uint32_t afGroups[1];
287	};
288
289	/** RTLOGGERRC::u32Magic value. (John Rogers Searle) */
290	#define RTLOGGERRC_MAGIC 0x19320731
291
292
293
294	#ifndef IN_RC
295
296	/** Pointer to internal logger bits. */
297	typedef struct RTLOGGERINTERNAL *PRTLOGGERINTERNAL;
298
299	/**
300	* Logger instance structure.
301	*/
302	struct RTLOGGER
303	{
304	/** Pointer to temporary scratch buffer.
305	* This is used to format the log messages. */
306	char achScratch[49152];
307	/** Current scratch buffer position. */
308	uint32_t offScratch;
309	/** Magic number. */
310	uint32_t u32Magic;
311	/** Logger instance flags - RTLOGFLAGS. */
312	uint32_t fFlags;
313	/** Destination flags - RTLOGDEST. */
314	uint32_t fDestFlags;
315	/** Pointer to the internal bits of the logger.
316	* (The memory is allocated in the same block as RTLOGGER.) */
317	PRTLOGGERINTERNAL pInt;
318	/** Pointer to the logger function (used in non-C99 mode only).
319	*
320	* This is actually pointer to a wrapper which will push a pointer to the
321	* instance pointer onto the stack before jumping to the real logger function.
322	* A very unfortunate hack to work around the missing variadic macro
323	* support in older C++/C standards. (The memory is allocated using
324	* RTMemExecAlloc(), except for agnostic R0 code.) */
325	PFNRTLOGGER pfnLogger;
326	/** Number of groups in the afGroups and papszGroups members. */
327	uint32_t cGroups;
328	/** Group flags array - RTLOGGRPFLAGS.
329	* This member have variable length and may extend way beyond
330	* the declared size of 1 entry. */
331	uint32_t afGroups[1];
332	};
333
334	/** RTLOGGER::u32Magic value. (Avram Noam Chomsky) */
335	# define RTLOGGER_MAGIC UINT32_C(0x19281207)
336
337	#endif /* !IN_RC */
338
339
340	/**
341	* Logger flags.
342	*/
343	typedef enum RTLOGFLAGS
344	{
345	/** The logger instance is disabled for normal output. */
346	RTLOGFLAGS_DISABLED = 0x00000001,
347	/** The logger instance is using buffered output. */
348	RTLOGFLAGS_BUFFERED = 0x00000002,
349	/** The logger instance expands LF to CR/LF. */
350	RTLOGFLAGS_USECRLF = 0x00000010,
351	/** Append to the log destination where applicable. */
352	RTLOGFLAGS_APPEND = 0x00000020,
353	/** Show relative timestamps with PREFIX_TSC and PREFIX_TS */
354	RTLOGFLAGS_REL_TS = 0x00000040,
355	/** Show decimal timestamps with PREFIX_TSC and PREFIX_TS */
356	RTLOGFLAGS_DECIMAL_TS = 0x00000080,
357	/** Open the file in write through mode. */
358	RTLOGFLAGS_WRITE_THROUGH = 0x00000100,
359	/** Flush the file to disk when flushing the buffer. */
360	RTLOGFLAGS_FLUSH = 0x00000200,
361	/** Restrict the number of log entries per group. */
362	RTLOGFLAGS_RESTRICT_GROUPS = 0x00000400,
363	/** New lines should be prefixed with the write and read lock counts. */
364	RTLOGFLAGS_PREFIX_LOCK_COUNTS = 0x00008000,
365	/** New lines should be prefixed with the CPU id (ApicID on intel/amd). */
366	RTLOGFLAGS_PREFIX_CPUID = 0x00010000,
367	/** New lines should be prefixed with the native process id. */
368	RTLOGFLAGS_PREFIX_PID = 0x00020000,
369	/** New lines should be prefixed with group flag number causing the output. */
370	RTLOGFLAGS_PREFIX_FLAG_NO = 0x00040000,
371	/** New lines should be prefixed with group flag name causing the output. */
372	RTLOGFLAGS_PREFIX_FLAG = 0x00080000,
373	/** New lines should be prefixed with group number. */
374	RTLOGFLAGS_PREFIX_GROUP_NO = 0x00100000,
375	/** New lines should be prefixed with group name. */
376	RTLOGFLAGS_PREFIX_GROUP = 0x00200000,
377	/** New lines should be prefixed with the native thread id. */
378	RTLOGFLAGS_PREFIX_TID = 0x00400000,
379	/** New lines should be prefixed with thread name. */
380	RTLOGFLAGS_PREFIX_THREAD = 0x00800000,
381	/** New lines should be prefixed with data from a custom callback. */
382	RTLOGFLAGS_PREFIX_CUSTOM = 0x01000000,
383	/** New lines should be prefixed with formatted timestamp since program start. */
384	RTLOGFLAGS_PREFIX_TIME_PROG = 0x04000000,
385	/** New lines should be prefixed with formatted timestamp (UCT). */
386	RTLOGFLAGS_PREFIX_TIME = 0x08000000,
387	/** New lines should be prefixed with milliseconds since program start. */
388	RTLOGFLAGS_PREFIX_MS_PROG = 0x10000000,
389	/** New lines should be prefixed with timestamp. */
390	RTLOGFLAGS_PREFIX_TSC = 0x20000000,
391	/** New lines should be prefixed with timestamp. */
392	RTLOGFLAGS_PREFIX_TS = 0x40000000,
393	/** The prefix mask. */
394	RTLOGFLAGS_PREFIX_MASK = 0x7dff8000
395	} RTLOGFLAGS;
396
397	/**
398	* Logger per group flags.
399	*/
400	typedef enum RTLOGGRPFLAGS
401	{
402	/** Enabled. */
403	RTLOGGRPFLAGS_ENABLED = 0x00000001,
404	/** Level 1 logging. */
405	RTLOGGRPFLAGS_LEVEL_1 = 0x00000002,
406	/** Level 2 logging. */
407	RTLOGGRPFLAGS_LEVEL_2 = 0x00000004,
408	/** Level 3 logging. */
409	RTLOGGRPFLAGS_LEVEL_3 = 0x00000008,
410	/** Level 4 logging. */
411	RTLOGGRPFLAGS_LEVEL_4 = 0x00000010,
412	/** Level 5 logging. */
413	RTLOGGRPFLAGS_LEVEL_5 = 0x00000020,
414	/** Level 6 logging. */
415	RTLOGGRPFLAGS_LEVEL_6 = 0x00000040,
416	/** Flow logging. */
417	RTLOGGRPFLAGS_FLOW = 0x00000080,
418	/** Restrict the number of log entries. */
419	RTLOGGRPFLAGS_RESTRICT = 0x00000100,
420
421	/** Lelik logging. */
422	RTLOGGRPFLAGS_LELIK = 0x00010000,
423	/** Michael logging. */
424	RTLOGGRPFLAGS_MICHAEL = 0x00020000,
425	/** sunlover logging. */
426	RTLOGGRPFLAGS_SUNLOVER = 0x00040000,
427	/** Achim logging. */
428	RTLOGGRPFLAGS_ACHIM = 0x00080000,
429	/** Sander logging. */
430	RTLOGGRPFLAGS_SANDER = 0x00100000,
431	/** Klaus logging. */
432	RTLOGGRPFLAGS_KLAUS = 0x00200000,
433	/** Frank logging. */
434	RTLOGGRPFLAGS_FRANK = 0x00400000,
435	/** bird logging. */
436	RTLOGGRPFLAGS_BIRD = 0x00800000,
437	/** aleksey logging. */
438	RTLOGGRPFLAGS_ALEKSEY = 0x01000000,
439	/** dj logging. */
440	RTLOGGRPFLAGS_DJ = 0x02000000,
441	/** NoName logging. */
442	RTLOGGRPFLAGS_NONAME = 0x04000000
443	} RTLOGGRPFLAGS;
444
445	/**
446	* Logger destination type.
447	*/
448	typedef enum RTLOGDEST
449	{
450	/** Log to file. */
451	RTLOGDEST_FILE = 0x00000001,
452	/** Log to stdout. */
453	RTLOGDEST_STDOUT = 0x00000002,
454	/** Log to stderr. */
455	RTLOGDEST_STDERR = 0x00000004,
456	/** Log to debugger (win32 only). */
457	RTLOGDEST_DEBUGGER = 0x00000008,
458	/** Log to com port. */
459	RTLOGDEST_COM = 0x00000010,
460	/** Log a memory ring buffer. */
461	RTLOGDEST_RINGBUF = 0x00000020,
462	/** Just a dummy flag to be used when no other flag applies. */
463	RTLOGDEST_DUMMY = 0x20000000,
464	/** Log to a user defined output stream. */
465	RTLOGDEST_USER = 0x40000000
466	} RTLOGDEST;
467
468
469	RTDECL(void) RTLogPrintfEx(void pvInstance, unsigned fFlags, unsigned iGroup, const char pszFormat, ...);
470
471
472	#ifdef DOXYGEN_RUNNING
473	# define LOG_DISABLED
474	# define LOG_ENABLED
475	# define LOG_ENABLE_FLOW
476	#endif
477
478	/** @def LOG_DISABLED
479	* Use this compile time define to disable all logging macros. It can
480	* be overridden for each of the logging macros by the LOG_ENABLE*
481	* compile time defines.
482	*/
483
484	/** @def LOG_ENABLED
485	* Use this compile time define to enable logging when not in debug mode
486	* or LOG_DISABLED is set.
487	* This will enabled Log() only.
488	*/
489
490	/** @def LOG_ENABLE_FLOW
491	* Use this compile time define to enable flow logging when not in
492	* debug mode or LOG_DISABLED is defined.
493	* This will enable LogFlow() only.
494	*/
495
496	/*
497	* Determine whether logging is enabled and forcefully normalize the indicators.
498	*/
499	#if (defined(DEBUG) \|\| defined(LOG_ENABLED)) && !defined(LOG_DISABLED)
500	# undef LOG_DISABLED
501	# undef LOG_ENABLED
502	# define LOG_ENABLED
503	#else
504	# undef LOG_ENABLED
505	# undef LOG_DISABLED
506	# define LOG_DISABLED
507	#endif
508
509
510	/** @def LOG_USE_C99
511	* Governs the use of variadic macros.
512	*/
513	#ifndef LOG_USE_C99
514	# if defined(RT_ARCH_AMD64) \|\| defined(RT_OS_DARWIN) \|\| defined(RT_ARCH_SPARC) \|\| defined(RT_ARCH_SPARC64)
515	# define LOG_USE_C99
516	# endif
517	#endif
518
519
520	/** @def LogIt
521	* Write to specific logger if group enabled.
522	*/
523	#ifdef LOG_ENABLED
524	# if defined(LOG_USE_C99)
525	# define _LogRemoveParentheseis(...) __VA_ARGS__
526	# define _LogIt(a_pvInst, a_fFlags, a_iGroup, ...) RTLogLoggerEx((PRTLOGGER)a_pvInst, a_fFlags, a_iGroup, __VA_ARGS__)
527	# define LogIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) _LogIt(a_pvInst, a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
528	# define _LogItAlways(a_pvInst, a_fFlags, a_iGroup, ...) RTLogLoggerEx((PRTLOGGER)a_pvInst, a_fFlags, ~0U, __VA_ARGS__)
529	# define LogItAlways(a_pvInst, a_fFlags, a_iGroup, fmtargs) _LogItAlways(a_pvInst, a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
530	/** @todo invent a flag or something for skipping the group check so we can pass iGroup. LogItAlways. */
531	# else
532	# define LogIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) \
533	do \
534	{ \
535	register PRTLOGGER LogIt_pLogger = (PRTLOGGER)(a_pvInst) ? (PRTLOGGER)(a_pvInst) : RTLogDefaultInstance(); \
536	if ( LogIt_pLogger \
537	&& !(LogIt_pLogger->fFlags & RTLOGFLAGS_DISABLED)) \
538	{ \
539	register unsigned LogIt_fFlags = LogIt_pLogger->afGroups[(unsigned)(a_iGroup) < LogIt_pLogger->cGroups ? (unsigned)(a_iGroup) : 0]; \
540	if ((LogIt_fFlags & ((a_fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((a_fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
541	LogIt_pLogger->pfnLogger fmtargs; \
542	} \
543	} while (0)
544	# define LogItAlways(a_pvInst, a_fFlags, a_iGroup, fmtargs) \
545	do \
546	{ \
547	register PRTLOGGER LogIt_pLogger = (PRTLOGGER)(a_pvInst) ? (PRTLOGGER)(a_pvInst) : RTLogDefaultInstance(); \
548	if ( LogIt_pLogger \
549	&& !(LogIt_pLogger->fFlags & RTLOGFLAGS_DISABLED)) \
550	LogIt_pLogger->pfnLogger fmtargs; \
551	} while (0)
552	# endif
553	#else
554	# define LogIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) do { } while (0)
555	# define LogItAlways(a_pvInst, a_fFlags, a_iGroup, fmtargs) do { } while (0)
556	# if defined(LOG_USE_C99)
557	# define _LogRemoveParentheseis(...) __VA_ARGS__
558	# define _LogIt(a_pvInst, a_fFlags, a_iGroup, ...) do { } while (0)
559	# define _LogItAlways(a_pvInst, a_fFlags, a_iGroup, ...) do { } while (0)
560	# endif
561	#endif
562
563
564	/** @def Log
565	* Level 1 logging that works regardless of the group settings.
566	*/
567	#define LogAlways(a) LogItAlways(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
568
569	/** @def Log
570	* Level 1 logging.
571	*/
572	#define Log(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
573
574	/** @def Log2
575	* Level 2 logging.
576	*/
577	#define Log2(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
578
579	/** @def Log3
580	* Level 3 logging.
581	*/
582	#define Log3(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
583
584	/** @def Log4
585	* Level 4 logging.
586	*/
587	#define Log4(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
588
589	/** @def Log5
590	* Level 5 logging.
591	*/
592	#define Log5(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
593
594	/** @def Log6
595	* Level 6 logging.
596	*/
597	#define Log6(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
598
599	/** @def LogFlow
600	* Logging of execution flow.
601	*/
602	#define LogFlow(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
603
604	/** @def LogLelik
605	* lelik logging.
606	*/
607	#define LogLelik(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
608
609
610	/** @def LogMichael
611	* michael logging.
612	*/
613	#define LogMichael(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
614
615	/** @def LogSunlover
616	* sunlover logging.
617	*/
618	#define LogSunlover(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
619
620	/** @def LogAchim
621	* Achim logging.
622	*/
623	#define LogAchim(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
624
625	/** @def LogSander
626	* Sander logging.
627	*/
628	#define LogSander(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
629
630	/** @def LogKlaus
631	* klaus logging.
632	*/
633	#define LogKlaus(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
634
635	/** @def LogFrank
636	* frank logging.
637	*/
638	#define LogFrank(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
639
640	/** @def LogBird
641	* bird logging.
642	*/
643	#define LogBird(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
644
645	/** @def LogAleksey
646	* aleksey logging.
647	*/
648	#define LogAleksey(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_ALEKSEY, LOG_GROUP, a)
649
650	/** @def LogDJ
651	* dj logging.
652	*/
653	#define LogDJ(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_DJ, LOG_GROUP, a)
654
655	/** @def LogNoName
656	* NoName logging.
657	*/
658	#define LogNoName(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
659
660	/** @def LogWarning
661	* The same as Log(), but prepents a <tt>"WARNING! "</tt> string to the message.
662	*
663	* @param a Custom log message in format <tt>("string\n" [, args])</tt>.
664	*/
665	#if defined(LOG_USE_C99)
666	# define LogWarning(a) \
667	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "WARNING! %M", _LogRemoveParentheseis a )
668	#else
669	# define LogWarning(a) \
670	do { Log(("WARNING! ")); Log(a); } while (0)
671	#endif
672
673	/** @def LogTrace
674	* Macro to trace the execution flow: logs the file name, line number and
675	* function name. Can be easily searched for in log files using the
676	* ">>>>>" pattern (prepended to the beginning of each line).
677	*/
678	#define LogTrace() \
679	LogFlow((">>>>> %s (%d): " LOG_FN_FMT "\n", __FILE__, __LINE__, __PRETTY_FUNCTION__))
680
681	/** @def LogTraceMsg
682	* The same as LogTrace but logs a custom log message right after the trace line.
683	*
684	* @param a Custom log message in format <tt>("string\n" [, args])</tt>.
685	*/
686	#ifdef LOG_USE_C99
687	# define LogTraceMsg(a) \
688	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, ">>>>> %s (%d): " LOG_FN_FMT ": %M", __FILE__, __LINE__, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
689	#else
690	# define LogTraceMsg(a) \
691	do { LogFlow((">>>>> %s (%d): " LOG_FN_FMT ": ", __FILE__, __LINE__, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
692	#endif
693
694	/** @def LogFunc
695	* Level 1 logging inside C/C++ functions.
696	*
697	* Prepends the given log message with the function name followed by a
698	* semicolon and space.
699	*
700	* @param a Log message in format <tt>("string\n" [, args])</tt>.
701	*/
702	#ifdef LOG_USE_C99
703	# define LogFunc(a) \
704	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
705	#else
706	# define LogFunc(a) \
707	do { Log((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log(a); } while (0)
708	#endif
709
710	/** @def Log2Func
711	* Level 2 logging inside C/C++ functions.
712	*
713	* Prepends the given log message with the function name followed by a
714	* semicolon and space.
715	*
716	* @param a Log message in format <tt>("string\n" [, args])</tt>.
717	*/
718	#ifdef LOG_USE_C99
719	# define Log2Func(a) \
720	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
721	#else
722	# define Log2Func(a) \
723	do { Log2((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log2(a); } while (0)
724	#endif
725
726	/** @def Log3Func
727	* Level 3 logging inside C/C++ functions.
728	*
729	* Prepends the given log message with the function name followed by a
730	* semicolon and space.
731	*
732	* @param a Log message in format <tt>("string\n" [, args])</tt>.
733	*/
734	#ifdef LOG_USE_C99
735	# define Log3Func(a) \
736	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
737	#else
738	# define Log3Func(a) \
739	do { Log3((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log3(a); } while (0)
740	#endif
741
742	/** @def Log4Func
743	* Level 4 logging inside C/C++ functions.
744	*
745	* Prepends the given log message with the function name followed by a
746	* semicolon and space.
747	*
748	* @param a Log message in format <tt>("string\n" [, args])</tt>.
749	*/
750	#ifdef LOG_USE_C99
751	# define Log4Func(a) \
752	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
753	#else
754	# define Log4Func(a) \
755	do { Log4((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log4(a); } while (0)
756	#endif
757
758	/** @def Log5Func
759	* Level 5 logging inside C/C++ functions.
760	*
761	* Prepends the given log message with the function name followed by a
762	* semicolon and space.
763	*
764	* @param a Log message in format <tt>("string\n" [, args])</tt>.
765	*/
766	#ifdef LOG_USE_C99
767	# define Log5Func(a) \
768	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
769	#else
770	# define Log5Func(a) \
771	do { Log5((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log5(a); } while (0)
772	#endif
773
774	/** @def Log6Func
775	* Level 6 logging inside C/C++ functions.
776	*
777	* Prepends the given log message with the function name followed by a
778	* semicolon and space.
779	*
780	* @param a Log message in format <tt>("string\n" [, args])</tt>.
781	*/
782	#ifdef LOG_USE_C99
783	# define Log6Func(a) \
784	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
785	#else
786	# define Log6Func(a) \
787	do { Log6((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); Log6(a); } while (0)
788	#endif
789
790	/** @def LogThisFunc
791	* The same as LogFunc but for class functions (methods): the resulting log
792	* line is additionally prepended with a hex value of \|this\| pointer.
793	*
794	* @param a Log message in format <tt>("string\n" [, args])</tt>.
795	*/
796	#ifdef LOG_USE_C99
797	# define LogThisFunc(a) \
798	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
799	#else
800	# define LogThisFunc(a) \
801	do { Log(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
802	#endif
803
804	/** @def LogFlowFunc
805	* Macro to log the execution flow inside C/C++ functions.
806	*
807	* Prepends the given log message with the function name followed by
808	* a semicolon and space.
809	*
810	* @param a Log message in format <tt>("string\n" [, args])</tt>.
811	*/
812	#ifdef LOG_USE_C99
813	# define LogFlowFunc(a) \
814	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
815	#else
816	# define LogFlowFunc(a) \
817	do { LogFlow((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
818	#endif
819
820	/** @def LogWarningFunc
821	* The same as LogWarning(), but prepents the log message with the function name.
822	*
823	* @param a Log message in format <tt>("string\n" [, args])</tt>.
824	*/
825	#ifdef LOG_USE_C99
826	# define LogWarningFunc(a) \
827	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": WARNING! %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
828	#else
829	# define LogWarningFunc(a) \
830	do { Log((LOG_FN_FMT ": WARNING! ", __PRETTY_FUNCTION__)); Log(a); } while (0)
831	#endif
832
833	/** @def LogFlowThisFunc
834	* The same as LogFlowFunc but for class functions (methods): the resulting log
835	* line is additionally prepended with a hex value of \|this\| pointer.
836	*
837	* @param a Log message in format <tt>("string\n" [, args])</tt>.
838	*/
839	#ifdef LOG_USE_C99
840	# define LogFlowThisFunc(a) \
841	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
842	#else
843	# define LogFlowThisFunc(a) \
844	do { LogFlow(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
845	#endif
846
847	/** @def LogWarningThisFunc
848	* The same as LogWarningFunc() but for class functions (methods): the resulting
849	* log line is additionally prepended with a hex value of \|this\| pointer.
850	*
851	* @param a Log message in format <tt>("string\n" [, args])</tt>.
852	*/
853	#ifdef LOG_USE_C99
854	# define LogWarningThisFunc(a) \
855	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": WARNING! %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
856	#else
857	# define LogWarningThisFunc(a) \
858	do { Log(("{%p} " LOG_FN_FMT ": WARNING! ", this, __PRETTY_FUNCTION__)); Log(a); } while (0)
859	#endif
860
861	/** Shortcut to \|LogFlowFunc ("ENTER\n")\|, marks the beginnig of the function. */
862	#define LogFlowFuncEnter() LogFlowFunc(("ENTER\n"))
863
864	/** Shortcut to \|LogFlowFunc ("LEAVE\n")\|, marks the end of the function. */
865	#define LogFlowFuncLeave() LogFlowFunc(("LEAVE\n"))
866
867	/** Shortcut to \|LogFlowFunc ("LEAVE: %Rrc\n")\|, marks the end of the function. */
868	#define LogFlowFuncLeaveRC(rc) LogFlowFunc(("LEAVE: %Rrc\n", (rc)))
869
870	/** Shortcut to \|LogFlowThisFunc ("ENTER\n")\|, marks the beginnig of the function. */
871	#define LogFlowThisFuncEnter() LogFlowThisFunc(("ENTER\n"))
872
873	/** Shortcut to \|LogFlowThisFunc ("LEAVE\n")\|, marks the end of the function. */
874	#define LogFlowThisFuncLeave() LogFlowThisFunc(("LEAVE\n"))
875
876	/** @def LogObjRefCnt
877	* Helper macro to print the current reference count of the given COM object
878	* to the log file.
879	*
880	* @param pObj Pointer to the object in question (must be a pointer to an
881	* IUnknown subclass or simply define COM-style AddRef() and
882	* Release() methods)
883	*
884	* @note Use it only for temporary debugging. It leaves dummy code even if
885	* logging is disabled.
886	*/
887	#define LogObjRefCnt(pObj) \
888	do { \
889	int refc = (pObj)->AddRef(); \
890	LogFlow((#pObj "{%p}.refCnt=%d\n", (pObj), refc - 1)); \
891	(pObj)->Release(); \
892	} while (0)
893
894
895	/** @def LogIsItEnabled
896	* Checks whether the specified logging group is enabled or not.
897	*/
898	#ifdef LOG_ENABLED
899	# define LogIsItEnabled(a_pvInst, a_fFlags, a_iGroup) \
900	LogIsItEnabledInternal((a_pvInst), (unsigned)(a_iGroup), (unsigned)(a_fFlags))
901	#else
902	# define LogIsItEnabled(a_pvInst, a_fFlags, a_iGroup) (false)
903	#endif
904
905	/** @def LogIsEnabled
906	* Checks whether level 1 logging is enabled.
907	*/
908	#define LogIsEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
909
910	/** @def LogIs2Enabled
911	* Checks whether level 2 logging is enabled.
912	*/
913	#define LogIs2Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
914
915	/** @def LogIs3Enabled
916	* Checks whether level 3 logging is enabled.
917	*/
918	#define LogIs3Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
919
920	/** @def LogIs4Enabled
921	* Checks whether level 4 logging is enabled.
922	*/
923	#define LogIs4Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
924
925	/** @def LogIs5Enabled
926	* Checks whether level 5 logging is enabled.
927	*/
928	#define LogIs5Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
929
930	/** @def LogIs6Enabled
931	* Checks whether level 6 logging is enabled.
932	*/
933	#define LogIs6Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
934
935	/** @def LogIsFlowEnabled
936	* Checks whether execution flow logging is enabled.
937	*/
938	#define LogIsFlowEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
939
940
941	/** @name Passing Function Call Position When Logging.
942	*
943	* This is a little bit ugly as we have to omit the comma before the
944	* position parameters so that we don't inccur any overhead in non-logging
945	* builds (!defined(LOG_ENABLED).
946	*
947	* @{ */
948	/** Source position for passing to a function call. */
949	#ifdef LOG_ENABLED
950	# define RTLOG_COMMA_SRC_POS , __FILE__, __LINE__, __PRETTY_FUNCTION__
951	#else
952	# define RTLOG_COMMA_SRC_POS RT_NOTHING
953	#endif
954	/** Source position declaration. */
955	#ifdef LOG_ENABLED
956	# define RTLOG_COMMA_SRC_POS_DECL , const char pszFile, unsigned iLine, const char pszFunction
957	#else
958	# define RTLOG_COMMA_SRC_POS_DECL RT_NOTHING
959	#endif
960	/** Source position arguments. */
961	#ifdef LOG_ENABLED
962	# define RTLOG_COMMA_SRC_POS_ARGS , pszFile, iLine, pszFunction
963	#else
964	# define RTLOG_COMMA_SRC_POS_ARGS RT_NOTHING
965	#endif
966	/** Applies NOREF() to the source position arguments. */
967	#ifdef LOG_ENABLED
968	# define RTLOG_SRC_POS_NOREF() do { NOREF(pszFile); NOREF(iLine); NOREF(pszFunction); } while (0)
969	#else
970	# define RTLOG_SRC_POS_NOREF() do { } while (0)
971	#endif
972	/** @} */
973
974
975
976	/** @name Release Logging
977	* @{
978	*/
979
980	#ifdef DOXYGEN_RUNNING
981	# define RTLOG_REL_DISABLED
982	# define RTLOG_REL_ENABLED
983	#endif
984
985	/** @def RTLOG_REL_DISABLED
986	* Use this compile time define to disable all release logging
987	* macros.
988	*/
989
990	/** @def RTLOG_REL_ENABLED
991	* Use this compile time define to override RTLOG_REL_DISABLE.
992	*/
993
994	/*
995	* Determine whether release logging is enabled and forcefully normalize the indicators.
996	*/
997	#if !defined(RTLOG_REL_DISABLED) \|\| defined(RTLOG_REL_ENABLED)
998	# undef RTLOG_REL_DISABLED
999	# undef RTLOG_REL_ENABLED
1000	# define RTLOG_REL_ENABLED
1001	#else
1002	# undef RTLOG_REL_ENABLED
1003	# undef RTLOG_REL_DISABLED
1004	# define RTLOG_REL_DISABLED
1005	#endif
1006
1007
1008	/** @def LogIt
1009	* Write to specific logger if group enabled.
1010	*/
1011	#ifdef RTLOG_REL_ENABLED
1012	# if defined(LOG_USE_C99)
1013	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1014	# define _LogRelIt(a_pvInst, a_fFlags, a_iGroup, ...) \
1015	do \
1016	{ \
1017	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(a_pvInst) ? (PRTLOGGER)(a_pvInst) : RTLogRelDefaultInstance(); \
1018	if ( LogRelIt_pLogger \
1019	&& !(LogRelIt_pLogger->fFlags & RTLOGFLAGS_DISABLED)) \
1020	RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1021	_LogIt(LOG_INSTANCE, a_fFlags, a_iGroup, __VA_ARGS__); \
1022	} while (0)
1023	# define LogRelIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) _LogRelIt(a_pvInst, a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1024	# else
1025	# define LogRelIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) \
1026	do \
1027	{ \
1028	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(a_pvInst) ? (PRTLOGGER)(a_pvInst) : RTLogRelDefaultInstance(); \
1029	if ( LogRelIt_pLogger \
1030	&& !(LogRelIt_pLogger->fFlags & RTLOGFLAGS_DISABLED)) \
1031	{ \
1032	unsigned LogIt_fFlags = LogRelIt_pLogger->afGroups[(unsigned)(a_iGroup) < LogRelIt_pLogger->cGroups ? (unsigned)(a_iGroup) : 0]; \
1033	if ((LogIt_fFlags & ((a_fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((a_fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
1034	LogRelIt_pLogger->pfnLogger fmtargs; \
1035	} \
1036	LogIt(LOG_INSTANCE, a_fFlags, a_iGroup, fmtargs); \
1037	} while (0)
1038	# endif
1039	#else /* !RTLOG_REL_ENABLED */
1040	# define LogRelIt(a_pvInst, a_fFlags, a_iGroup, fmtargs) do { } while (0)
1041	# if defined(LOG_USE_C99)
1042	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1043	# define _LogRelIt(a_pvInst, a_fFlags, a_iGroup, ...) do { } while (0)
1044	# endif
1045	#endif /* !RTLOG_REL_ENABLED */
1046
1047
1048	/** @def LogRel
1049	* Level 1 logging.
1050	*/
1051	#define LogRel(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
1052
1053	/** @def LogRel2
1054	* Level 2 logging.
1055	*/
1056	#define LogRel2(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
1057
1058	/** @def LogRel3
1059	* Level 3 logging.
1060	*/
1061	#define LogRel3(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
1062
1063	/** @def LogRel4
1064	* Level 4 logging.
1065	*/
1066	#define LogRel4(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
1067
1068	/** @def LogRel5
1069	* Level 5 logging.
1070	*/
1071	#define LogRel5(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
1072
1073	/** @def LogRel6
1074	* Level 6 logging.
1075	*/
1076	#define LogRel6(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
1077
1078	/** @def LogRelFlow
1079	* Logging of execution flow.
1080	*/
1081	#define LogRelFlow(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
1082
1083	/** @def LogRelFunc
1084	* Release logging. Prepends the given log message with the function name
1085	* followed by a semicolon and space.
1086	*/
1087	#ifdef LOG_USE_C99
1088	# define LogRelFunc(a) \
1089	_LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1090	# define LogFunc(a) \
1091	_LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1092	#else
1093	# define LogRelFunc(a) \
1094	do { LogRel((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1095	#endif
1096
1097	/** @def LogRelThisFunc
1098	* The same as LogRelFunc but for class functions (methods): the resulting log
1099	* line is additionally prepended with a hex value of \|this\| pointer.
1100	*/
1101	#ifdef LOG_USE_C99
1102	# define LogRelThisFunc(a) \
1103	_LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1104	#else
1105	# define LogRelThisFunc(a) \
1106	do { LogRel(("{%p} " LOG_FN_FMT ": ", this, __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1107	#endif
1108
1109	/** @def LogRelFlowFunc
1110	* Release logging. Macro to log the execution flow inside C/C++ functions.
1111	*
1112	* Prepends the given log message with the function name followed by
1113	* a semicolon and space.
1114	*
1115	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1116	*/
1117	#ifdef LOG_USE_C99
1118	# define LogRelFlowFunc(a) \
1119	_LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1120	#else
1121	# define LogRelFlowFunc(a) \
1122	do { LogRelFlow((LOG_FN_FMT ": ", __PRETTY_FUNCTION__)); LogRelFlow(a); } while (0)
1123	#endif
1124
1125	/** @def LogRelLelik
1126	* lelik logging.
1127	*/
1128	#define LogRelLelik(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
1129
1130	/** @def LogRelMichael
1131	* michael logging.
1132	*/
1133	#define LogRelMichael(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
1134
1135	/** @def LogRelSunlover
1136	* sunlover logging.
1137	*/
1138	#define LogRelSunlover(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
1139
1140	/** @def LogRelAchim
1141	* Achim logging.
1142	*/
1143	#define LogRelAchim(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
1144
1145	/** @def LogRelSander
1146	* Sander logging.
1147	*/
1148	#define LogRelSander(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
1149
1150	/** @def LogRelKlaus
1151	* klaus logging.
1152	*/
1153	#define LogRelKlaus(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
1154
1155	/** @def LogRelFrank
1156	* frank logging.
1157	*/
1158	#define LogRelFrank(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
1159
1160	/** @def LogRelBird
1161	* bird logging.
1162	*/
1163	#define LogRelBird(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
1164
1165	/** @def LogRelNoName
1166	* NoName logging.
1167	*/
1168	#define LogRelNoName(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
1169
1170
1171	/** @def LogRelIsItEnabled
1172	* Checks whether the specified logging group is enabled or not.
1173	*/
1174	#define LogRelIsItEnabled(a_pvInst, a_fFlags, a_iGroup) \
1175	LogRelIsItEnabledInternal((a_pvInst), (unsigned)(a_iGroup), (unsigned)(a_fFlags))
1176
1177	/** @def LogRelIsEnabled
1178	* Checks whether level 1 logging is enabled.
1179	*/
1180	#define LogRelIsEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
1181
1182	/** @def LogRelIs2Enabled
1183	* Checks whether level 2 logging is enabled.
1184	*/
1185	#define LogRelIs2Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
1186
1187	/** @def LogRelIs3Enabled
1188	* Checks whether level 3 logging is enabled.
1189	*/
1190	#define LogRelIs3Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
1191
1192	/** @def LogRelIs4Enabled
1193	* Checks whether level 4 logging is enabled.
1194	*/
1195	#define LogRelIs4Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
1196
1197	/** @def LogRelIs5Enabled
1198	* Checks whether level 5 logging is enabled.
1199	*/
1200	#define LogRelIs5Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
1201
1202	/** @def LogRelIs6Enabled
1203	* Checks whether level 6 logging is enabled.
1204	*/
1205	#define LogRelIs6Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
1206
1207	/** @def LogRelIsFlowEnabled
1208	* Checks whether execution flow logging is enabled.
1209	*/
1210	#define LogRelIsFlowEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
1211
1212
1213	#ifndef IN_RC
1214	/**
1215	* Sets the default release logger instance.
1216	*
1217	* @returns The old default instance.
1218	* @param pLogger The new default release logger instance.
1219	*/
1220	RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger);
1221	#endif /* !IN_RC */
1222
1223	/**
1224	* Gets the default release logger instance.
1225	*
1226	* @returns Pointer to default release logger instance.
1227	* @returns NULL if no default release logger instance available.
1228	*/
1229	RTDECL(PRTLOGGER) RTLogRelDefaultInstance(void);
1230
1231	/** Internal worker function.
1232	* Don't call directly, use the LogRelIsItEnabled macro!
1233	*/
1234	DECLINLINE(bool) LogRelIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
1235	{
1236	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogRelDefaultInstance();
1237	if ( pLogger
1238	&& !(pLogger->fFlags & RTLOGFLAGS_DISABLED))
1239	{
1240	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
1241	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
1242	return true;
1243	}
1244	return false;
1245	}
1246
1247	/**
1248	* Write to a logger instance, defaulting to the release one.
1249	*
1250	* This function will check whether the instance, group and flags makes up a
1251	* logging kind which is currently enabled before writing anything to the log.
1252	*
1253	* @param pLogger Pointer to logger instance.
1254	* @param fFlags The logging flags.
1255	* @param iGroup The group.
1256	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1257	* only for internal usage!
1258	* @param pszFormat Format string.
1259	* @param ... Format arguments.
1260	* @remark This is a worker function for LogRelIt.
1261	*/
1262	RTDECL(void) RTLogRelLogger(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
1263
1264	/**
1265	* Write to a logger instance, defaulting to the release one.
1266	*
1267	* This function will check whether the instance, group and flags makes up a
1268	* logging kind which is currently enabled before writing anything to the log.
1269	*
1270	* @param pLogger Pointer to logger instance. If NULL the default release instance is attempted.
1271	* @param fFlags The logging flags.
1272	* @param iGroup The group.
1273	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1274	* only for internal usage!
1275	* @param pszFormat Format string.
1276	* @param args Format arguments.
1277	*/
1278	RTDECL(void) RTLogRelLoggerV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
1279
1280	/**
1281	* printf like function for writing to the default release log.
1282	*
1283	* @param pszFormat Printf like format string.
1284	* @param ... Optional arguments as specified in pszFormat.
1285	*
1286	* @remark The API doesn't support formatting of floating point numbers at the moment.
1287	*/
1288	RTDECL(void) RTLogRelPrintf(const char *pszFormat, ...);
1289
1290	/**
1291	* vprintf like function for writing to the default release log.
1292	*
1293	* @param pszFormat Printf like format string.
1294	* @param args Optional arguments as specified in pszFormat.
1295	*
1296	* @remark The API doesn't support formatting of floating point numbers at the moment.
1297	*/
1298	RTDECL(void) RTLogRelPrintfV(const char *pszFormat, va_list args);
1299
1300	/**
1301	* Changes the buffering setting of the default release logger.
1302	*
1303	* This can be used for optimizing longish logging sequences.
1304	*
1305	* @returns The old state.
1306	* @param fBuffered The new state.
1307	*/
1308	RTDECL(bool) RTLogRelSetBuffering(bool fBuffered);
1309
1310	/** @} */
1311
1312
1313
1314	/** @name COM port logging
1315	* {
1316	*/
1317
1318	#ifdef DOXYGEN_RUNNING
1319	# define LOG_TO_COM
1320	# define LOG_NO_COM
1321	#endif
1322
1323	/** @def LOG_TO_COM
1324	* Redirects the normal logging macros to the serial versions.
1325	*/
1326
1327	/** @def LOG_NO_COM
1328	* Disables all LogCom* macros.
1329	*/
1330
1331	/** @def LogCom
1332	* Generic logging to serial port.
1333	*/
1334	#if defined(LOG_ENABLED) && !defined(LOG_NO_COM)
1335	# define LogCom(a) RTLogComPrintf a
1336	#else
1337	# define LogCom(a) do { } while (0)
1338	#endif
1339
1340	/** @def LogComFlow
1341	* Logging to serial port of execution flow.
1342	*/
1343	#if defined(LOG_ENABLED) && defined(LOG_ENABLE_FLOW) && !defined(LOG_NO_COM)
1344	# define LogComFlow(a) RTLogComPrintf a
1345	#else
1346	# define LogComFlow(a) do { } while (0)
1347	#endif
1348
1349	#ifdef LOG_TO_COM
1350	# undef Log
1351	# define Log(a) LogCom(a)
1352	# undef LogFlow
1353	# define LogFlow(a) LogComFlow(a)
1354	#endif
1355
1356	/** @} */
1357
1358
1359	/** @name Backdoor Logging
1360	* @{
1361	*/
1362
1363	#ifdef DOXYGEN_RUNNING
1364	# define LOG_TO_BACKDOOR
1365	# define LOG_NO_BACKDOOR
1366	#endif
1367
1368	/** @def LOG_TO_BACKDOOR
1369	* Redirects the normal logging macros to the backdoor versions.
1370	*/
1371
1372	/** @def LOG_NO_BACKDOOR
1373	* Disables all LogBackdoor* macros.
1374	*/
1375
1376	/** @def LogBackdoor
1377	* Generic logging to the VBox backdoor via port I/O.
1378	*/
1379	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1380	# define LogBackdoor(a) RTLogBackdoorPrintf a
1381	#else
1382	# define LogBackdoor(a) do { } while (0)
1383	#endif
1384
1385	/** @def LogBackdoorFlow
1386	* Logging of execution flow messages to the backdoor I/O port.
1387	*/
1388	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1389	# define LogBackdoorFlow(a) RTLogBackdoorPrintf a
1390	#else
1391	# define LogBackdoorFlow(a) do { } while (0)
1392	#endif
1393
1394	/** @def LogRelBackdoor
1395	* Release logging to the VBox backdoor via port I/O.
1396	*/
1397	#if !defined(LOG_NO_BACKDOOR)
1398	# define LogRelBackdoor(a) RTLogBackdoorPrintf a
1399	#else
1400	# define LogRelBackdoor(a) do { } while (0)
1401	#endif
1402
1403	#ifdef LOG_TO_BACKDOOR
1404	# undef Log
1405	# define Log(a) LogBackdoor(a)
1406	# undef LogFlow
1407	# define LogFlow(a) LogBackdoorFlow(a)
1408	# undef LogRel
1409	# define LogRel(a) LogRelBackdoor(a)
1410	# if defined(LOG_USE_C99)
1411	# undef _LogIt
1412	# define _LogIt(a_pvInst, a_fFlags, a_iGroup, ...) LogBackdoor((__VA_ARGS__))
1413	# endif
1414	#endif
1415
1416	/** @} */
1417
1418
1419
1420	/**
1421	* Gets the default logger instance, creating it if necessary.
1422	*
1423	* @returns Pointer to default logger instance.
1424	* @returns NULL if no default logger instance available.
1425	*/
1426	RTDECL(PRTLOGGER) RTLogDefaultInstance(void);
1427
1428	/**
1429	* Gets the default logger instance.
1430	*
1431	* @returns Pointer to default logger instance.
1432	* @returns NULL if no default logger instance available.
1433	*/
1434	RTDECL(PRTLOGGER) RTLogGetDefaultInstance(void);
1435
1436	#ifndef IN_RC
1437	/**
1438	* Sets the default logger instance.
1439	*
1440	* @returns The old default instance.
1441	* @param pLogger The new default logger instance.
1442	*/
1443	RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger);
1444	#endif /* !IN_RC */
1445
1446	#ifdef IN_RING0
1447	/**
1448	* Changes the default logger instance for the current thread.
1449	*
1450	* @returns IPRT status code.
1451	* @param pLogger The logger instance. Pass NULL for deregistration.
1452	* @param uKey Associated key for cleanup purposes. If pLogger is NULL,
1453	* all instances with this key will be deregistered. So in
1454	* order to only deregister the instance associated with the
1455	* current thread use 0.
1456	*/
1457	RTDECL(int) RTLogSetDefaultInstanceThread(PRTLOGGER pLogger, uintptr_t uKey);
1458	#endif /* IN_RING0 */
1459
1460
1461	#ifdef LOG_ENABLED
1462	/** Internal worker function.
1463	* Don't call directly, use the LogIsItEnabled macro!
1464	*/
1465	DECLINLINE(bool) LogIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
1466	{
1467	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogDefaultInstance();
1468	if ( pLogger
1469	&& !(pLogger->fFlags & RTLOGFLAGS_DISABLED))
1470	{
1471	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
1472	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
1473	return true;
1474	}
1475	return false;
1476	}
1477	#endif
1478
1479
1480	#ifndef IN_RC
1481	/**
1482	* Creates the default logger instance for a iprt users.
1483	*
1484	* Any user of the logging features will need to implement
1485	* this or use the generic dummy.
1486	*
1487	* @returns Pointer to the logger instance.
1488	*/
1489	RTDECL(PRTLOGGER) RTLogDefaultInit(void);
1490
1491	/**
1492	* Create a logger instance.
1493	*
1494	* @returns iprt status code.
1495	*
1496	* @param ppLogger Where to store the logger instance.
1497	* @param fFlags Logger instance flags, a combination of the
1498	* RTLOGFLAGS_* values.
1499	* @param pszGroupSettings The initial group settings.
1500	* @param pszEnvVarBase Base name for the environment variables for
1501	* this instance.
1502	* @param cGroups Number of groups in the array.
1503	* @param papszGroups Pointer to array of groups. This must stick
1504	* around for the life of the logger instance.
1505	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
1506	* if pszFilenameFmt specified.
1507	* @param pszFilenameFmt Log filename format string. Standard
1508	* RTStrFormat().
1509	* @param ... Format arguments.
1510	*/
1511	RTDECL(int) RTLogCreate(PRTLOGGER ppLogger, uint32_t fFlags, const char pszGroupSettings,
1512	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1513	uint32_t fDestFlags, const char *pszFilenameFmt, ...);
1514
1515	/**
1516	* Create a logger instance.
1517	*
1518	* @returns iprt status code.
1519	*
1520	* @param ppLogger Where to store the logger instance.
1521	* @param fFlags Logger instance flags, a combination of the
1522	* RTLOGFLAGS_* values.
1523	* @param pszGroupSettings The initial group settings.
1524	* @param pszEnvVarBase Base name for the environment variables for
1525	* this instance.
1526	* @param cGroups Number of groups in the array.
1527	* @param papszGroups Pointer to array of groups. This must stick
1528	* around for the life of the logger instance.
1529	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
1530	* if pszFilenameFmt specified.
1531	* @param pfnPhase Callback function for starting logging and for
1532	* ending or starting a new file for log history
1533	* rotation. NULL is OK.
1534	* @param cHistory Number of old log files to keep when performing
1535	* log history rotation. 0 means no history.
1536	* @param cbHistoryFileMax Maximum size of log file when performing
1537	* history rotation. 0 means no size limit.
1538	* @param cSecsHistoryTimeSlot Maximum time interval per log file when
1539	* performing history rotation, in seconds.
1540	* 0 means time limit.
1541	* @param pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
1542	* @param cchErrorMsg The size of the error message buffer.
1543	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1544	* @param ... Format arguments.
1545	*/
1546	RTDECL(int) RTLogCreateEx(PRTLOGGER ppLogger, uint32_t fFlags, const char pszGroupSettings,
1547	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1548	uint32_t fDestFlags, PFNRTLOGPHASE pfnPhase, uint32_t cHistory,
1549	uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot,
1550	char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, ...);
1551
1552	/**
1553	* Create a logger instance.
1554	*
1555	* @returns iprt status code.
1556	*
1557	* @param ppLogger Where to store the logger instance.
1558	* @param fFlags Logger instance flags, a combination of the
1559	* RTLOGFLAGS_* values.
1560	* @param pszGroupSettings The initial group settings.
1561	* @param pszEnvVarBase Base name for the environment variables for
1562	* this instance.
1563	* @param cGroups Number of groups in the array.
1564	* @param papszGroups Pointer to array of groups. This must stick
1565	* around for the life of the logger instance.
1566	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
1567	* if pszFilenameFmt specified.
1568	* @param pfnPhase Callback function for starting logging and for
1569	* ending or starting a new file for log history
1570	* rotation.
1571	* @param cHistory Number of old log files to keep when performing
1572	* log history rotation. 0 means no history.
1573	* @param cbHistoryFileMax Maximum size of log file when performing
1574	* history rotation. 0 means no size limit.
1575	* @param cSecsHistoryTimeSlot Maximum time interval per log file when
1576	* performing history rotation, in seconds.
1577	* 0 means no time limit.
1578	* @param pszErrorMsg A buffer which is filled with an error message
1579	* if something fails. May be NULL.
1580	* @param cchErrorMsg The size of the error message buffer.
1581	* @param pszFilenameFmt Log filename format string. Standard
1582	* RTStrFormat().
1583	* @param args Format arguments.
1584	*/
1585	RTDECL(int) RTLogCreateExV(PRTLOGGER ppLogger, uint32_t fFlags, const char pszGroupSettings,
1586	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1587	uint32_t fDestFlags, PFNRTLOGPHASE pfnPhase, uint32_t cHistory,
1588	uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot,
1589	char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, va_list args);
1590
1591	/**
1592	* Create a logger instance for singled threaded ring-0 usage.
1593	*
1594	* @returns iprt status code.
1595	*
1596	* @param pLogger Where to create the logger instance.
1597	* @param cbLogger The amount of memory available for the logger instance.
1598	* @param pLoggerR0Ptr The ring-0 address corresponding to @a pLogger.
1599	* @param pfnLoggerR0Ptr Pointer to logger wrapper function.
1600	* @param pfnFlushR0Ptr Pointer to flush function.
1601	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1602	* @param fDestFlags The destination flags.
1603	*/
1604	RTDECL(int) RTLogCreateForR0(PRTLOGGER pLogger, size_t cbLogger,
1605	RTR0PTR pLoggerR0Ptr, RTR0PTR pfnLoggerR0Ptr, RTR0PTR pfnFlushR0Ptr,
1606	uint32_t fFlags, uint32_t fDestFlags);
1607
1608	/**
1609	* Calculates the minimum size of a ring-0 logger instance.
1610	*
1611	* @returns The minimum size.
1612	* @param cGroups The number of groups.
1613	* @param fFlags Relevant flags.
1614	*/
1615	RTDECL(size_t) RTLogCalcSizeForR0(uint32_t cGroups, uint32_t fFlags);
1616
1617	/**
1618	* Destroys a logger instance.
1619	*
1620	* The instance is flushed and all output destinations closed (where applicable).
1621	*
1622	* @returns iprt status code.
1623	* @param pLogger The logger instance which close destroyed. NULL is fine.
1624	*/
1625	RTDECL(int) RTLogDestroy(PRTLOGGER pLogger);
1626
1627	/**
1628	* Create a logger instance clone for RC usage.
1629	*
1630	* @returns iprt status code.
1631	*
1632	* @param pLogger The logger instance to be cloned.
1633	* @param pLoggerRC Where to create the RC logger instance.
1634	* @param cbLoggerRC Amount of memory allocated to for the RC logger
1635	* instance clone.
1636	* @param pfnLoggerRCPtr Pointer to logger wrapper function for this
1637	* instance (RC Ptr).
1638	* @param pfnFlushRCPtr Pointer to flush function (RC Ptr).
1639	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1640	*/
1641	RTDECL(int) RTLogCloneRC(PRTLOGGER pLogger, PRTLOGGERRC pLoggerRC, size_t cbLoggerRC,
1642	RTRCPTR pfnLoggerRCPtr, RTRCPTR pfnFlushRCPtr, uint32_t fFlags);
1643
1644	/**
1645	* Flushes a RC logger instance to a R3 logger.
1646	*
1647	* @returns iprt status code.
1648	* @param pLogger The R3 logger instance to flush pLoggerRC to. If NULL
1649	* the default logger is used.
1650	* @param pLoggerRC The RC logger instance to flush.
1651	*/
1652	RTDECL(void) RTLogFlushRC(PRTLOGGER pLogger, PRTLOGGERRC pLoggerRC);
1653
1654	/**
1655	* Flushes the buffer in one logger instance onto another logger.
1656	*
1657	* @returns iprt status code.
1658	*
1659	* @param pSrcLogger The logger instance to flush.
1660	* @param pDstLogger The logger instance to flush onto.
1661	* If NULL the default logger will be used.
1662	*/
1663	RTDECL(void) RTLogFlushToLogger(PRTLOGGER pSrcLogger, PRTLOGGER pDstLogger);
1664
1665	/**
1666	* Flushes a R0 logger instance to a R3 logger.
1667	*
1668	* @returns iprt status code.
1669	* @param pLogger The R3 logger instance to flush pLoggerR0 to. If NULL
1670	* the default logger is used.
1671	* @param pLoggerR0 The R0 logger instance to flush.
1672	*/
1673	RTDECL(void) RTLogFlushR0(PRTLOGGER pLogger, PRTLOGGER pLoggerR0);
1674
1675	/**
1676	* Sets the custom prefix callback.
1677	*
1678	* @returns IPRT status code.
1679	* @param pLogger The logger instance.
1680	* @param pfnCallback The callback.
1681	* @param pvUser The user argument for the callback.
1682	* */
1683	RTDECL(int) RTLogSetCustomPrefixCallback(PRTLOGGER pLogger, PFNRTLOGPREFIX pfnCallback, void *pvUser);
1684
1685	/**
1686	* Same as RTLogSetCustomPrefixCallback for loggers created by
1687	* RTLogCreateForR0.
1688	*
1689	* @returns IPRT status code.
1690	* @param pLogger The logger instance.
1691	* @param pLoggerR0Ptr The ring-0 address corresponding to @a pLogger.
1692	* @param pfnCallbackR0Ptr The callback.
1693	* @param pvUserR0Ptr The user argument for the callback.
1694	* */
1695	RTDECL(int) RTLogSetCustomPrefixCallbackForR0(PRTLOGGER pLogger, RTR0PTR pLoggerR0Ptr,
1696	RTR0PTR pfnCallbackR0Ptr, RTR0PTR pvUserR0Ptr);
1697
1698	/**
1699	* Copies the group settings and flags from logger instance to another.
1700	*
1701	* @returns IPRT status code.
1702	* @param pDstLogger The destination logger instance.
1703	* @param pDstLoggerR0Ptr The ring-0 address corresponding to @a pDstLogger.
1704	* @param pSrcLogger The source logger instance. If NULL the default one is used.
1705	* @param fFlagsOr OR mask for the flags.
1706	* @param fFlagsAnd AND mask for the flags.
1707	*/
1708	RTDECL(int) RTLogCopyGroupsAndFlagsForR0(PRTLOGGER pDstLogger, RTR0PTR pDstLoggerR0Ptr,
1709	PCRTLOGGER pSrcLogger, uint32_t fFlagsOr, uint32_t fFlagsAnd);
1710
1711	/**
1712	* Get the current log group settings as a string.
1713	*
1714	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
1715	* @param pLogger Logger instance (NULL for default logger).
1716	* @param pszBuf The output buffer.
1717	* @param cchBuf The size of the output buffer. Must be greater
1718	* than zero.
1719	*/
1720	RTDECL(int) RTLogGetGroupSettings(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
1721
1722	/**
1723	* Updates the group settings for the logger instance using the specified
1724	* specification string.
1725	*
1726	* @returns iprt status code.
1727	* Failures can safely be ignored.
1728	* @param pLogger Logger instance (NULL for default logger).
1729	* @param pszValue Value to parse.
1730	*/
1731	RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszValue);
1732	#endif /* !IN_RC */
1733
1734	/**
1735	* Updates the flags for the logger instance using the specified
1736	* specification string.
1737	*
1738	* @returns iprt status code.
1739	* Failures can safely be ignored.
1740	* @param pLogger Logger instance (NULL for default logger).
1741	* @param pszValue Value to parse.
1742	*/
1743	RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszValue);
1744
1745	/**
1746	* Changes the buffering setting of the specified logger.
1747	*
1748	* This can be used for optimizing longish logging sequences.
1749	*
1750	* @returns The old state.
1751	* @param pLogger The logger instance (NULL is an alias for the
1752	* default logger).
1753	* @param fBuffered The new state.
1754	*/
1755	RTDECL(bool) RTLogSetBuffering(PRTLOGGER pLogger, bool fBuffered);
1756
1757	/**
1758	* Sets the max number of entries per group.
1759	*
1760	* @returns Old restriction.
1761	*
1762	* @param pLogger The logger instance (NULL is an alias for the
1763	* default logger).
1764	* @param cMaxEntriesPerGroup The max number of entries per group.
1765	*
1766	* @remarks Lowering the limit of an active logger may quietly mute groups.
1767	* Raising it may reactive already muted groups.
1768	*/
1769	RTDECL(uint32_t) RTLogSetGroupLimit(PRTLOGGER pLogger, uint32_t cMaxEntriesPerGroup);
1770
1771	#ifndef IN_RC
1772	/**
1773	* Get the current log flags as a string.
1774	*
1775	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
1776	* @param pLogger Logger instance (NULL for default logger).
1777	* @param pszBuf The output buffer.
1778	* @param cchBuf The size of the output buffer. Must be greater
1779	* than zero.
1780	*/
1781	RTDECL(int) RTLogGetFlags(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
1782
1783	/**
1784	* Updates the logger destination using the specified string.
1785	*
1786	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
1787	* @param pLogger Logger instance (NULL for default logger).
1788	* @param pszValue The value to parse.
1789	*/
1790	RTDECL(int) RTLogDestinations(PRTLOGGER pLogger, char const *pszValue);
1791
1792	/**
1793	* Get the current log destinations as a string.
1794	*
1795	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
1796	* @param pLogger Logger instance (NULL for default logger).
1797	* @param pszBuf The output buffer.
1798	* @param cchBuf The size of the output buffer. Must be greater
1799	* than 0.
1800	*/
1801	RTDECL(int) RTLogGetDestinations(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
1802	#endif /* !IN_RC */
1803
1804	/**
1805	* Flushes the specified logger.
1806	*
1807	* @param pLogger The logger instance to flush.
1808	* If NULL the default instance is used. The default instance
1809	* will not be initialized by this call.
1810	*/
1811	RTDECL(void) RTLogFlush(PRTLOGGER pLogger);
1812
1813	/**
1814	* Write to a logger instance.
1815	*
1816	* @param pLogger Pointer to logger instance.
1817	* @param pvCallerRet Ignored.
1818	* @param pszFormat Format string.
1819	* @param ... Format arguments.
1820	*/
1821	RTDECL(void) RTLogLogger(PRTLOGGER pLogger, void pvCallerRet, const char pszFormat, ...);
1822
1823	/**
1824	* Write to a logger instance.
1825	*
1826	* @param pLogger Pointer to logger instance.
1827	* @param pszFormat Format string.
1828	* @param args Format arguments.
1829	*/
1830	RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args);
1831
1832	/**
1833	* Write to a logger instance.
1834	*
1835	* This function will check whether the instance, group and flags makes up a
1836	* logging kind which is currently enabled before writing anything to the log.
1837	*
1838	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1839	* @param fFlags The logging flags.
1840	* @param iGroup The group.
1841	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1842	* only for internal usage!
1843	* @param pszFormat Format string.
1844	* @param ... Format arguments.
1845	* @remark This is a worker function of LogIt.
1846	*/
1847	RTDECL(void) RTLogLoggerEx(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
1848
1849	/**
1850	* Write to a logger instance.
1851	*
1852	* This function will check whether the instance, group and flags makes up a
1853	* logging kind which is currently enabled before writing anything to the log.
1854	*
1855	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1856	* @param fFlags The logging flags.
1857	* @param iGroup The group.
1858	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1859	* only for internal usage!
1860	* @param pszFormat Format string.
1861	* @param args Format arguments.
1862	*/
1863	RTDECL(void) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
1864
1865	/**
1866	* printf like function for writing to the default log.
1867	*
1868	* @param pszFormat Printf like format string.
1869	* @param ... Optional arguments as specified in pszFormat.
1870	*
1871	* @remark The API doesn't support formatting of floating point numbers at the moment.
1872	*/
1873	RTDECL(void) RTLogPrintf(const char *pszFormat, ...);
1874
1875	/**
1876	* vprintf like function for writing to the default log.
1877	*
1878	* @param pszFormat Printf like format string.
1879	* @param args Optional arguments as specified in pszFormat.
1880	*
1881	* @remark The API doesn't support formatting of floating point numbers at the moment.
1882	*/
1883	RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list args);
1884
1885	/**
1886	* Dumper vprintf-like function outputting to a logger.
1887	*
1888	* @param pvUser Pointer to the logger instance to use, NULL for
1889	* default instance.
1890	* @param pszFormat Format string.
1891	* @param va Format arguments.
1892	*/
1893	RTDECL(void) RTLogDumpPrintfV(void pvUser, const char pszFormat, va_list va);
1894
1895
1896	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h */
1897	#define DECLARED_FNRTSTROUTPUT
1898	/**
1899	* Output callback.
1900	*
1901	* @returns number of bytes written.
1902	* @param pvArg User argument.
1903	* @param pachChars Pointer to an array of utf-8 characters.
1904	* @param cbChars Number of bytes in the character array pointed to by pachChars.
1905	*/
1906	typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void pvArg, const char pachChars, size_t cbChars);
1907	/** Pointer to callback function. */
1908	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
1909	#endif
1910
1911	/**
1912	* Partial vsprintf worker implementation.
1913	*
1914	* @returns number of bytes formatted.
1915	* @param pfnOutput Output worker.
1916	* Called in two ways. Normally with a string an it's length.
1917	* For termination, it's called with NULL for string, 0 for length.
1918	* @param pvArg Argument to output worker.
1919	* @param pszFormat Format string.
1920	* @param args Argument list.
1921	*/
1922	RTDECL(size_t) RTLogFormatV(PFNRTSTROUTPUT pfnOutput, void pvArg, const char pszFormat, va_list args);
1923
1924	/**
1925	* Write log buffer to COM port.
1926	*
1927	* @param pach Pointer to the buffer to write.
1928	* @param cb Number of bytes to write.
1929	*/
1930	RTDECL(void) RTLogWriteCom(const char *pach, size_t cb);
1931
1932	/**
1933	* Prints a formatted string to the serial port used for logging.
1934	*
1935	* @returns Number of bytes written.
1936	* @param pszFormat Format string.
1937	* @param ... Optional arguments specified in the format string.
1938	*/
1939	RTDECL(size_t) RTLogComPrintf(const char *pszFormat, ...);
1940
1941	/**
1942	* Prints a formatted string to the serial port used for logging.
1943	*
1944	* @returns Number of bytes written.
1945	* @param pszFormat Format string.
1946	* @param args Optional arguments specified in the format string.
1947	*/
1948	RTDECL(size_t) RTLogComPrintfV(const char *pszFormat, va_list args);
1949
1950
1951	#if 0 /* not implemented yet */
1952
1953	/** Indicates that the semaphores shall be used to notify the other
1954	* part about buffer changes. */
1955	#define LOGHOOKBUFFER_FLAGS_SEMAPHORED 1
1956
1957	/**
1958	* Log Hook Buffer.
1959	* Use to communicate between the logger and a log consumer.
1960	*/
1961	typedef struct RTLOGHOOKBUFFER
1962	{
1963	/** Write pointer. */
1964	volatile void *pvWrite;
1965	/** Read pointer. */
1966	volatile void *pvRead;
1967	/** Buffer start. */
1968	void *pvStart;
1969	/** Buffer end (exclusive). */
1970	void *pvEnd;
1971	/** Signaling semaphore used by the writer to wait on a full buffer.
1972	* Only used when indicated in flags. */
1973	void *pvSemWriter;
1974	/** Signaling semaphore used by the read to wait on an empty buffer.
1975	* Only used when indicated in flags. */
1976	void *pvSemReader;
1977	/** Buffer flags. Current reserved and set to zero. */
1978	volatile unsigned fFlags;
1979	} RTLOGHOOKBUFFER;
1980	/** Pointer to a log hook buffer. */
1981	typedef RTLOGHOOKBUFFER *PRTLOGHOOKBUFFER;
1982
1983
1984	/**
1985	* Register a logging hook.
1986	*
1987	* This type of logging hooks are expecting different threads acting
1988	* producer and consumer. They share a circular buffer which have two
1989	* pointers one for each end. When the buffer is full there are two
1990	* alternatives (indicated by a buffer flag), either wait for the
1991	* consumer to get it's job done, or to write a generic message saying
1992	* buffer overflow.
1993	*
1994	* Since the waiting would need a signal semaphore, we'll skip that for now.
1995	*
1996	* @returns iprt status code.
1997	* @param pBuffer Pointer to a logger hook buffer.
1998	*/
1999	RTDECL(int) RTLogRegisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
2000
2001	/**
2002	* Deregister a logging hook registered with RTLogRegisterHook().
2003	*
2004	* @returns iprt status code.
2005	* @param pBuffer Pointer to a logger hook buffer.
2006	*/
2007	RTDECL(int) RTLogDeregisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
2008
2009	#endif /* not implemented yet */
2010
2011
2012
2013	/**
2014	* Write log buffer to a debugger (RTLOGDEST_DEBUGGER).
2015	*
2016	* @param pach What to write.
2017	* @param cb How much to write.
2018	* @remark When linking statically, this function can be replaced by defining your own.
2019	*/
2020	RTDECL(void) RTLogWriteDebugger(const char *pach, size_t cb);
2021
2022	/**
2023	* Write log buffer to a user defined output stream (RTLOGDEST_USER).
2024	*
2025	* @param pach What to write.
2026	* @param cb How much to write.
2027	* @remark When linking statically, this function can be replaced by defining your own.
2028	*/
2029	RTDECL(void) RTLogWriteUser(const char *pach, size_t cb);
2030
2031	/**
2032	* Write log buffer to stdout (RTLOGDEST_STDOUT).
2033	*
2034	* @param pach What to write.
2035	* @param cb How much to write.
2036	* @remark When linking statically, this function can be replaced by defining your own.
2037	*/
2038	RTDECL(void) RTLogWriteStdOut(const char *pach, size_t cb);
2039
2040	/**
2041	* Write log buffer to stdout (RTLOGDEST_STDERR).
2042	*
2043	* @param pach What to write.
2044	* @param cb How much to write.
2045	* @remark When linking statically, this function can be replaced by defining your own.
2046	*/
2047	RTDECL(void) RTLogWriteStdErr(const char *pach, size_t cb);
2048
2049	#ifdef VBOX
2050
2051	/**
2052	* Prints a formatted string to the backdoor port.
2053	*
2054	* @returns Number of bytes written.
2055	* @param pszFormat Format string.
2056	* @param ... Optional arguments specified in the format string.
2057	*/
2058	RTDECL(size_t) RTLogBackdoorPrintf(const char *pszFormat, ...);
2059
2060	/**
2061	* Prints a formatted string to the backdoor port.
2062	*
2063	* @returns Number of bytes written.
2064	* @param pszFormat Format string.
2065	* @param args Optional arguments specified in the format string.
2066	*/
2067	RTDECL(size_t) RTLogBackdoorPrintfV(const char *pszFormat, va_list args);
2068
2069	#endif /* VBOX */
2070
2071	RT_C_DECLS_END
2072
2073	/** @} */
2074
2075	#endif
2076

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: