<!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: Utility Functions</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="#typedef-members">Typedefs</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Utility Functions</div> </div>
</div><!--header-->
<div class="contents">
<p>A collection of useful functions.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:gaf964999a4cde8d01e0771753cbef4bc9"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="gaf964999a4cde8d01e0771753cbef4bc9"></a>
#define </td><td class="memItemRight" valign="bottom"><b>VMTOOLS_GUEST_SERVICE</b>   "vmsvc"</td></tr>
<tr class="separator:gaf964999a4cde8d01e0771753cbef4bc9"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga48e5d8ebb93c1edb1da3eda888907d92"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga48e5d8ebb93c1edb1da3eda888907d92"></a>
#define </td><td class="memItemRight" valign="bottom"><b>VMTOOLS_USER_SERVICE</b>   "vmusr"</td></tr>
<tr class="separator:ga48e5d8ebb93c1edb1da3eda888907d92"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga83001e4e4b9c2872f10ce2c0bb7ffc16"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga83001e4e4b9c2872f10ce2c0bb7ffc16"></a>
#define </td><td class="memItemRight" valign="bottom"><b>VMTOOLS_EXTERN_C</b></td></tr>
<tr class="separator:ga83001e4e4b9c2872f10ce2c0bb7ffc16"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gab9852cd74e388a6797dbbb3e87aa8bc8"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#gab9852cd74e388a6797dbbb3e87aa8bc8">VMTOOLS_GET_FILENAME_LOCAL</a>(path, err)</td></tr>
<tr class="separator:gab9852cd74e388a6797dbbb3e87aa8bc8"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga611757887a50a7f51e649120a3df6c4f"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga611757887a50a7f51e649120a3df6c4f">VMTOOLS_RELEASE_FILENAME_LOCAL</a>(path)   g_free(path)</td></tr>
<tr class="separator:ga611757887a50a7f51e649120a3df6c4f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga8c9d83035e890b7273dc2d4385be260b"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga8c9d83035e890b7273dc2d4385be260b">VMTOOLS_WRAP_ARRAY</a>(a)   <a class="el" href="group__vmtools__utils.html#ga40b30302b4d3997bdc4745b92a09d70f">VMTools_WrapArray</a>((a), sizeof *(a), G_N_ELEMENTS(a))</td></tr>
<tr class="separator:ga8c9d83035e890b7273dc2d4385be260b"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:gab13153016401a208b1c41f6b8c81c052"><td class="memItemLeft" align="right" valign="top">typedef gboolean(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#gab13153016401a208b1c41f6b8c81c052">SignalSourceCb</a> )(const siginfo_t *, gpointer)</td></tr>
<tr class="separator:gab13153016401a208b1c41f6b8c81c052"><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:ga6f935b7648b47dbae52c2edb4f892dda"><td class="memItemLeft" align="right" valign="top">G_BEGIN_DECLS void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga6f935b7648b47dbae52c2edb4f892dda">vm_free</a> (void *ptr)</td></tr>
<tr class="separator:ga6f935b7648b47dbae52c2edb4f892dda"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga3db49abe969e99a29b8d2590feec64a9"><td class="memItemLeft" align="right" valign="top">gboolean </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga3db49abe969e99a29b8d2590feec64a9">VMTools_LoadConfig</a> (const gchar *path, GKeyFileFlags flags, GKeyFile **config, time_t *mtime)</td></tr>
<tr class="separator:ga3db49abe969e99a29b8d2590feec64a9"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gac9052f51dcb62b42dfd7eceec5591fb1"><td class="memItemLeft" align="right" valign="top">gboolean </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#gac9052f51dcb62b42dfd7eceec5591fb1">VMTools_WriteConfig</a> (const gchar *path, GKeyFile *config, GError **err)</td></tr>
<tr class="separator:gac9052f51dcb62b42dfd7eceec5591fb1"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga61fb50a329cdef171dcb0132f0df1e89"><td class="memItemLeft" align="right" valign="top">GSource * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga61fb50a329cdef171dcb0132f0df1e89">VMTools_NewSignalSource</a> (int signum)</td></tr>
<tr class="separator:ga61fb50a329cdef171dcb0132f0df1e89"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaadfa18f1e3d7a6a1b258e9678c7acdbc"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="gaadfa18f1e3d7a6a1b258e9678c7acdbc"></a>
gchar * </td><td class="memItemRight" valign="bottom"><b>VMTools_GetLibdir</b> (void)</td></tr>
<tr class="separator:gaadfa18f1e3d7a6a1b258e9678c7acdbc"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gac0df56babdddde9efc60a57c02e268aa"><td class="memItemLeft" align="right" valign="top">GSource * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#gac0df56babdddde9efc60a57c02e268aa">VMTools_CreateTimer</a> (gint timeout)</td></tr>
<tr class="memdesc:gac0df56babdddde9efc60a57c02e268aa"><td class="mdescLeft"> </td><td class="mdescRight">Create a timer based on a monotonic clock source. <a href="#gac0df56babdddde9efc60a57c02e268aa">More...</a><br/></td></tr>
<tr class="separator:gac0df56babdddde9efc60a57c02e268aa"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga40b30302b4d3997bdc4745b92a09d70f"><td class="memItemLeft" align="right" valign="top">GArray * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__utils.html#ga40b30302b4d3997bdc4745b92a09d70f">VMTools_WrapArray</a> (gconstpointer data, guint elemSize, guint count)</td></tr>
<tr class="separator:ga40b30302b4d3997bdc4745b92a09d70f"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>A collection of useful functions. </p>
<p>This module contains functions for loading configuration data and extensions to the glib API that are useful when writing applications. </p>
<h2 class="groupheader">Macro Definition Documentation</h2>
<a class="anchor" id="gab9852cd74e388a6797dbbb3e87aa8bc8"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define VMTOOLS_GET_FILENAME_LOCAL</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">path, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname">err </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<b>Value:</b><div class="fragment"><div class="line">g_filename_from_utf8((path), \</div>
<div class="line"> -1, \</div>
<div class="line"> NULL, \</div>
<div class="line"> NULL, \</div>
<div class="line"> (err))</div>
</div><!-- fragment --><p>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.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">path</td><td>Path in UTF-8 (should not be NULL). </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">err</td><td>Where to store errors (type: GError **; may be NULL).</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The path in glib's filename encoding, or NULL on error. </dd></dl>
</div>
</div>
<a class="anchor" id="ga611757887a50a7f51e649120a3df6c4f"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define VMTOOLS_RELEASE_FILENAME_LOCAL</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">path</td><td>)</td>
<td>   g_free(path)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Frees a path allocated with VMTOOLS_GET_FILENAME_LOCAL. No-op on Windows.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">path</td><td>Path in UTF-8. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga8c9d83035e890b7273dc2d4385be260b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define VMTOOLS_WRAP_ARRAY</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">a</td><td>)</td>
<td>   <a class="el" href="group__vmtools__utils.html#ga40b30302b4d3997bdc4745b92a09d70f">VMTools_WrapArray</a>((a), sizeof *(a), G_N_ELEMENTS(a))</td>
</tr>
</table>
</div><div class="memdoc">
<p>Convenience macro around VMTools_WrapArray. </p>
</div>
</div>
<h2 class="groupheader">Typedef Documentation</h2>
<a class="anchor" id="gab13153016401a208b1c41f6b8c81c052"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef gboolean(* SignalSourceCb)(const siginfo_t *, gpointer)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Type of callback used by the signal event source. </p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga6f935b7648b47dbae52c2edb4f892dda"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_BEGIN_DECLS void vm_free </td>
<td>(</td>
<td class="paramtype">void * </td>
<td class="paramname"><em>ptr</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Frees a pointer allocated by the vmtools library.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">ptr</td><td>Pointer to memory to be freed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="gac0df56babdddde9efc60a57c02e268aa"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">GSource * VMTools_CreateTimer </td>
<td>(</td>
<td class="paramtype">gint </td>
<td class="paramname"><em>timeout</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Create a timer based on a monotonic clock source. </p>
<p>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).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">timeout</td><td>The timeout for the timer, must be >= 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The new source. </dd></dl>
</div>
</div>
<a class="anchor" id="ga3db49abe969e99a29b8d2590feec64a9"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">gboolean VMTools_LoadConfig </td>
<td>(</td>
<td class="paramtype">const gchar * </td>
<td class="paramname"><em>path</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GKeyFileFlags </td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GKeyFile ** </td>
<td class="paramname"><em>config</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">time_t * </td>
<td class="paramname"><em>mtime</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Loads the configuration file at the given path.</p>
<p>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).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">path</td><td>Path to the configuration file, or NULL for default Tools config file. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">flags</td><td>Flags for opening the file. </td></tr>
<tr><td class="paramdir">[in,out]</td><td class="paramname">config</td><td>Where to store the config dictionary; when reloading the file, the old config object will be destroyed. </td></tr>
<tr><td class="paramdir">[in,out]</td><td class="paramname">mtime</td><td>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.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Whether a new config dictionary was loaded. </dd></dl>
</div>
</div>
<a class="anchor" id="ga61fb50a329cdef171dcb0132f0df1e89"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">GSource * VMTools_NewSignalSource </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>signum</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Creates a new source for the given signal.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Example of setting a handler for a signal:</p>
<div class="fragment"><div class="line">*</div>
<div class="line">* GSource *src = <a class="code" href="group__vmtools__utils.html#ga61fb50a329cdef171dcb0132f0df1e89">VMTools_NewSignalSource</a>(signum);</div>
<div class="line">* g_source_set_callback(src, MyCallback, myData, NULL);</div>
<div class="line">* g_source_attach(src, myContext);</div>
<div class="line">*</div>
<div class="line">* </div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>This API is not available on Win32.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">signum</td><td>Signal to watch.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Pointer to the new source, NULL if failed to set signal handler. </dd></dl>
</div>
</div>
<a class="anchor" id="ga40b30302b4d3997bdc4745b92a09d70f"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">GArray* VMTools_WrapArray </td>
<td>(</td>
<td class="paramtype">gconstpointer </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">guint </td>
<td class="paramname"><em>elemSize</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">guint </td>
<td class="paramname"><em>count</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>A convenience function for wrapping an array with a GArray instance.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>The array data. The original data is copied into the new array. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">elemSize</td><td>The size of each element in the array. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">count</td><td>The number of elements in the array.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A new GArray. </dd></dl>
</div>
</div>
<a class="anchor" id="gac9052f51dcb62b42dfd7eceec5591fb1"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">gboolean VMTools_WriteConfig </td>
<td>(</td>
<td class="paramtype">const gchar * </td>
<td class="paramname"><em>path</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GKeyFile * </td>
<td class="paramname"><em>config</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GError ** </td>
<td class="paramname"><em>err</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Saves the given config data to the given path.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">path</td><td>Where to save the data. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">config</td><td>Config data. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">err</td><td>Where to store error information (may be NULL).</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Whether saving was successful. </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>
