diff options
Diffstat (limited to 'share/doc/glog-0.3.4')
| -rw-r--r-- | share/doc/glog-0.3.4/AUTHORS | 2 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/COPYING | 65 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/ChangeLog | 84 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/INSTALL | 297 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/NEWS | 0 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/README | 5 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/README.windows | 26 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/designstyle.css | 115 | ||||
| -rw-r--r-- | share/doc/glog-0.3.4/glog.html | 613 |
9 files changed, 1207 insertions, 0 deletions
diff --git a/share/doc/glog-0.3.4/AUTHORS b/share/doc/glog-0.3.4/AUTHORS new file mode 100644 index 0000000..ee92be8 --- /dev/null +++ b/share/doc/glog-0.3.4/AUTHORS @@ -0,0 +1,2 @@ +opensource@google.com + diff --git a/share/doc/glog-0.3.4/COPYING b/share/doc/glog-0.3.4/COPYING new file mode 100644 index 0000000..38396b5 --- /dev/null +++ b/share/doc/glog-0.3.4/COPYING @@ -0,0 +1,65 @@ +Copyright (c) 2008, Google Inc. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +A function gettimeofday in utilities.cc is based on + +http://www.google.com/codesearch/p?hl=en#dR3YEbitojA/COPYING&q=GetSystemTimeAsFileTime%20license:bsd + +The license of this code is: + +Copyright (c) 2003-2008, Jouni Malinen <j@w1.fi> and contributors +All Rights Reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name(s) of the above-listed copyright holder(s) nor the + names of its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/share/doc/glog-0.3.4/ChangeLog b/share/doc/glog-0.3.4/ChangeLog new file mode 100644 index 0000000..d1b4248 --- /dev/null +++ b/share/doc/glog-0.3.4/ChangeLog @@ -0,0 +1,84 @@ +2013-02-01 Google Inc. <opensource@google.com> + + * google-glog: version 0.3.3 + * Add --disable-rtti option for configure. + * Visual Studio build and test fix. + * QNX build fix (thanks vanuan). + * Reduce warnings. + * Fixed LOG_SYSRESULT (thanks ukai). + * FreeBSD build fix (thanks yyanagisawa). + * Clang build fix. + * Now users can re-initialize glog after ShutdownGoogleLogging. + * Color output support by GLOG_colorlogtostderr (thanks alexs). + * Now glog's ABI around flags are compatible with gflags. + * Document mentions how to modify flags from user programs. + +2012-01-12 Google Inc. <opensource@google.com> + + * google-glog: version 0.3.2 + * Clang support. + * Demangler and stacktrace improvement for newer GCCs. + * Now fork(2) doesn't mess up log files. + * Make valgrind happier. + * Reduce warnings for more -W options. + * Provide a workaround for ERROR defined by windows.h. + +2010-06-15 Google Inc. <opensource@google.com> + + * google-glog: version 0.3.1 + * GLOG_* environment variables now work even when gflags is installed. + * Snow leopard support. + * Now we can build and test from out side tree. + * Add DCHECK_NOTNULL. + * Add ShutdownGoogleLogging to close syslog (thanks DGunchev) + * Fix --enable-frame-pointers option (thanks kazuki.ohta) + * Fix libunwind detection (thanks giantchen) + +2009-07-30 Google Inc. <opensource@google.com> + + * google-glog: version 0.3.0 + * Fix a deadlock happened when user uses glog with recent gflags. + * Suppress several unnecessary warnings (thanks keir). + * NetBSD and OpenBSD support. + * Use Win32API GetComputeNameA properly (thanks magila). + * Fix user name detection for Windows (thanks ademin). + * Fix several minor bugs. + +2009-04-10 Google Inc. <opensource@google.com> + * google-glog: version 0.2.1 + * Fix timestamps of VC++ version. + * Add pkg-config support (thanks Tomasz) + * Fix build problem when building with gtest (thanks Michael) + * Add --with-gflags option for configure (thanks Michael) + * Fixes for GCC 4.4 (thanks John) + +2009-01-23 Google Inc. <opensource@google.com> + * google-glog: version 0.2 + * Add initial Windows VC++ support. + * Google testing/mocking frameworks integration. + * Link pthread library automatically. + * Flush logs in signal handlers. + * Add macros LOG_TO_STRING, LOG_AT_LEVEL, DVLOG, and LOG_TO_SINK_ONLY. + * Log microseconds. + * Add --log_backtrace_at option. + * Fix some minor bugs. + +2008-11-18 Google Inc. <opensource@google.com> + * google-glog: version 0.1.2 + * Add InstallFailureSignalHandler(). (satorux) + * Re-organize the way to produce stacktraces. + * Don't define unnecessary macro DISALLOW_EVIL_CONSTRUCTORS. + +2008-10-15 Google Inc. <opensource@google.com> + * google-glog: version 0.1.1 + * Support symbolize for MacOSX 10.5. + * BUG FIX: --vmodule didn't work with gflags. + * BUG FIX: symbolize_unittest failed with GCC 4.3. + * Several fixes on the document. + +2008-10-07 Google Inc. <opensource@google.com> + + * google-glog: initial release: + The glog package contains a library that implements application-level + logging. This library provides logging APIs based on C++-style + streams and various helper macros. diff --git a/share/doc/glog-0.3.4/INSTALL b/share/doc/glog-0.3.4/INSTALL new file mode 100644 index 0000000..0babe24 --- /dev/null +++ b/share/doc/glog-0.3.4/INSTALL @@ -0,0 +1,297 @@ +Installation Instructions +************************* + +Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005, +2006, 2007 Free Software Foundation, Inc. + +This file is free documentation; the Free Software Foundation gives +unlimited permission to copy, distribute and modify it. + +Glog-Specific Install Notes +================================ + +*** NOTE FOR 64-BIT LINUX SYSTEMS + +The glibc built-in stack-unwinder on 64-bit systems has some problems +with the glog libraries. (In particular, if you are using +InstallFailureSignalHandler(), the signal may be raised in the middle +of malloc, holding some malloc-related locks when they invoke the +stack unwinder. The built-in stack unwinder may call malloc +recursively, which may require the thread to acquire a lock it already +holds: deadlock.) + +For that reason, if you use a 64-bit system and you need +InstallFailureSignalHandler(), we strongly recommend you install +libunwind before trying to configure or install google glog. +libunwind can be found at + + http://download.savannah.nongnu.org/releases/libunwind/libunwind-snap-070410.tar.gz + +Even if you already have libunwind installed, you will probably still +need to install from the snapshot to get the latest version. + +CAUTION: if you install libunwind from the URL above, be aware that +you may have trouble if you try to statically link your binary with +glog: that is, if you link with 'gcc -static -lgcc_eh ...'. This +is because both libunwind and libgcc implement the same C++ exception +handling APIs, but they implement them differently on some platforms. +This is not likely to be a problem on ia64, but may be on x86-64. + +Also, if you link binaries statically, make sure that you add +-Wl,--eh-frame-hdr to your linker options. This is required so that +libunwind can find the information generated by the compiler required +for stack unwinding. + +Using -static is rare, though, so unless you know this will affect you +it probably won't. + +If you cannot or do not wish to install libunwind, you can still try +to use two kinds of stack-unwinder: 1. glibc built-in stack-unwinder +and 2. frame pointer based stack-unwinder. + +1. As we already mentioned, glibc's unwinder has a deadlock issue. +However, if you don't use InstallFailureSignalHandler() or you don't +worry about the rare possibilities of deadlocks, you can use this +stack-unwinder. If you specify no options and libunwind isn't +detected on your system, the configure script chooses this unwinder by +default. + +2. The frame pointer based stack unwinder requires that your +application, the glog library, and system libraries like libc, all be +compiled with a frame pointer. This is *not* the default for x86-64. + +If you are on x86-64 system, know that you have a set of system +libraries with frame-pointers enabled, and compile all your +applications with -fno-omit-frame-pointer, then you can enable the +frame pointer based stack unwinder by passing the +--enable-frame-pointers flag to configure. + + +Basic Installation +================== + +Briefly, the shell commands `./configure; make; make install' should +configure, build, and install this package. The following +more-detailed instructions are generic; see the `README' file for +instructions specific to this package. + + The `configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a `Makefile' in each directory of the package. +It may also create one or more `.h' files containing system-dependent +definitions. Finally, it creates a shell script `config.status' that +you can run in the future to recreate the current configuration, and a +file `config.log' containing compiler output (useful mainly for +debugging `configure'). + + It can also use an optional file (typically called `config.cache' +and enabled with `--cache-file=config.cache' or simply `-C') that saves +the results of its tests to speed up reconfiguring. Caching is +disabled by default to prevent problems with accidental use of stale +cache files. + + If you need to do unusual things to compile the package, please try +to figure out how `configure' could check whether to do them, and mail +diffs or instructions to the address given in the `README' so they can +be considered for the next release. If you are using the cache, and at +some point `config.cache' contains results you don't want to keep, you +may remove or edit it. + + The file `configure.ac' (or `configure.in') is used to create +`configure' by a program called `autoconf'. You need `configure.ac' if +you want to change it or regenerate `configure' using a newer version +of `autoconf'. + +The simplest way to compile this package is: + + 1. `cd' to the directory containing the package's source code and type + `./configure' to configure the package for your system. + + Running `configure' might take a while. While running, it prints + some messages telling which features it is checking for. + + 2. Type `make' to compile the package. + + 3. Optionally, type `make check' to run any self-tests that come with + the package. + + 4. Type `make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source code directory by typing `make clean'. To also remove the + files that `configure' created (so you can compile the package for + a different kind of computer), type `make distclean'. There is + also a `make maintainer-clean' target, but that is intended mainly + for the package's developers. If you use it, you may have to get + all sorts of other programs in order to regenerate files that came + with the distribution. + + 6. Often, you can also type `make uninstall' to remove the installed + files again. + +Compilers and Options +===================== + +Some systems require unusual options for compilation or linking that the +`configure' script does not know about. Run `./configure --help' for +details on some of the pertinent environment variables. + + You can give `configure' initial values for configuration parameters +by setting variables in the command line or in the environment. Here +is an example: + + ./configure CC=c99 CFLAGS=-g LIBS=-lposix + + *Note Defining Variables::, for more details. + +Compiling For Multiple Architectures +==================================== + +You can compile the package for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you can use GNU `make'. `cd' to the +directory where you want the object files and executables to go and run +the `configure' script. `configure' automatically checks for the +source code in the directory that `configure' is in and in `..'. + + With a non-GNU `make', it is safer to compile the package for one +architecture at a time in the source code directory. After you have +installed the package for one architecture, use `make distclean' before +reconfiguring for another architecture. + +Installation Names +================== + +By default, `make install' installs the package's commands under +`/usr/local/bin', include files under `/usr/local/include', etc. You +can specify an installation prefix other than `/usr/local' by giving +`configure' the option `--prefix=PREFIX'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +pass the option `--exec-prefix=PREFIX' to `configure', the package uses +PREFIX as the prefix for installing programs and libraries. +Documentation and other data files still use the regular prefix. + + In addition, if you use an unusual directory layout you can give +options like `--bindir=DIR' to specify different values for particular +kinds of files. Run `configure --help' for a list of the directories +you can set and what kinds of files go in them. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving `configure' the +option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. + +Optional Features +================= + +Some packages pay attention to `--enable-FEATURE' options to +`configure', where FEATURE indicates an optional part of the package. +They may also pay attention to `--with-PACKAGE' options, where PACKAGE +is something like `gnu-as' or `x' (for the X Window System). The +`README' should mention any `--enable-' and `--with-' options that the +package recognizes. + + For packages that use the X Window System, `configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the `configure' options `--x-includes=DIR' and +`--x-libraries=DIR' to specify their locations. + +Specifying the System Type +========================== + +There may be some features `configure' cannot figure out automatically, +but needs to determine by the type of machine the package will run on. +Usually, assuming the package is built to be run on the _same_ +architectures, `configure' can figure that out, but if it prints a +message saying it cannot guess the machine type, give it the +`--build=TYPE' option. TYPE can either be a short name for the system +type, such as `sun4', or a canonical name which has the form: + + CPU-COMPANY-SYSTEM + +where SYSTEM can have one of these forms: + + OS KERNEL-OS + + See the file `config.sub' for the possible values of each field. If +`config.sub' isn't included in this package, then this package doesn't +need to know the machine type. + + If you are _building_ compiler tools for cross-compiling, you should +use the option `--target=TYPE' to select the type of system they will +produce code for. + + If you want to _use_ a cross compiler, that generates code for a +platform different from the build platform, you should specify the +"host" platform (i.e., that on which the generated programs will +eventually be run) with `--host=TYPE'. + +Sharing Defaults +================ + +If you want to set default values for `configure' scripts to share, you +can create a site shell script called `config.site' that gives default +values for variables like `CC', `cache_file', and `prefix'. +`configure' looks for `PREFIX/share/config.site' if it exists, then +`PREFIX/etc/config.site' if it exists. Or, you can set the +`CONFIG_SITE' environment variable to the location of the site script. +A warning: not all `configure' scripts look for a site script. + +Defining Variables +================== + +Variables not defined in a site shell script can be set in the +environment passed to `configure'. However, some packages may run +configure again during the build, and the customized values of these +variables may be lost. In order to avoid this problem, you should set +them in the `configure' command line, using `VAR=value'. For example: + + ./configure CC=/usr/local2/bin/gcc + +causes the specified `gcc' to be used as the C compiler (unless it is +overridden in the site shell script). + +Unfortunately, this technique does not work for `CONFIG_SHELL' due to +an Autoconf bug. Until the bug is fixed you can use this workaround: + + CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash + +`configure' Invocation +====================== + +`configure' recognizes the following options to control how it operates. + +`--help' +`-h' + Print a summary of the options to `configure', and exit. + +`--version' +`-V' + Print the version of Autoconf used to generate the `configure' + script, and exit. + +`--cache-file=FILE' + Enable the cache: use and save the results of the tests in FILE, + traditionally `config.cache'. FILE defaults to `/dev/null' to + disable caching. + +`--config-cache' +`-C' + Alias for `--cache-file=config.cache'. + +`--quiet' +`--silent' +`-q' + Do not print messages saying which checks are being made. To + suppress all normal output, redirect it to `/dev/null' (any error + messages will still be shown). + +`--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + `configure' can determine that directory automatically. + +`configure' also accepts some other, not widely useful, options. Run +`configure --help' for more details. + diff --git a/share/doc/glog-0.3.4/NEWS b/share/doc/glog-0.3.4/NEWS new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/share/doc/glog-0.3.4/NEWS diff --git a/share/doc/glog-0.3.4/README b/share/doc/glog-0.3.4/README new file mode 100644 index 0000000..77efd37 --- /dev/null +++ b/share/doc/glog-0.3.4/README @@ -0,0 +1,5 @@ +This repository contains a C++ implementation of the Google logging +module. Documentation for the implementation is in doc/. + +See INSTALL for (generic) installation instructions for C++: basically + ./configure && make && make install diff --git a/share/doc/glog-0.3.4/README.windows b/share/doc/glog-0.3.4/README.windows new file mode 100644 index 0000000..dbeef32 --- /dev/null +++ b/share/doc/glog-0.3.4/README.windows @@ -0,0 +1,26 @@ +This project has begun being ported to Windows. A working solution +file exists in this directory: + google-glog.sln + +You can load this solution file into VC++ 9.0 (Visual Studio +2008). You may also be able to use this solution file with older +Visual Studios by converting the solution file. + +Note that stack tracing and some unittests are not ported +yet. + +You can also link glog code in statically -- see the example project +libglog_static and logging_unittest_static, which does this. For this +to work, you'll need to add "/D GOOGLE_GLOG_DLL_DECL=" to the compile +line of every glog's .cc file. + +I have little experience with Windows programming, so there may be +better ways to set this up than I've done! If you run across any +problems, please post to the google-glog Google Group, or report +them on the google-glog Google Code site: + http://groups.google.com/group/google-glog + https://github.com/google/glog/issues + +-- Shinichiro Hamaji + +Last modified: 23 January 2009 diff --git a/share/doc/glog-0.3.4/designstyle.css b/share/doc/glog-0.3.4/designstyle.css new file mode 100644 index 0000000..f5d1ec2 --- /dev/null +++ b/share/doc/glog-0.3.4/designstyle.css @@ -0,0 +1,115 @@ +body { + background-color: #ffffff; + color: black; + margin-right: 1in; + margin-left: 1in; +} + + +h1, h2, h3, h4, h5, h6 { + color: #3366ff; + font-family: sans-serif; +} +@media print { + /* Darker version for printing */ + h1, h2, h3, h4, h5, h6 { + color: #000080; + font-family: helvetica, sans-serif; + } +} + +h1 { + text-align: center; + font-size: 18pt; +} +h2 { + margin-left: -0.5in; +} +h3 { + margin-left: -0.25in; +} +h4 { + margin-left: -0.125in; +} +hr { + margin-left: -1in; +} + +/* Definition lists: definition term bold */ +dt { + font-weight: bold; +} + +address { + text-align: right; +} +/* Use the <code> tag for bits of code and <var> for variables and objects. */ +code,pre,samp,var { + color: #006000; +} +/* Use the <file> tag for file and directory paths and names. */ +file { + color: #905050; + font-family: monospace; +} +/* Use the <kbd> tag for stuff the user should type. */ +kbd { + color: #600000; +} +div.note p { + float: right; + width: 3in; + margin-right: 0%; + padding: 1px; + border: 2px solid #6060a0; + background-color: #fffff0; +} + +UL.nobullets { + list-style-type: none; + list-style-image: none; + margin-left: -1em; +} + +/* +body:after { + content: "Google Confidential"; +} +*/ + +/* pretty printing styles. See prettify.js */ +.str { color: #080; } +.kwd { color: #008; } +.com { color: #800; } +.typ { color: #606; } +.lit { color: #066; } +.pun { color: #660; } +.pln { color: #000; } +.tag { color: #008; } +.atn { color: #606; } +.atv { color: #080; } +pre.prettyprint { padding: 2px; border: 1px solid #888; } + +.embsrc { background: #eee; } + +@media print { + .str { color: #060; } + .kwd { color: #006; font-weight: bold; } + .com { color: #600; font-style: italic; } + .typ { color: #404; font-weight: bold; } + .lit { color: #044; } + .pun { color: #440; } + .pln { color: #000; } + .tag { color: #006; font-weight: bold; } + .atn { color: #404; } + .atv { color: #060; } +} + +/* Table Column Headers */ +.hdr { + color: #006; + font-weight: bold; + background-color: #dddddd; } +.hdr2 { + color: #006; + background-color: #eeeeee; }
\ No newline at end of file diff --git a/share/doc/glog-0.3.4/glog.html b/share/doc/glog-0.3.4/glog.html new file mode 100644 index 0000000..8b200ba --- /dev/null +++ b/share/doc/glog-0.3.4/glog.html @@ -0,0 +1,613 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + +<html> +<head> +<title>How To Use Google Logging Library (glog)</title> + +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="http://www.google.com/favicon.ico" type="image/x-icon" + rel="shortcut icon"> +<link href="designstyle.css" type="text/css" rel="stylesheet"> +<style type="text/css"> +<!-- + ol.bluelist li { + color: #3366ff; + font-family: sans-serif; + } + ol.bluelist li p { + color: #000; + font-family: "Times Roman", times, serif; + } + ul.blacklist li { + color: #000; + font-family: "Times Roman", times, serif; + } +//--> +</style> +</head> + +<body> + +<h1>How To Use Google Logging Library (glog)</h1> +<small>(as of +<script type=text/javascript> + var lm = new Date(document.lastModified); + document.write(lm.toDateString()); +</script>) +</small> +<br> + +<h2> <A NAME=intro>Introduction</A> </h2> + +<p><b>Google glog</b> is a library that implements application-level +logging. This library provides logging APIs based on C++-style +streams and various helper macros. +You can log a message by simply streaming things to LOG(<a +particular <a href="#severity">severity level</a>>), e.g. + +<pre> + #include <glog/logging.h> + + int main(int argc, char* argv[]) { + // Initialize Google's logging library. + google::InitGoogleLogging(argv[0]); + + // ... + LOG(INFO) << "Found " << num_cookies << " cookies"; + } +</pre> + +<p>Google glog defines a series of macros that simplify many common logging +tasks. You can log messages by severity level, control logging +behavior from the command line, log based on conditionals, abort the +program when expected conditions are not met, introduce your own +verbose logging levels, and more. This document describes the +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/glog</code> directory. + +<h2> <A NAME=severity>Severity Level</A> </h2> + +<p> +You can specify one of the following severity levels (in +increasing order of severity): <code>INFO</code>, <code>WARNING</code>, +<code>ERROR</code>, and <code>FATAL</code>. +Logging a <code>FATAL</code> message terminates the program (after the +message is logged). +Note that messages of a given severity are logged not only in the +logfile for that severity, but also in all logfiles of lower severity. +E.g., a message of severity <code>FATAL</code> will be logged to the +logfiles of severity <code>FATAL</code>, <code>ERROR</code>, +<code>WARNING</code>, and <code>INFO</code>. + +<p> +The <code>DFATAL</code> severity logs a <code>FATAL</code> error in +debug mode (i.e., there is no <code>NDEBUG</code> macro defined), but +avoids halting the program in production by automatically reducing the +severity to <code>ERROR</code>. + +<p>Unless otherwise specified, glog writes to the filename +"/tmp/<program name>.<hostname>.<user name>.log.<severity level>.<date>.<time>.<pid>" +(e.g., "/tmp/hello_world.example.com.hamaji.log.INFO.20080709-222411.10474"). +By default, glog copies the log messages of severity level +<code>ERROR</code> or <code>FATAL</code> to standard error (stderr) +in addition to log files. + +<h2><A NAME=flags>Setting Flags</A></h2> + +<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 +detail of this script) will automatically detect and use it, +allowing you to pass flags on the command line. For example, if you +want to turn the flag <code>--logtostderr</code> on, you can start +your application with the following command line: + +<pre> + ./your_application --logtostderr=1 +</pre> + +If the Google gflags library isn't installed, you set flags via +environment variables, prefixing the flag name with "GLOG_", e.g. + +<pre> + 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 +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 +insensitive). +<dt><code>stderrthreshold</code> (<code>int</code>, default=2, which +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>FATAL</code> are 0, 1, 2, and 3, respectively. +<dt><code>minloglevel</code> (<code>int</code>, default=0, which +is <code>INFO</code>) +<dd>Log messages at or above this level. Again, the numbers of +severity levels <code>INFO</code>, <code>WARNING</code>, +<code>ERROR</code>, and <code>FATAL</code> are 0, 1, 2, and 3, +respectively. +<dt><code>log_dir</code> (<code>string</code>, default="") +<dd>If specified, logfiles are written into this directory instead +of the default logging directory. +<dt><code>v</code> (<code>int</code>, default=0) +<dd>Show all <code>VLOG(m)</code> messages for <code>m</code> less or +equal the value of this flag. Overridable by --vmodule. +See <a href="#verbose">the section about verbose logging</a> for more +detail. +<dt><code>vmodule</code> (<code>string</code>, default="") +<dd>Per-module verbose level. The argument has to contain a +comma-separated list of <module name>=<log level>. +<module name> +is a glob pattern (e.g., <code>gfs*</code> for all modules whose name +starts with "gfs"), matched against the filename base +(that is, name ignoring .cc/.h./-inl.h). +<log level> overrides any value given by --v. +See also <a href="#verbose">the section about verbose logging</a>. +</dl> + +<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 +conditions. You can use the following macros to perform conditional +logging: + +<pre> + LOG_IF(INFO, num_cookies > 10) << "Got lots of cookies"; +</pre> + +The "Got lots of cookies" message is logged only when the variable +<code>num_cookies</code> exceeds 10. + +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. + +<pre> + 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>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 " << google::COUNTER + << "th big cookie"; +</pre> + +<p>Instead of outputting a message every nth time, you can also limit +the output to the first n occurrences: + +<pre> + 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>google::COUNTER</code> identifier indicates which repetition is +happening. + +<h2><A NAME=debug>Debug Mode Support</A></h2> + +<p>Special "debug mode" logging macros only have an effect in debug +mode and are compiled away to nothing for non-debug mode +compiles. Use these macros to avoid slowing down your production +application due to excessive logging. + +<pre> + DLOG(INFO) << "Found cookies"; + + DLOG_IF(INFO, num_cookies > 10) << "Got lots of cookies"; + + DLOG_EVERY_N(INFO, 10) << "Got the " << google::COUNTER << "th cookie"; +</pre> + +<h2><A NAME=check>CHECK Macros</A></h2> + +<p>It is a good practice to check expected conditions in your program +frequently to detect errors as early as possible. The +<code>CHECK</code> macro provides the ability to abort the application +when a condition is not met, similar to the <code>assert</code> macro +defined in the standard C library. + +<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 +following example is always executed: + +<pre> + CHECK(fp->Write(x) == 4) << "Write failed!"; +</pre> + +<p>There are various helper macros for +equality/inequality checks - <code>CHECK_EQ</code>, +<code>CHECK_NE</code>, <code>CHECK_LE</code>, <code>CHECK_LT</code>, +<code>CHECK_GE</code>, and <code>CHECK_GT</code>. +They compare two values, and log a +<code>FATAL</code> message including the two values when the result is +not as expected. The values must have <code>operator<<(ostream, +...)</code> defined. + +<p>You may append to the error message like so: + +<pre> + CHECK_NE(1, 2) << ": The world must be ending!"; +</pre> + +<p>We are very careful to ensure that each argument is evaluated exactly +once, and that anything which is legal to pass as a function argument is +legal here. In particular, the arguments may be temporary expressions +which will end up being destroyed at the end of the apparent statement, +for example: + +<pre> + CHECK_EQ(string("abc")[1], 'b'); +</pre> + +<p>The compiler reports an error if one of the arguments is a +pointer and the other is NULL. To work around this, simply static_cast +NULL to the type of the desired pointer. + +<pre> + 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(); +</pre> + +<p>Since this macro returns the given pointer, this is very useful in +constructor initializer lists. + +<pre> + struct S { + S(Something* ptr) : ptr_(CHECK_NOTNULL(ptr)) {} + Something* ptr_; + }; +</pre> + +<p>Note that you cannot use this macro as a C++ stream due to this +feature. Please use <code>CHECK_EQ</code> described above to log a +custom message before aborting the application. + +<p>If you are comparing C strings (char *), a handy set of macros +performs case sensitive as well as case insensitive comparisons - +<code>CHECK_STREQ</code>, <code>CHECK_STRNE</code>, +<code>CHECK_STRCASEEQ</code>, and <code>CHECK_STRCASENE</code>. The +CASE versions are case-insensitive. You can safely pass <code>NULL</code> +pointers for this macro. They treat <code>NULL</code> and any +non-<code>NULL</code> string as not equal. Two <code>NULL</code>s are +equal. + +<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> return C++'s +<code>std::string</code>). + +<p>The <code>CHECK_DOUBLE_EQ</code> macro checks the equality of two +floating point values, accepting a small error margin. +<code>CHECK_NEAR</code> accepts a third floating point argument, which +specifies the acceptable error margin. + +<h2><A NAME=verbose>Verbose Logging</A></h2> + +<p>When you are chasing difficult bugs, thorough log messages are very +useful. However, you may want to ignore too verbose messages in usual +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: + +<pre> + VLOG(1) << "I'm printed when you run the program with --v=1 or higher"; + VLOG(2) << "I'm printed when you run the program with --v=2 or higher"; +</pre> + +<p>With <code>VLOG</code>, the lower the verbose level, the more +likely messages are to be logged. For example, if +<code>--v==1</code>, <code>VLOG(1)</code> will log, but +<code>VLOG(2)</code> will not log. This is opposite of the severity +level, where <code>INFO</code> is 0, and <code>ERROR</code> is 2. +<code>--minloglevel</code> of 1 will log <code>WARNING</code> and +above. Though you can specify any integers for both <code>VLOG</code> +macro and <code>--v</code> flag, the common values for them are small +positive integers. For example, if you write <code>VLOG(0)</code>, +you should specify <code>--v=-1</code> or lower to silence it. This +is less useful since we may not want verbose logs by default in most +cases. The <code>VLOG</code> macros always log at the +<code>INFO</code> log level (when they log at all). + +<p>Verbose logging can be controlled from the command line on a +per-module basis: + +<pre> + --vmodule=mapreduce=2,file=1,gfs*=3 --v=0 +</pre> + +<p>will: + +<ul> + <li>a. Print VLOG(2) and lower messages from mapreduce.{h,cc} + <li>b. Print VLOG(1) and lower messages from file.{h,cc} + <li>c. Print VLOG(3) and lower messages from files prefixed with "gfs" + <li>d. Print VLOG(0) and lower messages from elsewhere +</ul> + +<p>The wildcarding functionality shown by (c) supports both '*' +(matches 0 or more characters) and '?' (matches any single character) +wildcards. Please also check the section about <a +href="#flags">command line flags</a>. + +<p>There's also <code>VLOG_IS_ON(n)</code> "verbose level" condition +macro. This macro returns true when the <code>--v</code> is equal or +greater than <code>n</code>. To be used as + +<pre> + if (VLOG_IS_ON(2)) { + // do some logging preparation and logging + // that can't be accomplished with just VLOG(2) << ...; + } +</pre> + +<p>Verbose level condition macros <code>VLOG_IF</code>, +<code>VLOG_EVERY_N</code> and <code>VLOG_IF_EVERY_N</code> behave +analogous to <code>LOG_IF</code>, <code>LOG_EVERY_N</code>, +<code>LOF_IF_EVERY</code>, but accept a numeric verbosity level as +opposed to a severity level. + +<pre> + 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 " << 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 " << 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> + +<p>The conditional logging macros provided by glog (e.g., +<code>CHECK</code>, <code>LOG_IF</code>, <code>VLOG</code>, ...) are +carefully implemented and don't execute the right hand side +expressions when the conditions are false. So, the following check +may not sacrifice the performance of your application. + +<pre> + CHECK(obj.ok) << obj.CreatePrettyFormattedStringButVerySlow(); +</pre> + +<h3><A NAME=failure>User-defined Failure Function</A></h3> + +<p><code>FATAL</code> severity level messages or unsatisfied +<code>CHECK</code> condition terminate your program. You can change +the behavior of the termination by +<code>InstallFailureFunction</code>. + +<pre> + void YourFailureFunction() { + // Reports something... + exit(1); + } + + int main(int argc, char* argv[]) { + google::InstallFailureFunction(&YourFailureFunction); + } +</pre> + +<p>By default, glog tries to dump stacktrace and makes the program +exit with status 1. The stacktrace is produced only when you run the +program on an architecture for which glog supports stack tracing (as +of September 2008, glog supports stack tracing for x86 and x86_64). + +<h3><A NAME=raw>Raw Logging</A></h3> + +<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/glog/raw_logging.h.in</code> for detail. +</p> + +<h3><A NAME=plog>Google Style perror()</A></h3> + +<p><code>PLOG()</code> and <code>PLOG_IF()</code> and +<code>PCHECK()</code> behave exactly like their <code>LOG*</code> and +<code>CHECK</code> equivalents with the addition that they append a +description of the current state of errno to their output lines. +E.g. + +<pre> + 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] +</pre> + +<h3><A NAME=syslog>Syslog</A></h3> + +<p><code>SYSLOG</code>, <code>SYSLOG_IF</code>, and +<code>SYSLOG_EVERY_N</code> macros are available. +These log to syslog in addition to the normal logs. Be aware that +logging to syslog can drastically impact performance, especially if +syslog is configured for remote logging! Make sure you understand the +implications of outputting to syslog before you use these macros. In +general, it's wise to use these macros sparingly. + +<h3><A NAME=strip>Strip Logging Messages</A></h3> + +<p>Strings used in log messages can increase the size of your binary +and present a privacy concern. You can therefore instruct glog to +remove all strings which fall below a certain severity level by using +the GOOGLE_STRIP_LOG macro: + +<p>If your application has code like this: + +<pre> + #define GOOGLE_STRIP_LOG 1 // this must go before the #include! + #include <glog/logging.h> +</pre> + +<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>), +setting <code>GOOGLE_STRIP_LOG</code> to 1 or greater removes +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> +Gregor Hohpe<br> +<script type=text/javascript> + var lm = new Date(document.lastModified); + document.write(lm.toDateString()); +</script> +</address> + +</body> +</html> |