log.h@ 4919

Last change on this file since 4919 was 4860, checked in by vboxsync, 17 years ago
Activated the full backdoor logger in release builds of the Linux Guest Additions kernel modules
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 50.1 KB

Line
1	/** @file
2	* innotek Portable Runtime - Logging.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 innotek GmbH
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 as published by the Free Software Foundation,
12	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13	* distribution. VirtualBox OSE is distributed in the hope that it will
14	* be useful, but WITHOUT ANY WARRANTY of any kind.
15	*/
16
17	#ifndef ___iprt_log_h
18	#define ___iprt_log_h
19
20	#include <iprt/cdefs.h>
21	#include <iprt/types.h>
22	#include <iprt/stdarg.h>
23
24	__BEGIN_DECLS
25
26	/** @defgroup grp_rt_log RTLog - Logging
27	* @ingroup grp_rt
28	* @{
29	*/
30
31	/**
32	* innotek Portable Runtime Logging Groups.
33	* (Remember to update RT_LOGGROUP_NAMES!)
34	*
35	* @remark It should be pretty obvious, but just to have
36	* mentioned it, the values are sorted alphabetically (using the
37	* english alphabet) except for _DEFAULT which is always first.
38	*
39	* If anyone might be wondering what the alphabet looks like:
40	* 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
41	*/
42	typedef enum RTLOGGROUP
43	{
44	/** Default logging group. */
45	RTLOGGROUP_DEFAULT,
46	RTLOGGROUP_DIR,
47	RTLOGGROUP_FILE,
48	RTLOGGROUP_FS,
49	RTLOGGROUP_LDR,
50	RTLOGGROUP_PATH,
51	RTLOGGROUP_PROCESS,
52	RTLOGGROUP_THREAD,
53	RTLOGGROUP_TIME,
54	RTLOGGROUP_TIMER,
55	RTLOGGROUP_ZIP = 31,
56	RTLOGGROUP_FIRST_USER = 32
57	} RTLOGGROUP;
58
59	/** @def RT_LOGGROUP_NAMES
60	* innotek Portable Runtime Logging group names.
61	*
62	* Must correspond 100% to RTLOGGROUP!
63	* Don't forget commas!
64	*
65	* @remark It should be pretty obvious, but just to have
66	* mentioned it, the values are sorted alphabetically (using the
67	* english alphabet) except for _DEFAULT which is always first.
68	*
69	* If anyone might be wondering what the alphabet looks like:
70	* 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
71	*/
72	#define RT_LOGGROUP_NAMES \
73	"DEFAULT", \
74	"RT_DIR", \
75	"RT_FILE", \
76	"RT_FS", \
77	"RT_LDR", \
78	"RT_PATH", \
79	"RT_PROCESS", \
80	"RT_TIME", \
81	"RT_TIMER", \
82	"RT_THREAD", \
83	"RT_10", \
84	"RT_11", \
85	"RT_12", \
86	"RT_13", \
87	"RT_14", \
88	"RT_15", \
89	"RT_16", \
90	"RT_17", \
91	"RT_18", \
92	"RT_19", \
93	"RT_20", \
94	"RT_21", \
95	"RT_22", \
96	"RT_23", \
97	"RT_24", \
98	"RT_25", \
99	"RT_26", \
100	"RT_27", \
101	"RT_28", \
102	"RT_29", \
103	"RT_30", \
104	"RT_ZIP" \
105
106
107	/** @def LOG_GROUP
108	* Active logging group.
109	*/
110	#ifndef LOG_GROUP
111	# define LOG_GROUP RTLOGGROUP_DEFAULT
112	#endif
113
114	/** @def LOG_INSTANCE
115	* Active logging instance.
116	*/
117	#ifndef LOG_INSTANCE
118	# define LOG_INSTANCE NULL
119	#endif
120
121	/** @def LOG_REL_INSTANCE
122	* Active release logging instance.
123	*/
124	#ifndef LOG_REL_INSTANCE
125	# define LOG_REL_INSTANCE NULL
126	#endif
127
128
129	/** Logger structure. */
130	#ifdef IN_GC
131	typedef struct RTLOGGERGC RTLOGGER;
132	#else
133	typedef struct RTLOGGER RTLOGGER;
134	#endif
135	/** Pointer to logger structure. */
136	typedef RTLOGGER *PRTLOGGER;
137	/** Pointer to const logger structure. */
138	typedef const RTLOGGER *PCRTLOGGER;
139
140
141	/** Guest context logger structure. */
142	typedef struct RTLOGGERGC RTLOGGERGC;
143	/** Pointer to guest context logger structure. */
144	typedef RTLOGGERGC *PRTLOGGERGC;
145	/** Pointer to const guest context logger structure. */
146	typedef const RTLOGGERGC *PCRTLOGGERGC;
147
148
149	/**
150	* Logger function.
151	*
152	* @param pszFormat Format string.
153	* @param ... Optional arguments as specified in the format string.
154	*/
155	typedef DECLCALLBACK(void) FNRTLOGGER(const char *pszFormat, ...);
156	/** Pointer to logger function. */
157	typedef FNRTLOGGER *PFNRTLOGGER;
158
159	/**
160	* Flush function.
161	*
162	* @param pLogger Pointer to the logger instance which is to be flushed.
163	*/
164	typedef DECLCALLBACK(void) FNRTLOGFLUSH(PRTLOGGER pLogger);
165	/** Pointer to logger function. */
166	typedef FNRTLOGFLUSH *PFNRTLOGFLUSH;
167
168	/**
169	* Flush function.
170	*
171	* @param pLogger Pointer to the logger instance which is to be flushed.
172	*/
173	typedef DECLCALLBACK(void) FNRTLOGFLUSHGC(PRTLOGGERGC pLogger);
174	/** Pointer to logger function. */
175	typedef GCPTRTYPE(FNRTLOGFLUSHGC *) PFNRTLOGFLUSHGC;
176
177
178	/**
179	* Logger instance structure for GC.
180	*/
181	struct RTLOGGERGC
182	{
183	/** Pointer to temporary scratch buffer.
184	* This is used to format the log messages. */
185	char achScratch[16384];
186	/** Current scratch buffer position. */
187	RTUINT offScratch;
188	/** This is set if a prefix is pending. */
189	RTUINT fPendingPrefix;
190	/** Pointer to the logger function.
191	* This is actually pointer to a wrapper which will push a pointer to the
192	* instance pointer onto the stack before jumping to the real logger function.
193	* A very unfortunate hack to work around the missing variadic macro support in C++. */
194	GCPTRTYPE(PFNRTLOGGER) pfnLogger;
195	/** Pointer to the flush function. */
196	PFNRTLOGFLUSHGC pfnFlush;
197	/** Magic number (RTLOGGERGC_MAGIC). */
198	uint32_t u32Magic;
199	/** Logger instance flags - RTLOGFLAGS. */
200	RTUINT fFlags;
201	/** Number of groups in the afGroups member. */
202	RTUINT cGroups;
203	/** Group flags array - RTLOGGRPFLAGS.
204	* This member have variable length and may extend way beyond
205	* the declared size of 1 entry. */
206	RTUINT afGroups[1];
207	};
208
209	/** RTLOGGERGC::u32Magic value. (John Rogers Searle) */
210	#define RTLOGGERGC_MAGIC 0x19320731
211
212
213
214	#ifndef IN_GC
215	/**
216	* Logger instance structure.
217	*/
218	struct RTLOGGER
219	{
220	/** Pointer to temporary scratch buffer.
221	* This is used to format the log messages. */
222	char achScratch[16384];
223	/** Current scratch buffer position. */
224	RTUINT offScratch;
225	/** This is set if a prefix is pending. */
226	RTUINT fPendingPrefix;
227	/** Pointer to the logger function.
228	* This is actually pointer to a wrapper which will push a pointer to the
229	* instance pointer onto the stack before jumping to the real logger function.
230	* A very unfortunate hack to work around the missing variadic macro support in C++.
231	* (The memory is (not R0) allocated using RTMemExecAlloc().) */
232	PFNRTLOGGER pfnLogger;
233	/** Pointer to the flush function. */
234	PFNRTLOGFLUSH pfnFlush;
235	/** Mutex. */
236	RTSEMFASTMUTEX MutexSem;
237	/** Magic number. */
238	uint32_t u32Magic;
239	/** Logger instance flags - RTLOGFLAGS. */
240	RTUINT fFlags;
241	/** Destination flags - RTLOGDEST. */
242	RTUINT fDestFlags;
243	/** Handle to log file (if open). */
244	RTFILE File;
245	/** Pointer to filename.
246	* (The memory is allocated in the smae block as RTLOGGER.) */
247	char *pszFilename;
248	/** Pointer to the group name array.
249	* (The data is readonly and provided by the user.) */
250	const char * const *papszGroups;
251	/** The max number of groups that there is room for in afGroups and papszGroups.
252	* Used by RTLogCopyGroupAndFlags(). */
253	RTUINT cMaxGroups;
254	/** Number of groups in the afGroups and papszGroups members. */
255	RTUINT cGroups;
256	/** Group flags array - RTLOGGRPFLAGS.
257	* This member have variable length and may extend way beyond
258	* the declared size of 1 entry. */
259	RTUINT afGroups[1];
260	};
261
262	/** RTLOGGER::u32Magic value. (Avram Noam Chomsky) */
263	#define RTLOGGER_MAGIC 0x19281207
264
265	#endif
266
267
268	/**
269	* Logger flags.
270	*/
271	typedef enum RTLOGFLAGS
272	{
273	/** The logger instance is disabled for normal output. */
274	RTLOGFLAGS_DISABLED = 0x00000001,
275	/** The logger instance is using buffered output. */
276	RTLOGFLAGS_BUFFERED = 0x00000002,
277	/** The logger instance expands LF to CR/LF. */
278	RTLOGFLAGS_USECRLF = 0x00000010,
279	/** Show relative timestamps with PREFIX_TSC and PREFIX_TS */
280	RTLOGFLAGS_REL_TS = 0x00010000,
281	/** Show decimal timestamps with PREFIX_TSC and PREFIX_TS */
282	RTLOGFLAGS_DECIMAL_TS = 0x00020000,
283	/** New lines should be prefixed with group flag number causing the output. */
284	RTLOGFLAGS_PREFIX_FLAG_NO = 0x00040000,
285	/** New lines should be prefixed with group flag name causing the output. */
286	RTLOGFLAGS_PREFIX_FLAG = 0x00080000,
287	/** New lines should be prefixed with group number. */
288	RTLOGFLAGS_PREFIX_GROUP_NO = 0x00100000,
289	/** New lines should be prefixed with group name. */
290	RTLOGFLAGS_PREFIX_GROUP = 0x00200000,
291	/** New lines should be prefixed with the native thread id. */
292	RTLOGFLAGS_PREFIX_TID = 0x00400000,
293	/** New lines should be prefixed with thread name. */
294	RTLOGFLAGS_PREFIX_THREAD = 0x00800000,
295	/** New lines should be prefixed with formatted timestamp since program start. */
296	RTLOGFLAGS_PREFIX_TIME_PROG = 0x04000000,
297	/** New lines should be prefixed with formatted timestamp (UCT). */
298	RTLOGFLAGS_PREFIX_TIME = 0x08000000,
299	/** New lines should be prefixed with milliseconds since program start. */
300	RTLOGFLAGS_PREFIX_MS_PROG = 0x10000000,
301	/** New lines should be prefixed with timestamp. */
302	RTLOGFLAGS_PREFIX_TSC = 0x20000000,
303	/** New lines should be prefixed with timestamp. */
304	RTLOGFLAGS_PREFIX_TS = 0x40000000,
305	/** The prefix mask. */
306	RTLOGFLAGS_PREFIX_MASK = 0x7cff0000
307	} RTLOGFLAGS;
308
309	/**
310	* Logger per group flags.
311	*/
312	typedef enum RTLOGGRPFLAGS
313	{
314	/** Enabled. */
315	RTLOGGRPFLAGS_ENABLED = 0x00000001,
316	/** Level 1 logging. */
317	RTLOGGRPFLAGS_LEVEL_1 = 0x00000002,
318	/** Level 2 logging. */
319	RTLOGGRPFLAGS_LEVEL_2 = 0x00000004,
320	/** Level 3 logging. */
321	RTLOGGRPFLAGS_LEVEL_3 = 0x00000008,
322	/** Level 4 logging. */
323	RTLOGGRPFLAGS_LEVEL_4 = 0x00000010,
324	/** Level 5 logging. */
325	RTLOGGRPFLAGS_LEVEL_5 = 0x00000020,
326	/** Level 6 logging. */
327	RTLOGGRPFLAGS_LEVEL_6 = 0x00000040,
328	/** Flow logging. */
329	RTLOGGRPFLAGS_FLOW = 0x00000080,
330
331	/** Lelik logging. */
332	RTLOGGRPFLAGS_LELIK = 0x00000100,
333	/** Michael logging. */
334	RTLOGGRPFLAGS_MICHAEL = 0x00000200,
335	/** dmik logging. */
336	RTLOGGRPFLAGS_DMIK = 0x00000400,
337	/** sunlover logging. */
338	RTLOGGRPFLAGS_SUNLOVER = 0x00000800,
339	/** Achim logging. */
340	RTLOGGRPFLAGS_ACHIM = 0x00001000,
341	/** Sander logging. */
342	RTLOGGRPFLAGS_SANDER = 0x00002000,
343	/** Klaus logging. */
344	RTLOGGRPFLAGS_KLAUS = 0x00004000,
345	/** Frank logging. */
346	RTLOGGRPFLAGS_FRANK = 0x00008000,
347	/** bird logging. */
348	RTLOGGRPFLAGS_BIRD = 0x00010000,
349	/** NoName logging. */
350	RTLOGGRPFLAGS_NONAME = 0x00020000
351	} RTLOGGRPFLAGS;
352
353	/**
354	* Logger destination type.
355	*/
356	typedef enum RTLOGDEST
357	{
358	/** Log to file. */
359	RTLOGDEST_FILE = 0x00000001,
360	/** Log to stdout. */
361	RTLOGDEST_STDOUT = 0x00000002,
362	/** Log to stderr. */
363	RTLOGDEST_STDERR = 0x00000004,
364	/** Log to debugger (win32 only). */
365	RTLOGDEST_DEBUGGER = 0x00000008,
366	/** Log to com port. */
367	RTLOGDEST_COM = 0x00000010,
368	/** Just a dummy flag to be used when no other flag applies. */
369	RTLOGDEST_DUMMY = 0x20000000,
370	/** Log to a user defined output stream. */
371	RTLOGDEST_USER = 0x40000000
372	} RTLOGDEST;
373
374
375	RTDECL(void) RTLogPrintfEx(void pvInstance, unsigned fFlags, unsigned iGroup, const char pszFormat, ...);
376
377
378	/*
379	* Determin whether logging is enabled and forcefully normalize the indicators.
380	*/
381	#if (defined(DEBUG) \|\| defined(LOG_ENABLED)) && !defined(LOG_DISABLED)
382	# undef LOG_DISABLED
383	# undef LOG_ENABLED
384	# define LOG_ENABLED
385	#else
386	# undef LOG_ENABLED
387	# undef LOG_DISABLED
388	# define LOG_DISABLED
389	#endif
390
391
392	/** @def LogIt
393	* Write to specific logger if group enabled.
394	*/
395	#ifdef LOG_ENABLED
396	# if defined(RT_ARCH_AMD64) \|\| defined(LOG_USE_C99)
397	# define _LogRemoveParentheseis(...) __VA_ARGS__
398	# define _LogIt(pvInst, fFlags, iGroup, ...) RTLogLoggerEx((PRTLOGGER)pvInst, fFlags, iGroup, __VA_ARGS__)
399	# define LogIt(pvInst, fFlags, iGroup, fmtargs) _LogIt(pvInst, fFlags, iGroup, _LogRemoveParentheseis fmtargs)
400	# else
401	# define LogIt(pvInst, fFlags, iGroup, fmtargs) \
402	do \
403	{ \
404	register PRTLOGGER LogIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogDefaultInstance(); \
405	if (LogIt_pLogger) \
406	{ \
407	register unsigned LogIt_fFlags = LogIt_pLogger->afGroups[(unsigned)(iGroup) < LogIt_pLogger->cGroups ? (unsigned)(iGroup) : 0]; \
408	if ((LogIt_fFlags & ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
409	LogIt_pLogger->pfnLogger fmtargs; \
410	} \
411	} while (0)
412	# endif
413	#else
414	# define LogIt(pvInst, fFlags, iGroup, fmtargs) do { } while (0)
415	#endif
416
417
418	/** @def Log
419	* Level 1 logging.
420	*/
421	#define Log(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
422
423	/** @def Log2
424	* Level 2 logging.
425	*/
426	#define Log2(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
427
428	/** @def Log3
429	* Level 3 logging.
430	*/
431	#define Log3(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
432
433	/** @def Log4
434	* Level 4 logging.
435	*/
436	#define Log4(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
437
438	/** @def Log5
439	* Level 5 logging.
440	*/
441	#define Log5(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
442
443	/** @def Log6
444	* Level 6 logging.
445	*/
446	#define Log6(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
447
448	/** @def LogFlow
449	* Logging of execution flow.
450	*/
451	#define LogFlow(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
452
453	/** @def LogLelik
454	* lelik logging.
455	*/
456	#define LogLelik(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
457
458
459	/** @def LogMichael
460	* michael logging.
461	*/
462	#define LogMichael(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
463
464	/** @def LogDmik
465	* dmik logging.
466	*/
467	#define LogDmik(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_DMIK, LOG_GROUP, a)
468
469	/** @def LogSunlover
470	* sunlover logging.
471	*/
472	#define LogSunlover(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
473
474	/** @def LogAchim
475	* Achim logging.
476	*/
477	#define LogAchim(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
478
479	/** @def LogSander
480	* Sander logging.
481	*/
482	#define LogSander(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
483
484	/** @def LogKlaus
485	* klaus logging.
486	*/
487	#define LogKlaus(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
488
489	/** @def LogFrank
490	* frank logging.
491	*/
492	#define LogFrank(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
493
494	/** @def LogBird
495	* bird logging.
496	*/
497	#define LogBird(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
498
499	/** @def LogNoName
500	* NoName logging.
501	*/
502	#define LogNoName(a) LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
503
504
505	/** @def LogWarning
506	* The same as Log(), but prepents a <tt>"WARNING! "</tt> string to the message.
507	* @param m custom log message in format <tt>("string\n" [, args])</tt>
508	* @todo use a Log macro with a variable argument list (requires MSVC8) to
509	* join two separate Log* calls and make this op atomic
510	*/
511	#define LogWarning(m) \
512	do { Log(("WARNING! ")); Log(m); } while (0)
513
514	/** @def LogTrace
515	* Macro to trace the execution flow: logs the file name, line number and
516	* function name. Can be easily searched for in log files using the
517	* ">>>>>" pattern (prepended to the beginning of each line).
518	*/
519	#define LogTrace() \
520	LogFlow((">>>>> %s (%d): %s\n", __FILE__, __LINE__, __PRETTY_FUNCTION__))
521
522	/** @def LogTraceMsg
523	* The same as LogTrace but logs a custom log message right after the trace line.
524	* @param m custom log message in format <tt>("string\n" [, args])</tt>
525	* @todo use a Log macro with a variable argument list (requires MSVC8) to
526	* join two separate Log* calls and make this op atomic
527	*/
528	#define LogTraceMsg(m) \
529	do { LogTrace(); LogFlow(m); } while (0)
530
531	/** @def LogFunc
532	* Level 1 logging inside C/C++ functions.
533	* Prepends the given log message with the function name followed by a semicolon
534	* and space.
535	* @param m log message in format <tt>("string\n" [, args])</tt>
536	* @todo use a Log macro with a variable argument list (requires MSVC8) to
537	* join two separate Log* calls and make this op atomic
538	*/
539	#define LogFunc(m) \
540	do { Log(("%s: ", __PRETTY_FUNCTION__)); Log(m); } while (0)
541
542	/** @def LogThisFunc
543	* The same as LogFunc but for class functions (methods): the resulting log
544	* line is additionally perpended with a hex value of \|this\| pointer.
545	* @param m log message in format <tt>("string\n" [, args])</tt>
546	* @todo use a Log macro with a variable argument list (requires MSVC8) to
547	* join two separate Log* calls and make this op atomic
548	*/
549	#define LogThisFunc(m) \
550	do { Log(("{%p} %s: ", this, __PRETTY_FUNCTION__)); Log(m); } while (0)
551
552	/** @def LogFlowFunc
553	* Macro to log the execution flow inside C/C++ functions.
554	* Prepends the given log message with the function name followed by a semicolon
555	* and space.
556	* @param m log message in format <tt>("string\n" [, args])</tt>
557	* @todo use a Log macro with a variable argument list (requires MSVC8) to
558	* join two separate Log* calls and make this op atomic
559	*/
560	#define LogFlowFunc(m) \
561	do { LogFlow(("%s: ", __PRETTY_FUNCTION__)); LogFlow(m); } while (0)
562
563	/** @def LogWarningFunc
564	* The same as LogWarning(), but prepents the log message with the function name.
565	* @param m log message in format <tt>("string\n" [, args])</tt>
566	* @todo use a Log macro with a variable argument list (requires MSVC8) to
567	* join two separate Log* calls and make this op atomic
568	*/
569	#define LogWarningFunc(m) \
570	do { Log(("%s: WARNING! ", __PRETTY_FUNCTION__)); Log(m); } while (0)
571
572	/** @def LogFlowThisFunc
573	* The same as LogFlowFunc but for class functions (methods): the resulting log
574	* line is additionally perpended with a hex value of \|this\| pointer.
575	* @param m log message in format <tt>("string\n" [, args])</tt>
576	* @todo use a Log macro with a variable argument list (requires MSVC8) to
577	* join two separate Log* calls and make this op atomic
578	*/
579	#define LogFlowThisFunc(m) \
580	do { LogFlow(("{%p} %s: ", this, __PRETTY_FUNCTION__)); LogFlow(m); } while (0)
581
582	/** @def LogWarningThisFunc
583	* The same as LogWarningFunc() but for class functions (methods): the resulting
584	* log line is additionally perpended with a hex value of \|this\| pointer.
585	* @param m log message in format <tt>("string\n" [, args])</tt>
586	* @todo use a Log macro with a variable argument list (requires MSVC8) to
587	* join two separate Log* calls and make this op atomic
588	*/
589	#define LogWarningThisFunc(m) \
590	do { Log(("{%p} %s: WARNING! ", this, __PRETTY_FUNCTION__)); Log(m); } while (0)
591
592	/** Shortcut to \|LogFlowFunc ("ENTER\n")\|, marks the beginnig of the function */
593	#define LogFlowFuncEnter() LogFlowFunc(("ENTER\n"))
594
595	/** Shortcut to \|LogFlowFunc ("LEAVE\n")\|, marks the end of the function */
596	#define LogFlowFuncLeave() LogFlowFunc(("LEAVE\n"))
597
598	/** Shortcut to \|LogFlowThisFunc ("ENTER\n")\|, marks the beginnig of the function */
599	#define LogFlowThisFuncEnter() LogFlowThisFunc(("ENTER\n"))
600
601	/** Shortcut to \|LogFlowThisFunc ("LEAVE\n")\|, marks the end of the function */
602	#define LogFlowThisFuncLeave() LogFlowThisFunc(("LEAVE\n"))
603
604	/** @def LogObjRefCnt
605	* Helper macro to print the current reference count of the given COM object
606	* to the log file.
607	* @param obj object in question (must be a pointer to an IUnknown subclass
608	* or simply define COM-style AddRef() and Release() methods)
609	* @note Use it only for temporary debugging. It leaves dummy code even if
610	* logging is disabled.
611	*/
612	#define LogObjRefCnt(obj) \
613	do { \
614	int refc = (obj)->AddRef(); -- refc; \
615	LogFlow((#obj "{%p}.refCnt=%d\n", (obj), refc)); \
616	(obj)->Release(); \
617	} while (0)
618
619
620	/** @def LogIsItEnabled
621	* Checks whether the specified logging group is enabled or not.
622	*/
623	#ifdef LOG_ENABLED
624	# define LogIsItEnabled(pvInst, fFlags, iGroup) \
625	LogIsItEnabledInternal((pvInst), (unsigned)(iGroup), (unsigned)(fFlags))
626	#else
627	# define LogIsItEnabled(pvInst, fFlags, iGroup) (false)
628	#endif
629
630	/** @def LogIsEnabled
631	* Checks whether level 1 logging is enabled.
632	*/
633	#define LogIsEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
634
635	/** @def LogIs2Enabled
636	* Checks whether level 2 logging is enabled.
637	*/
638	#define LogIs2Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
639
640	/** @def LogIs3Enabled
641	* Checks whether level 3 logging is enabled.
642	*/
643	#define LogIs3Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
644
645	/** @def LogIs4Enabled
646	* Checks whether level 4 logging is enabled.
647	*/
648	#define LogIs4Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
649
650	/** @def LogIs5Enabled
651	* Checks whether level 5 logging is enabled.
652	*/
653	#define LogIs5Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
654
655	/** @def LogIs6Enabled
656	* Checks whether level 6 logging is enabled.
657	*/
658	#define LogIs6Enabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
659
660	/** @def LogIsFlowEnabled
661	* Checks whether execution flow logging is enabled.
662	*/
663	#define LogIsFlowEnabled() LogIsItEnabled(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
664
665
666	#ifdef __DOXYGEN__
667	# define LOG_DISABLED
668	# define LOG_ENABLED
669	# define LOG_ENABLE_FLOW
670	#endif
671
672	/** @def LOG_DISABLED
673	* Use this compile time define to disable all logging macros. It can
674	* be overriden for each of the logging macros by the LOG_ENABLE*
675	* compile time defines.
676	*/
677
678	/** @def LOG_ENABLED
679	* Use this compile time define to enable logging when not in debug mode
680	* or LOG_DISABLED is set.
681	* This will enabled Log() only.
682	*/
683
684	/** @def LOG_ENABLE_FLOW
685	* Use this compile time define to enable flow logging when not in
686	* debug mode or LOG_DISABLED is defined.
687	* This will enable LogFlow() only.
688	*/
689
690
691
692	/** @name Release Logging
693	* @{
694	*/
695
696	/** @def LogIt
697	* Write to specific logger if group enabled.
698	*/
699	#if defined(RT_ARCH_AMD64) \|\| defined(LOG_USE_C99)
700	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
701	# define _LogRelIt(pvInst, fFlags, iGroup, ...) RTLogLoggerEx((PRTLOGGER)pvInst, fFlags, iGroup, __VA_ARGS__)
702	# define LogRelIt(pvInst, fFlags, iGroup, fmtargs) \
703	do \
704	{ \
705	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogRelDefaultInstance(); \
706	if (LogRelIt_pLogger) \
707	_LogRelIt(LogRelIt_pLogger, fFlags, iGroup, _LogRelRemoveParentheseis fmtargs); \
708	LogIt(LOG_INSTANCE, fFlags, iGroup, fmtargs); \
709	} while (0)
710	#else
711	# define LogRelIt(pvInst, fFlags, iGroup, fmtargs) \
712	do \
713	{ \
714	PRTLOGGER LogRelIt_pLogger = (PRTLOGGER)(pvInst) ? (PRTLOGGER)(pvInst) : RTLogRelDefaultInstance(); \
715	if (LogRelIt_pLogger) \
716	{ \
717	unsigned LogIt_fFlags = LogRelIt_pLogger->afGroups[(unsigned)(iGroup) < LogRelIt_pLogger->cGroups ? (unsigned)(iGroup) : 0]; \
718	if ((LogIt_fFlags & ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) == ((fFlags) \| RTLOGGRPFLAGS_ENABLED)) \
719	LogRelIt_pLogger->pfnLogger fmtargs; \
720	} \
721	LogIt(LOG_INSTANCE, fFlags, iGroup, fmtargs); \
722	} while (0)
723	#endif
724
725
726	/** @def LogRel
727	* Level 1 logging.
728	*/
729	#define LogRel(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
730
731	/** @def LogRel2
732	* Level 2 logging.
733	*/
734	#define LogRel2(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
735
736	/** @def LogRel3
737	* Level 3 logging.
738	*/
739	#define LogRel3(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
740
741	/** @def LogRel4
742	* Level 4 logging.
743	*/
744	#define LogRel4(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
745
746	/** @def LogRel5
747	* Level 5 logging.
748	*/
749	#define LogRel5(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
750
751	/** @def LogRel6
752	* Level 6 logging.
753	*/
754	#define LogRel6(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
755
756	/** @def LogRelFlow
757	* Logging of execution flow.
758	*/
759	#define LogRelFlow(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
760
761	/** @def LogRelFunc
762	* Release logging. Prepends the given log message with the function name
763	* followed by a semicolon and space.
764	*/
765	#define LogRelFunc(a) \
766	do { LogRel(("%s: ", __PRETTY_FUNCTION__)); LogRel(a); } while (0)
767
768	/** @def LogRelThisFunc
769	* The same as LogRelFunc but for class functions (methods): the resulting log
770	* line is additionally perpended with a hex value of \|this\| pointer.
771	*/
772	#define LogRelThisFunc(a) \
773	do { LogRel(("{%p} %s: ", this, __PRETTY_FUNCTION__)); LogRel(a); } while (0)
774
775	/** @def LogRelLelik
776	* lelik logging.
777	*/
778	#define LogRelLelik(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LELIK, LOG_GROUP, a)
779
780	/** @def LogRelMichael
781	* michael logging.
782	*/
783	#define LogRelMichael(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_MICHAEL, LOG_GROUP, a)
784
785	/** @def LogRelDmik
786	* dmik logging.
787	*/
788	#define LogRelDmik(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_DMIK, LOG_GROUP, a)
789
790	/** @def LogRelSunlover
791	* sunlover logging.
792	*/
793	#define LogRelSunlover(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SUNLOVER, LOG_GROUP, a)
794
795	/** @def LogRelAchim
796	* Achim logging.
797	*/
798	#define LogRelAchim(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_ACHIM, LOG_GROUP, a)
799
800	/** @def LogRelSander
801	* Sander logging.
802	*/
803	#define LogRelSander(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_SANDER, LOG_GROUP, a)
804
805	/** @def LogRelKlaus
806	* klaus logging.
807	*/
808	#define LogRelKlaus(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_KLAUS, LOG_GROUP, a)
809
810	/** @def LogRelFrank
811	* frank logging.
812	*/
813	#define LogRelFrank(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FRANK, LOG_GROUP, a)
814
815	/** @def LogRelBird
816	* bird logging.
817	*/
818	#define LogRelBird(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_BIRD, LOG_GROUP, a)
819
820	/** @def LogRelNoName
821	* NoName logging.
822	*/
823	#define LogRelNoName(a) LogRelIt(LOG_REL_INSTANCE, RTLOGGRPFLAGS_NONAME, LOG_GROUP, a)
824
825
826	/** @def LogRelIsItEnabled
827	* Checks whether the specified logging group is enabled or not.
828	*/
829	#define LogRelIsItEnabled(pvInst, fFlags, iGroup) \
830	LogRelIsItEnabledInternal((pvInst), (unsigned)(iGroup), (unsigned)(fFlags))
831
832	/** @def LogRelIsEnabled
833	* Checks whether level 1 logging is enabled.
834	*/
835	#define LogRelIsEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
836
837	/** @def LogRelIs2Enabled
838	* Checks whether level 2 logging is enabled.
839	*/
840	#define LogRelIs2Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
841
842	/** @def LogRelIs3Enabled
843	* Checks whether level 3 logging is enabled.
844	*/
845	#define LogRelIs3Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
846
847	/** @def LogRelIs4Enabled
848	* Checks whether level 4 logging is enabled.
849	*/
850	#define LogRelIs4Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
851
852	/** @def LogRelIs5Enabled
853	* Checks whether level 5 logging is enabled.
854	*/
855	#define LogRelIs5Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
856
857	/** @def LogRelIs6Enabled
858	* Checks whether level 6 logging is enabled.
859	*/
860	#define LogRelIs6Enabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
861
862	/** @def LogRelIsFlowEnabled
863	* Checks whether execution flow logging is enabled.
864	*/
865	#define LogRelIsFlowEnabled() LogRelIsItEnabled(LOG_REL_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP)
866
867
868	#ifndef IN_GC
869	/**
870	* Sets the default release logger instance.
871	*
872	* @returns The old default instance.
873	* @param pLogger The new default release logger instance.
874	*/
875	RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger);
876	#endif /* !IN_GC */
877
878	/**
879	* Gets the default release logger instance.
880	*
881	* @returns Pointer to default release logger instance.
882	* @returns NULL if no default release logger instance available.
883	*/
884	RTDECL(PRTLOGGER) RTLogRelDefaultInstance(void);
885
886	/** Internal worker function.
887	* Don't call directly, use the LogRelIsItEnabled macro!
888	*/
889	DECLINLINE(bool) LogRelIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
890	{
891	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogRelDefaultInstance();
892	if (pLogger)
893	{
894	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
895	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
896	return true;
897	}
898	return false;
899	}
900
901	/**
902	* Write to a logger instance, defaulting to the release one.
903	*
904	* This function will check whether the instance, group and flags makes up a
905	* logging kind which is currently enabled before writing anything to the log.
906	*
907	* @param pLogger Pointer to logger instance.
908	* @param fFlags The logging flags.
909	* @param iGroup The group.
910	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
911	* only for internal usage!
912	* @param pszFormat Format string.
913	* @param ... Format arguments.
914	* @remark This is a worker function for LogRelIt.
915	*/
916	RTDECL(void) RTLogRelLogger(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
917
918	/**
919	* Write to a logger instance, defaulting to the release one.
920	*
921	* This function will check whether the instance, group and flags makes up a
922	* logging kind which is currently enabled before writing anything to the log.
923	*
924	* @param pLogger Pointer to logger instance. If NULL the default release instance is attempted.
925	* @param fFlags The logging flags.
926	* @param iGroup The group.
927	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
928	* only for internal usage!
929	* @param pszFormat Format string.
930	* @param args Format arguments.
931	*/
932	RTDECL(void) RTLogRelLoggerV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
933
934	/**
935	* printf like function for writing to the default release log.
936	*
937	* @param pszFormat Printf like format string.
938	* @param ... Optional arguments as specified in pszFormat.
939	*
940	* @remark The API doesn't support formatting of floating point numbers at the moment.
941	*/
942	RTDECL(void) RTLogRelPrintf(const char *pszFormat, ...);
943
944	/**
945	* vprintf like function for writing to the default release log.
946	*
947	* @param pszFormat Printf like format string.
948	* @param args Optional arguments as specified in pszFormat.
949	*
950	* @remark The API doesn't support formatting of floating point numbers at the moment.
951	*/
952	RTDECL(void) RTLogRelPrintfV(const char *pszFormat, va_list args);
953
954
955	/** @} */
956
957
958
959	/** @name COM port logging
960	* {
961	*/
962
963	#ifdef __DOXYGEN__
964	# define LOG_TO_COM
965	# define LOG_NO_COM
966	#endif
967
968	/** @def LOG_TO_COM
969	* Redirects the normal loging macros to the serial versions.
970	*/
971
972	/** @def LOG_NO_COM
973	* Disables all LogCom* macros.
974	*/
975
976	/** @def LogCom
977	* Generic logging to serial port.
978	*/
979	#if defined(LOG_ENABLED) && !defined(LOG_NO_COM)
980	# define LogCom(a) RTLogComPrintf a
981	#else
982	# define LogCom(a) do { } while (0)
983	#endif
984
985	/** @def LogComFlow
986	* Logging to serial port of execution flow.
987	*/
988	#if defined(LOG_ENABLED) && defined(LOG_ENABLE_FLOW) && !defined(LOG_NO_COM)
989	# define LogComFlow(a) RTLogComPrintf a
990	#else
991	# define LogComFlow(a) do { } while (0)
992	#endif
993
994	#ifdef LOG_TO_COM
995	# undef Log
996	# define Log(a) LogCom(a)
997	# undef LogFlow
998	# define LogFlow(a) LogComFlow(a)
999	#endif
1000
1001	/** @} */
1002
1003
1004	/** @name Backdoor Logging
1005	* @{
1006	*/
1007
1008	#ifdef __DOXYGEN__
1009	# define LOG_TO_BACKDOOR
1010	# define LOG_NO_BACKDOOR
1011	#endif
1012
1013	/** @def LOG_TO_BACKDOOR
1014	* Redirects the normal logging macros to the backdoor versions.
1015	*/
1016
1017	/** @def LOG_NO_BACKDOOR
1018	* Disables all LogBackdoor* macros.
1019	*/
1020
1021	/** @def LogBackdoor
1022	* Generic logging to the VBox backdoor via port I/O.
1023	*/
1024	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1025	# define LogBackdoor(a) RTLogBackdoorPrintf a
1026	#else
1027	# define LogBackdoor(a) do { } while (0)
1028	#endif
1029
1030	/** @def LogBackdoorFlow
1031	* Logging of execution flow messages to the backdoor I/O port.
1032	*/
1033	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1034	# define LogBackdoorFlow(a) RTLogBackdoorPrintf a
1035	#else
1036	# define LogBackdoorFlow(a) do { } while (0)
1037	#endif
1038
1039	/** @def LogRelBackdoor
1040	* Release logging to the VBox backdoor via port I/O.
1041	*/
1042	#if !defined(LOG_NO_BACKDOOR)
1043	# define LogRelBackdoor(a) RTLogBackdoorPrintf a
1044	#else
1045	# define LogRelBackdoor(a) do { } while (0)
1046	#endif
1047
1048	#ifdef LOG_TO_BACKDOOR
1049	# undef Log
1050	# define Log(a) LogBackdoor(a)
1051	# undef LogFlow
1052	# define LogFlow(a) LogBackdoorFlow(a)
1053	# undef LogRel
1054	# define LogRel(a) LogRelBackdoor(a)
1055	#endif
1056
1057	/** @} */
1058
1059
1060
1061
1062	/**
1063	* Gets the default logger instance.
1064	*
1065	* @returns Pointer to default logger instance.
1066	* @returns NULL if no default logger instance available.
1067	*/
1068	RTDECL(PRTLOGGER) RTLogDefaultInstance(void);
1069
1070	#ifdef IN_RING0
1071	/**
1072	* Changes the default logger instance for the current thread.
1073	*
1074	* @returns IPRT status code.
1075	* @param pLogger The logger instance. Pass NULL for deregistration.
1076	* @param uKey Associated key for cleanup purposes. If pLogger is NULL,
1077	* all instances with this key will be deregistered. So in
1078	* order to only deregister the instance associated with the
1079	* current thread use 0.
1080	*/
1081	RTDECL(int) RTLogSetDefaultInstanceThread(PRTLOGGER pLogger, uintptr_t uKey);
1082	#endif /* IN_RING0 */
1083
1084
1085	#ifdef LOG_ENABLED
1086	/** Internal worker function.
1087	* Don't call directly, use the LogIsItEnabled macro!
1088	*/
1089	DECLINLINE(bool) LogIsItEnabledInternal(void *pvInst, unsigned iGroup, unsigned fFlags)
1090	{
1091	register PRTLOGGER pLogger = (PRTLOGGER)pvInst ? (PRTLOGGER)pvInst : RTLogDefaultInstance();
1092	if (pLogger)
1093	{
1094	register unsigned fGrpFlags = pLogger->afGroups[(unsigned)iGroup < pLogger->cGroups ? (unsigned)iGroup : 0];
1095	if ((fGrpFlags & (fFlags \| RTLOGGRPFLAGS_ENABLED)) == (fFlags \| RTLOGGRPFLAGS_ENABLED))
1096	return true;
1097	}
1098	return false;
1099	}
1100	#endif
1101
1102
1103	#ifndef IN_GC
1104	/**
1105	* Creates the default logger instance for a iprt users.
1106	*
1107	* Any user of the logging features will need to implement
1108	* this or use the generic dummy.
1109	*
1110	* @returns Pointer to the logger instance.
1111	*/
1112	RTDECL(PRTLOGGER) RTLogDefaultInit(void);
1113
1114	/**
1115	* Create a logger instance.
1116	*
1117	* @returns iprt status code.
1118	*
1119	* @param ppLogger Where to store the logger instance.
1120	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1121	* @param pszGroupSettings The initial group settings.
1122	* @param pszEnvVarBase Base name for the environment variables for this instance.
1123	* @param cGroups Number of groups in the array.
1124	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1125	* logger instance.
1126	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1127	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1128	* @param ... Format arguments.
1129	*/
1130	RTDECL(int) RTLogCreate(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1131	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1132	RTUINT fDestFlags, const char *pszFilenameFmt, ...);
1133
1134	/**
1135	* Create a logger instance.
1136	*
1137	* @returns iprt status code.
1138	*
1139	* @param ppLogger Where to store the logger instance.
1140	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1141	* @param pszGroupSettings The initial group settings.
1142	* @param pszEnvVarBase Base name for the environment variables for this instance.
1143	* @param cGroups Number of groups in the array.
1144	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1145	* logger instance.
1146	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1147	* @param pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
1148	* @param cchErrorMsg The size of the error message buffer.
1149	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1150	* @param ... Format arguments.
1151	*/
1152	RTDECL(int) RTLogCreateEx(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1153	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1154	RTUINT fDestFlags, char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, ...);
1155
1156	/**
1157	* Create a logger instance.
1158	*
1159	* @returns iprt status code.
1160	*
1161	* @param ppLogger Where to store the logger instance.
1162	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1163	* @param pszGroupSettings The initial group settings.
1164	* @param pszEnvVarBase Base name for the environment variables for this instance.
1165	* @param cGroups Number of groups in the array.
1166	* @param papszGroups Pointer to array of groups. This must stick around for the life of the
1167	* logger instance.
1168	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed if pszFilenameFmt specified.
1169	* @param pszErrorMsg A buffer which is filled with an error message if something fails. May be NULL.
1170	* @param cchErrorMsg The size of the error message buffer.
1171	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
1172	* @param args Format arguments.
1173	*/
1174	RTDECL(int) RTLogCreateExV(PRTLOGGER ppLogger, RTUINT fFlags, const char pszGroupSettings,
1175	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1176	RTUINT fDestFlags, char pszErrorMsg, size_t cchErrorMsg, const char pszFilenameFmt, va_list args);
1177
1178	/**
1179	* Create a logger instance for singled threaded ring-0 usage.
1180	*
1181	* @returns iprt status code.
1182	*
1183	* @param pLogger Where to create the logger instance.
1184	* @param cbLogger The amount of memory available for the logger instance.
1185	* @param pfnLogger Pointer to logger wrapper function for the clone.
1186	* @param pfnFlush Pointer to flush function for the clone.
1187	* @param fFlags Logger instance flags for the clone, a combination of the RTLOGFLAGS_* values.
1188	* @param fDestFlags The destination flags.
1189	*/
1190	RTDECL(int) RTLogCreateForR0(PRTLOGGER pLogger, size_t cbLogger, PFNRTLOGGER pfnLogger, PFNRTLOGFLUSH pfnFlush, RTUINT fFlags, RTUINT fDestFlags);
1191
1192	/**
1193	* Destroys a logger instance.
1194	*
1195	* The instance is flushed and all output destinations closed (where applicable).
1196	*
1197	* @returns iprt status code.
1198	* @param pLogger The logger instance which close destroyed.
1199	*/
1200	RTDECL(int) RTLogDestroy(PRTLOGGER pLogger);
1201
1202	/**
1203	* Create a logger instance clone for GC usage.
1204	*
1205	* @returns iprt status code.
1206	*
1207	* @param pLogger The logger instance to be cloned.
1208	* @param pLoggerGC Where to create the GC logger instance.
1209	* @param cbLoggerGC Amount of memory allocated to for the GC logger instance clone.
1210	* @param pfnLoggerGCPtr Pointer to logger wrapper function for this instance (GC Ptr).
1211	* @param pfnFlushGCPtr Pointer to flush function (GC Ptr).
1212	* @param fFlags Logger instance flags, a combination of the RTLOGFLAGS_* values.
1213	*/
1214	RTDECL(int) RTLogCloneGC(PRTLOGGER pLogger, PRTLOGGERGC pLoggerGC, size_t cbLoggerGC,
1215	RTGCPTR pfnLoggerGCPtr, RTGCPTR pfnFlushGCPtr, RTUINT fFlags);
1216
1217	/**
1218	* Flushes a GC logger instance to a HC logger.
1219	*
1220	* @returns iprt status code.
1221	* @param pLogger The HC logger instance to flush pLoggerGC to.
1222	* If NULL the default logger is used.
1223	* @param pLoggerGC The GC logger instance to flush.
1224	*/
1225	RTDECL(void) RTLogFlushGC(PRTLOGGER pLogger, PRTLOGGERGC pLoggerGC);
1226
1227	/**
1228	* Flushes the buffer in one logger instance onto another logger.
1229	*
1230	* @returns iprt status code.
1231	*
1232	* @param pSrcLogger The logger instance to flush.
1233	* @param pDstLogger The logger instance to flush onto.
1234	* If NULL the default logger will be used.
1235	*/
1236	RTDECL(void) RTLogFlushToLogger(PRTLOGGER pSrcLogger, PRTLOGGER pDstLogger);
1237
1238	/**
1239	* Copies the group settings and flags from logger instance to another.
1240	*
1241	* @returns IPRT status code.
1242	* @param pDstLogger The destination logger instance.
1243	* @param pSrcLogger The source logger instance. If NULL the default one is used.
1244	* @param fFlagsOr OR mask for the flags.
1245	* @param fFlagsAnd AND mask for the flags.
1246	*/
1247	RTDECL(int) RTLogCopyGroupsAndFlags(PRTLOGGER pDstLogger, PCRTLOGGER pSrcLogger, unsigned fFlagsOr, unsigned fFlagsAnd);
1248
1249	/**
1250	* Updates the group settings for the logger instance using the specified
1251	* specification string.
1252	*
1253	* @returns iprt status code.
1254	* Failures can safely be ignored.
1255	* @param pLogger Logger instance (NULL for default logger).
1256	* @param pszVar Value to parse.
1257	*/
1258	RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszVar);
1259	#endif /* !IN_GC */
1260
1261	/**
1262	* Updates the flags for the logger instance using the specified
1263	* specification string.
1264	*
1265	* @returns iprt status code.
1266	* Failures can safely be ignored.
1267	* @param pLogger Logger instance (NULL for default logger).
1268	* @param pszVar Value to parse.
1269	*/
1270	RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszVar);
1271
1272	/**
1273	* Flushes the specified logger.
1274	*
1275	* @param pLogger The logger instance to flush.
1276	* If NULL the default instance is used. The default instance
1277	* will not be initialized by this call.
1278	*/
1279	RTDECL(void) RTLogFlush(PRTLOGGER pLogger);
1280
1281	/**
1282	* Write to a logger instance.
1283	*
1284	* @param pLogger Pointer to logger instance.
1285	* @param pvCallerRet Ignored.
1286	* @param pszFormat Format string.
1287	* @param ... Format arguments.
1288	*/
1289	RTDECL(void) RTLogLogger(PRTLOGGER pLogger, void pvCallerRet, const char pszFormat, ...);
1290
1291	/**
1292	* Write to a logger instance.
1293	*
1294	* @param pLogger Pointer to logger instance.
1295	* @param pszFormat Format string.
1296	* @param args Format arguments.
1297	*/
1298	RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args);
1299
1300	/**
1301	* Write to a logger instance.
1302	*
1303	* This function will check whether the instance, group and flags makes up a
1304	* logging kind which is currently enabled before writing anything to the log.
1305	*
1306	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1307	* @param fFlags The logging flags.
1308	* @param iGroup The group.
1309	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
1310	* only for internal usage!
1311	* @param pszFormat Format string.
1312	* @param ... Format arguments.
1313	* @remark This is a worker function of LogIt.
1314	*/
1315	RTDECL(void) RTLogLoggerEx(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, ...);
1316
1317	/**
1318	* Write to a logger instance.
1319	*
1320	* This function will check whether the instance, group and flags makes up a
1321	* logging kind which is currently enabled before writing anything to the log.
1322	*
1323	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
1324	* @param fFlags The logging flags.
1325	* @param iGroup The group.
1326	* The value ~0U is reserved for compatability with RTLogLogger[V] and is
1327	* only for internal usage!
1328	* @param pszFormat Format string.
1329	* @param args Format arguments.
1330	*/
1331	RTDECL(void) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args);
1332
1333	/**
1334	* printf like function for writing to the default log.
1335	*
1336	* @param pszFormat Printf like format string.
1337	* @param ... Optional arguments as specified in pszFormat.
1338	*
1339	* @remark The API doesn't support formatting of floating point numbers at the moment.
1340	*/
1341	RTDECL(void) RTLogPrintf(const char *pszFormat, ...);
1342
1343	/**
1344	* vprintf like function for writing to the default log.
1345	*
1346	* @param pszFormat Printf like format string.
1347	* @param args Optional arguments as specified in pszFormat.
1348	*
1349	* @remark The API doesn't support formatting of floating point numbers at the moment.
1350	*/
1351	RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list args);
1352
1353
1354	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h */
1355	#define DECLARED_FNRTSTROUTPUT
1356	/**
1357	* Output callback.
1358	*
1359	* @returns number of bytes written.
1360	* @param pvArg User argument.
1361	* @param pachChars Pointer to an array of utf-8 characters.
1362	* @param cbChars Number of bytes in the character array pointed to by pachChars.
1363	*/
1364	typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void pvArg, const char pachChars, size_t cbChars);
1365	/** Pointer to callback function. */
1366	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
1367	#endif
1368
1369	/**
1370	* Partial vsprintf worker implementation.
1371	*
1372	* @returns number of bytes formatted.
1373	* @param pfnOutput Output worker.
1374	* Called in two ways. Normally with a string an it's length.
1375	* For termination, it's called with NULL for string, 0 for length.
1376	* @param pvArg Argument to output worker.
1377	* @param pszFormat Format string.
1378	* @param args Argument list.
1379	*/
1380	RTDECL(size_t) RTLogFormatV(PFNRTSTROUTPUT pfnOutput, void pvArg, const char pszFormat, va_list args);
1381
1382	/**
1383	* Write log buffer to COM port.
1384	*
1385	* @param pach Pointer to the buffer to write.
1386	* @param cb Number of bytes to write.
1387	*/
1388	RTDECL(void) RTLogWriteCom(const char *pach, size_t cb);
1389
1390	/**
1391	* Prints a formatted string to the serial port used for logging.
1392	*
1393	* @returns Number of bytes written.
1394	* @param pszFormat Format string.
1395	* @param ... Optional arguments specified in the format string.
1396	*/
1397	RTDECL(size_t) RTLogComPrintf(const char *pszFormat, ...);
1398
1399	/**
1400	* Prints a formatted string to the serial port used for logging.
1401	*
1402	* @returns Number of bytes written.
1403	* @param pszFormat Format string.
1404	* @param args Optional arguments specified in the format string.
1405	*/
1406	RTDECL(size_t) RTLogComPrintfV(const char *pszFormat, va_list args);
1407
1408
1409	#if 0 /* not implemented yet */
1410
1411	/** Indicates that the semaphores shall be used to notify the other
1412	* part about buffer changes. */
1413	#define LOGHOOKBUFFER_FLAGS_SEMAPHORED 1
1414
1415	/**
1416	* Log Hook Buffer.
1417	* Use to commuicate between the logger and a log consumer.
1418	*/
1419	typedef struct RTLOGHOOKBUFFER
1420	{
1421	/** Write pointer. */
1422	volatile void *pvWrite;
1423	/** Read pointer. */
1424	volatile void *pvRead;
1425	/** Buffer start. */
1426	void *pvStart;
1427	/** Buffer end (exclusive). */
1428	void *pvEnd;
1429	/** Signaling semaphore used by the writer to wait on a full buffer.
1430	* Only used when indicated in flags. */
1431	void *pvSemWriter;
1432	/** Signaling semaphore used by the read to wait on an empty buffer.
1433	* Only used when indicated in flags. */
1434	void *pvSemReader;
1435	/** Buffer flags. Current reserved and set to zero. */
1436	volatile unsigned fFlags;
1437	} RTLOGHOOKBUFFER;
1438	/** Pointer to a log hook buffer. */
1439	typedef RTLOGHOOKBUFFER *PRTLOGHOOKBUFFER;
1440
1441
1442	/**
1443	* Register a logging hook.
1444	*
1445	* This type of logging hooks are expecting different threads acting
1446	* producer and consumer. They share a circular buffer which have two
1447	* pointers one for each end. When the buffer is full there are two
1448	* alternatives (indicated by a buffer flag), either wait for the
1449	* consumer to get it's job done, or to write a generic message saying
1450	* buffer overflow.
1451	*
1452	* Since the waiting would need a signal semaphore, we'll skip that for now.
1453	*
1454	* @returns iprt status code.
1455	* @param pBuffer Pointer to a logger hook buffer.
1456	*/
1457	RTDECL(int) RTLogRegisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
1458
1459	/**
1460	* Deregister a logging hook registerd with RTLogRegisterHook().
1461	*
1462	* @returns iprt status code.
1463	* @param pBuffer Pointer to a logger hook buffer.
1464	*/
1465	RTDECL(int) RTLogDeregisterHook(PRTLOGGER pLogger, PRTLOGHOOKBUFFER pBuffer);
1466
1467	#endif /* not implemented yet */
1468
1469
1470
1471	/**
1472	* Write log buffer to a debugger (RTLOGDEST_DEBUGGER).
1473	*
1474	* @param pach What to write.
1475	* @param cb How much to write.
1476	* @remark When linking statically, this function can be replaced by defining your own.
1477	*/
1478	RTDECL(void) RTLogWriteDebugger(const char *pach, size_t cb);
1479
1480	/**
1481	* Write log buffer to a user defined output stream (RTLOGDEST_USER).
1482	*
1483	* @param pach What to write.
1484	* @param cb How much to write.
1485	* @remark When linking statically, this function can be replaced by defining your own.
1486	*/
1487	RTDECL(void) RTLogWriteUser(const char *pach, size_t cb);
1488
1489	/**
1490	* Write log buffer to stdout (RTLOGDEST_STDOUT).
1491	*
1492	* @param pach What to write.
1493	* @param cb How much to write.
1494	* @remark When linking statically, this function can be replaced by defining your own.
1495	*/
1496	RTDECL(void) RTLogWriteStdOut(const char *pach, size_t cb);
1497
1498	/**
1499	* Write log buffer to stdout (RTLOGDEST_STDERR).
1500	*
1501	* @param pach What to write.
1502	* @param cb How much to write.
1503	* @remark When linking statically, this function can be replaced by defining your own.
1504	*/
1505	RTDECL(void) RTLogWriteStdErr(const char *pach, size_t cb);
1506
1507	#ifdef VBOX
1508
1509	/**
1510	* Prints a formatted string to the backdoor port.
1511	*
1512	* @returns Number of bytes written.
1513	* @param pszFormat Format string.
1514	* @param ... Optional arguments specified in the format string.
1515	*/
1516	RTDECL(size_t) RTLogBackdoorPrintf(const char *pszFormat, ...);
1517
1518	/**
1519	* Prints a formatted string to the backdoor port.
1520	*
1521	* @returns Number of bytes written.
1522	* @param pszFormat Format string.
1523	* @param args Optional arguments specified in the format string.
1524	*/
1525	RTDECL(size_t) RTLogBackdoorPrintfV(const char *pszFormat, va_list args);
1526
1527	#endif /* VBOX */
1528
1529	__END_DECLS
1530
1531	/** @} */
1532
1533	#endif
1534

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

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

Download in other formats: