1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Improve description of QT_FATAL_ environment vars

Browse Source 
Much like QT_FATAL_WARNINGS, QT_FATAL_CRITICALS also is
interpreted as a counter. Revamp both function descriptions
to make scope and purpose clearer.

Also, mention logging rules as a way to surpress output,
in addition to a custom message hander.

Pick-to: 6.5 6.6
Change-Id: I44767abb067a6accd81f13dc549c9787ef9a4729
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
Kai Köhne 2023-07-05 11:23:39 +02:00
parent 06d520dbef
commit 62e3fa28d7
1 changed files with 28 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
src/corelib/global/qlogging.cpp
View File

@ -2378,13 +2378,7 @@ QMessageLogContext &QMessageLogContext::copyContextFrom(const QMessageLogContext
Calls the message handler with the warning message \a message. If no Calls the message handler with the warning message \a message. If no
message handler has been installed, the message is printed to message handler has been installed, the message is printed to
stderr. Under Windows, the message is sent to the debugger. stderr. Under Windows, the message is sent to the debugger.
On QNX the message is sent to slogger2. This On QNX the message is sent to slogger2.
function does nothing if \c QT_NO_WARNING_OUTPUT was defined
during compilation; it exits if at the nth warning corresponding to the
counter in environment variable \c QT_FATAL_WARNINGS. That is, if the
environment variable contains the value 1, it will exit on the 1st message;
if it contains the value 10, it will exit on the 10th message. Any
non-numeric value is equivalent to 1.
This function takes a format string and a list of arguments, This function takes a format string and a list of arguments,
similar to the C printf() function. The format should be a Latin-1 similar to the C printf() function. The format should be a Latin-1
@ -2401,8 +2395,20 @@ QMessageLogContext &QMessageLogContext::copyContextFrom(const QMessageLogContext
This syntax inserts a space between each item, and This syntax inserts a space between each item, and
appends a newline at the end. appends a newline at the end.
To suppress the output at runtime, install your own message handler This function does nothing if \c QT_NO_WARNING_OUTPUT was defined
with qInstallMessageHandler(). during compilation.
To suppress the output at runtime, you can set
\l{QLoggingCategory}{logging rules} or register a custom
\l{QLoggingCategory::installFilter()}{filter}.
For debugging purposes, it is sometimes convenient to let the
program abort for warning messages. This allows you then
to inspect the core dump, or attach a debugger - see also \l{qFatal()}.
To enable this, set the environment variable \c{QT_FATAL_WARNINGS}
to a number \c n. The program terminates then for the n-th warning.
That is, if the environment variable is set to 1, it will terminate
on the first call; if it contains the value 10, it will exit on the 10th
call. Any non-numeric value in the environment variable is equivalent to 1.
\sa qDebug(), qInfo(), qCritical(), qFatal(), qInstallMessageHandler(), \sa qDebug(), qInfo(), qCritical(), qFatal(), qInstallMessageHandler(),
{Debugging Techniques} {Debugging Techniques}
@ -2418,8 +2424,6 @@ QMessageLogContext &QMessageLogContext::copyContextFrom(const QMessageLogContext
stderr. Under Windows, the message is sent to the debugger. stderr. Under Windows, the message is sent to the debugger.
On QNX the message is sent to slogger2. On QNX the message is sent to slogger2.
It exits if the environment variable QT_FATAL_CRITICALS is not empty.
This function takes a format string and a list of arguments, This function takes a format string and a list of arguments,
similar to the C printf() function. The format should be a Latin-1 similar to the C printf() function. The format should be a Latin-1
string. string.
@ -2435,8 +2439,19 @@ QMessageLogContext &QMessageLogContext::copyContextFrom(const QMessageLogContext
A space is inserted between the items, and a newline is A space is inserted between the items, and a newline is
appended at the end. appended at the end.
To suppress the output at runtime, install your own message handler To suppress the output at runtime, you can define
with qInstallMessageHandler(). \l{QLoggingCategory}{logging rules} or register a custom
\l{QLoggingCategory::installFilter()}{filter}.
For debugging purposes, it is sometimes convenient to let the
program abort for critical messages. This allows you then
to inspect the core dump, or attach a debugger - see also \l{qFatal()}.
To enable this, set the environment variable \c{QT_FATAL_CRITICALS}
to a number \c n. The program terminates then for the n-th critical
message.
That is, if the environment variable is set to 1, it will terminate
on the first call; if it contains the value 10, it will exit on the 10th
call. Any non-numeric value in the environment variable is equivalent to 1.
\sa qDebug(), qInfo(), qWarning(), qFatal(), qInstallMessageHandler(), \sa qDebug(), qInfo(), qWarning(), qFatal(), qInstallMessageHandler(),
{Debugging Techniques} {Debugging Techniques}