A collection of useful functions for when writing applications. More...
Defines | |
#define | MSG_MAGIC "@&!*@*@" |
#define | MSG_MAGIC_LEN 7 |
#define | MSGID(id) MSG_MAGIC "(" #id ")" |
#define | SU_(msgid, en) VMTools_GetString(VMW_TEXT_DOMAIN, MSGID(msgid) en) |
#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 | VMTools_BindTextDomain (const char *domain, const char *locale, const char *catdir) |
const char * | VMTools_GetString (const char *domain, const char *msgid) |
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) |
GSource * | VMTools_CreateTimer (gint timeout) |
Create a timer based on a monotonic clock source. | |
GArray * | VMTools_WrapArray (gconstpointer data, guint elemSize, guint count) |
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.
Logging is configurable on a per-domain basis. The configuration options for each domain are:
For file handlers, the following extra configuration information can be provided:
When using syslog, the following options are available:
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:
[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. The following variables are expanded when determining the path of the log file:
So, for example, log.${USER}.${PID}.txt would expand to "log.jdoe.1234.txt" for user "jdoe" if the process ID were 1234.
To create a localizable string, use the MSGID macro in the following manner:
VMTools_GetString("domain", MSGID(message.id) "Default English text.")
Or, in shorthand form:
SU_(message.id, "Default English text.")
This will instruct the code to retrive the message under key "message.id" in the translation catalog for the configured locale.
The shorthand macros use the VMW_TEXT_DOMAIN macro to identify the domain from which translated messages will be loaded. Each domain should first be initialized by calling VMTools_BindTextDomain().
#define SU_ | ( | msgid, | ||
en | ||||
) | VMTools_GetString(VMW_TEXT_DOMAIN, MSGID(msgid) en) |
Shorthand macro to retrieve a localized message in UTF-8.
[in] | msgid | The message ID. |
[in] | en | English version of the message. |
#define VMTOOLS_GET_FILENAME_LOCAL | ( | path, | ||
err | ||||
) |
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.
[in] | path | Path in UTF-8 (should not be NULL). |
[out] | err | Where to store errors (type: GError **; may be NULL). |
#define VMTOOLS_RELEASE_FILENAME_LOCAL | ( | path | ) | g_free(path) |
Frees a path allocated with VMTOOLS_GET_FILENAME_LOCAL. No-op on Windows.
[in] | path | Path in UTF-8. |
typedef gboolean(* SignalSourceCb)(const siginfo_t *, gpointer) |
Type of callback used by the signal event source.
G_BEGIN_DECLS void vm_free | ( | void * | ptr | ) |
Frees a pointer allocated by the vmtools library.
[in] | ptr | Pointer to memory to be freed. |
G_BEGIN_DECLS void VMTools_BindTextDomain | ( | const char * | domain, | |
const char * | lang, | |||
const char * | catdir | |||
) |
Loads the message catalog for a text domain. Each text domain contains a different set of messages loaded from a different catalog.
If a catalog has already been bound to the given name, it is replaced with the newly loaded data.
[in] | domain | Name of the text domain being loaded. |
[in] | lang | Language code for the text domain. |
[in] | catdir | Root directory of catalog files (NULL = default). |
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).
[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. |
GSource * VMTools_CreateTimer | ( | gint | timeout | ) |
Create a timer based on a monotonic clock source.
This timer differs from the glib timeout source, which uses the system time. It is recommended for code that needs more reliable time tracking, using a clock that is not affected by changes in the system time (which can happen when using NTP or the Tools time synchronization feature).
[in] | timeout | The timeout for the timer, must be >= 0. |
const char* VMTools_GetString | ( | const char * | domain, | |
const char * | msgid | |||
) |
Returns a localized version of the requested string in UTF-8.
[in] | domain | Text domain. |
[in] | msgid | Message id (including English translation). |
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).
[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. |
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);
[in] | signum | Signal to watch. |
GArray* VMTools_WrapArray | ( | gconstpointer | data, | |
guint | elemSize, | |||
guint | count | |||
) |
A convenience function for wrapping an array with a GArray instance.
[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. |
gboolean VMTools_WriteConfig | ( | const gchar * | path, | |
GKeyFile * | config, | |||
GError ** | err | |||
) |
Saves the given config data to the given path.
[in] | path | Where to save the data. |
[in] | config | Config data. |
[out] | err | Where to store error information (may be NULL). |