<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>open-vm-tools 9.4.0: Logging</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">open-vm-tools 9.4.0
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#define-members">Macros</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Logging</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga587e21dda1f72be700a6206023ad681b"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga587e21dda1f72be700a6206023ad681b"></a>
#define </td><td class="memItemRight" valign="bottom"><b>FUNC</b>   __FUNCTION__</td></tr>
<tr class="separator:ga587e21dda1f72be700a6206023ad681b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga70ba83e48efbb05f34086febacc73a1d"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga70ba83e48efbb05f34086febacc73a1d">g_info</a>(fmt,...)   g_log(G_LOG_DOMAIN, G_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga70ba83e48efbb05f34086febacc73a1d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga9e18287dc7c31eb280a776e7ca0842f3"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga9e18287dc7c31eb280a776e7ca0842f3">vm_critical</a>(fmt,...)   g_critical("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga9e18287dc7c31eb280a776e7ca0842f3"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga4b4b57811a8b98e84f3264fff739a7f3"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga4b4b57811a8b98e84f3264fff739a7f3">vm_debug</a>(fmt,...)   g_debug("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga4b4b57811a8b98e84f3264fff739a7f3"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga110b31400dcfd1ceb4e0db5a0f94f620"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga110b31400dcfd1ceb4e0db5a0f94f620">vm_error</a>(fmt,...)   g_error("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga110b31400dcfd1ceb4e0db5a0f94f620"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga1db45780168d7e5170bf035d82464988"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga1db45780168d7e5170bf035d82464988">vm_info</a>(fmt,...)   <a class="el" href="group__vmtools__logging.html#ga70ba83e48efbb05f34086febacc73a1d">g_info</a>("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga1db45780168d7e5170bf035d82464988"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga2d67df6d33c5a345aa7fe31f2e00eb57"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga2d67df6d33c5a345aa7fe31f2e00eb57">vm_message</a>(fmt,...)   g_message("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga2d67df6d33c5a345aa7fe31f2e00eb57"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga45c1b487669dbd0414012a663a48bcaf"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#ga45c1b487669dbd0414012a663a48bcaf">vm_warning</a>(fmt,...)   g_warning("%s: " fmt, FUNC, ## __VA_ARGS__)</td></tr>
<tr class="separator:ga45c1b487669dbd0414012a663a48bcaf"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gadde2056a5a855f11ab1577a7373b81e1"><td class="memItemLeft" align="right" valign="top">G_BEGIN_DECLS void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__logging.html#gadde2056a5a855f11ab1577a7373b81e1">VMTools_ConfigLogging</a> (const gchar *defaultDomain, GKeyFile *cfg, gboolean force, gboolean reset)</td></tr>
<tr class="separator:gadde2056a5a855f11ab1577a7373b81e1"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>The Tools logging facility is built on top of glib's logging functions (<a href="http://developer.gnome.org/glib/stable/glib-Message-Logging.html">http://developer.gnome.org/glib/stable/glib-Message-Logging.html</a>). Some convenience macros built on top of glib's existing macros are also provided.</p>
<p>Logging is configurable on a per-domain basis. The configuration options for each domain are:</p>
<ul>
<li>level: minimum log level to log. Also used to declare specific log domain configurations.<ul>
<li>Valid values: error, critical, warning, message, info, debug, none</li>
<li>This value is required when configuring a domain.</li>
</ul>
</li>
<li>handler: the handler to use when logging.<ul>
<li>Valid values: std, outputdebugstring (Win32-only), file, file+ (same as "file", but appends to existing log file), vmx, syslog.</li>
<li>Default: "syslog".</li>
</ul>
</li>
</ul>
<p>For file handlers, the following extra configuration information can be provided:</p>
<ul>
<li>data: path to the log file, required.</li>
<li>maxOldLogFiles: maximum number of rotated log files to keep around. By default, at most 10 backed up log files will be kept. Value should be >= 1.</li>
<li>maxLogSize: maximum size of each log file, defaults to 10 (MB). A value of 0 disables log rotation.</li>
</ul>
<p>When using syslog on Unix, the following options are available:</p>
<ul>
<li>facility: either of "daemon", "user" or "local[0-7]". Controls whether to connect to syslog as LOG_DAEMON, LOG_USER or LOG_LOCAL[0-7], respectively (see syslog(3)). Defaults to "user". Any unknown value is mapped to LOG_USER. This option should be defined for the application's default log domain (it's ignored for all other domains).</li>
</ul>
<p>The "vmx" logger will log all messages to the host; it's not recommended for normal use, since writing to the host log is an expensive operation and can also affect other running applications that need to send messages to the host. Do not use this logger unless explicitly instructed to do so.</p>
<p>Logging configuration should be under the "[logging]" group in the application's configuration file.</p>
<p>Each application can specify a default log domain (which defaults to "vmtools"). If no handler is specified for a particular domain when logging, the default handler will be used. The default logging level for the default domain is "warning" in non-debug builds, and "message" in debug builds.</p>
<p>Example of logging configuration in the config file:</p>
<pre class="fragment">* [logging]
* # Turns on logging globally. It can still be disabled for each domain.
* log = true
*
* # Disables core dumps on fatal errors; they're enabled by default.
* enableCoreDump = false
*
* # Defines the "vmsvc" domain, logging to stdout/stderr.
* vmsvc.level = info
* vmsvc.handler = std
*
* # Defines the "unity" domain, logging to a file.
* unity.level = warning
* unity.handler = file
* unity.data = /tmp/unity.log
*
* # Defines the "vmtoolsd" domain, and disable logging for it.
* vmtoolsd.level = none
* </pre><p>Log file names can contain references to pre-defined variables. The following variables are expanded when determining the path of the log file:</p>
<ul>
<li><em>${USER}</em>: expands to the current user's login name</li>
<li><em>${PID}</em>: expands to the current process's ID.</li>
<li><em>${IDX}</em>: expands to the log file index (for rolling logs).</li>
</ul>
<p>So, for example, <em>log</em>.${USER}.${PID}.txt would expand to "log.jdoe.1234.txt" for user "jdoe" if the process ID were 1234. </p>
<h2 class="groupheader">Macro Definition Documentation</h2>
<a class="anchor" id="ga70ba83e48efbb05f34086febacc73a1d"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define g_info</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_log(G_LOG_DOMAIN, G_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Log a message with G_LOG_LEVEL_INFO; this function is missing in glib for whatever reason.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga9e18287dc7c31eb280a776e7ca0842f3"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_critical</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_critical("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga4b4b57811a8b98e84f3264fff739a7f3"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_debug</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_debug("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p></p>
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga110b31400dcfd1ceb4e0db5a0f94f620"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_error</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_error("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p></p>
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga1db45780168d7e5170bf035d82464988"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_info</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   <a class="el" href="group__vmtools__logging.html#ga70ba83e48efbb05f34086febacc73a1d">g_info</a>("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p></p>
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga2d67df6d33c5a345aa7fe31f2e00eb57"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_message</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_message("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p></p>
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga45c1b487669dbd0414012a663a48bcaf"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define vm_warning</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">fmt, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"><em>...</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td>   g_warning("%s: " fmt, FUNC, ## __VA_ARGS__)</td>
</tr>
</table>
</div><div class="memdoc">
<p></p>
<p>Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">fmt</td><td>Log message format. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>Message arguments. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="gadde2056a5a855f11ab1577a7373b81e1"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_BEGIN_DECLS void VMTools_ConfigLogging </td>
<td>(</td>
<td class="paramtype">const gchar * </td>
<td class="paramname"><em>defaultDomain</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GKeyFile * </td>
<td class="paramname"><em>cfg</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">gboolean </td>
<td class="paramname"><em>force</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">gboolean </td>
<td class="paramname"><em>reset</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Configures the logging system according to the configuration in the given dictionary.</p>
<p>Optionally, it's possible to reset the logging subsystem; this will shut down all log handlers managed by the vmtools library before configuring the log system, which means that logging will behave as if the application was just started. A visible side-effect of this is that log files may be rotated (if they're not configure for appending).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">defaultDomain</td><td>Name of the default log domain. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">cfg</td><td>The configuration data. May be NULL. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">force</td><td>Whether to force logging to be enabled. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">reset</td><td>Whether to reset the logging subsystem first. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Nov 13 2013 17:04:41 for open-vm-tools 9.4.0 by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
