1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3// Qt-Security score:significant reason:default
4
5#include "qloggingcategory.h"
6#include "qloggingcategory_p.h"
7#include "qloggingregistry_p.h"
8
9QT_BEGIN_NAMESPACE
10
11/*!
12 \class QLoggingCategory
13 \inmodule QtCore
14 \since 5.2
15 \threadsafe
16
17 \brief The QLoggingCategory class represents a category, or 'area' in the
18 logging infrastructure.
19
20 QLoggingCategory represents a certain logging category - identified by a
21 string - at runtime. A category can be configured to enable or disable
22 logging of messages per message type. An exception are fatal messages,
23 which are always enabled.
24
25 To check whether a message type is enabled or not, use one of these methods:
26 \l isDebugEnabled(), \l isInfoEnabled(), \l isWarningEnabled(), and
27 \l isCriticalEnabled().
28
29 All objects are meant to be configured by a common registry, as described in
30 \l{Configuring Categories}. Different objects can also represent the same
31 category. Therefore, it's \b{not} recommended to export objects across
32 module boundaries, to manipulate the objects directly, or to inherit from
33 QLoggingCategory.
34
35 \section1 Creating Category Objects
36
37 The Q_DECLARE_LOGGING_CATEGORY() and Q_LOGGING_CATEGORY() macros
38 conveniently declare and create QLoggingCategory objects:
39
40 \snippet qloggingcategory/main.cpp 1
41
42 There is also the Q_DECLARE_EXPORTED_LOGGING_CATEGORY() macro in
43 order to use a logging category across library boundaries.
44
45 Category names are free text; to configure categories using \l{Logging Rules}, their
46 names should follow this convention:
47 \list
48 \li Use letters and numbers only.
49 \li Use dots to further structure categories into common areas.
50 \li Avoid the category names: \c{debug}, \c{info}, \c{warning}, and \c{critical}.
51 \li Category names with the \c{qt} prefix are solely reserved for Qt modules.
52 \endlist
53
54 QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY()
55 are created on first use, in a thread-safe manner.
56
57 \section1 Checking Category Configuration
58
59 QLoggingCategory provides \l isDebugEnabled(), \l isInfoEnabled(),
60 \l isWarningEnabled(), \l isCriticalEnabled(), as well as \l isEnabled()
61 to check whether messages for the given message type should be logged.
62
63 The qCDebug(), qCWarning(), and qCCritical() macros prevent arguments from
64 being evaluated if the respective message types are not enabled for the
65 category, so explicit checking is not needed:
66
67 \snippet qloggingcategory/main.cpp 4
68
69 \section1 Default Category Configuration
70
71 Both the QLoggingCategory constructor and the Q_LOGGING_CATEGORY() macro
72 accept an optional QtMsgType argument, which disables all message types with
73 a lower severity. That is, a category declared with
74
75 \snippet qloggingcategory/main.cpp 5
76
77 logs messages of type \c QtWarningMsg, \c QtCriticalMsg, \c QtFatalMsg, but
78 ignores messages of type \c QtDebugMsg and \c QtInfoMsg.
79
80 If no argument is passed, all messages are logged. Only Qt internal categories
81 which start with \c{qt} are handled differently: For these, only messages of type
82 \c QtInfoMsg, \c QtWarningMsg, \c QtCriticalMsg, and \c QFatalMsg are logged by default.
83
84 \note Logging categories are not affected by your C++ build configuration.
85 That is, whether messages are printed does not change depending on whether
86 the code is compiled with debug symbols ('Debug Build'), optimizations
87 ('Release Build'), or some other combination.
88
89 \section1 Configuring Categories
90
91 You can override the default configuration for categories either by setting
92 logging rules, or by installing a custom filter.
93
94 \section2 Logging Rules
95
96 Logging rules let you enable or disable logging for categories in a flexible
97 way. Rules are specified in text, where every line must have the format:
98
99 \snippet code/src_corelib_io_qloggingcategory.cpp 0
100
101 \c <category> is the name of the category, potentially with \c{*} as a
102 wildcard symbol for the first or last character; or at both positions.
103 The optional \c <type> must be \c debug, \c info, \c warning, or \c critical.
104 Lines that don't fit this scheme are ignored.
105
106 Rules are evaluated in text order, from first to last. That is, if two rules
107 apply to a category/type, the rule that comes later is applied.
108
109 Rules can be set via \l setFilterRules():
110
111 \snippet code/src_corelib_io_qloggingcategory.cpp 1
112
113 Logging rules are automatically loaded from the \c [Rules] section in a logging
114 configuration file. These configuration files are looked up in the QtProject
115 configuration directory, or explicitly set in a \c QT_LOGGING_CONF environment
116 variable:
117
118 \snippet code/src_corelib_io_qloggingcategory.cpp 2
119
120 Logging rules can also be specified in a \c QT_LOGGING_RULES environment variable;
121 multiple rules can also be separated by semicolons:
122
123 \snippet code/src_corelib_io_qloggingcategory.cpp 3
124
125 Rules set by \l setFilterRules() take precedence over rules specified in the
126 QtProject configuration directory. In turn, these rules can be overwritten by those
127 from the configuration file specified by \c QT_LOGGING_CONF, and those set by
128 \c QT_LOGGING_RULES.
129
130 The order of evaluation is as follows:
131 \list 1
132 \li [QLibraryInfo::DataPath]/qtlogging.ini
133 \li QtProject/qtlogging.ini
134 \li \l setFilterRules()
135 \li \c QT_LOGGING_CONF
136 \li \c QT_LOGGING_RULES
137 \endlist
138
139 The \c QtProject/qtlogging.ini file is looked up in all directories returned
140 by QStandardPaths::GenericConfigLocation.
141
142 Set the \c QT_LOGGING_DEBUG environment variable to find out where your logging
143 rules are loaded from.
144
145 \section2 Installing a Custom Filter
146
147 As a lower-level alternative to the text rules, you can also implement a
148 custom filter via \l installFilter(). All filter rules are ignored in this
149 case.
150
151 \section1 Printing the Category
152
153 Use the \c %{category} placeholder to print the category in the default
154 message handler:
155
156 \snippet qloggingcategory/main.cpp 3
157*/
158
159/*!
160 Constructs a QLoggingCategory object with the provided \a category name,
161 and enables all messages with types at least as verbose as \a enableForLevel,
162 which defaults to QtDebugMsg (which enables all categories).
163
164 If \a category is \nullptr, the category name \c "default" is used.
165
166 \note \a category must be kept valid during the lifetime of this object.
167 Using a string literal for it is the usual way to achieve this.
168
169 \since 5.4
170*/
171QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)
172 : QLoggingCategory(UnregisteredInitialization{},
173 category ? category : QLoggingRegistry::defaultCategoryName)
174{
175 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
176 reg->registerCategory(category: this, enableForLevel);
177}
178
179/*!
180 Destroys a QLoggingCategory object.
181*/
182QLoggingCategory::~QLoggingCategory()
183{
184 // Note: this destructor is never called for the defaultCategory(), so it
185 // is always registered. If we ever need to free memory, make
186 // QLoggingRegistry do it.
187 if (QLoggingRegistry *reg = QLoggingRegistry::instance())
188 reg->unregisterCategory(category: this);
189}
190
191/*!
192 \fn const char *QLoggingCategory::categoryName() const
193
194 Returns the name of the category.
195*/
196
197/*!
198 \fn bool QLoggingCategory::isDebugEnabled() const
199
200 Returns \c true if debug messages should be shown for this category;
201 \c false otherwise.
202
203 \note The \l qCDebug() macro already does this check before running any
204 code. However, calling this method may be useful to avoid the
205 expensive generation of data for debug output only.
206*/
207
208
209/*!
210 \fn bool QLoggingCategory::isInfoEnabled() const
211
212 Returns \c true if informational messages should be shown for this category;
213 \c false otherwise.
214
215 \note The \l qCInfo() macro already does this check before executing any
216 code. However, calling this method may be useful to avoid the
217 expensive generation of data for debug output only.
218
219 \since 5.5
220*/
221
222
223/*!
224 \fn bool QLoggingCategory::isWarningEnabled() const
225
226 Returns \c true if warning messages should be shown for this category;
227 \c false otherwise.
228
229 \note The \l qCWarning() macro already does this check before executing any
230 code. However, calling this method may be useful to avoid the
231 expensive generation of data for debug output only.
232*/
233
234/*!
235 \fn bool QLoggingCategory::isCriticalEnabled() const
236
237 Returns \c true if critical messages should be shown for this category;
238 \c false otherwise.
239
240 \note The \l qCCritical() macro already does this check before executing any
241 code. However, calling this method may be useful to avoid the
242 expensive generation of data for debug output only.
243*/
244
245/*!
246 Returns \c true if a message of type \a msgtype for the category should be
247 shown; \c false otherwise.
248*/
249bool QLoggingCategory::isEnabled(QtMsgType msgtype) const
250{
251 switch (msgtype) {
252 case QtDebugMsg: return isDebugEnabled();
253 case QtInfoMsg: return isInfoEnabled();
254 case QtWarningMsg: return isWarningEnabled();
255 case QtCriticalMsg: return isCriticalEnabled();
256 case QtFatalMsg: return true;
257 }
258 return false;
259}
260
261/*!
262 Changes the message type \a type for the category to \a enable.
263
264 This method is meant for use only from inside a filter installed with
265 \l installFilter(). For an overview on how to configure categories globally,
266 see \l {Configuring Categories}.
267
268 \note \c QtFatalMsg cannot be changed; it will always remain \c true.
269*/
270void QLoggingCategory::setEnabled(QtMsgType type, bool enable)
271{
272 switch (type) {
273 case QtDebugMsg: bools.enabledDebug.storeRelaxed(newValue: enable); break;
274 case QtInfoMsg: bools.enabledInfo.storeRelaxed(newValue: enable); break;
275 case QtWarningMsg: bools.enabledWarning.storeRelaxed(newValue: enable); break;
276 case QtCriticalMsg: bools.enabledCritical.storeRelaxed(newValue: enable); break;
277 case QtFatalMsg: break;
278 }
279}
280
281/*!
282 \fn QLoggingCategory &QLoggingCategory::operator()()
283
284 Returns the object itself. This allows for both: a QLoggingCategory variable, and
285 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
286 \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.
287 */
288
289/*!
290 \fn const QLoggingCategory &QLoggingCategory::operator()() const
291
292 Returns the object itself. This allows for both: a QLoggingCategory variable, and
293 a factory method that returns a QLoggingCategory, to be used in \l qCDebug(),
294 \l qCWarning(), \l qCCritical(), or \l qCFatal() macros.
295 */
296
297/*!
298 Returns a pointer to the global category \c "default" that is used, for
299 example, by qDebug(), qInfo(), qWarning(), qCritical(), or qFatal().
300
301 \note The pointer returned may be null during destruction of static objects.
302 Also, don't \c delete this pointer, as ownership of the category isn't transferred.
303
304 */
305QLoggingCategory *QLoggingCategory::defaultCategory()
306{
307 return QLoggingRegistry::defaultCategory();
308}
309
310/*!
311 \typedef QLoggingCategory::CategoryFilter
312
313 This is a typedef for a pointer to a function with the following signature:
314
315 \snippet qloggingcategory/main.cpp 20
316
317 A function with this signature can be installed with \l installFilter().
318*/
319
320/*!
321 \brief Take control of how logging categories are configured.
322
323 Installs a function \a filter that is used to determine which categories and
324 message types should be enabled. If \a filter is \nullptr, the default
325 message filter is reinstated. Returns a pointer to the previously-installed
326 filter.
327
328 Every QLoggingCategory object that already exists is passed to the filter
329 before \c installFilter() returns, and the filter is free to change each
330 category's configuration with \l setEnabled(). Any category it doesn't
331 change will retain the configuration it was given by the prior filter, so
332 the new filter does not need to delegate to the prior filter during this
333 initial pass over existing categories.
334
335 Any new categories added later will be passed to the new filter; a filter
336 that only aims to tweak the configuration of a select few categories, rather
337 than completely overriding the logging policy, can first pass the new
338 category to the prior filter, to give it its standard configuration, and
339 then tweak that as desired, if it is one of the categories of specific
340 interest to the filter. The code that installs the new filter can record the
341 return from \c installFilter() for the filter to use in such later calls.
342
343 When you define your filter, note that it can be called from different threads; but never
344 concurrently. This filter cannot call any static functions from QLoggingCategory.
345
346 Example:
347 \snippet qloggingcategory/main.cpp 21
348
349 installed (in \c{main()}, for example) by
350
351 \snippet qloggingcategory/main.cpp 22
352
353 Alternatively, you can configure the default filter via \l setFilterRules().
354 */
355QLoggingCategory::CategoryFilter
356QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
357{
358 return QLoggingRegistry::instance()->installFilter(filter);
359}
360
361/*!
362 Configures which categories and message types should be enabled through a
363 set of \a rules.
364
365 Example:
366
367 \snippet qloggingcategory/main.cpp 2
368
369 \note The rules might be ignored if a custom category filter is installed
370 with \l installFilter(), or if the user has defined the \c QT_LOGGING_CONF
371 or the \c QT_LOGGING_RULES environment variable.
372*/
373void QLoggingCategory::setFilterRules(const QString &rules)
374{
375 QLoggingRegistry::instance()->setApiRules(rules);
376}
377
378/*!
379 \macro qCDebug(category)
380 \relates QLoggingCategory
381 \threadsafe
382 \since 5.2
383
384 Returns an output stream for debug messages in the logging category,
385 \a category.
386
387 The macro expands to code that checks whether
388 \l QLoggingCategory::isDebugEnabled() evaluates to \c true.
389 If so, the stream arguments are processed and sent to the message handler.
390
391 Example:
392
393 \snippet qloggingcategory/main.cpp 10
394
395 \note Arguments aren't processed if the debug output for that \a category is not
396 enabled, so don't rely on any side effects.
397
398 \sa QDebug::qDebug()
399*/
400
401/*!
402 \macro qCDebug(category, const char *message, ...)
403 \relates QLoggingCategory
404 \threadsafe
405 \since 5.3
406
407 Logs a debug message, \a message, in the logging category, \a category.
408 \a message may contain place holders to be replaced by additional arguments,
409 similar to the C printf() function.
410
411 Example:
412
413 \snippet qloggingcategory/main.cpp 13
414
415 \note Arguments aren't processed if the debug output for that \a category is not
416 enabled, so don't rely on any side effects.
417
418 \sa qDebug(const char *, ...)
419*/
420
421/*!
422 \macro qCInfo(category)
423 \relates QLoggingCategory
424 \threadsafe
425 \since 5.5
426
427 Returns an output stream for informational messages in the logging category,
428 \a category.
429
430 The macro expands to code that checks whether
431 \l QLoggingCategory::isInfoEnabled() evaluates to \c true.
432 If so, the stream arguments are processed and sent to the message handler.
433
434 Example:
435
436 \snippet qloggingcategory/main.cpp qcinfo_stream
437
438 \note If the debug output for a particular category isn't enabled, arguments
439 won't be processed, so don't rely on any side effects.
440
441 \sa QDebug::qInfo()
442*/
443
444/*!
445 \macro qCInfo(category, const char *message, ...)
446 \relates QLoggingCategory
447 \threadsafe
448 \since 5.5
449
450 Logs an informational message, \a message, in the logging category, \a category.
451 \a message may contain place holders to be replaced by additional arguments,
452 similar to the C printf() function.
453
454 Example:
455
456 \snippet qloggingcategory/main.cpp qcinfo_printf
457
458 \note If the debug output for a particular category isn't enabled, arguments
459 won't be processed, so don't rely on any side effects.
460
461 \sa qInfo(const char *, ...)
462*/
463
464/*!
465 \macro qCWarning(category)
466 \relates QLoggingCategory
467 \threadsafe
468 \since 5.2
469
470 Returns an output stream for warning messages in the logging category,
471 \a category.
472
473 The macro expands to code that checks whether
474 \l QLoggingCategory::isWarningEnabled() evaluates to \c true.
475 If so, the stream arguments are processed and sent to the message handler.
476
477 Example:
478
479 \snippet qloggingcategory/main.cpp 11
480
481 \note If the warning output for a particular category isn't enabled, arguments
482 won't be processed, so don't rely on any side effects.
483
484 \sa QDebug::qWarning()
485*/
486
487/*!
488 \macro qCWarning(category, const char *message, ...)
489 \relates QLoggingCategory
490 \threadsafe
491 \since 5.3
492
493 Logs a warning message, \a message, in the logging category, \a category.
494 \a message may contain place holders to be replaced by additional arguments,
495 similar to the C printf() function.
496
497 Example:
498
499 \snippet qloggingcategory/main.cpp 14
500
501 \note If the warning output for a particular category isn't enabled, arguments
502 won't be processed, so don't rely on any side effects.
503
504 \sa qWarning(const char *, ...)
505*/
506
507/*!
508 \macro qCCritical(category)
509 \relates QLoggingCategory
510 \threadsafe
511 \since 5.2
512
513 Returns an output stream for critical messages in the logging category,
514 \a category.
515
516 The macro expands to code that checks whether
517 \l QLoggingCategory::isCriticalEnabled() evaluates to \c true.
518 If so, the stream arguments are processed and sent to the message handler.
519
520 Example:
521
522 \snippet qloggingcategory/main.cpp 12
523
524
525 \note If the critical output for a particular category isn't enabled, arguments
526 won't be processed, so don't rely on any side effects.
527
528 \sa QDebug::qCritical()
529*/
530
531/*!
532 \macro qCCritical(category, const char *message, ...)
533 \relates QLoggingCategory
534 \threadsafe
535 \since 5.3
536
537 Logs a critical message, \a message, in the logging category, \a category.
538 \a message may contain place holders to be replaced by additional arguments,
539 similar to the C printf() function.
540
541 Example:
542
543 \snippet qloggingcategory/main.cpp 15
544
545 \note If the critical output for a particular category isn't enabled, arguments
546 won't be processed, so don't rely on any side effects.
547
548 \sa qCritical(const char *, ...)
549*/
550
551/*!
552 \macro qCFatal(category)
553 \relates QLoggingCategory
554 \since 6.5
555
556 Returns an output stream for fatal messages in the logging category,
557 \a category.
558
559 If you are using the \b{default message handler}, the returned stream will abort
560 to create a core dump. On Windows, for debug builds, this function will
561 report a \c _CRT_ERROR enabling you to connect a debugger to the application.
562
563 Example:
564
565 \snippet qloggingcategory/main.cpp 16
566
567 \sa QDebug::qFatal()
568*/
569
570/*!
571 \macro qCFatal(category, const char *message, ...)
572 \relates QLoggingCategory
573 \since 6.5
574
575 Logs a fatal message, \a message, in the logging category, \a category.
576 \a message may contain place holders to be replaced by additional arguments,
577 similar to the C printf() function.
578
579 Example:
580
581 \snippet qloggingcategory/main.cpp 17
582
583 If you are using the \b{default message handler}, this function will abort
584 to create a core dump. On Windows, for debug builds, this function will
585 report a \c _CRT_ERROR enabling you to connect a debugger to the application.
586
587 \sa qFatal(const char *, ...)
588*/
589
590/*!
591 \macro Q_DECLARE_LOGGING_CATEGORY(name)
592 \sa Q_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
593 \relates QLoggingCategory
594 \since 5.2
595
596 Declares a logging category \a name. The macro can be used to declare
597 a common logging category shared in different parts of the program.
598
599 This macro must be used outside of a class or method.
600*/
601
602/*!
603 \macro Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)
604 \sa Q_LOGGING_CATEGORY(), Q_DECLARE_LOGGING_CATEGORY()
605 \relates QLoggingCategory
606 \since 6.5
607
608 Declares a logging category \a name. The macro can be used to declare
609 a common logging category shared in different parts of the program.
610
611 This works exactly like Q_DECLARE_LOGGING_CATEGORY(). However,
612 the logging category declared by this macro is additionally
613 qualified with \a EXPORT_MACRO. This is useful if the logging
614 category needs to be exported from a dynamic library.
615
616 For example:
617
618 \code
619 Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)
620 \endcode
621
622 This macro must be used outside of a class or function.
623*/
624
625/*!
626 \macro Q_LOGGING_CATEGORY(name, string)
627 \sa Q_DECLARE_LOGGING_CATEGORY(), Q_DECLARE_EXPORTED_LOGGING_CATEGORY()
628 \relates QLoggingCategory
629 \since 5.2
630
631 Defines a logging category \a name, and makes it configurable under the
632 \a string identifier. By default, all message types are enabled.
633
634 Only one translation unit in a library or executable can define a category
635 with a specific name. The implicitly-defined QLoggingCategory object is
636 created on first use, in a thread-safe manner.
637
638 This macro must be used outside of a class or method.
639*/
640
641/*!
642 \macro Q_LOGGING_CATEGORY(name, string, msgType)
643 \sa Q_DECLARE_LOGGING_CATEGORY()
644 \relates QLoggingCategory
645 \since 5.4
646
647 Defines a logging category \a name, and makes it configurable under the
648 \a string identifier. By default, messages of QtMsgType \a msgType
649 and more severe are enabled, types with a lower severity are disabled.
650
651 Only one translation unit in a library or executable can define a category
652 with a specific name. The implicitly-defined QLoggingCategory object is
653 created on first use, in a thread-safe manner.
654
655 This macro must be used outside of a class or method.
656*/
657
658/*!
659 \macro Q_STATIC_LOGGING_CATEGORY(name, string)
660 \sa Q_LOGGING_CATEGORY()
661 \relates QLoggingCategory
662 \since 6.9
663
664 Defines a static logging category \a name, and makes it configurable under
665 the \a string identifier. By default, all message types are enabled.
666
667 The logging category is created using the \c static qualifier so that you
668 can only access it in the same translation unit. This avoids accidental
669 symbol clashes.
670
671 The implicitly-defined QLoggingCategory object is created on first use,
672 in a thread-safe manner.
673
674 This macro must be used outside of a class or method.
675*/
676
677/*!
678 \macro Q_STATIC_LOGGING_CATEGORY(name, string, msgType)
679 \sa Q_LOGGING_CATEGORY()
680 \relates QLoggingCategory
681 \since 6.9
682
683 Defines a static logging category \a name, and makes it configurable under
684 the \a string identifier. By default, messages of QtMsgType \a msgType and
685 more severe are enabled, types with a lower severity are disabled.
686
687 The logging category is created using the \c static qualifier so that you
688 can only access it in the same translation unit. This avoids accidental
689 symbol clashes.
690
691 The implicitly-defined QLoggingCategory object is created on first use, in
692 a thread-safe manner.
693
694 This macro must be used outside of a class or method.
695*/
696
697QT_END_NAMESPACE
698

source code of qtbase/src/corelib/io/qloggingcategory.cpp