log.h@ 90864

Last change on this file since 90864 was 90862, checked in by vboxsync, 3 years ago
IPRT,SUPDrv,VMM,++: Bumped major support driver version. Added RTLogSetR0ProgramStart and make the VMM use it when configuring the ring-0 loggers. Removed pfnFlush from the parameter list of RTLogCreateEx[V]. bugref:10086
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 88.6 KB

Line
1	/** @file
2	* IPRT - Logging.
3	*/
4
5	/*
6	* Copyright (C) 2006-2020 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_INCLUDED_log_h
27	#define IPRT_INCLUDED_log_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/cdefs.h>
33	#include <iprt/types.h>
34	#include <iprt/stdarg.h>
35
36	RT_C_DECLS_BEGIN
37
38	/** @defgroup grp_rt_log RTLog - Logging
39	* @ingroup grp_rt
40	* @{
41	*/
42
43	/**
44	* IPRT Logging Groups.
45	* (Remember to update RT_LOGGROUP_NAMES!)
46	*
47	* @remark It should be pretty obvious, but just to have
48	* mentioned it, the values are sorted alphabetically (using the
49	* english alphabet) except for _DEFAULT which is always first.
50	*
51	* If anyone might be wondering what the alphabet looks like:
52	* 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
53	*/
54	typedef enum RTLOGGROUP
55	{
56	/** Default logging group. */
57	RTLOGGROUP_DEFAULT,
58	RTLOGGROUP_CRYPTO,
59	RTLOGGROUP_DBG,
60	RTLOGGROUP_DBG_DWARF,
61	RTLOGGROUP_DIR,
62	RTLOGGROUP_FILE,
63	RTLOGGROUP_FS,
64	RTLOGGROUP_FTP,
65	RTLOGGROUP_HTTP,
66	RTLOGGROUP_IOQUEUE,
67	RTLOGGROUP_LDR,
68	RTLOGGROUP_LOCALIPC,
69	RTLOGGROUP_PATH,
70	RTLOGGROUP_PROCESS,
71	RTLOGGROUP_REST,
72	RTLOGGROUP_SYMLINK,
73	RTLOGGROUP_THREAD,
74	RTLOGGROUP_TIME,
75	RTLOGGROUP_TIMER,
76	RTLOGGROUP_VFS,
77	RTLOGGROUP_ZIP = 31,
78	RTLOGGROUP_FIRST_USER = 32
79	} RTLOGGROUP;
80
81	/** @def RT_LOGGROUP_NAMES
82	* IPRT Logging group names.
83	*
84	* Must correspond 100% to RTLOGGROUP!
85	* Don't forget commas!
86	*
87	* @remark It should be pretty obvious, but just to have
88	* mentioned it, the values are sorted alphabetically (using the
89	* english alphabet) except for _DEFAULT which is always first.
90	*
91	* If anyone might be wondering what the alphabet looks like:
92	* 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
93	*
94	* The RT_XX log group names are placeholders for new modules being added,
95	* to make sure that there always is a total of 32 log group entries.
96	*/
97	#define RT_LOGGROUP_NAMES \
98	"DEFAULT", \
99	"RT_CRYPTO", \
100	"RT_DBG", \
101	"RT_DBG_DWARF", \
102	"RT_DIR", \
103	"RT_FILE", \
104	"RT_FS", \
105	"RT_FTP", \
106	"RT_HTTP", \
107	"RT_IOQUEUE", \
108	"RT_LDR", \
109	"RT_LOCALIPC", \
110	"RT_PATH", \
111	"RT_PROCESS", \
112	"RT_REST", \
113	"RT_SYMLINK", \
114	"RT_THREAD", \
115	"RT_TIME", \
116	"RT_TIMER", \
117	"RT_VFS", \
118	"RT_20", \
119	"RT_21", \
120	"RT_22", \
121	"RT_23", \
122	"RT_24", \
123	"RT_25", \
124	"RT_26", \
125	"RT_27", \
126	"RT_28", \
127	"RT_29", \
128	"RT_30", \
129	"RT_ZIP"
130
131
132	/** @def LOG_GROUP
133	* Active logging group.
134	*/
135	#ifndef LOG_GROUP
136	# define LOG_GROUP RTLOGGROUP_DEFAULT
137	#endif
138
139	/** @def LOG_FN_FMT
140	* You can use this to specify your desired way of printing __PRETTY_FUNCTION__
141	* if you dislike the default one.
142	*/
143	#ifndef LOG_FN_FMT
144	# define LOG_FN_FMT "%Rfn"
145	#endif
146
147	#ifdef LOG_INSTANCE
148	# error "LOG_INSTANCE is no longer supported."
149	#endif
150	#ifdef LOG_REL_INSTANCE
151	# error "LOG_REL_INSTANCE is no longer supported."
152	#endif
153
154	/** Logger structure. */
155	typedef struct RTLOGGER RTLOGGER;
156	/** Pointer to logger structure. */
157	typedef RTLOGGER *PRTLOGGER;
158	/** Pointer to const logger structure. */
159	typedef const RTLOGGER *PCRTLOGGER;
160
161
162	/** Pointer to a log buffer descriptor. */
163	typedef struct RTLOGBUFFERDESC *PRTLOGBUFFERDESC;
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 DECLCALLBACKTYPE(void, FNRTLOGGER,(const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(1, 2);
193	/** Pointer to logger function. */
194	typedef FNRTLOGGER *PFNRTLOGGER;
195
196	/**
197	* Custom buffer flushing function.
198	*
199	* @retval true if flushed.
200	* @retval false if flushing pending on other thread and the logger should
201	* switch to the next buffer. The other thread will call
202	* RTLogFlushDone when finished.
203	* @param pLogger Pointer to the logger instance which is to be flushed.
204	* @param pBufDesc The descriptor of the buffer to be flushed.
205	*/
206	typedef DECLCALLBACKTYPE(bool, FNRTLOGFLUSH,(PRTLOGGER pLogger, PRTLOGBUFFERDESC pBufDesc));
207	/** Pointer to flush function. */
208	typedef FNRTLOGFLUSH *PFNRTLOGFLUSH;
209
210	/**
211	* Header/footer message callback.
212	*
213	* @param pLogger Pointer to the logger instance.
214	* @param pszFormat Format string.
215	* @param ... Optional arguments specified in the format string.
216	*/
217	typedef DECLCALLBACKTYPE(void, FNRTLOGPHASEMSG,(PRTLOGGER pLogger, const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(2, 3);
218	/** Pointer to header/footer message callback function. */
219	typedef FNRTLOGPHASEMSG *PFNRTLOGPHASEMSG;
220
221	/**
222	* Log file header/footer callback.
223	*
224	* @param pLogger Pointer to the logger instance.
225	* @param enmLogPhase Indicates at what time the callback is invoked.
226	* @param pfnLogPhaseMsg Callback for writing the header/footer (RTLogPrintf
227	* and others are out of bounds).
228	*/
229	typedef DECLCALLBACKTYPE(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 DECLCALLBACKTYPE(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	* Auxiliary buffer descriptor.
253	*
254	* This is what we share we ring-3 and use for flushing ring-0 EMT loggers when
255	* we return to ring-3.
256	*/
257	typedef struct RTLOGBUFFERAUXDESC
258	{
259	/** Flush indicator.
260	* Ring-3 sets this if it flushed the buffer, ring-0 clears it again after
261	* writing. */
262	bool volatile fFlushedIndicator;
263	bool afPadding[3];
264	/** Copy of RTLOGBUFFERDESC::offBuf. */
265	uint32_t offBuf;
266	} RTLOGBUFFERAUXDESC;
267	/** Pointer to auxiliary buffer descriptor. */
268	typedef RTLOGBUFFERAUXDESC *PRTLOGBUFFERAUXDESC;
269
270	/**
271	* Log buffer desciptor.
272	*/
273	typedef struct RTLOGBUFFERDESC
274	{
275	/** Magic value / eye catcher (RTLOGBUFFERDESC_MAGIC). */
276	uint32_t u32Magic;
277	/** Padding. */
278	uint32_t uReserved;
279	/** The buffer size. */
280	uint32_t cbBuf;
281	/** The current buffer offset. */
282	uint32_t offBuf;
283	/** Pointer to the buffer. */
284	char *pchBuf;
285	/** Pointer to auxiliary desciptor, NULL if not used. */
286	PRTLOGBUFFERAUXDESC pAux;
287	} RTLOGBUFFERDESC;
288
289	/** RTLOGBUFFERDESC::u32Magic value. (Avram Noam Chomsky) */
290	# define RTLOGBUFFERDESC_MAGIC UINT32_C(0x19281207)
291
292	/**
293	* The public logger instance part.
294	*
295	* The logger instance is mostly abstract and kept as RTLOGGERINTERNAL within
296	* log.cpp. This public part is at the start of RTLOGGERINTERNAL.
297	*/
298	struct RTLOGGER
299	{
300	/** Magic number (RTLOGGER_MAGIC). */
301	uint32_t u32Magic;
302	/** User value \#1, initialized to zero. */
303	uint32_t u32UserValue1;
304	/** User value \#2, initialized to zero. */
305	uint64_t u64UserValue2;
306	/** User value \#3, initialized to zero. */
307	uint64_t u64UserValue3;
308	/** Pointer to the logger function (used in non-C99 mode only).
309	*
310	* This is actually pointer to a wrapper/stub function which will push a pointer
311	* to the instance pointer onto the stack before jumping to the real logger
312	* function. A very unfortunate hack to work around the missing variadic macro
313	* support in older C++/C standards. (The memory is allocated using
314	* RTMemExecAlloc(), except for agnostic R0 code.) */
315	PFNRTLOGGER pfnLogger;
316	#if ARCH_BITS == 32
317	/** Explicit padding. */
318	uint32_t uReserved1;
319	#endif
320	};
321
322	/** RTLOGGER::u32Magic value. (John Rogers Searle) */
323	#define RTLOGGER_MAGIC UINT32_C(0x19320731)
324
325	/**
326	* Logger flags.
327	*/
328	typedef enum RTLOGFLAGS
329	{
330	/** The logger instance is disabled for normal output. */
331	RTLOGFLAGS_DISABLED = 0x00000001,
332	/** The logger instance is using buffered output. */
333	RTLOGFLAGS_BUFFERED = 0x00000002,
334	/** The logger instance expands LF to CR/LF. */
335	RTLOGFLAGS_USECRLF = 0x00000010,
336	/** Append to the log destination where applicable. */
337	RTLOGFLAGS_APPEND = 0x00000020,
338	/** Show relative timestamps with PREFIX_TSC and PREFIX_TS */
339	RTLOGFLAGS_REL_TS = 0x00000040,
340	/** Show decimal timestamps with PREFIX_TSC and PREFIX_TS */
341	RTLOGFLAGS_DECIMAL_TS = 0x00000080,
342	/** Open the file in write through mode. */
343	RTLOGFLAGS_WRITE_THROUGH = 0x00000100,
344	/** Flush the file to disk when flushing the buffer. */
345	RTLOGFLAGS_FLUSH = 0x00000200,
346	/** Restrict the number of log entries per group. */
347	RTLOGFLAGS_RESTRICT_GROUPS = 0x00000400,
348	/** New lines should be prefixed with the write and read lock counts. */
349	RTLOGFLAGS_PREFIX_LOCK_COUNTS = 0x00008000,
350	/** New lines should be prefixed with the CPU id (ApicID on intel/amd). */
351	RTLOGFLAGS_PREFIX_CPUID = 0x00010000,
352	/** New lines should be prefixed with the native process id. */
353	RTLOGFLAGS_PREFIX_PID = 0x00020000,
354	/** New lines should be prefixed with group flag number causing the output. */
355	RTLOGFLAGS_PREFIX_FLAG_NO = 0x00040000,
356	/** New lines should be prefixed with group flag name causing the output. */
357	RTLOGFLAGS_PREFIX_FLAG = 0x00080000,
358	/** New lines should be prefixed with group number. */
359	RTLOGFLAGS_PREFIX_GROUP_NO = 0x00100000,
360	/** New lines should be prefixed with group name. */
361	RTLOGFLAGS_PREFIX_GROUP = 0x00200000,
362	/** New lines should be prefixed with the native thread id. */
363	RTLOGFLAGS_PREFIX_TID = 0x00400000,
364	/** New lines should be prefixed with thread name. */
365	RTLOGFLAGS_PREFIX_THREAD = 0x00800000,
366	/** New lines should be prefixed with data from a custom callback. */
367	RTLOGFLAGS_PREFIX_CUSTOM = 0x01000000,
368	/** New lines should be prefixed with formatted timestamp since program start. */
369	RTLOGFLAGS_PREFIX_TIME_PROG = 0x04000000,
370	/** New lines should be prefixed with formatted timestamp (UCT). */
371	RTLOGFLAGS_PREFIX_TIME = 0x08000000,
372	/** New lines should be prefixed with milliseconds since program start. */
373	RTLOGFLAGS_PREFIX_MS_PROG = 0x10000000,
374	/** New lines should be prefixed with timestamp. */
375	RTLOGFLAGS_PREFIX_TSC = 0x20000000,
376	/** New lines should be prefixed with timestamp. */
377	RTLOGFLAGS_PREFIX_TS = 0x40000000,
378	/** The prefix mask. */
379	RTLOGFLAGS_PREFIX_MASK = 0x7dff8000
380	} RTLOGFLAGS;
381	/** Don't use locking. */
382	#define RTLOG_F_NO_LOCKING RT_BIT_64(63)
383	/** Mask with all valid log flags (for validation). */
384	#define RTLOG_F_VALID_MASK UINT64_C(0x800000007fff87f3)
385
386	/**
387	* Logger per group flags.
388	*
389	* @remarks We only use the lower 16 bits here. We'll be combining it with the
390	* group number in a few places.
391	*/
392	typedef enum RTLOGGRPFLAGS
393	{
394	/** Enabled. */
395	RTLOGGRPFLAGS_ENABLED = 0x0001,
396	/** Flow logging. */
397	RTLOGGRPFLAGS_FLOW = 0x0002,
398	/** Warnings logging. */
399	RTLOGGRPFLAGS_WARN = 0x0004,
400	/* 0x0008 for later. */
401	/** Level 1 logging. */
402	RTLOGGRPFLAGS_LEVEL_1 = 0x0010,
403	/** Level 2 logging. */
404	RTLOGGRPFLAGS_LEVEL_2 = 0x0020,
405	/** Level 3 logging. */
406	RTLOGGRPFLAGS_LEVEL_3 = 0x0040,
407	/** Level 4 logging. */
408	RTLOGGRPFLAGS_LEVEL_4 = 0x0080,
409	/** Level 5 logging. */
410	RTLOGGRPFLAGS_LEVEL_5 = 0x0100,
411	/** Level 6 logging. */
412	RTLOGGRPFLAGS_LEVEL_6 = 0x0200,
413	/** Level 7 logging. */
414	RTLOGGRPFLAGS_LEVEL_7 = 0x0400,
415	/** Level 8 logging. */
416	RTLOGGRPFLAGS_LEVEL_8 = 0x0800,
417	/** Level 9 logging. */
418	RTLOGGRPFLAGS_LEVEL_9 = 0x1000,
419	/** Level 10 logging. */
420	RTLOGGRPFLAGS_LEVEL_10 = 0x2000,
421	/** Level 11 logging. */
422	RTLOGGRPFLAGS_LEVEL_11 = 0x4000,
423	/** Level 12 logging. */
424	RTLOGGRPFLAGS_LEVEL_12 = 0x8000,
425
426	/** Restrict the number of log entries. */
427	RTLOGGRPFLAGS_RESTRICT = 0x40000000,
428	/** Blow up the type. */
429	RTLOGGRPFLAGS_32BIT_HACK = 0x7fffffff
430	} RTLOGGRPFLAGS;
431
432	/**
433	* Logger destination types and flags.
434	*/
435	typedef enum RTLOGDEST
436	{
437	/** Log to file. */
438	RTLOGDEST_FILE = 0x00000001,
439	/** Log to stdout. */
440	RTLOGDEST_STDOUT = 0x00000002,
441	/** Log to stderr. */
442	RTLOGDEST_STDERR = 0x00000004,
443	/** Log to debugger (win32 only). */
444	RTLOGDEST_DEBUGGER = 0x00000008,
445	/** Log to com port. */
446	RTLOGDEST_COM = 0x00000010,
447	/** Log a memory ring buffer. */
448	RTLOGDEST_RINGBUF = 0x00000020,
449	/** Open files with no deny (share read, write, delete) on Windows. */
450	RTLOGDEST_F_NO_DENY = 0x00010000,
451	/** Delay opening the log file, logging to the buffer untill
452	* RTLogClearFileDelayFlag is called. */
453	RTLOGDEST_F_DELAY_FILE = 0x00020000,
454	/** Don't allow changes to the filename or mode of opening it. */
455	RTLOGDEST_FIXED_FILE = 0x01000000,
456	/** Don't allow changing the directory. */
457	RTLOGDEST_FIXED_DIR = 0x02000000,
458	/** Just a dummy flag to be used when no other flag applies. */
459	RTLOGDEST_DUMMY = 0x20000000,
460	/** Log to a user defined output stream. */
461	RTLOGDEST_USER = 0x40000000
462	} RTLOGDEST;
463	/** Valid log destinations. */
464	#define RTLOG_DST_VALID_MASK UINT32_C(0x6303003f)
465	/** Log destinations that can be changed via RTLogChangeDestinations. */
466	#define RTLOG_DST_CHANGE_MASK UINT32_C(0x4000001e)
467
468
469	#ifdef DOXYGEN_RUNNING
470	# define LOG_DISABLED
471	# define LOG_ENABLED
472	# define LOG_ENABLE_FLOW
473	#endif
474
475	/** @def LOG_DISABLED
476	* Use this compile time define to disable all logging macros. It can
477	* be overridden for each of the logging macros by the LOG_ENABLE*
478	* compile time defines.
479	*/
480
481	/** @def LOG_ENABLED
482	* Use this compile time define to enable logging when not in debug mode
483	* or LOG_DISABLED is set.
484	* This will enable Log() only.
485	*/
486
487	/** @def LOG_ENABLE_FLOW
488	* Use this compile time define to enable flow logging when not in
489	* debug mode or LOG_DISABLED is defined.
490	* This will enable LogFlow() only.
491	*/
492
493	/*
494	* Determine whether logging is enabled and forcefully normalize the indicators.
495	*/
496	#if (defined(DEBUG) \|\| defined(LOG_ENABLED)) && !defined(LOG_DISABLED)
497	# undef LOG_DISABLED
498	# undef LOG_ENABLED
499	# define LOG_ENABLED
500	#else
501	# undef LOG_ENABLED
502	# undef LOG_DISABLED
503	# define LOG_DISABLED
504	#endif
505
506
507	/** @def LOG_USE_C99
508	* Governs the use of variadic macros.
509	*/
510	#ifndef LOG_USE_C99
511	# if defined(RT_ARCH_AMD64) \|\| defined(RT_OS_DARWIN) \|\| defined(RT_ARCH_SPARC) \|\| defined(RT_ARCH_SPARC64)
512	# define LOG_USE_C99
513	# endif
514	#endif
515
516
517	/** @name Macros for checking whether a log level is enabled.
518	* @{ */
519	/** @def LogIsItEnabled
520	* Checks whether the specified logging group is enabled or not.
521	*/
522	#ifdef LOG_ENABLED
523	# define LogIsItEnabled(a_fFlags, a_iGroup) ( RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)) != NULL )
524	#else
525	# define LogIsItEnabled(a_fFlags, a_iGroup) (false)
526	#endif
527
528	/** @def LogIsEnabled
529	* Checks whether level 1 logging is enabled.
530	*/
531	#define LogIsEnabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
532
533	/** @def LogIs2Enabled
534	* Checks whether level 2 logging is enabled.
535	*/
536	#define LogIs2Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
537
538	/** @def LogIs3Enabled
539	* Checks whether level 3 logging is enabled.
540	*/
541	#define LogIs3Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
542
543	/** @def LogIs4Enabled
544	* Checks whether level 4 logging is enabled.
545	*/
546	#define LogIs4Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
547
548	/** @def LogIs5Enabled
549	* Checks whether level 5 logging is enabled.
550	*/
551	#define LogIs5Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
552
553	/** @def LogIs6Enabled
554	* Checks whether level 6 logging is enabled.
555	*/
556	#define LogIs6Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
557
558	/** @def LogIs7Enabled
559	* Checks whether level 7 logging is enabled.
560	*/
561	#define LogIs7Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP)
562
563	/** @def LogIs8Enabled
564	* Checks whether level 8 logging is enabled.
565	*/
566	#define LogIs8Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP)
567
568	/** @def LogIs9Enabled
569	* Checks whether level 9 logging is enabled.
570	*/
571	#define LogIs9Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP)
572
573	/** @def LogIs10Enabled
574	* Checks whether level 10 logging is enabled.
575	*/
576	#define LogIs10Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP)
577
578	/** @def LogIs11Enabled
579	* Checks whether level 11 logging is enabled.
580	*/
581	#define LogIs11Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP)
582
583	/** @def LogIs12Enabled
584	* Checks whether level 12 logging is enabled.
585	*/
586	#define LogIs12Enabled() LogIsItEnabled(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP)
587
588	/** @def LogIsFlowEnabled
589	* Checks whether execution flow logging is enabled.
590	*/
591	#define LogIsFlowEnabled() LogIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
592
593	/** @def LogIsWarnEnabled
594	* Checks whether execution flow logging is enabled.
595	*/
596	#define LogIsWarnEnabled() LogIsItEnabled(RTLOGGRPFLAGS_WARN, LOG_GROUP)
597	/** @} */
598
599
600	/** @def LogIt
601	* Write to specific logger if group enabled.
602	*/
603	#ifdef LOG_ENABLED
604	# if defined(LOG_USE_C99)
605	# define _LogRemoveParentheseis(...) __VA_ARGS__
606	# define _LogIt(a_fFlags, a_iGroup, ...) \
607	do \
608	{ \
609	PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
610	if (RT_LIKELY(!LogIt_pLogger)) \
611	{ /* likely */ } \
612	else \
613	RTLogLoggerEx(LogIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
614	} while (0)
615	# define LogIt(a_fFlags, a_iGroup, fmtargs) _LogIt(a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
616	# define _LogItAlways(a_fFlags, a_iGroup, ...) RTLogLoggerEx(NULL, a_fFlags, UINT32_MAX, __VA_ARGS__)
617	# define LogItAlways(a_fFlags, a_iGroup, fmtargs) _LogItAlways(a_fFlags, a_iGroup, _LogRemoveParentheseis fmtargs)
618	/** @todo invent a flag or something for skipping the group check so we can pass iGroup. LogItAlways. */
619	# else
620	# define LogIt(a_fFlags, a_iGroup, fmtargs) \
621	do \
622	{ \
623	PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
624	if (RT_LIKELY(!LogIt_pLogger)) \
625	{ /* likely */ } \
626	else \
627	{ \
628	LogIt_pLogger->pfnLogger fmtargs; \
629	} \
630	} while (0)
631	# define LogItAlways(a_fFlags, a_iGroup, fmtargs) \
632	do \
633	{ \
634	PRTLOGGER LogIt_pLogger = RTLogDefaultInstanceEx(RT_MAKE_U32(0, UINT16_MAX)); \
635	if (LogIt_pLogger) \
636	LogIt_pLogger->pfnLogger fmtargs; \
637	} while (0)
638	# endif
639	#else
640	# define LogIt(a_fFlags, a_iGroup, fmtargs) do { } while (0)
641	# define LogItAlways(a_fFlags, a_iGroup, fmtargs) do { } while (0)
642	# if defined(LOG_USE_C99)
643	# define _LogRemoveParentheseis(...) __VA_ARGS__
644	# define _LogIt(a_fFlags, a_iGroup, ...) do { } while (0)
645	# define _LogItAlways(a_fFlags, a_iGroup, ...) do { } while (0)
646	# endif
647	#endif
648
649
650	/** @name Basic logging macros
651	* @{ */
652	/** @def Log
653	* Level 1 logging that works regardless of the group settings.
654	*/
655	#define LogAlways(a) LogItAlways(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
656
657	/** @def Log
658	* Level 1 logging.
659	*/
660	#define Log(a) LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
661
662	/** @def Log2
663	* Level 2 logging.
664	*/
665	#define Log2(a) LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
666
667	/** @def Log3
668	* Level 3 logging.
669	*/
670	#define Log3(a) LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
671
672	/** @def Log4
673	* Level 4 logging.
674	*/
675	#define Log4(a) LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
676
677	/** @def Log5
678	* Level 5 logging.
679	*/
680	#define Log5(a) LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
681
682	/** @def Log6
683	* Level 6 logging.
684	*/
685	#define Log6(a) LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
686
687	/** @def Log7
688	* Level 7 logging.
689	*/
690	#define Log7(a) LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
691
692	/** @def Log8
693	* Level 8 logging.
694	*/
695	#define Log8(a) LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
696
697	/** @def Log9
698	* Level 9 logging.
699	*/
700	#define Log9(a) LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
701
702	/** @def Log10
703	* Level 10 logging.
704	*/
705	#define Log10(a) LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
706
707	/** @def Log11
708	* Level 11 logging.
709	*/
710	#define Log11(a) LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
711
712	/** @def Log12
713	* Level 12 logging.
714	*/
715	#define Log12(a) LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
716
717	/** @def LogFlow
718	* Logging of execution flow.
719	*/
720	#define LogFlow(a) LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
721
722	/** @def LogWarn
723	* Logging of warnings.
724	*/
725	#define LogWarn(a) LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, a)
726	/** @} */
727
728
729	/** @name Logging macros prefixing the current function name.
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) _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
741	#else
742	# define LogFunc(a) do { Log((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log(a); } while (0)
743	#endif
744
745	/** @def Log2Func
746	* Level 2 logging inside C/C++ functions.
747	*
748	* Prepends the given log message with the function name followed by a
749	* semicolon and space.
750	*
751	* @param a Log message in format <tt>("string\n" [, args])</tt>.
752	*/
753	#ifdef LOG_USE_C99
754	# define Log2Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
755	#else
756	# define Log2Func(a) do { Log2((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log2(a); } while (0)
757	#endif
758
759	/** @def Log3Func
760	* Level 3 logging inside C/C++ functions.
761	*
762	* Prepends the given log message with the function name followed by a
763	* semicolon and space.
764	*
765	* @param a Log message in format <tt>("string\n" [, args])</tt>.
766	*/
767	#ifdef LOG_USE_C99
768	# define Log3Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
769	#else
770	# define Log3Func(a) do { Log3((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log3(a); } while (0)
771	#endif
772
773	/** @def Log4Func
774	* Level 4 logging inside C/C++ functions.
775	*
776	* Prepends the given log message with the function name followed by a
777	* semicolon and space.
778	*
779	* @param a Log message in format <tt>("string\n" [, args])</tt>.
780	*/
781	#ifdef LOG_USE_C99
782	# define Log4Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
783	#else
784	# define Log4Func(a) do { Log4((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log4(a); } while (0)
785	#endif
786
787	/** @def Log5Func
788	* Level 5 logging inside C/C++ functions.
789	*
790	* Prepends the given log message with the function name followed by a
791	* semicolon and space.
792	*
793	* @param a Log message in format <tt>("string\n" [, args])</tt>.
794	*/
795	#ifdef LOG_USE_C99
796	# define Log5Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
797	#else
798	# define Log5Func(a) do { Log5((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log5(a); } while (0)
799	#endif
800
801	/** @def Log6Func
802	* Level 6 logging inside C/C++ functions.
803	*
804	* Prepends the given log message with the function name followed by a
805	* semicolon and space.
806	*
807	* @param a Log message in format <tt>("string\n" [, args])</tt>.
808	*/
809	#ifdef LOG_USE_C99
810	# define Log6Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
811	#else
812	# define Log6Func(a) do { Log6((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log6(a); } while (0)
813	#endif
814
815	/** @def Log7Func
816	* Level 7 logging inside C/C++ functions.
817	*
818	* Prepends the given log message with the function name followed by a
819	* semicolon and space.
820	*
821	* @param a Log message in format <tt>("string\n" [, args])</tt>.
822	*/
823	#ifdef LOG_USE_C99
824	# define Log7Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
825	#else
826	# define Log7Func(a) do { Log7((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log7(a); } while (0)
827	#endif
828
829	/** @def Log8Func
830	* Level 8 logging inside C/C++ functions.
831	*
832	* Prepends the given log message with the function name followed by a
833	* semicolon and space.
834	*
835	* @param a Log message in format <tt>("string\n" [, args])</tt>.
836	*/
837	#ifdef LOG_USE_C99
838	# define Log8Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
839	#else
840	# define Log8Func(a) do { Log8((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log8(a); } while (0)
841	#endif
842
843	/** @def Log9Func
844	* Level 9 logging inside C/C++ functions.
845	*
846	* Prepends the given log message with the function name followed by a
847	* semicolon and space.
848	*
849	* @param a Log message in format <tt>("string\n" [, args])</tt>.
850	*/
851	#ifdef LOG_USE_C99
852	# define Log9Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
853	#else
854	# define Log9Func(a) do { Log9((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log9(a); } while (0)
855	#endif
856
857	/** @def Log10Func
858	* Level 10 logging inside C/C++ functions.
859	*
860	* Prepends the given log message with the function name followed by a
861	* semicolon and space.
862	*
863	* @param a Log message in format <tt>("string\n" [, args])</tt>.
864	*/
865	#ifdef LOG_USE_C99
866	# define Log10Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
867	#else
868	# define Log10Func(a) do { Log10((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log10(a); } while (0)
869	#endif
870
871	/** @def Log11Func
872	* Level 11 logging inside C/C++ functions.
873	*
874	* Prepends the given log message with the function name followed by a
875	* semicolon and space.
876	*
877	* @param a Log message in format <tt>("string\n" [, args])</tt>.
878	*/
879	#ifdef LOG_USE_C99
880	# define Log11Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
881	#else
882	# define Log11Func(a) do { Log11((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log11(a); } while (0)
883	#endif
884
885	/** @def Log12Func
886	* Level 12 logging inside C/C++ functions.
887	*
888	* Prepends the given log message with the function name followed by a
889	* semicolon and space.
890	*
891	* @param a Log message in format <tt>("string\n" [, args])</tt>.
892	*/
893	#ifdef LOG_USE_C99
894	# define Log12Func(a) _LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
895	#else
896	# define Log12Func(a) do { Log12((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log12(a); } while (0)
897	#endif
898
899	/** @def LogFlowFunc
900	* Macro to log the execution flow inside C/C++ functions.
901	*
902	* Prepends the given log message with the function name followed by
903	* a semicolon and space.
904	*
905	* @param a Log message in format <tt>("string\n" [, args])</tt>.
906	*/
907	#ifdef LOG_USE_C99
908	# define LogFlowFunc(a) \
909	_LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
910	#else
911	# define LogFlowFunc(a) \
912	do { LogFlow((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
913	#endif
914
915	/** @def LogWarnFunc
916	* Macro to log a warning inside C/C++ functions.
917	*
918	* Prepends the given log message with the function name followed by
919	* a semicolon and space.
920	*
921	* @param a Log message in format <tt>("string\n" [, args])</tt>.
922	*/
923	#ifdef LOG_USE_C99
924	# define LogWarnFunc(a) \
925	_LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
926	#else
927	# define LogWarnFunc(a) \
928	do { LogFlow((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
929	#endif
930	/** @} */
931
932
933	/** @name Logging macros prefixing the this pointer value and method name.
934	* @{ */
935
936	/** @def LogThisFunc
937	* Level 1 logging inside a C++ non-static method, with object pointer and
938	* method name prefixed to the given message.
939	* @param a Log message in format <tt>("string\n" [, args])</tt>.
940	*/
941	#ifdef LOG_USE_C99
942	# define LogThisFunc(a) \
943	_LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
944	#else
945	# define LogThisFunc(a) do { Log(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log(a); } while (0)
946	#endif
947
948	/** @def Log2ThisFunc
949	* Level 2 logging inside a C++ non-static method, with object pointer and
950	* method name prefixed to the given message.
951	* @param a Log message in format <tt>("string\n" [, args])</tt>.
952	*/
953	#ifdef LOG_USE_C99
954	# define Log2ThisFunc(a) \
955	_LogIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
956	#else
957	# define Log2ThisFunc(a) do { Log2(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log2(a); } while (0)
958	#endif
959
960	/** @def Log3ThisFunc
961	* Level 3 logging inside a C++ non-static method, with object pointer and
962	* method name prefixed to the given message.
963	* @param a Log message in format <tt>("string\n" [, args])</tt>.
964	*/
965	#ifdef LOG_USE_C99
966	# define Log3ThisFunc(a) \
967	_LogIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
968	#else
969	# define Log3ThisFunc(a) do { Log3(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log3(a); } while (0)
970	#endif
971
972	/** @def Log4ThisFunc
973	* Level 4 logging inside a C++ non-static method, with object pointer and
974	* method name prefixed to the given message.
975	* @param a Log message in format <tt>("string\n" [, args])</tt>.
976	*/
977	#ifdef LOG_USE_C99
978	# define Log4ThisFunc(a) \
979	_LogIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
980	#else
981	# define Log4ThisFunc(a) do { Log4(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log4(a); } while (0)
982	#endif
983
984	/** @def Log5ThisFunc
985	* Level 5 logging inside a C++ non-static method, with object pointer and
986	* method name prefixed to the given message.
987	* @param a Log message in format <tt>("string\n" [, args])</tt>.
988	*/
989	#ifdef LOG_USE_C99
990	# define Log5ThisFunc(a) \
991	_LogIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
992	#else
993	# define Log5ThisFunc(a) do { Log5(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log5(a); } while (0)
994	#endif
995
996	/** @def Log6ThisFunc
997	* Level 6 logging inside a C++ non-static method, with object pointer and
998	* method name prefixed to the given message.
999	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1000	*/
1001	#ifdef LOG_USE_C99
1002	# define Log6ThisFunc(a) \
1003	_LogIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1004	#else
1005	# define Log6ThisFunc(a) do { Log6(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log6(a); } while (0)
1006	#endif
1007
1008	/** @def Log7ThisFunc
1009	* Level 7 logging inside a C++ non-static method, with object pointer and
1010	* method name prefixed to the given message.
1011	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1012	*/
1013	#ifdef LOG_USE_C99
1014	# define Log7ThisFunc(a) \
1015	_LogIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1016	#else
1017	# define Log7ThisFunc(a) do { Log7(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log7(a); } while (0)
1018	#endif
1019
1020	/** @def Log8ThisFunc
1021	* Level 8 logging inside a C++ non-static method, with object pointer and
1022	* method name prefixed to the given message.
1023	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1024	*/
1025	#ifdef LOG_USE_C99
1026	# define Log8ThisFunc(a) \
1027	_LogIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1028	#else
1029	# define Log8ThisFunc(a) do { Log8(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log8(a); } while (0)
1030	#endif
1031
1032	/** @def Log9ThisFunc
1033	* Level 9 logging inside a C++ non-static method, with object pointer and
1034	* method name prefixed to the given message.
1035	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1036	*/
1037	#ifdef LOG_USE_C99
1038	# define Log9ThisFunc(a) \
1039	_LogIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1040	#else
1041	# define Log9ThisFunc(a) do { Log9(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log9(a); } while (0)
1042	#endif
1043
1044	/** @def Log10ThisFunc
1045	* Level 10 logging inside a C++ non-static method, with object pointer and
1046	* method name prefixed to the given message.
1047	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1048	*/
1049	#ifdef LOG_USE_C99
1050	# define Log10ThisFunc(a) \
1051	_LogIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1052	#else
1053	# define Log10ThisFunc(a) do { Log10(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log10(a); } while (0)
1054	#endif
1055
1056	/** @def Log11ThisFunc
1057	* Level 11 logging inside a C++ non-static method, with object pointer and
1058	* method name prefixed to the given message.
1059	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1060	*/
1061	#ifdef LOG_USE_C99
1062	# define Log11ThisFunc(a) \
1063	_LogIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1064	#else
1065	# define Log11ThisFunc(a) do { Log11(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log11(a); } while (0)
1066	#endif
1067
1068	/** @def Log12ThisFunc
1069	* Level 12 logging inside a C++ non-static method, with object pointer and
1070	* method name prefixed to the given message.
1071	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1072	*/
1073	#ifdef LOG_USE_C99
1074	# define Log12ThisFunc(a) \
1075	_LogIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1076	#else
1077	# define Log12ThisFunc(a) do { Log12(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log12(a); } while (0)
1078	#endif
1079
1080	/** @def LogFlowThisFunc
1081	* Flow level logging inside a C++ non-static method, with object pointer and
1082	* method name prefixed to the given message.
1083	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1084	*/
1085	#ifdef LOG_USE_C99
1086	# define LogFlowThisFunc(a) \
1087	_LogIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1088	#else
1089	# define LogFlowThisFunc(a) do { LogFlow(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
1090	#endif
1091
1092	/** @def LogWarnThisFunc
1093	* Warning level logging inside a C++ non-static method, with object pointer and
1094	* method name prefixed to the given message.
1095	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1096	*/
1097	#ifdef LOG_USE_C99
1098	# define LogWarnThisFunc(a) \
1099	_LogIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1100	#else
1101	# define LogWarnThisFunc(a) do { LogWarn(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogWarn(a); } while (0)
1102	#endif
1103	/** @} */
1104
1105
1106	/** @name Misc Logging Macros
1107	* @{ */
1108
1109	/** @def Log1Warning
1110	* The same as Log(), but prepents a <tt>"WARNING! "</tt> string to the message.
1111	*
1112	* @param a Custom log message in format <tt>("string\n" [, args])</tt>.
1113	*/
1114	#if defined(LOG_USE_C99)
1115	# define Log1Warning(a) _LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "WARNING! %M", _LogRemoveParentheseis a )
1116	#else
1117	# define Log1Warning(a) do { Log(("WARNING! ")); Log(a); } while (0)
1118	#endif
1119
1120	/** @def Log1WarningFunc
1121	* The same as LogWarning(), but prepents the log message with the function name.
1122	*
1123	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1124	*/
1125	#ifdef LOG_USE_C99
1126	# define Log1WarningFunc(a) \
1127	_LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": WARNING! %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1128	#else
1129	# define Log1WarningFunc(a) \
1130	do { Log((LOG_FN_FMT ": WARNING! ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log(a); } while (0)
1131	#endif
1132
1133	/** @def Log1WarningThisFunc
1134	* The same as LogWarningFunc() but for class functions (methods): the resulting
1135	* log line is additionally prepended with a hex value of \|this\| pointer.
1136	*
1137	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1138	*/
1139	#ifdef LOG_USE_C99
1140	# define Log1WarningThisFunc(a) \
1141	_LogIt(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": WARNING! %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1142	#else
1143	# define Log1WarningThisFunc(a) \
1144	do { Log(("{%p} " LOG_FN_FMT ": WARNING! ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); Log(a); } while (0)
1145	#endif
1146
1147
1148	/** Shortcut to \|LogFlowFunc ("ENTER\n")\|, marks the beginnig of the function. */
1149	#define LogFlowFuncEnter() LogFlowFunc(("ENTER\n"))
1150
1151	/** Shortcut to \|LogFlowFunc ("LEAVE\n")\|, marks the end of the function. */
1152	#define LogFlowFuncLeave() LogFlowFunc(("LEAVE\n"))
1153
1154	/** Shortcut to \|LogFlowFunc ("LEAVE: %Rrc\n")\|, marks the end of the function. */
1155	#define LogFlowFuncLeaveRC(rc) LogFlowFunc(("LEAVE: %Rrc\n", (rc)))
1156
1157	/** Shortcut to \|LogFlowThisFunc ("ENTER\n")\|, marks the beginnig of the function. */
1158	#define LogFlowThisFuncEnter() LogFlowThisFunc(("ENTER\n"))
1159
1160	/** Shortcut to \|LogFlowThisFunc ("LEAVE\n")\|, marks the end of the function. */
1161	#define LogFlowThisFuncLeave() LogFlowThisFunc(("LEAVE\n"))
1162
1163
1164	/** @def LogObjRefCnt
1165	* Helper macro to print the current reference count of the given COM object
1166	* to the log file.
1167	*
1168	* @param pObj Pointer to the object in question (must be a pointer to an
1169	* IUnknown subclass or simply define COM-style AddRef() and
1170	* Release() methods)
1171	*/
1172	#define LogObjRefCnt(pObj) \
1173	do { \
1174	if (LogIsFlowEnabled()) \
1175	{ \
1176	int cRefsForLog = (pObj)->AddRef(); \
1177	LogFlow((#pObj "{%p}.refCnt=%d\n", (pObj), cRefsForLog - 1)); \
1178	(pObj)->Release(); \
1179	} \
1180	} while (0)
1181	/** @} */
1182
1183
1184
1185	/** @name Passing Function Call Position When Logging.
1186	*
1187	* This is a little bit ugly as we have to omit the comma before the
1188	* position parameters so that we don't inccur any overhead in non-logging
1189	* builds (!defined(LOG_ENABLED).
1190	*
1191	* @{ */
1192	/** Source position for passing to a function call. */
1193	#ifdef LOG_ENABLED
1194	# define RTLOG_COMMA_SRC_POS , __FILE__, __LINE__, RT_GCC_EXTENSION __PRETTY_FUNCTION__
1195	#else
1196	# define RTLOG_COMMA_SRC_POS RT_NOTHING
1197	#endif
1198	/** Source position declaration. */
1199	#ifdef LOG_ENABLED
1200	# define RTLOG_COMMA_SRC_POS_DECL , const char pszFile, unsigned iLine, const char pszFunction
1201	#else
1202	# define RTLOG_COMMA_SRC_POS_DECL RT_NOTHING
1203	#endif
1204	/** Source position arguments. */
1205	#ifdef LOG_ENABLED
1206	# define RTLOG_COMMA_SRC_POS_ARGS , pszFile, iLine, pszFunction
1207	#else
1208	# define RTLOG_COMMA_SRC_POS_ARGS RT_NOTHING
1209	#endif
1210	/** Applies NOREF() to the source position arguments. */
1211	#ifdef LOG_ENABLED
1212	# define RTLOG_SRC_POS_NOREF() do { NOREF(pszFile); NOREF(iLine); NOREF(pszFunction); } while (0)
1213	#else
1214	# define RTLOG_SRC_POS_NOREF() do { } while (0)
1215	#endif
1216	/** @} */
1217
1218
1219
1220	/** @defgroup grp_rt_log_rel Release Logging
1221	* @{
1222	*/
1223
1224	#ifdef DOXYGEN_RUNNING
1225	# define RTLOG_REL_DISABLED
1226	# define RTLOG_REL_ENABLED
1227	#endif
1228
1229	/** @def RTLOG_REL_DISABLED
1230	* Use this compile time define to disable all release logging
1231	* macros.
1232	*/
1233
1234	/** @def RTLOG_REL_ENABLED
1235	* Use this compile time define to override RTLOG_REL_DISABLE.
1236	*/
1237
1238	/*
1239	* Determine whether release logging is enabled and forcefully normalize the indicators.
1240	*/
1241	#if !defined(RTLOG_REL_DISABLED) \|\| defined(RTLOG_REL_ENABLED)
1242	# undef RTLOG_REL_DISABLED
1243	# undef RTLOG_REL_ENABLED
1244	# define RTLOG_REL_ENABLED
1245	#else
1246	# undef RTLOG_REL_ENABLED
1247	# undef RTLOG_REL_DISABLED
1248	# define RTLOG_REL_DISABLED
1249	#endif
1250
1251	/** @name Macros for checking whether a release log level is enabled.
1252	* @{ */
1253	/** @def LogRelIsItEnabled
1254	* Checks whether the specified release logging group is enabled or not.
1255	*/
1256	#define LogRelIsItEnabled(a_fFlags, a_iGroup) ( RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)) != NULL )
1257
1258	/** @def LogRelIsEnabled
1259	* Checks whether level 1 release logging is enabled.
1260	*/
1261	#define LogRelIsEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP)
1262
1263	/** @def LogRelIs2Enabled
1264	* Checks whether level 2 release logging is enabled.
1265	*/
1266	#define LogRelIs2Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP)
1267
1268	/** @def LogRelIs3Enabled
1269	* Checks whether level 3 release logging is enabled.
1270	*/
1271	#define LogRelIs3Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP)
1272
1273	/** @def LogRelIs4Enabled
1274	* Checks whether level 4 release logging is enabled.
1275	*/
1276	#define LogRelIs4Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP)
1277
1278	/** @def LogRelIs5Enabled
1279	* Checks whether level 5 release logging is enabled.
1280	*/
1281	#define LogRelIs5Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP)
1282
1283	/** @def LogRelIs6Enabled
1284	* Checks whether level 6 release logging is enabled.
1285	*/
1286	#define LogRelIs6Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP)
1287
1288	/** @def LogRelIs7Enabled
1289	* Checks whether level 7 release logging is enabled.
1290	*/
1291	#define LogRelIs7Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP)
1292
1293	/** @def LogRelIs8Enabled
1294	* Checks whether level 8 release logging is enabled.
1295	*/
1296	#define LogRelIs8Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP)
1297
1298	/** @def LogRelIs2Enabled
1299	* Checks whether level 9 release logging is enabled.
1300	*/
1301	#define LogRelIs9Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP)
1302
1303	/** @def LogRelIs10Enabled
1304	* Checks whether level 10 release logging is enabled.
1305	*/
1306	#define LogRelIs10Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP)
1307
1308	/** @def LogRelIs11Enabled
1309	* Checks whether level 10 release logging is enabled.
1310	*/
1311	#define LogRelIs11Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP)
1312
1313	/** @def LogRelIs12Enabled
1314	* Checks whether level 12 release logging is enabled.
1315	*/
1316	#define LogRelIs12Enabled() LogRelIsItEnabled(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP)
1317
1318	/** @def LogRelIsFlowEnabled
1319	* Checks whether execution flow release logging is enabled.
1320	*/
1321	#define LogRelIsFlowEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
1322
1323	/** @def LogRelIsWarnEnabled
1324	* Checks whether warning level release logging is enabled.
1325	*/
1326	#define LogRelIsWarnEnabled() LogRelIsItEnabled(RTLOGGRPFLAGS_FLOW, LOG_GROUP)
1327	/** @} */
1328
1329
1330	/** @def LogRelIt
1331	* Write to specific logger if group enabled.
1332	*/
1333	/** @def LogRelItLikely
1334	* Write to specific logger if group enabled, assuming it likely it is enabled.
1335	*/
1336	/** @def LogRelMaxIt
1337	* Write to specific logger if group enabled and at less than a_cMax messages
1338	* have hit the log. Uses a static variable to count.
1339	*/
1340	#ifdef RTLOG_REL_ENABLED
1341	# if defined(LOG_USE_C99)
1342	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1343	# define _LogRelIt(a_fFlags, a_iGroup, ...) \
1344	do \
1345	{ \
1346	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1347	if (RT_LIKELY(!LogRelIt_pLogger)) \
1348	{ /* likely */ } \
1349	else \
1350	RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1351	_LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1352	} while (0)
1353	# define LogRelIt(a_fFlags, a_iGroup, fmtargs) \
1354	_LogRelIt(a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1355	# define _LogRelItLikely(a_fFlags, a_iGroup, ...) \
1356	do \
1357	{ \
1358	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1359	if (LogRelIt_pLogger) \
1360	RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1361	_LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1362	} while (0)
1363	# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) \
1364	_LogRelItLikely(a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1365	# define _LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, ...) \
1366	do \
1367	{ \
1368	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1369	if (LogRelIt_pLogger) \
1370	{ \
1371	static uint32_t s_LogRelMaxIt_cLogged = 0; \
1372	if (s_LogRelMaxIt_cLogged < (a_cMax)) \
1373	{ \
1374	s_LogRelMaxIt_cLogged++; \
1375	RTLogLoggerEx(LogRelIt_pLogger, a_fFlags, a_iGroup, __VA_ARGS__); \
1376	} \
1377	} \
1378	_LogIt(a_fFlags, a_iGroup, __VA_ARGS__); \
1379	} while (0)
1380	# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) \
1381	_LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, _LogRelRemoveParentheseis fmtargs)
1382	# else
1383	# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) \
1384	do \
1385	{ \
1386	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1387	if (LogRelIt_pLogger) \
1388	{ \
1389	LogRelIt_pLogger->pfnLogger fmtargs; \
1390	} \
1391	LogIt(a_fFlags, a_iGroup, fmtargs); \
1392	} while (0)
1393	# define LogRelIt(a_fFlags, a_iGroup, fmtargs) \
1394	do \
1395	{ \
1396	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1397	if (RT_LIKELY(!LogRelIt_pLogger)) \
1398	{ /* likely */ } \
1399	else \
1400	{ \
1401	LogRelIt_pLogger->pfnLogger fmtargs; \
1402	} \
1403	LogIt(a_fFlags, a_iGroup, fmtargs); \
1404	} while (0)
1405	# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) \
1406	do \
1407	{ \
1408	PRTLOGGER LogRelIt_pLogger = RTLogRelGetDefaultInstanceEx(RT_MAKE_U32(a_fFlags, a_iGroup)); \
1409	if (LogRelIt_pLogger) \
1410	{ \
1411	static uint32_t s_LogRelMaxIt_cLogged = 0; \
1412	if (s_LogRelMaxIt_cLogged < (a_cMax)) \
1413	{ \
1414	s_LogRelMaxIt_cLogged++; \
1415	LogRelIt_pLogger->pfnLogger fmtargs; \
1416	} \
1417	} \
1418	LogIt(a_fFlags, a_iGroup, fmtargs); \
1419	} while (0)
1420	# endif
1421	#else /* !RTLOG_REL_ENABLED */
1422	# define LogRelIt(a_fFlags, a_iGroup, fmtargs) do { } while (0)
1423	# define LogRelItLikely(a_fFlags, a_iGroup, fmtargs) do { } while (0)
1424	# define LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, fmtargs) do { } while (0)
1425	# if defined(LOG_USE_C99)
1426	# define _LogRelRemoveParentheseis(...) __VA_ARGS__
1427	# define _LogRelIt(a_fFlags, a_iGroup, ...) do { } while (0)
1428	# define _LogRelItLikely(a_fFlags, a_iGroup, ...) do { } while (0)
1429	# define _LogRelMaxIt(a_cMax, a_fFlags, a_iGroup, ...) do { } while (0)
1430	# endif
1431	#endif /* !RTLOG_REL_ENABLED */
1432
1433
1434	/** @name Basic release logging macros
1435	* @{ */
1436	/** @def LogRel
1437	* Level 1 release logging.
1438	*/
1439	#define LogRel(a) LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
1440
1441	/** @def LogRel2
1442	* Level 2 release logging.
1443	*/
1444	#define LogRel2(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
1445
1446	/** @def LogRel3
1447	* Level 3 release logging.
1448	*/
1449	#define LogRel3(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
1450
1451	/** @def LogRel4
1452	* Level 4 release logging.
1453	*/
1454	#define LogRel4(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
1455
1456	/** @def LogRel5
1457	* Level 5 release logging.
1458	*/
1459	#define LogRel5(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
1460
1461	/** @def LogRel6
1462	* Level 6 release logging.
1463	*/
1464	#define LogRel6(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
1465
1466	/** @def LogRel7
1467	* Level 7 release logging.
1468	*/
1469	#define LogRel7(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
1470
1471	/** @def LogRel8
1472	* Level 8 release logging.
1473	*/
1474	#define LogRel8(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
1475
1476	/** @def LogRel9
1477	* Level 9 release logging.
1478	*/
1479	#define LogRel9(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
1480
1481	/** @def LogRel10
1482	* Level 10 release logging.
1483	*/
1484	#define LogRel10(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
1485
1486	/** @def LogRel11
1487	* Level 11 release logging.
1488	*/
1489	#define LogRel11(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
1490
1491	/** @def LogRel12
1492	* Level 12 release logging.
1493	*/
1494	#define LogRel12(a) LogRelIt(RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
1495
1496	/** @def LogRelFlow
1497	* Logging of execution flow.
1498	*/
1499	#define LogRelFlow(a) LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
1500
1501	/** @def LogRelWarn
1502	* Warning level release logging.
1503	*/
1504	#define LogRelWarn(a) LogRelIt(RTLOGGRPFLAGS_WARN, LOG_GROUP, a)
1505	/** @} */
1506
1507
1508
1509	/** @name Basic release logging macros with local max
1510	* @{ */
1511	/** @def LogRelMax
1512	* Level 1 release logging with a max number of log entries.
1513	*/
1514	#define LogRelMax(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, a)
1515
1516	/** @def LogRelMax2
1517	* Level 2 release logging with a max number of log entries.
1518	*/
1519	#define LogRelMax2(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_2, LOG_GROUP, a)
1520
1521	/** @def LogRelMax3
1522	* Level 3 release logging with a max number of log entries.
1523	*/
1524	#define LogRelMax3(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_3, LOG_GROUP, a)
1525
1526	/** @def LogRelMax4
1527	* Level 4 release logging with a max number of log entries.
1528	*/
1529	#define LogRelMax4(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_4, LOG_GROUP, a)
1530
1531	/** @def LogRelMax5
1532	* Level 5 release logging with a max number of log entries.
1533	*/
1534	#define LogRelMax5(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_5, LOG_GROUP, a)
1535
1536	/** @def LogRelMax6
1537	* Level 6 release logging with a max number of log entries.
1538	*/
1539	#define LogRelMax6(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_6, LOG_GROUP, a)
1540
1541	/** @def LogRelMax7
1542	* Level 7 release logging with a max number of log entries.
1543	*/
1544	#define LogRelMax7(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_7, LOG_GROUP, a)
1545
1546	/** @def LogRelMax8
1547	* Level 8 release logging with a max number of log entries.
1548	*/
1549	#define LogRelMax8(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_8, LOG_GROUP, a)
1550
1551	/** @def LogRelMax9
1552	* Level 9 release logging with a max number of log entries.
1553	*/
1554	#define LogRelMax9(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_9, LOG_GROUP, a)
1555
1556	/** @def LogRelMax10
1557	* Level 10 release logging with a max number of log entries.
1558	*/
1559	#define LogRelMax10(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_10, LOG_GROUP, a)
1560
1561	/** @def LogRelMax11
1562	* Level 11 release logging with a max number of log entries.
1563	*/
1564	#define LogRelMax11(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_11, LOG_GROUP, a)
1565
1566	/** @def LogRelMax12
1567	* Level 12 release logging with a max number of log entries.
1568	*/
1569	#define LogRelMax12(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_12, LOG_GROUP, a)
1570
1571	/** @def LogRelMaxFlow
1572	* Logging of execution flow with a max number of log entries.
1573	*/
1574	#define LogRelMaxFlow(a_cMax, a) LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_FLOW, LOG_GROUP, a)
1575	/** @} */
1576
1577
1578	/** @name Release logging macros prefixing the current function name.
1579	* @{ */
1580
1581	/** @def LogRelFunc
1582	* Release logging. Prepends the given log message with the function name
1583	* followed by a semicolon and space.
1584	*/
1585	#ifdef LOG_USE_C99
1586	# define LogRelFunc(a) \
1587	_LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1588	#else
1589	# define LogRelFunc(a) do { LogRel((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1590	#endif
1591
1592	/** @def LogRelFlowFunc
1593	* Release logging. Macro to log the execution flow inside C/C++ functions.
1594	*
1595	* Prepends the given log message with the function name followed by
1596	* a semicolon and space.
1597	*
1598	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1599	*/
1600	#ifdef LOG_USE_C99
1601	# define LogRelFlowFunc(a) _LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1602	#else
1603	# define LogRelFlowFunc(a) do { LogRelFlow((LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRelFlow(a); } while (0)
1604	#endif
1605
1606	/** @def LogRelMaxFunc
1607	* Release logging. Prepends the given log message with the function name
1608	* followed by a semicolon and space.
1609	*/
1610	#ifdef LOG_USE_C99
1611	# define LogRelMaxFunc(a_cMax, a) \
1612	_LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1613	#else
1614	# define LogRelMaxFunc(a_cMax, a) \
1615	do { LogRelMax(a_cMax, (LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRelMax(a_cMax, a); } while (0)
1616	#endif
1617
1618	/** @def LogRelMaxFlowFunc
1619	* Release logging. Macro to log the execution flow inside C/C++ functions.
1620	*
1621	* Prepends the given log message with the function name followed by
1622	* a semicolon and space.
1623	*
1624	* @param a_cMax Max number of times this should hit the log.
1625	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1626	*/
1627	#ifdef LOG_USE_C99
1628	# define LogRelMaxFlowFunc(a_cMax, a) \
1629	_LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_FLOW, LOG_GROUP, LOG_FN_FMT ": %M", RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1630	#else
1631	# define LogRelMaxFlowFunc(a_cMax, a) \
1632	do { LogRelMaxFlow(a_cMax, (LOG_FN_FMT ": ", RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRelFlow(a_cMax, a); } while (0)
1633	#endif
1634
1635	/** @} */
1636
1637
1638	/** @name Release Logging macros prefixing the this pointer value and method name.
1639	* @{ */
1640
1641	/** @def LogRelThisFunc
1642	* The same as LogRelFunc but for class functions (methods): the resulting log
1643	* line is additionally prepended with a hex value of \|this\| pointer.
1644	*/
1645	#ifdef LOG_USE_C99
1646	# define LogRelThisFunc(a) \
1647	_LogRelItLikely(RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1648	#else
1649	# define LogRelThisFunc(a) \
1650	do { LogRel(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRel(a); } while (0)
1651	#endif
1652
1653	/** @def LogRelMaxThisFunc
1654	* The same as LogRelFunc but for class functions (methods): the resulting log
1655	* line is additionally prepended with a hex value of \|this\| pointer.
1656	* @param a_cMax Max number of times this should hit the log.
1657	* @param a Log message in format <tt>("string\n" [, args])</tt>.
1658	*/
1659	#ifdef LOG_USE_C99
1660	# define LogRelMaxThisFunc(a_cMax, a) \
1661	_LogRelMaxIt(a_cMax, RTLOGGRPFLAGS_LEVEL_1, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1662	#else
1663	# define LogRelMaxThisFunc(a_cMax, a) \
1664	do { LogRelMax(a_cMax, ("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRelMax(a_cMax, a); } while (0)
1665	#endif
1666
1667	/** @def LogRelFlowThisFunc
1668	* The same as LogRelFlowFunc but for class functions (methods): the resulting
1669	* log line is additionally prepended with a hex value of \|this\| pointer.
1670	*/
1671	#ifdef LOG_USE_C99
1672	# define LogRelFlowThisFunc(a) \
1673	_LogRelIt(RTLOGGRPFLAGS_FLOW, LOG_GROUP, "{%p} " LOG_FN_FMT ": %M", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
1674	#else
1675	# define LogRelFlowThisFunc(a) do { LogRelFlow(("{%p} " LOG_FN_FMT ": ", this, RT_GCC_EXTENSION __PRETTY_FUNCTION__)); LogRelFlow(a); } while (0)
1676	#endif
1677
1678
1679	/** Shortcut to \|LogRelFlowFunc ("ENTER\n")\|, marks the beginnig of the function. */
1680	#define LogRelFlowFuncEnter() LogRelFlowFunc(("ENTER\n"))
1681
1682	/** Shortcut to \|LogRelFlowFunc ("LEAVE\n")\|, marks the end of the function. */
1683	#define LogRelFlowFuncLeave() LogRelFlowFunc(("LEAVE\n"))
1684
1685	/** Shortcut to \|LogRelFlowFunc ("LEAVE: %Rrc\n")\|, marks the end of the function. */
1686	#define LogRelFlowFuncLeaveRC(rc) LogRelFlowFunc(("LEAVE: %Rrc\n", (rc)))
1687
1688	/** Shortcut to \|LogRelFlowThisFunc ("ENTER\n")\|, marks the beginnig of the function. */
1689	#define LogRelFlowThisFuncEnter() LogRelFlowThisFunc(("ENTER\n"))
1690
1691	/** Shortcut to \|LogRelFlowThisFunc ("LEAVE\n")\|, marks the end of the function. */
1692	#define LogRelFlowThisFuncLeave() LogRelFlowThisFunc(("LEAVE\n"))
1693
1694	/** @} */
1695
1696
1697	/**
1698	* Sets the default release logger instance.
1699	*
1700	* @returns The old default instance.
1701	* @param pLogger The new default release logger instance.
1702	*/
1703	RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger);
1704
1705	/**
1706	* Gets the default release logger instance.
1707	*
1708	* @returns Pointer to default release logger instance if availble, otherwise NULL.
1709	*/
1710	RTDECL(PRTLOGGER) RTLogRelGetDefaultInstance(void);
1711
1712	/**
1713	* Gets the default release logger instance.
1714	*
1715	* @returns Pointer to default release logger instance if availble, otherwise NULL.
1716	* @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1717	* the high 16 bits.
1718	*/
1719	RTDECL(PRTLOGGER) RTLogRelGetDefaultInstanceEx(uint32_t fFlagsAndGroup);
1720
1721	/**
1722	* Write to a logger instance, defaulting to the release one.
1723	*
1724	* This function will check whether the instance, group and flags makes up a
1725	* logging kind which is currently enabled before writing anything to the log.
1726	*
1727	* @param pLogger Pointer to logger instance.
1728	* @param fFlags The logging flags.
1729	* @param iGroup The group.
1730	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1731	* only for internal usage!
1732	* @param pszFormat Format string.
1733	* @param ... Format arguments.
1734	* @remark This is a worker function for LogRelIt.
1735	*/
1736	RTDECL(void) RTLogRelLogger(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
1737	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
1738
1739	/**
1740	* Write to a logger instance, defaulting to the release one.
1741	*
1742	* This function will check whether the instance, group and flags makes up a
1743	* logging kind which is currently enabled before writing anything to the log.
1744	*
1745	* @param pLogger Pointer to logger instance. If NULL the default release instance is attempted.
1746	* @param fFlags The logging flags.
1747	* @param iGroup The group.
1748	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
1749	* only for internal usage!
1750	* @param pszFormat Format string.
1751	* @param args Format arguments.
1752	*/
1753	RTDECL(void) RTLogRelLoggerV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
1754	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(4, 0);
1755
1756	/**
1757	* printf like function for writing to the default release log.
1758	*
1759	* @param pszFormat Printf like format string.
1760	* @param ... Optional arguments as specified in pszFormat.
1761	*
1762	* @remark The API doesn't support formatting of floating point numbers at the moment.
1763	*/
1764	RTDECL(void) RTLogRelPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
1765
1766	/**
1767	* vprintf like function for writing to the default release log.
1768	*
1769	* @param pszFormat Printf like format string.
1770	* @param args Optional arguments as specified in pszFormat.
1771	*
1772	* @remark The API doesn't support formatting of floating point numbers at the moment.
1773	*/
1774	RTDECL(void) RTLogRelPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
1775
1776	/**
1777	* Changes the buffering setting of the default release logger.
1778	*
1779	* This can be used for optimizing longish logging sequences.
1780	*
1781	* @returns The old state.
1782	* @param fBuffered The new state.
1783	*/
1784	RTDECL(bool) RTLogRelSetBuffering(bool fBuffered);
1785
1786	/** @} */
1787
1788
1789
1790	/** @name COM port logging
1791	* @{
1792	*/
1793
1794	#ifdef DOXYGEN_RUNNING
1795	# define LOG_TO_COM
1796	# define LOG_NO_COM
1797	#endif
1798
1799	/** @def LOG_TO_COM
1800	* Redirects the normal logging macros to the serial versions.
1801	*/
1802
1803	/** @def LOG_NO_COM
1804	* Disables all LogCom* macros.
1805	*/
1806
1807	/** @def LogCom
1808	* Generic logging to serial port.
1809	*/
1810	#if defined(LOG_ENABLED) && !defined(LOG_NO_COM)
1811	# define LogCom(a) RTLogComPrintf a
1812	#else
1813	# define LogCom(a) do { } while (0)
1814	#endif
1815
1816	/** @def LogComFlow
1817	* Logging to serial port of execution flow.
1818	*/
1819	#if defined(LOG_ENABLED) && defined(LOG_ENABLE_FLOW) && !defined(LOG_NO_COM)
1820	# define LogComFlow(a) RTLogComPrintf a
1821	#else
1822	# define LogComFlow(a) do { } while (0)
1823	#endif
1824
1825	#ifdef LOG_TO_COM
1826	# undef Log
1827	# define Log(a) LogCom(a)
1828	# undef LogFlow
1829	# define LogFlow(a) LogComFlow(a)
1830	#endif
1831
1832	/** @} */
1833
1834
1835	/** @name Backdoor Logging
1836	* @{
1837	*/
1838
1839	#ifdef DOXYGEN_RUNNING
1840	# define LOG_TO_BACKDOOR
1841	# define LOG_NO_BACKDOOR
1842	#endif
1843
1844	/** @def LOG_TO_BACKDOOR
1845	* Redirects the normal logging macros to the backdoor versions.
1846	*/
1847
1848	/** @def LOG_NO_BACKDOOR
1849	* Disables all LogBackdoor* macros.
1850	*/
1851
1852	/** @def LogBackdoor
1853	* Generic logging to the VBox backdoor via port I/O.
1854	*/
1855	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1856	# define LogBackdoor(a) RTLogBackdoorPrintf a
1857	#else
1858	# define LogBackdoor(a) do { } while (0)
1859	#endif
1860
1861	/** @def LogBackdoorFlow
1862	* Logging of execution flow messages to the backdoor I/O port.
1863	*/
1864	#if defined(LOG_ENABLED) && !defined(LOG_NO_BACKDOOR)
1865	# define LogBackdoorFlow(a) RTLogBackdoorPrintf a
1866	#else
1867	# define LogBackdoorFlow(a) do { } while (0)
1868	#endif
1869
1870	/** @def LogRelBackdoor
1871	* Release logging to the VBox backdoor via port I/O.
1872	*/
1873	#if !defined(LOG_NO_BACKDOOR)
1874	# define LogRelBackdoor(a) RTLogBackdoorPrintf a
1875	#else
1876	# define LogRelBackdoor(a) do { } while (0)
1877	#endif
1878
1879	#ifdef LOG_TO_BACKDOOR
1880	# undef Log
1881	# define Log(a) LogBackdoor(a)
1882	# undef LogFlow
1883	# define LogFlow(a) LogBackdoorFlow(a)
1884	# undef LogRel
1885	# define LogRel(a) LogRelBackdoor(a)
1886	# if defined(LOG_USE_C99)
1887	# undef _LogIt
1888	# define _LogIt(a_fFlags, a_iGroup, ...) LogBackdoor((__VA_ARGS__))
1889	# endif
1890	#endif
1891
1892	/** @} */
1893
1894
1895
1896	/**
1897	* Gets the default logger instance, creating it if necessary.
1898	*
1899	* @returns Pointer to default logger instance if availble, otherwise NULL.
1900	*/
1901	RTDECL(PRTLOGGER) RTLogDefaultInstance(void);
1902
1903	/**
1904	* Gets the logger instance if enabled, creating it if necessary.
1905	*
1906	* @returns Pointer to default logger instance, if group has the specified
1907	* flags enabled. Otherwise NULL is returned.
1908	* @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1909	* the high 16 bits.
1910	*/
1911	RTDECL(PRTLOGGER) RTLogDefaultInstanceEx(uint32_t fFlagsAndGroup);
1912
1913	/**
1914	* Gets the default logger instance (does not create one).
1915	*
1916	* @returns Pointer to default logger instance if availble, otherwise NULL.
1917	*/
1918	RTDECL(PRTLOGGER) RTLogGetDefaultInstance(void);
1919
1920	/**
1921	* Gets the default logger instance if enabled (does not create one).
1922	*
1923	* @returns Pointer to default logger instance, if group has the specified
1924	* flags enabled. Otherwise NULL is returned.
1925	* @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1926	* the high 16 bits.
1927	*/
1928	RTDECL(PRTLOGGER) RTLogGetDefaultInstanceEx(uint32_t fFlagsAndGroup);
1929
1930	/**
1931	* Sets the default logger instance.
1932	*
1933	* @returns The old default instance.
1934	* @param pLogger The new default logger instance.
1935	*/
1936	RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger);
1937
1938	#ifdef IN_RING0
1939	/**
1940	* Changes the default logger instance for the current thread.
1941	*
1942	* @returns IPRT status code.
1943	* @param pLogger The logger instance. Pass NULL for deregistration.
1944	* @param uKey Associated key for cleanup purposes. If pLogger is NULL,
1945	* all instances with this key will be deregistered. So in
1946	* order to only deregister the instance associated with the
1947	* current thread use 0.
1948	*/
1949	RTR0DECL(int) RTLogSetDefaultInstanceThread(PRTLOGGER pLogger, uintptr_t uKey);
1950	#endif /* IN_RING0 */
1951
1952	/**
1953	* Creates the default logger instance for IPRT users.
1954	*
1955	* Any user of the logging features will need to implement
1956	* this or use the generic dummy.
1957	*
1958	* @returns Pointer to the logger instance.
1959	*/
1960	RTDECL(PRTLOGGER) RTLogDefaultInit(void);
1961
1962	/**
1963	* This is the 2nd half of what RTLogGetDefaultInstanceEx() and
1964	* RTLogRelGetDefaultInstanceEx() does.
1965	*
1966	* @returns If the group has the specified flags enabled @a pLogger will be
1967	* returned returned. Otherwise NULL is returned.
1968	* @param pLogger The logger. NULL is NULL.
1969	* @param fFlagsAndGroup The flags in the lower 16 bits, the group number in
1970	* the high 16 bits.
1971	*/
1972	RTDECL(PRTLOGGER) RTLogCheckGroupFlags(PRTLOGGER pLogger, uint32_t fFlagsAndGroup);
1973
1974	/**
1975	* Create a logger instance.
1976	*
1977	* @returns iprt status code.
1978	*
1979	* @param ppLogger Where to store the logger instance.
1980	* @param fFlags Logger instance flags, a combination of the
1981	* RTLOGFLAGS_* values.
1982	* @param pszGroupSettings The initial group settings.
1983	* @param pszEnvVarBase Base name for the environment variables for
1984	* this instance.
1985	* @param cGroups Number of groups in the array.
1986	* @param papszGroups Pointer to array of groups. This must stick
1987	* around for the life of the logger instance.
1988	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
1989	* if pszFilenameFmt specified.
1990	* @param pszFilenameFmt Log filename format string. Standard
1991	* RTStrFormat().
1992	* @param ... Format arguments.
1993	*/
1994	RTDECL(int) RTLogCreate(PRTLOGGER ppLogger, uint64_t fFlags, const char pszGroupSettings,
1995	const char pszEnvVarBase, unsigned cGroups, const char const * papszGroups,
1996	uint32_t fDestFlags, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(8, 9);
1997
1998	/**
1999	* Create a logger instance.
2000	*
2001	* @returns iprt status code.
2002	*
2003	* @param ppLogger Where to store the logger instance.
2004	* @param pszEnvVarBase Base name for the environment variables for
2005	* this instance (ring-3 only).
2006	* @param fFlags Logger instance flags, a combination of the
2007	* RTLOGFLAGS_* values.
2008	* @param pszGroupSettings The initial group settings.
2009	* @param cGroups Number of groups in the array.
2010	* @param papszGroups Pointer to array of groups. This must stick
2011	* around for the life of the logger instance.
2012	* @param cMaxEntriesPerGroup The max number of entries per group. UINT32_MAX
2013	* or zero for unlimited.
2014	* @param cBufDescs Number of buffer descriptors that @a paBufDescs
2015	* points to. Zero for defaults.
2016	* @param paBufDescs Buffer descriptors, optional.
2017	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
2018	* if pszFilenameFmt specified.
2019	* @param pfnPhase Callback function for starting logging and for
2020	* ending or starting a new file for log history
2021	* rotation. NULL is OK.
2022	* @param cHistory Number of old log files to keep when performing
2023	* log history rotation. 0 means no history.
2024	* @param cbHistoryFileMax Maximum size of log file when performing
2025	* history rotation. 0 means no size limit.
2026	* @param cSecsHistoryTimeSlot Maximum time interval per log file when
2027	* performing history rotation, in seconds.
2028	* 0 means time limit.
2029	* @param pErrInfo Where to return extended error information.
2030	* Optional.
2031	* @param pszFilenameFmt Log filename format string. Standard RTStrFormat().
2032	* @param ... Format arguments.
2033	*/
2034	RTDECL(int) RTLogCreateEx(PRTLOGGER ppLogger, const char pszEnvVarBase, uint64_t fFlags, const char *pszGroupSettings,
2035	unsigned cGroups, const char * const *papszGroups, uint32_t cMaxEntriesPerGroup,
2036	uint32_t cBufDescs, PRTLOGBUFFERDESC paBufDescs, uint32_t fDestFlags,
2037	PFNRTLOGPHASE pfnPhase, uint32_t cHistory, uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot,
2038	PRTERRINFO pErrInfo, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(17, 18);
2039
2040	/**
2041	* Create a logger instance.
2042	*
2043	* @returns iprt status code.
2044	*
2045	* @param ppLogger Where to store the logger instance.
2046	* @param pszEnvVarBase Base name for the environment variables for
2047	* this instance (ring-3 only).
2048	* @param fFlags Logger instance flags, a combination of the
2049	* RTLOGFLAGS_* values.
2050	* @param pszGroupSettings The initial group settings.
2051	* @param cGroups Number of groups in the array.
2052	* @param papszGroups Pointer to array of groups. This must stick
2053	* around for the life of the logger instance.
2054	* @param cMaxEntriesPerGroup The max number of entries per group. UINT32_MAX
2055	* or zero for unlimited.
2056	* @param cBufDescs Number of buffer descriptors that @a paBufDescs
2057	* points to. Zero for defaults.
2058	* @param paBufDescs Buffer descriptors, optional.
2059	* @param fDestFlags The destination flags. RTLOGDEST_FILE is ORed
2060	* if pszFilenameFmt specified.
2061	* @param pfnPhase Callback function for starting logging and for
2062	* ending or starting a new file for log history
2063	* rotation.
2064	* @param cHistory Number of old log files to keep when performing
2065	* log history rotation. 0 means no history.
2066	* @param cbHistoryFileMax Maximum size of log file when performing
2067	* history rotation. 0 means no size limit.
2068	* @param cSecsHistoryTimeSlot Maximum time interval per log file when
2069	* performing history rotation, in seconds.
2070	* 0 means no time limit.
2071	* @param pErrInfo Where to return extended error information.
2072	* Optional.
2073	* @param pszFilenameFmt Log filename format string. Standard
2074	* RTStrFormat().
2075	* @param va Format arguments.
2076	*/
2077	RTDECL(int) RTLogCreateExV(PRTLOGGER ppLogger, const char pszEnvVarBase, uint64_t fFlags, const char *pszGroupSettings,
2078	uint32_t cGroups, const char * const *papszGroups, uint32_t cMaxEntriesPerGroup,
2079	uint32_t cBufDescs, PRTLOGBUFFERDESC paBufDescs, uint32_t fDestFlags,
2080	PFNRTLOGPHASE pfnPhase, uint32_t cHistory, uint64_t cbHistoryFileMax, uint32_t cSecsHistoryTimeSlot,
2081	PRTERRINFO pErrInfo, const char *pszFilenameFmt, va_list va) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(17, 0);
2082
2083	/**
2084	* Destroys a logger instance.
2085	*
2086	* The instance is flushed and all output destinations closed (where applicable).
2087	*
2088	* @returns iprt status code.
2089	* @param pLogger The logger instance which close destroyed. NULL is fine.
2090	*/
2091	RTDECL(int) RTLogDestroy(PRTLOGGER pLogger);
2092
2093	/**
2094	* Sets the custom prefix callback.
2095	*
2096	* @returns IPRT status code.
2097	* @param pLogger The logger instance.
2098	* @param pfnCallback The callback.
2099	* @param pvUser The user argument for the callback.
2100	* */
2101	RTDECL(int) RTLogSetCustomPrefixCallback(PRTLOGGER pLogger, PFNRTLOGPREFIX pfnCallback, void *pvUser);
2102
2103	/**
2104	* Sets the custom flush callback.
2105	*
2106	* This can be handy for special loggers like the per-EMT ones in ring-0,
2107	* but also for implementing a log viewer in the debugger GUI.
2108	*
2109	* @returns IPRT status code.
2110	* @retval VWRN_ALREADY_EXISTS if it was set to a different flusher.
2111	* @param pLogger The logger instance.
2112	* @param pfnFlush The flush callback.
2113	*/
2114	RTDECL(int) RTLogSetFlushCallback(PRTLOGGER pLogger, PFNRTLOGFLUSH pfnFlush);
2115
2116	/**
2117	* Sets the thread name for a thread specific ring-0 logger.
2118	*
2119	* @returns IPRT status code.
2120	* @param pLogger The logger. NULL is not allowed.
2121	* @param pszNameFmt The format string for the thread name.
2122	* @param ... Format arguments.
2123	*/
2124	RTR0DECL(int) RTLogSetR0ThreadNameF(PRTLOGGER pLogger, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2125
2126	/**
2127	* Sets the program start time for a thread specific ring-0 logger.
2128	*
2129	* @returns IPRT status code.
2130	* @param pLogger The logger. NULL is not allowed.
2131	* @param nsStart The RTTimeNanoTS() value at program start.
2132	*/
2133	RTR0DECL(int) RTLogSetR0ProgramStart(PRTLOGGER pLogger, uint64_t nsStart);
2134
2135	/**
2136	* Get the current log group settings as a string.
2137	*
2138	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2139	* @param pLogger Logger instance (NULL for default logger).
2140	* @param pszBuf The output buffer.
2141	* @param cchBuf The size of the output buffer. Must be greater than
2142	* zero.
2143	*/
2144	RTDECL(int) RTLogQueryGroupSettings(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2145
2146	/**
2147	* Updates the group settings for the logger instance using the specified
2148	* specification string.
2149	*
2150	* @returns iprt status code.
2151	* Failures can safely be ignored.
2152	* @param pLogger Logger instance (NULL for default logger).
2153	* @param pszValue Value to parse.
2154	*/
2155	RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszValue);
2156
2157	/**
2158	* Sets the max number of entries per group.
2159	*
2160	* @returns Old restriction.
2161	*
2162	* @param pLogger The logger instance (NULL is an alias for the
2163	* default logger).
2164	* @param cMaxEntriesPerGroup The max number of entries per group.
2165	*
2166	* @remarks Lowering the limit of an active logger may quietly mute groups.
2167	* Raising it may reactive already muted groups.
2168	*/
2169	RTDECL(uint32_t) RTLogSetGroupLimit(PRTLOGGER pLogger, uint32_t cMaxEntriesPerGroup);
2170
2171	/**
2172	* Gets the current flag settings for the given logger.
2173	*
2174	* @returns Logger flags, UINT64_MAX if no logger.
2175	* @param pLogger Logger instance (NULL for default logger).
2176	*/
2177	RTDECL(uint64_t) RTLogGetFlags(PRTLOGGER pLogger);
2178
2179	/**
2180	* Modifies the flag settings for the given logger.
2181	*
2182	* @returns IPRT status code. Returns VINF_LOG_NO_LOGGER if no default logger
2183	* and @a pLogger is NULL.
2184	* @param pLogger Logger instance (NULL for default logger).
2185	* @param fSet Mask of flags to set (OR).
2186	* @param fClear Mask of flags to clear (NAND). This is allowed to
2187	* include invalid flags - e.g. UINT64_MAX is okay.
2188	*/
2189	RTDECL(int) RTLogChangeFlags(PRTLOGGER pLogger, uint64_t fSet, uint64_t fClear);
2190
2191	/**
2192	* Updates the flags for the logger instance using the specified
2193	* specification string.
2194	*
2195	* @returns iprt status code.
2196	* Failures can safely be ignored.
2197	* @param pLogger Logger instance (NULL for default logger).
2198	* @param pszValue Value to parse.
2199	*/
2200	RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszValue);
2201
2202	/**
2203	* Changes the buffering setting of the specified logger.
2204	*
2205	* This can be used for optimizing longish logging sequences.
2206	*
2207	* @returns The old state.
2208	* @param pLogger The logger instance (NULL is an alias for the default
2209	* logger).
2210	* @param fBuffered The new state.
2211	*/
2212	RTDECL(bool) RTLogSetBuffering(PRTLOGGER pLogger, bool fBuffered);
2213
2214	/**
2215	* Get the current log flags as a string.
2216	*
2217	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2218	* @param pLogger Logger instance (NULL for default logger).
2219	* @param pszBuf The output buffer.
2220	* @param cchBuf The size of the output buffer. Must be greater than
2221	* zero.
2222	*/
2223	RTDECL(int) RTLogQueryFlags(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2224
2225	/**
2226	* Gets the current destinations flags for the given logger.
2227	*
2228	* @returns Logger destination flags, UINT32_MAX if no logger.
2229	* @param pLogger Logger instance (NULL for default logger).
2230	*/
2231	RTDECL(uint32_t) RTLogGetDestinations(PRTLOGGER pLogger);
2232
2233	/**
2234	* Modifies the log destinations settings for the given logger.
2235	*
2236	* This is only suitable for simple destination settings that doesn't take
2237	* additional arguments, like RTLOGDEST_FILE.
2238	*
2239	* @returns IPRT status code. Returns VINF_LOG_NO_LOGGER if no default logger
2240	* and @a pLogger is NULL.
2241	* @param pLogger Logger instance (NULL for default logger).
2242	* @param fSet Mask of destinations to set (OR).
2243	* @param fClear Mask of destinations to clear (NAND).
2244	*/
2245	RTDECL(int) RTLogChangeDestinations(PRTLOGGER pLogger, uint32_t fSet, uint32_t fClear);
2246
2247	/**
2248	* Updates the logger destination using the specified string.
2249	*
2250	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2251	* @param pLogger Logger instance (NULL for default logger).
2252	* @param pszValue The value to parse.
2253	*/
2254	RTDECL(int) RTLogDestinations(PRTLOGGER pLogger, char const *pszValue);
2255
2256	/**
2257	* Clear the file delay flag if set, opening the destination and flushing.
2258	*
2259	* @returns IPRT status code.
2260	* @param pLogger Logger instance (NULL for default logger).
2261	* @param pErrInfo Where to return extended error info. Optional.
2262	*/
2263	RTDECL(int) RTLogClearFileDelayFlag(PRTLOGGER pLogger, PRTERRINFO pErrInfo);
2264
2265	/**
2266	* Get the current log destinations as a string.
2267	*
2268	* @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.
2269	* @param pLogger Logger instance (NULL for default logger).
2270	* @param pszBuf The output buffer.
2271	* @param cchBuf The size of the output buffer. Must be greater than 0.
2272	*/
2273	RTDECL(int) RTLogQueryDestinations(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf);
2274
2275	/**
2276	* Performs a bulk update of logger flags and group flags.
2277	*
2278	* This is for instanced used for copying settings from ring-3 to ring-0
2279	* loggers.
2280	*
2281	* @returns IPRT status code.
2282	* @param pLogger The logger instance (NULL for default logger).
2283	* @param fFlags The new logger flags.
2284	* @param uGroupCrc32 The CRC32 of the group name strings.
2285	* @param cGroups Number of groups.
2286	* @param pafGroups Array of group flags.
2287	* @sa RTLogQueryBulk
2288	*/
2289	RTDECL(int) RTLogBulkUpdate(PRTLOGGER pLogger, uint64_t fFlags, uint32_t uGroupCrc32, uint32_t cGroups, uint32_t const *pafGroups);
2290
2291	/**
2292	* Queries data for a bulk update of logger flags and group flags.
2293	*
2294	* This is for instanced used for copying settings from ring-3 to ring-0
2295	* loggers.
2296	*
2297	* @returns IPRT status code.
2298	* @retval VERR_BUFFER_OVERFLOW if pafGroups is too small, @a pcGroups will be
2299	* set to the actual number of groups.
2300	* @param pLogger The logger instance (NULL for default logger).
2301	* @param pfFlags Where to return the logger flags.
2302	* @param puGroupCrc32 Where to return the CRC32 of the group names.
2303	* @param pcGroups Input: Size of the @a pafGroups allocation.
2304	* Output: Actual number of groups returned.
2305	* @param pafGroups Where to return the flags for each group.
2306	* @sa RTLogBulkUpdate
2307	*/
2308	RTDECL(int) RTLogQueryBulk(PRTLOGGER pLogger, uint64_t pfFlags, uint32_t puGroupCrc32, uint32_t pcGroups, uint32_t pafGroups);
2309
2310	/**
2311	* Write/copy bulk log data from another logger.
2312	*
2313	* This is used for transferring stuff from the ring-0 loggers and into the
2314	* ring-3 one. The text goes in as-is w/o any processing (i.e. prefixing or
2315	* newline fun).
2316	*
2317	* @returns IRPT status code.
2318	* @param pLogger The logger instance (NULL for default logger).
2319	* @param pch Pointer to the block of bulk log text to write.
2320	* @param cch Size of the block of bulk log text to write.
2321	*/
2322	RTDECL(int) RTLogBulkWrite(PRTLOGGER pLogger, const char *pch, size_t cch);
2323
2324	/**
2325	* Flushes the specified logger.
2326	*
2327	* @returns IRPT status code.
2328	* @param pLogger The logger instance to flush.
2329	* If NULL the default instance is used. The default instance
2330	* will not be initialized by this call.
2331	*/
2332	RTDECL(int) RTLogFlush(PRTLOGGER pLogger);
2333
2334	/**
2335	* Write to a logger instance.
2336	*
2337	* @param pLogger Pointer to logger instance.
2338	* @param pvCallerRet Ignored.
2339	* @param pszFormat Format string.
2340	* @param ... Format arguments.
2341	*/
2342	RTDECL(void) RTLogLogger(PRTLOGGER pLogger, void pvCallerRet, const char pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
2343
2344	/**
2345	* Write to a logger instance.
2346	*
2347	* @param pLogger Pointer to logger instance.
2348	* @param pszFormat Format string.
2349	* @param args Format arguments.
2350	*/
2351	RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2352
2353	/**
2354	* Write to a logger instance.
2355	*
2356	* This function will check whether the instance, group and flags makes up a
2357	* logging kind which is currently enabled before writing anything to the log.
2358	*
2359	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
2360	* @param fFlags The logging flags.
2361	* @param iGroup The group.
2362	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
2363	* only for internal usage!
2364	* @param pszFormat Format string.
2365	* @param ... Format arguments.
2366	* @remark This is a worker function of LogIt.
2367	*/
2368	RTDECL(void) RTLogLoggerEx(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
2369	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
2370
2371	/**
2372	* Write to a logger instance.
2373	*
2374	* This function will check whether the instance, group and flags makes up a
2375	* logging kind which is currently enabled before writing anything to the log.
2376	*
2377	* @returns VINF_SUCCESS, VINF_LOG_NO_LOGGER, VINF_LOG_DISABLED, or IPRT error
2378	* status.
2379	* @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.
2380	* @param fFlags The logging flags.
2381	* @param iGroup The group.
2382	* The value ~0U is reserved for compatibility with RTLogLogger[V] and is
2383	* only for internal usage!
2384	* @param pszFormat Format string.
2385	* @param args Format arguments.
2386	*/
2387	RTDECL(int) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup,
2388	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(4, 0);
2389
2390	/**
2391	* printf like function for writing to the default log.
2392	*
2393	* @param pszFormat Printf like format string.
2394	* @param ... Optional arguments as specified in pszFormat.
2395	*
2396	* @remark The API doesn't support formatting of floating point numbers at the moment.
2397	*/
2398	RTDECL(void) RTLogPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2399
2400	/**
2401	* vprintf like function for writing to the default log.
2402	*
2403	* @param pszFormat Printf like format string.
2404	* @param va Optional arguments as specified in pszFormat.
2405	*
2406	* @remark The API doesn't support formatting of floating point numbers at the moment.
2407	*/
2408	RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
2409
2410	/**
2411	* Dumper vprintf-like function outputting to a logger.
2412	*
2413	* @param pvUser Pointer to the logger instance to use, NULL for default
2414	* instance.
2415	* @param pszFormat Format string.
2416	* @param va Format arguments.
2417	*/
2418	RTDECL(void) RTLogDumpPrintfV(void pvUser, const char pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
2419
2420
2421	#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/string.h & iprt/errcore.h */
2422	#define DECLARED_FNRTSTROUTPUT
2423	/**
2424	* Output callback.
2425	*
2426	* @returns number of bytes written.
2427	* @param pvArg User argument.
2428	* @param pachChars Pointer to an array of utf-8 characters.
2429	* @param cbChars Number of bytes in the character array pointed to by pachChars.
2430	*/
2431	typedef DECLCALLBACKTYPE(size_t, FNRTSTROUTPUT,(void pvArg, const char pachChars, size_t cbChars));
2432	/** Pointer to callback function. */
2433	typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
2434	#endif
2435
2436	/**
2437	* Partial vsprintf worker implementation.
2438	*
2439	* @returns number of bytes formatted.
2440	* @param pfnOutput Output worker.
2441	* Called in two ways. Normally with a string an it's length.
2442	* For termination, it's called with NULL for string, 0 for length.
2443	* @param pvArg Argument to output worker.
2444	* @param pszFormat Format string.
2445	* @param args Argument list.
2446	*/
2447	RTDECL(size_t) RTLogFormatV(PFNRTSTROUTPUT pfnOutput, void pvArg, const char pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2448
2449	/**
2450	* Write log buffer to COM port.
2451	*
2452	* @param pach Pointer to the buffer to write.
2453	* @param cb Number of bytes to write.
2454	*/
2455	RTDECL(void) RTLogWriteCom(const char *pach, size_t cb);
2456
2457	/**
2458	* Prints a formatted string to the serial port used for logging.
2459	*
2460	* @returns Number of bytes written.
2461	* @param pszFormat Format string.
2462	* @param ... Optional arguments specified in the format string.
2463	*/
2464	RTDECL(size_t) RTLogComPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2465
2466	/**
2467	* Prints a formatted string to the serial port used for logging.
2468	*
2469	* @returns Number of bytes written.
2470	* @param pszFormat Format string.
2471	* @param args Optional arguments specified in the format string.
2472	*/
2473	RTDECL(size_t) RTLogComPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
2474
2475	/**
2476	* Write log buffer to a debugger (RTLOGDEST_DEBUGGER).
2477	*
2478	* @param pach What to write.
2479	* @param cb How much to write.
2480	* @remark When linking statically, this function can be replaced by defining your own.
2481	*/
2482	RTDECL(void) RTLogWriteDebugger(const char *pach, size_t cb);
2483
2484	/**
2485	* Write log buffer to a user defined output stream (RTLOGDEST_USER).
2486	*
2487	* @param pach What to write.
2488	* @param cb How much to write.
2489	* @remark When linking statically, this function can be replaced by defining your own.
2490	*/
2491	RTDECL(void) RTLogWriteUser(const char *pach, size_t cb);
2492
2493	/**
2494	* Write log buffer to stdout (RTLOGDEST_STDOUT).
2495	*
2496	* @param pach What to write.
2497	* @param cb How much to write.
2498	* @remark When linking statically, this function can be replaced by defining your own.
2499	*/
2500	RTDECL(void) RTLogWriteStdOut(const char *pach, size_t cb);
2501
2502	/**
2503	* Write log buffer to stdout (RTLOGDEST_STDERR).
2504	*
2505	* @param pach What to write.
2506	* @param cb How much to write.
2507	* @remark When linking statically, this function can be replaced by defining your own.
2508	*/
2509	RTDECL(void) RTLogWriteStdErr(const char *pach, size_t cb);
2510
2511	#ifdef VBOX
2512
2513	/**
2514	* Prints a formatted string to the backdoor port.
2515	*
2516	* @returns Number of bytes written.
2517	* @param pszFormat Format string.
2518	* @param ... Optional arguments specified in the format string.
2519	*/
2520	RTDECL(size_t) RTLogBackdoorPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
2521
2522	/**
2523	* Prints a formatted string to the backdoor port.
2524	*
2525	* @returns Number of bytes written.
2526	* @param pszFormat Format string.
2527	* @param args Optional arguments specified in the format string.
2528	*/
2529	RTDECL(size_t) RTLogBackdoorPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
2530
2531	#endif /* VBOX */
2532
2533	RT_C_DECLS_END
2534
2535	/** @} */
2536
2537	#endif /* !IPRT_INCLUDED_log_h */
2538

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

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

Download in other formats: