log.h@ 36638

Last change on this file since 36638 was 36408, checked in by vboxsync, 14 years ago
log rotation review and adjustments: Don't delete any excess files if log roation is disabled - we don't know what these files might be. Moved RTLOGGERFILE into log.c. Keep RTLogCreate simple, anyone needing rotation can use RTLogCreateEx[V]. Made RTLogGetDestinations produce the log rotation bits.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 64.6 KB

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

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

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

Download in other formats: