Utility Functions

A collection of useful functions for when writing applications. More...

Defines

#define VMTOOLS_GUEST_SERVICE   "vmsvc"
#define VMTOOLS_USER_SERVICE   "vmusr"
#define VMTOOLS_EXTERN_C
#define VMTOOLS_GET_FILENAME_LOCAL(path, err)
#define VMTOOLS_RELEASE_FILENAME_LOCAL(path)   g_free(path)

Typedefs

typedef gboolean(* SignalSourceCb )(const siginfo_t *, gpointer)

Functions

G_BEGIN_DECLS void vm_free (void *ptr)
void VMTools_ConfigLogging (const gchar *defaultDomain, GKeyFile *cfg, gboolean force, gboolean reset)
gboolean VMTools_LoadConfig (const gchar *path, GKeyFileFlags flags, GKeyFile **config, time_t *mtime)
gboolean VMTools_WriteConfig (const gchar *path, GKeyFile *config, GError **err)
GSource * VMTools_NewSignalSource (int signum)
GArray * VMTools_WrapArray (gconstpointer data, guint elemSize, guint count)

Detailed Description

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.

Configuring Logging

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

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:

[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

Log file names can contain variable references. Currently, only two variables are expanded: ${USER} expands to the current user's login name, and ${PID} expands to the current process's ID. So, for example, log.${USER}.${PID}.txt would expand to "log.jdoe.1234.txt" for user "jdoe" if the process ID were 1234.


Define Documentation

#define VMTOOLS_GET_FILENAME_LOCAL ( path,
err   ) 
Value:
g_filename_from_utf8((path),  \
                                                                     -1,      \
                                                                     NULL,    \
                                                                     NULL,    \
                                                                     (err))

Converts an UTF-8 path to the local (i.e., glib) file name encoding. This is a no-op on Windows, since the local encoding is always UTF-8 in glib. The returned value should not be freed directly; instead, use VMTOOLS_RELEASE_FILENAME_LOCAL.

Parameters:
[in] path Path in UTF-8 (should not be NULL).
[out] err Where to store errors (type: GError **; may be NULL).
Returns:
The path in glib's filename encoding, or NULL on error.
#define VMTOOLS_RELEASE_FILENAME_LOCAL ( path   )     g_free(path)

Frees a path allocated with VMTOOLS_GET_FILENAME_LOCAL. No-op on Windows.

Parameters:
[in] path Path in UTF-8.

Typedef Documentation

typedef gboolean(* SignalSourceCb)(const siginfo_t *, gpointer)

Type of callback used by the signal event source.


Function Documentation

G_BEGIN_DECLS void vm_free ( void *  ptr  ) 

Frees a pointer allocated by the vmtools library.

Parameters:
[in] ptr Pointer to memory to be freed.
void VMTools_ConfigLogging ( const gchar *  defaultDomain,
GKeyFile *  cfg,
gboolean  force,
gboolean  reset 
)

Configures the logging system according to the configuration in the given dictionary.

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

Parameters:
[in] defaultDomain Name of the default log domain.
[in] cfg The configuration data. May be NULL.
[in] force Whether to force logging to be enabled.
[in] reset Whether to reset the logging subsystem first.
gboolean VMTools_LoadConfig ( const gchar *  path,
GKeyFileFlags  flags,
GKeyFile **  config,
time_t *  mtime 
)

Loads the configuration file at the given path.

If an old configuration file is detected and the current process has write permission to the file, the configuration data will automatically upgraded to the new configuration format (the old configuration file is saved with a ".old" extension).

Parameters:
[in] path Path to the configuration file, or NULL for default Tools config file.
[in] flags Flags for opening the file.
[in,out] config Where to store the config dictionary; when reloading the file, the old config object will be destroyed.
[in,out] mtime Last known modification time of the config file. When the function succeeds, will contain the new modification time read from the file. If NULL (or 0), the config dictionary is always loaded.
Returns:
Whether a new config dictionary was loaded.
GSource * VMTools_NewSignalSource ( int  signum  ) 

Creates a new source for the given signal.

Rather than processing the events in the signal handling context, the main loop is woken up and callbacks are processed in the main loop's thread.

The same "wakeup" file descriptors are used for all sources, so if sources are added to different main loop instances, all of them will be woken up if any signal for which handlers are registered occurs.

This code assumes that the rest of the app is not setting signal handlers directly, at least for signals for which glib sources have been set up.

Also note that on older Linux systems (pre-NPTL), some real-time signals are used by the pthread library and shouldn't be used by applications.

Example of setting a handler for a signal:

    GSource *src = VMTools_NewSignalSource(signum);
    g_source_set_callback(src, MyCallback, myData, NULL);
    g_source_attach(src, myContext);
Note:
This API is not available on Win32.
Parameters:
[in] signum Signal to watch.
Returns:
Pointer to the new source, NULL if failed to set signal handler.
GArray* VMTools_WrapArray ( gconstpointer  data,
guint  elemSize,
guint  count 
)

A convenience function for wrapping an array with a GArray instance.

Parameters:
[in] data The array data. The original data is copied into the new array.
[in] elemSize The size of each element in the array.
[in] count The number of elements in the array.
Returns:
A new GArray.
gboolean VMTools_WriteConfig ( const gchar *  path,
GKeyFile *  config,
GError **  err 
)

Saves the given config data to the given path.

Parameters:
[in] path Where to save the data.
[in] config Config data.
[out] err Where to store error information (may be NULL).
Returns:
Whether saving was successful.

Generated on 15 Jan 2010 for open-vm-tools 2009.12.16 by  doxygen 1.6.1