color: #000;
font-family: "Times Roman", times, serif;
}
- ul.blacklist li {
+ ul.blacklist li {
color: #000;
font-family: "Times Roman", times, serif;
}
particular <a href="#severity">severity level</a>>), e.g.
<pre>
- #include <google/logging.h>
+ #include <glog/logging.h>
int main(int argc, char* argv[]) {
// Initialize Google's logging library.
functionality supported by glog. Please note that this document
doesn't describe all features in this library, but the most useful
ones. If you want to find less common features, please check
-header files under <code>src/google</code> directory.
+header files under <code>src/glog</code> directory.
<h2> <A NAME=severity>Severity Level</A> </h2>
<h2><A NAME=flags>Setting Flags</A></h2>
-<p>Several flags influences glog's output behavior.
+<p>Several flags influence glog's output behavior.
If the <a href="http://code.google.com/p/google-gflags/">Google
gflags library</a> is installed on your machine, the
<code>configure</code> script (see the INSTALL file in the package for
GLOG_logtostderr=1 ./your_application
</pre>
+<!-- TODO(hamaji): Fill the version number
+<p>By glog version 0.x.x, you can use GLOG_* environment variables
+even if you have gflags. If both an environment variable and a flag
+are specified, the value specified by a flag wins. E.g., if GLOG_v=0
+and --v=1, the verbosity will be 1, not 0.
+-->
+
<p>The following flags are most commonly used:
<dl>
<dt><code>logtostderr</code> (<code>bool</code>, default=<code>false</code>)
<dd>Log messages to stderr instead of logfiles.<br>
Note: you can set binary flags to <code>true</code> by specifying
-<code>1</code>, <code>true</code> , or <code>yes</code> (case
+<code>1</code>, <code>true</code>, or <code>yes</code> (case
insensitive).
Also, you can set binary flags to <code>false</code> by specifying
<code>0</code>, <code>false</code>, or <code>no</code> (again, case
is <code>ERROR</code>)
<dd>Copy log messages at or above this level to stderr in
addition to logfiles. The numbers of severity levels
-<code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, and
+<code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, and
<code>FATAL</code> are 0, 1, 2, and 3, respectively.
<dt><code>minloglevel</code> (<code>int</code>, default=0, which
is <code>INFO</code>)
<p>There are some other flags defined in logging.cc. Please grep the
source code for "DEFINE_" to see a complete list of all flags.
+<p>You can also modify flag values in your program by modifying global
+variables <code>FLAGS_*</code> . Most settings start working
+immediately after you update <code>FLAGS_*</code> . The exceptions are
+the flags related to destination files. For example, you might want to
+set <code>FLAGS_log_dir</code> before
+calling <code>google::InitGoogleLogging</code> . Here is an example:
+
+<pre>
+ LOG(INFO) << "file";
+ // Most flags work immediately after updating values.
+ FLAGS_logtostderr = 1;
+ LOG(INFO) << "stderr";
+ FLAGS_logtostderr = 0;
+ // This won't change the log destination. If you want to set this
+ // value, you should do this before google::InitGoogleLogging .
+ FLAGS_log_dir = "/some/log/directory";
+ LOG(INFO) << "the same file";
+</pre>
+
<h2><A NAME=conditional>Conditional / Occasional Logging</A></h2>
<p>Sometimes, you may only want to log a message under certain
logging:
<pre>
- LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
+ LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
</pre>
The "Got lots of cookies" message is logged only when the variable
If a line of code is executed many times, it may be useful to only log
a message at certain intervals. This kind of logging is most useful
-for informational messages.
+for informational messages.
<pre>
- LOG_EVERY_N(INFO, 10) << "Got the " << COUNTER << "th cookie";
+ LOG_EVERY_N(INFO, 10) << "Got the " << google::COUNTER << "th cookie";
</pre>
<p>The above line outputs a log messages on the 1st, 11th,
21st, ... times it is executed. Note that the special
-<code>COUNTER</code> value is used to identify which repetition is
+<code>google::COUNTER</code> value is used to identify which repetition is
happening.
<p>You can combine conditional and occasional logging with the
following macro.
<pre>
- LOG_IF_EVERY_N(INFO, (size > 1024), 10) << "Got the " << COUNTER
+ LOG_IF_EVERY_N(INFO, (size > 1024), 10) << "Got the " << google::COUNTER
<< "th big cookie";
</pre>
the output to the first n occurrences:
<pre>
- LOG_FIRST_N(INFO, 20) << "Got the " << COUNTER << "th cookie";
+ LOG_FIRST_N(INFO, 20) << "Got the " << google::COUNTER << "th cookie";
</pre>
<p>Outputs log messages for the first 20 times it is executed. Again,
-the <code>COUNTER</code> identifier indicates which repetition is
+the <code>google::COUNTER</code> identifier indicates which repetition is
happening.
<h2><A NAME=debug>Debug Mode Support</A></h2>
<pre>
DLOG(INFO) << "Found cookies";
- DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
+ DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies";
- DLOG_EVERY_N(INFO, 10) << "Got the " << COUNTER << "th cookie";
+ DLOG_EVERY_N(INFO, 10) << "Got the " << google::COUNTER << "th cookie";
</pre>
-<p>All "debug mode" logging is compiled away to nothing for non-debug mode
-compiles.
-
<h2><A NAME=check>CHECK Macros</A></h2>
<p>It is a good practice to check expected conditions in your program
<p><code>CHECK</code> aborts the application if a condition is not
true. Unlike <code>assert</code>, it is *not* controlled by
<code>NDEBUG</code>, so the check will be executed regardless of
-compilation mode. Therefore, <code>fp->Write(x)</code> in the
+compilation mode. Therefore, <code>fp->Write(x)</code> in the
following example is always executed:
<pre>
- CHECK(fp->Write(x) == 4) << "Write failed!";
+ CHECK(fp->Write(x) == 4) << "Write failed!";
</pre>
<p>There are various helper macros for
NULL to the type of the desired pointer.
<pre>
- CHECK_EQ(some_ptr, static_cast<SomeType*>(NULL));
+ CHECK_EQ(some_ptr, static_cast<SomeType*>(NULL));
</pre>
<p>Better yet, use the CHECK_NOTNULL macro:
<pre>
CHECK_NOTNULL(some_ptr);
- some_ptr->DoSomething();
+ some_ptr->DoSomething();
</pre>
<p>Since this macro returns the given pointer, this is very useful in
<p>Note that both arguments may be temporary strings which are
destructed at the end of the current "full expression"
(e.g., <code>CHECK_STREQ(Foo().c_str(), Bar().c_str())</code> where
-<code>Foo</code> and <code>Bar</code> returns C++'s
+<code>Foo</code> and <code>Bar</code> return C++'s
<code>std::string</code>).
<p>The <code>CHECK_DOUBLE_EQ</code> macro checks the equality of two
development. For such verbose logging, glog provides the
<code>VLOG</code> macro, which allows you to define your own numeric
logging levels. The <code>--v</code> command line option controls
-which verbose messages are logged:
+which verbose messages are logged:
<pre>
VLOG(1) << "I'm printed when you run the program with --v=1 or higher";
opposed to a severity level.
<pre>
- VLOG_IF(1, (size > 1024))
+ VLOG_IF(1, (size > 1024))
<< "I'm printed when size is more than 1024 and when you run the "
"program with --v=1 or more";
VLOG_EVERY_N(1, 10)
<< "I'm printed every 10th occurrence, and when you run the program "
- "with --v=1 or more. Present occurence is " << COUNTER;
- VLOG_IF_EVERY_N(1, (size > 1024), 10)
+ "with --v=1 or more. Present occurence is " << google::COUNTER;
+ VLOG_IF_EVERY_N(1, (size > 1024), 10)
<< "I'm printed on every 10th occurence of case when size is more "
" than 1024, when you run the program with --v=1 or more. ";
- "Present occurence is " << COUNTER;
+ "Present occurence is " << google::COUNTER;
+</pre>
+
+<h2> <A name="signal">Failure Signal Handler</A> </h2>
+
+<p>
+The library provides a convenient signal handler that will dump useful
+information when the program crashes on certain signals such as SIGSEGV.
+The signal handler can be installed by
+google::InstallFailureSignalHandler(). The following is an example of output
+from the signal handler.
+
+<pre>
+*** Aborted at 1225095260 (unix time) try "date -d @1225095260" if you are using GNU date ***
+*** SIGSEGV (@0x0) received by PID 17711 (TID 0x7f893090a6f0) from PID 0; stack trace: ***
+PC: @ 0x412eb1 TestWaitingLogSink::send()
+ @ 0x7f892fb417d0 (unknown)
+ @ 0x412eb1 TestWaitingLogSink::send()
+ @ 0x7f89304f7f06 google::LogMessage::SendToLog()
+ @ 0x7f89304f35af google::LogMessage::Flush()
+ @ 0x7f89304f3739 google::LogMessage::~LogMessage()
+ @ 0x408cf4 TestLogSinkWaitTillSent()
+ @ 0x4115de main
+ @ 0x7f892f7ef1c4 (unknown)
+ @ 0x4046f9 (unknown)
</pre>
+<p>
+By default, the signal handler writes the failure dump to the standard
+error. You can customize the destination by InstallFailureWriter().
+
<h2> <A name="misc">Miscellaneous Notes</A> </h2>
<h3><A NAME=message>Performance of Messages</A></h3>
may not sacrifice the performance of your application.
<pre>
- CHECK(obj.ok) << obj.CreatePrettyFormattedStringButVerySlow();
+ CHECK(obj.ok) << obj.CreatePrettyFormattedStringButVerySlow();
</pre>
<h3><A NAME=failure>User-defined Failure Function</A></h3>
<h3><A NAME=raw>Raw Logging</A></h3>
-<p>The header file <code><google/raw_logging.h></code> can be
+<p>The header file <code><glog/raw_logging.h></code> can be
used for thread-safe logging, which does not allocate any memory or
acquire any locks. Therefore, the macros defined in this
header file can be used by low-level memory allocation and
synchronization code.
-Please check <code>src/google/raw_logging.h.in</code> for detail.
+Please check <code>src/glog/raw_logging.h.in</code> for detail.
</p>
<h3><A NAME=plog>Google Style perror()</A></h3>
E.g.
<pre>
- PCHECK(write(1, NULL, 2) >= 0) << "Write NULL failed";
+ PCHECK(write(1, NULL, 2) >= 0) << "Write NULL failed";
</pre>
<p>This check fails with the following error message.
<pre>
- F0825 185142 test.cc:22] Check failed: write(1, NULL, 2) >= 0 Write NULL failed: Bad address [14]
+ F0825 185142 test.cc:22] Check failed: write(1, NULL, 2) >= 0 Write NULL failed: Bad address [14]
</pre>
<h3><A NAME=syslog>Syslog</A></h3>
<pre>
#define GOOGLE_STRIP_LOG 1 // this must go before the #include!
- #include <google/logging.h>
+ #include <glog/logging.h>
</pre>
-<p>The compiler will remove the log messages whose severity are less
+<p>The compiler will remove the log messages whose severities are less
than the specified integer value. Since
<code>VLOG</code> logs at the severity level <code>INFO</code>
(numeric value <code>0</code>),
all log messages associated with <code>VLOG</code>s as well as
<code>INFO</code> log statements.
+<h3><A NAME=windows>Notes for Windows users</A></h3>
+
+<p>Google glog defines a severity level <code>ERROR</code>, which is
+also defined in <code>windows.h</code> . You can make glog not define
+<code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>,
+and <code>FATAL</code> by defining
+<code>GLOG_NO_ABBREVIATED_SEVERITIES</code> before
+including <code>glog/logging.h</code> . Even with this macro, you can
+still use the iostream like logging facilities:
+
+<pre>
+ #define GLOG_NO_ABBREVIATED_SEVERITIES
+ #include <windows.h>
+ #include <glog/logging.h>
+
+ // ...
+
+ LOG(ERROR) << "This should work";
+ LOG_IF(ERROR, x > y) << "This should be also OK";
+</pre>
+
+<p>
+However, you cannot
+use <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>,
+and <code>FATAL</code> anymore for functions defined
+in <code>glog/logging.h</code> .
+
+<pre>
+ #define GLOG_NO_ABBREVIATED_SEVERITIES
+ #include <windows.h>
+ #include <glog/logging.h>
+
+ // ...
+
+ // This won't work.
+ // google::FlushLogFiles(google::ERROR);
+
+ // Use this instead.
+ google::FlushLogFiles(google::GLOG_ERROR);
+</pre>
+
+<p>
+If you don't need <code>ERROR</code> defined
+by <code>windows.h</code>, there are a couple of more workarounds
+which sometimes don't work:
+
+<ul>
+ <li>#define <code>WIN32_LEAN_AND_MEAN</code> or <code>NOGDI</code>
+ <strong>before</strong> you #include <code>windows.h</code> .
+ <li>#undef <code>ERROR</code> <strong>after</strong> you #include
+ <code>windows.h</code> .
+</ul>
+
+<p>See <a href="http://code.google.com/p/google-glog/issues/detail?id=33">
+this issue</a> for more detail.
+
<hr>
<address>
Shinichiro Hamaji<br>
projects / platform / upstream / glog.git / blobdiff