| Current File : //usr/share/doc/dbus/api/group__DBusMisc.html |
<!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"/>
<title>D-Bus: Miscellaneous</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">D-Bus
 <span id="projectnumber">1.8.20</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.6.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</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>
<div class="header">
<div class="summary">
<a href="#define-members">Defines</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Miscellaneous</div> </div>
<div class="ingroups"><a class="el" href="group__DBus.html">D-Bus low-level public API</a></div></div><!--header-->
<div class="contents">
<p>Miscellaneous API that doesn't cleanly fit anywhere else.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="define-members"></a>
Defines</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#gab0c43046c79ba743bb2a4ed39ca4a5cd">DBUS_MAJOR_VERSION</a>   1</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The COMPILE TIME major version of libdbus, that is, the "X" in "X.Y.Z", as an integer literal. <a href="#gab0c43046c79ba743bb2a4ed39ca4a5cd"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#ga6dcc9731da9f0713d55faa14937b4e06">DBUS_MINOR_VERSION</a>   8</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The COMPILE TIME minor version of libdbus, that is, the "Y" in "X.Y.Z", as an integer literal. <a href="#ga6dcc9731da9f0713d55faa14937b4e06"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#ga44289275b3259451d0ba4185c735f1a3">DBUS_MICRO_VERSION</a>   20</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The COMPILE TIME micro version of libdbus, that is, the "Z" in "X.Y.Z", as an integer literal. <a href="#ga44289275b3259451d0ba4185c735f1a3"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#ga75f948aee9cf34afea18081cb4a7395f">DBUS_VERSION</a>   ((1 << 16) | (8 << 8) | (20))</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The COMPILE TIME version of libdbus, as a single integer that has 0 in the most significant byte, the major version in the next most significant byte, the minor version in the third most significant, and the micro version in the least significant byte. <a href="#ga75f948aee9cf34afea18081cb4a7395f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#ga538fff8f5929a940d195f3d74c49b27f">DBUS_VERSION_STRING</a>   "1.8.20"</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The COMPILE TIME version of libdbus, as a string "X.Y.Z". <a href="#ga538fff8f5929a940d195f3d74c49b27f"></a><br/></td></tr>
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">char * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#ga2b21c9a12fea5f92763441c65ccbfcf9">dbus_get_local_machine_id</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Obtains the machine UUID of the machine this process is running on. <a href="#ga2b21c9a12fea5f92763441c65ccbfcf9"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a">dbus_get_version</a> (int *major_version_p, int *minor_version_p, int *micro_version_p)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Gets the DYNAMICALLY LINKED version of libdbus. <a href="#gacf200f947f77da9857685b58dc453d8a"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusMisc.html#gac02f6b021decd9fa35697a36ea581f86">dbus_setenv</a> (const char *variable, const char *value)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Wrapper for setenv(). <a href="#gac02f6b021decd9fa35697a36ea581f86"></a><br/></td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<p>Miscellaneous API that doesn't cleanly fit anywhere else. </p>
<hr/><h2>Define Documentation</h2>
<a class="anchor" id="gab0c43046c79ba743bb2a4ed39ca4a5cd"></a><!-- doxytag: member="dbus-arch-deps.h::DBUS_MAJOR_VERSION" ref="gab0c43046c79ba743bb2a4ed39ca4a5cd" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define <a class="el" href="group__DBusMisc.html#gab0c43046c79ba743bb2a4ed39ca4a5cd">DBUS_MAJOR_VERSION</a>   1</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The COMPILE TIME major version of libdbus, that is, the "X" in "X.Y.Z", as an integer literal. </p>
<p>Consider carefully whether to use this or the runtime version from <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a" title="Gets the DYNAMICALLY LINKED version of libdbus.">dbus_get_version()</a>. </p>
<p>Referenced by <a class="el" href="dbus-misc_8c_source.html#l00161">dbus_get_version()</a>.</p>
</div>
</div>
<a class="anchor" id="ga44289275b3259451d0ba4185c735f1a3"></a><!-- doxytag: member="dbus-arch-deps.h::DBUS_MICRO_VERSION" ref="ga44289275b3259451d0ba4185c735f1a3" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define <a class="el" href="group__DBusMisc.html#ga44289275b3259451d0ba4185c735f1a3">DBUS_MICRO_VERSION</a>   20</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The COMPILE TIME micro version of libdbus, that is, the "Z" in "X.Y.Z", as an integer literal. </p>
<p>Consider carefully whether to use this or the runtime version from <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a" title="Gets the DYNAMICALLY LINKED version of libdbus.">dbus_get_version()</a>. </p>
<p>Referenced by <a class="el" href="dbus-misc_8c_source.html#l00161">dbus_get_version()</a>.</p>
</div>
</div>
<a class="anchor" id="ga6dcc9731da9f0713d55faa14937b4e06"></a><!-- doxytag: member="dbus-arch-deps.h::DBUS_MINOR_VERSION" ref="ga6dcc9731da9f0713d55faa14937b4e06" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define <a class="el" href="group__DBusMisc.html#ga6dcc9731da9f0713d55faa14937b4e06">DBUS_MINOR_VERSION</a>   8</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The COMPILE TIME minor version of libdbus, that is, the "Y" in "X.Y.Z", as an integer literal. </p>
<p>Consider carefully whether to use this or the runtime version from <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a" title="Gets the DYNAMICALLY LINKED version of libdbus.">dbus_get_version()</a>. </p>
<p>Referenced by <a class="el" href="dbus-misc_8c_source.html#l00161">dbus_get_version()</a>.</p>
</div>
</div>
<a class="anchor" id="ga75f948aee9cf34afea18081cb4a7395f"></a><!-- doxytag: member="dbus-arch-deps.h::DBUS_VERSION" ref="ga75f948aee9cf34afea18081cb4a7395f" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define <a class="el" href="group__DBusMisc.html#ga75f948aee9cf34afea18081cb4a7395f">DBUS_VERSION</a>   ((1 << 16) | (8 << 8) | (20))</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The COMPILE TIME version of libdbus, as a single integer that has 0 in the most significant byte, the major version in the next most significant byte, the minor version in the third most significant, and the micro version in the least significant byte. </p>
<p>This means two DBUS_VERSION can be compared to see which is higher.</p>
<p>Consider carefully whether to use this or the runtime version from <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a" title="Gets the DYNAMICALLY LINKED version of libdbus.">dbus_get_version()</a>. </p>
</div>
</div>
<a class="anchor" id="ga538fff8f5929a940d195f3d74c49b27f"></a><!-- doxytag: member="dbus-arch-deps.h::DBUS_VERSION_STRING" ref="ga538fff8f5929a940d195f3d74c49b27f" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define <a class="el" href="group__DBusMisc.html#ga538fff8f5929a940d195f3d74c49b27f">DBUS_VERSION_STRING</a>   "1.8.20"</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The COMPILE TIME version of libdbus, as a string "X.Y.Z". </p>
<p>Consider carefully whether to use this or the runtime version from <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a" title="Gets the DYNAMICALLY LINKED version of libdbus.">dbus_get_version()</a>. </p>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga2b21c9a12fea5f92763441c65ccbfcf9"></a><!-- doxytag: member="dbus-misc.c::dbus_get_local_machine_id" ref="ga2b21c9a12fea5f92763441c65ccbfcf9" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT char * <a class="el" href="group__DBusMisc.html#ga2b21c9a12fea5f92763441c65ccbfcf9">dbus_get_local_machine_id</a> </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Obtains the machine UUID of the machine this process is running on. </p>
<p>The returned string must be freed with <a class="el" href="group__DBusMemory.html#ga34e666b19b015035a9a31e53da84b39a" title="Frees a block of memory previously allocated by dbus_malloc() or dbus_malloc0().">dbus_free()</a>.</p>
<p>This UUID is guaranteed to remain the same until the next reboot (unless the sysadmin foolishly changes it and screws themselves). It will usually remain the same across reboots also, but hardware configuration changes or rebuilding the machine could break that.</p>
<p>The idea is that two processes with the same machine ID should be able to use shared memory, UNIX domain sockets, process IDs, and other features of the OS that require both processes to be running on the same OS kernel instance.</p>
<p>The machine ID can also be used to create unique per-machine instances. For example, you could use it in bus names or X selection names.</p>
<p>The machine ID is preferred over the machine hostname, because the hostname is frequently set to "localhost.localdomain" and may also change at runtime.</p>
<p>You can get the machine ID of a remote application by invoking the method GetMachineId from interface org.freedesktop.DBus.Peer.</p>
<p>If the remote application has the same machine ID as the one returned by this function, then the remote application is on the same machine as your application.</p>
<p>The UUID is not a UUID in the sense of RFC4122; the details are explained in the D-Bus specification.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>a 32-byte-long hex-encoded UUID string, or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> if insufficient memory </dd></dl>
<p>Definition at line <a class="el" href="dbus-misc_8c_source.html#l00073">73</a> of file <a class="el" href="dbus-misc_8c_source.html">dbus-misc.c</a>.</p>
<p>References <a class="el" href="dbus-internals_8c_source.html#l00854">_dbus_get_local_machine_uuid_encoded()</a>, <a class="el" href="dbus-string_8c_source.html#l00242">_dbus_string_free()</a>, <a class="el" href="dbus-string_8c_source.html#l00175">_dbus_string_init()</a>, <a class="el" href="dbus-string_8c_source.html#l00624">_dbus_string_steal_data()</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="gacf200f947f77da9857685b58dc453d8a"></a><!-- doxytag: member="dbus-misc.c::dbus_get_version" ref="gacf200f947f77da9857685b58dc453d8a" args="(int *major_version_p, int *minor_version_p, int *micro_version_p)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT void <a class="el" href="group__DBusMisc.html#gacf200f947f77da9857685b58dc453d8a">dbus_get_version</a> </td>
<td>(</td>
<td class="paramtype">int * </td>
<td class="paramname"><em>major_version_p</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>minor_version_p</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>micro_version_p</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Gets the DYNAMICALLY LINKED version of libdbus. </p>
<p>Alternatively, there are macros <a class="el" href="group__DBusMisc.html#gab0c43046c79ba743bb2a4ed39ca4a5cd" title="The COMPILE TIME major version of libdbus, that is, the "X" in "X.Y.Z", as an integer literal...">DBUS_MAJOR_VERSION</a>, <a class="el" href="group__DBusMisc.html#ga6dcc9731da9f0713d55faa14937b4e06" title="The COMPILE TIME minor version of libdbus, that is, the "Y" in "X.Y.Z", as an integer literal...">DBUS_MINOR_VERSION</a>, <a class="el" href="group__DBusMisc.html#ga44289275b3259451d0ba4185c735f1a3" title="The COMPILE TIME micro version of libdbus, that is, the "Z" in "X.Y.Z", as an integer literal...">DBUS_MICRO_VERSION</a>, and <a class="el" href="group__DBusMisc.html#ga75f948aee9cf34afea18081cb4a7395f" title="The COMPILE TIME version of libdbus, as a single integer that has 0 in the most significant byte...">DBUS_VERSION</a> which allow you to test the VERSION YOU ARE COMPILED AGAINST. In other words, you can get either the runtime or the compile-time version. Think carefully about which of these you want in a given case.</p>
<p>The libdbus full version number is "MAJOR.MINOR.MICRO" where the MINOR changes if API is added, and the MICRO changes with each release of a MAJOR.MINOR series. The MINOR is an odd number for development releases and an even number for stable releases.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">major_version_p</td><td>pointer to return the major version, or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> </td></tr>
<tr><td class="paramname">minor_version_p</td><td>pointer to return the minor version, or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> </td></tr>
<tr><td class="paramname">micro_version_p</td><td>pointer to return the micro version, or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <a class="el" href="dbus-misc_8c_source.html#l00161">161</a> of file <a class="el" href="dbus-misc_8c_source.html">dbus-misc.c</a>.</p>
<p>References <a class="el" href="group__DBusMisc.html#gab0c43046c79ba743bb2a4ed39ca4a5cd">DBUS_MAJOR_VERSION</a>, <a class="el" href="group__DBusMisc.html#ga44289275b3259451d0ba4185c735f1a3">DBUS_MICRO_VERSION</a>, and <a class="el" href="group__DBusMisc.html#ga6dcc9731da9f0713d55faa14937b4e06">DBUS_MINOR_VERSION</a>.</p>
</div>
</div>
<a class="anchor" id="gac02f6b021decd9fa35697a36ea581f86"></a><!-- doxytag: member="dbus-misc.h::dbus_setenv" ref="gac02f6b021decd9fa35697a36ea581f86" args="(const char *variable, const char *value)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> <a class="el" href="group__DBusMisc.html#gac02f6b021decd9fa35697a36ea581f86">dbus_setenv</a> </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>varname</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>value</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Wrapper for setenv(). </p>
<p>If the value is <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a>, unsets the environment variable.</p>
<p>There is an unfixable memleak in that it is unsafe to free memory malloced for use with setenv. This is because we can not rely on internal implementation details of the underlying libc library.</p>
<p>This function is not thread-safe, because altering the environment in Unix is not thread-safe in general.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">varname</td><td>name of environment variable </td></tr>
<tr><td class="paramname">value</td><td>value of environment variable, or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> to unset </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d" title="Expands to "1".">TRUE</a> on success, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1" title="Expands to "0".">FALSE</a> if not enough memory. </dd></dl>
<p>Definition at line <a class="el" href="dbus-sysdeps_8c_source.html#l00114">114</a> of file <a class="el" href="dbus-sysdeps_8c_source.html">dbus-sysdeps.c</a>.</p>
<p>References <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>, <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>, and <a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d">TRUE</a>.</p>
<p>Referenced by <a class="el" href="dbus-server-launchd_8c_source.html#l00065">_dbus_server_new_for_launchd()</a>.</p>
</div>
</div>
</div><!-- contents -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu Mar 3 2016 17:50:33 for D-Bus by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>
</body>
</html>