log.h@ 36344

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

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

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

Download in other formats: