open-vm-tools 13.1.0: Utility Functions

open-vm-tools 13.1.0

Utility Functions

A collection of useful functions. More...

## Macros
#define | VMTOOLS_GUEST_SERVICE "vmsvc"
#define | VMTOOLS_USER_SERVICE "vmusr"
#define | VMTOOLS_EXTERN_C
#define | ABS(x)
#define | VMTOOLS_GET_FILENAME_LOCAL(path, err)
#define | VMTOOLS_RELEASE_FILENAME_LOCAL(path)
#define | VMTOOLS_WRAP_ARRAY(a)

## Typedefs
typedef gboolean(* | SignalSourceCb) (const siginfo_t *, gpointer)

## Functions
G_BEGIN_DECLS void | vm_free (void *ptr)
gboolean | VMTools_LoadConfig (const gchar *path, GKeyFileFlags flags, GKeyFile **config, time_t *mtime)
gboolean | VMTools_AddConfig (GKeyFile *srcConfig, GKeyFile *dstConfig)
gboolean | VMTools_CompareConfig (GKeyFile *config1, GKeyFile *config2)
gboolean | VMTools_WriteConfig (const gchar *path, GKeyFile *config, GError **err)
gboolean | VMTools_ChangeLogFilePath (const gchar *delimiter, const gchar *appendString, const gchar *domain, GKeyFile *conf)
gboolean | VMTools_ConfigGetBoolean (GKeyFile *config, const gchar *section, const gchar *key, const gboolean defValue)
gint | VMTools_ConfigGetInteger (GKeyFile *config, const gchar *section, const gchar *key, const gint defValue)
gchar * | VMTools_ConfigGetString (GKeyFile *config, const gchar *section, const gchar *key, const gchar *defValue)
GSource * | VMTools_NewSignalSource (int signum)
gchar * | VMTools_GetLibdir (void)
void | VMTools_SetupEnv (const gchar *appName, GKeyFile *config, gboolean globalVars)
GSource * | VMTools_CreateTimer (gint timeout)
| Create a timer based on a monotonic clock source.
void | VMTools_AcquireLogStateLock (void)
void | VMTools_ReleaseLogStateLock (void)
gchar * | VMTools_GetTimeAsString (void)
void | VMTools_SuspendLogIO (void)
void | VMTools_ResumeLogIO (void)
GArray * | VMTools_WrapArray (gconstpointer data, guint elemSize, guint count)

## Detailed Description

A collection of useful functions.

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

## Macro Definition Documentation

## ◆ ABS

#define ABS | ( |  | x | ) |

Value:
(((x) >= 0) ? (x) : -(x))

## ◆ VMTOOLS_GET_FILENAME_LOCAL

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

## ◆ VMTOOLS_RELEASE_FILENAME_LOCAL

#define VMTOOLS_RELEASE_FILENAME_LOCAL | ( |  | path | ) |

Value:
g_free(path)

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

Parameters

  [in] | path | Path in UTF-8.

## ◆ VMTOOLS_WRAP_ARRAY

#define VMTOOLS_WRAP_ARRAY | ( |  | a | ) |

Value:
VMTools_WrapArray((a), sizeof *(a), G_N_ELEMENTS(a))
VMTools_WrapArray
GArray * VMTools_WrapArray(gconstpointer data, guint elemSize, guint count)
Definition vmtools.c:60

Convenience macro around VMTools_WrapArray.

## Typedef Documentation

## ◆ SignalSourceCb

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

Type of callback used by the signal event source.

## Function Documentation

## ◆ vm_free()

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.

## ◆ VMTools_AcquireLogStateLock()

void VMTools_AcquireLogStateLock | ( | void |  | ) |

Acquire the log state lock.

## ◆ VMTools_AddConfig()

gboolean VMTools_AddConfig | ( | GKeyFile * | srcConfig,
|  | GKeyFile * | dstConfig )

Copies the key/value pairs from one config dictionary to another config dictionary. The key/value pairs are added only if they are not already present in the destination configuration dictionary.

Parameters

  [in] | srcConfig | Configuration dictionary from which the key/value pairs should be added.
  [in] | dstConfig | Configuration dictionary to which the key/value pairs should be added..

Returns
  Whether any key/value pairs have been added to the config dictionary.

## ◆ VMTools_ChangeLogFilePath()

gboolean VMTools_ChangeLogFilePath | ( | const gchar * | delimiter,
|  | const gchar * | appendString,
|  | const gchar * | domain,
|  | GKeyFile * | conf )

This function gets the log file location given in the config file and appends the string provided just before the delimiter specified. If more than one delimiter is present in the string, it appends just before the first delimiter. If the delimiter does not exist in the location, the string provided is appended at the end of the location.

NOTE: It is up to the caller to free the delimiter and append string.

Example: 1) location - "C:\vmresset.log", delimiter - ".", appendString - "_4" location changed = "C:\vmresset_4.log" 2) location - "C:\vmresset", delimiter - ".", appendString - "_4" location changed = "C:\vmresset_4" 3) location - "C:\vmresset.log.log", delimiter - ".", appendString - "_4" location changed = "C:\vmresset_4.log.log"

Results: TRUE if log file location is changed, FALSE otherwise.

Side effects: Appends a string into the log file location.

## ◆ VMTools_CompareConfig()

gboolean VMTools_CompareConfig | ( | GKeyFile * | config1,
|  | GKeyFile * | config2 )

Compares two configuration dictionaries. Compares all the groups and key/value pairs in both the configuration dictionaries. If all the entries are same, TRUE is returned. Else, FALSE is returned.

Parameters

  [in] | config1 | First configuration dictionary to compare.
  [in] | config2 | Second configuration dictionary to compare.

Returns
  TRUE if both the specified configuration dictionaries are identical. FALSE otherwise.

## ◆ VMTools_ConfigGetBoolean()

gboolean VMTools_ConfigGetBoolean | ( | GKeyFile * | config,
|  | const gchar * | section,
|  | const gchar * | key,
|  | const gboolean | defValue )

Loads boolean value for a key from the specified config section.

Parameters

  [in] | config | Config file to read the key from.
  [in] | section | Section to look for in the config file.
  [in] | key | Key to look for in the section.
  [in] | defValue | Default value if the key is not found or error.

Returns
  value of the key if value was read successfully, else defValue.

## ◆ VMTools_ConfigGetInteger()

gint VMTools_ConfigGetInteger | ( | GKeyFile * | config,
|  | const gchar * | section,
|  | const gchar * | key,
|  | const gint | defValue )

Loads integer value for a key from the specified config section.

Parameters

  [in] | config | Config file to read the key from.
  [in] | section | Section to look for in the config file.
  [in] | key | Key to look for in the section.
  [in] | defValue | Default value if the key is not found or error.

Returns
  value of the key if value was read successfully, else defValue.

## ◆ VMTools_ConfigGetString()

gchar * VMTools_ConfigGetString | ( | GKeyFile * | config,
|  | const gchar * | section,
|  | const gchar * | key,
|  | const gchar * | defValue )

Loads string value for a key from the specified config section.

Parameters

  [in] | config | Config file to read the key from.
  [in] | section | Section to look for in the config file.
  [in] | key | Key to look for in the section.
  [in] | defValue | Default value if the key is not found or error.

Returns
  value of the key if value was read successfully, else a copy of defValue unless defValue is NULL, in which case it's NULL. The returned string should be freed with g_free() when no longer needed.

## ◆ VMTools_CreateTimer()

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

Parameters

  [in] | timeout | The timeout for the timer, must be >= 0.

Returns
  The new source.

## ◆ VMTools_GetLibdir()

gchar * VMTools_GetLibdir | ( | void |  | ) |

Reads the /etc/vmware-tools/config file and returns the vlaue of 'libdir' property.

Returns
  The value of 'libdir' property. NULL if the 'libdir' property is not found in the config file.

## ◆ VMTools_GetTimeAsString()

gchar * VMTools_GetTimeAsString | ( | void |  | ) |

VMTools_GetTimeAsString –

Returns the current UTC timestamp information

Ex: "2018-02-22T21:17:38.517Z"

The caller must free the return value using g_free

Returns
  Properly formatted string that contains the timestamp. NULL if the timestamp cannot be retrieved.

## ◆ VMTools_LoadConfig()

gboolean VMTools_LoadConfig | ( | const gchar * | path,
|  | GKeyFileFlags | flags,
|  | GKeyFile ** | config,
|  | time_t * | mtime )

Loads the configuration file at the given path.

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.

## ◆ VMTools_NewSignalSource()

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);
VMTools_NewSignalSource
GSource * VMTools_NewSignalSource(int signum)
Definition signalSource.c:271

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.

## ◆ VMTools_ReleaseLogStateLock()

void VMTools_ReleaseLogStateLock | ( | void |  | ) |

Release the log state lock.

## ◆ VMTools_ResumeLogIO()

void VMTools_ResumeLogIO | ( | void |  | ) |

Resume IO caused by logging activity.

## ◆ VMTools_SetupEnv()

void VMTools_SetupEnv | ( | const gchar * | appName,
|  | GKeyFile * | config,
|  | gboolean | globalVars )

Setup environment variables for the current process.

Parameters

  [in] | appName | app name.
  [in] | config | config dictionary.
  [in] | globalVars | global variables.

## ◆ VMTools_SuspendLogIO()

void VMTools_SuspendLogIO | ( | void |  | ) |

Suspend IO caused by logging activity.

## ◆ VMTools_WrapArray()

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.

## ◆ VMTools_WriteConfig()

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.