/*********************************************************
 * Copyright (C) 2008 VMware, 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:
 *
 * 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 of VMware Inc. nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission of VMware Inc.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
 *
 *********************************************************/

/**

@defgroup vmtools_utils Utility Functions

@brief A collection of useful functions for when writing applications.

This module contains functions for loading configuration data, logging, and
extensions to the glib API that are useful when writing applications.

@section vmtools_utils_log Configuring Logging

Logging is configurable on a per-domain basis. The configuration options
for each domain are:

   - level: minimum log level to log. Also used to declare specific log
     domain configurations.
     - Valid values: error, critical, warning, message, info, debug, none
     - This value is required when configuring a domain.
   - handler: the handler to use when logging.
     - Valid values: std, outputdebugstring (Win32-only), file, file+, vmx
       (same as "file", but appends to existing log file), syslog (Unix only).
     - Default: "std" on Unix, "outputdebugstring" on Windows.

For file handlers, the following extra configuration information can be
provided:

   - data: path to the log file, required.
   - 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.
   - maxLogSize: maximum size of each log file, defaults to 10 (MB). A value of
     0 disables log rotation.

When using syslog, the following options are available:

   - 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).

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.

Logging configuration should be under the "[logging]" group in the
application's configuration file.

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.

Example of logging configuration in the config file:

@verbatim
[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
@endverbatim

Log file names can contain variable references. The following variables are
expanded when determining the path of the log file:

   - @a ${USER}: expands to the current user's login name
   - @a ${PID}: expands to the current process's ID.
   - @a ${IDX}: expands to the log file index (for rolling logs).

So, for example, @a log.${USER}.${PID}.txt would expand to "log.jdoe.1234.txt"
for user "jdoe" if the process ID were 1234.

*/

