log.h@ 3086

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

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

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

Download in other formats: