log.h@ 8627

Last change on this file since 8627 was 8627, checked in by vboxsync, 17 years ago
Fixed build break.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 52.3 KB

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

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

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

Download in other formats: