<!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"/>
<title>Elektra Projekt: Key :: Meta Info Manipulation Methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<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>
</ul>
</div>
</div>
<div class="contents">
<h1>Key :: Meta Info Manipulation Methods</h1>
<p>Methods to do various operations on Key metainfo.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gab8189add5e562bdb148675ee595bd95b">keyStat</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">uid_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gacaa5060e67b03f50ae49a3620c54bc46">keyGetUID</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gab5f284f5ecd261e0a290095f50ba1af7">keySetUID</a> (Key *key, uid_t uid)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">gid_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga46a95e81d7d7f4e3eb59e60e5f3738c0">keyGetGID</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga9e3d0fb3f7ba906e067727b9155d22e3">keySetGID</a> (Key *key, gid_t gid)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">mode_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gabc0cec592ce3b77e9bc33dbc8e8f6bdc">keyGetMode</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode</a> (Key *key, mode_t mode)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">type_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga4fbbf04b1a2c5928dfcec939972e7347">keyGetType</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#gab92003db4b938594df48807c16766bf7">keySetType</a> (Key *key, type_t newType)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">time_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga6b05da399c3c78904969ef39f191b0eb">keyGetATime</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga995d8b84731673c88c7c01f3fed538b9">keySetATime</a> (Key *key, time_t atime)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">time_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga57689eb5691679071463b777ae786ae9">keyGetMTime</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga481d8997187992fe4bbf288bc8ef4db7">keySetMTime</a> (Key *key, time_t mtime)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">time_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga2c213c120cbe02201278ef7fb8cd94be">keyGetCTime</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keymeta.html#ga9f502ecab8ab43f0b17220fcc95f3fa5">keySetCTime</a> (Key *key, time_t ctime)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Methods to do various operations on Key metainfo. </p>
<p>To use them: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <kdb.h></span>
</pre></div><p>Next to <a class="el" href="group__keyname.html">Name (key and owner) </a> and <a class="el" href="group__keyvalue.html">Value (data and comment) </a> there is the so called metainfo inside every key.</p>
<p>Key metainfo insists of:</p>
<ul>
<li>UID, the user id</li>
<li>GID, the group id</li>
<li>filesystem-like mode permissions (rwx)</li>
<li>Mode, change and modification times</li>
</ul>
<p>The comment can contain userdata which directly belong to that key.</p>
<p>Owner is the user that owns the key. It only works for the user/ hierachy.</p>
<p>Every user and group of your System has a uniqe ID. These values are used in the keys too. They are very important for the mode. See man 2 chown.</p>
<p>With the mode mode you can choose if a user, group or the world can mode your key. See man 2 chmod. </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga6b05da399c3c78904969ef39f191b0eb"></a><!-- doxytag: member="keymeta.c::keyGetATime" ref="ga6b05da399c3c78904969ef39f191b0eb" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">time_t keyGetATime </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get last time the key data was read from disk.</p>
<p>Every <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> might update the access time of a key. You get information when the key was read the last time from the database.</p>
<p>You will get 0 when the key was not read already.</p>
<p>Beware that multiple copies of keys with <a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> might have different atimes because you <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> one, but not the other. You can use this information to decide which key is the latest.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>Key to get information from. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the time you got the key with <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> </dd>
<dd>
0 on key that was never <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> </dd>
<dd>
(time_t)-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga995d8b84731673c88c7c01f3fed538b9">keySetATime()</a> </dd>
<dd>
<a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga2c213c120cbe02201278ef7fb8cd94be"></a><!-- doxytag: member="keymeta.c::keyGetCTime" ref="ga2c213c120cbe02201278ef7fb8cd94be" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">time_t keyGetCTime </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get last time the key metadata was changed from disk.</p>
<p>You will get 0 when the key was not read already.</p>
<p>Any changed field in metadata will influence the ctime of a key.</p>
<p>This time is not updated if only value or comment are changed.</p>
<p>Not changed keys will not update this time, even after <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>.</p>
<p>It is possible that other keys written to disc influence this time if the backend is not grained enough.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>Key to get information from. </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga9f502ecab8ab43f0b17220fcc95f3fa5">keySetCTime()</a> </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>(time_t)-1 on NULL pointer </dd>
<dd>
the metadata change time </dd></dl>
</div>
</div>
<a class="anchor" id="ga46a95e81d7d7f4e3eb59e60e5f3738c0"></a><!-- doxytag: member="keymeta.c::keyGetGID" ref="ga46a95e81d7d7f4e3eb59e60e5f3738c0" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">gid_t keyGetGID </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the group ID of a key.</p>
<h2><a class="anchor" id="GID">
GID</a></h2>
<p>The group ID is a unique identification for every group present on a system. Keys will belong to root (0) as long as you did not get their real GID with <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>.</p>
<p>Unlike UID users might change their group. This makes it possible to share configuration between some users.</p>
<p>A fresh key will have (gid_t)-1 also known as the group nogroup. It means that the key is not related to a group ID at the moment.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the system's GID of the key </dd>
<dd>
(gid_t)-1 on NULL key or currently unknown ID </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga9e3d0fb3f7ba906e067727b9155d22e3">keySetGID()</a>, <a class="el" href="group__keymeta.html#gacaa5060e67b03f50ae49a3620c54bc46">keyGetUID()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gabc0cec592ce3b77e9bc33dbc8e8f6bdc"></a><!-- doxytag: member="keymeta.c::keyGetMode" ref="gabc0cec592ce3b77e9bc33dbc8e8f6bdc" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">mode_t keyGetMode </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the key mode permissions.</p>
<p>Default is 0664 (octal) for keys and 0775 for directory keys which used <a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a>.</p>
<p>The defaults are defined with the macros KEY_DEF_MODE and KEY_DEF_DIR.</p>
<p>For more information about the mode permissions see <a class="el" href="group__backend.html#mode">Mode</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>mode permissions of the key </dd>
<dd>
(mode_t)-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga57689eb5691679071463b777ae786ae9"></a><!-- doxytag: member="keymeta.c::keyGetMTime" ref="ga57689eb5691679071463b777ae786ae9" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">time_t keyGetMTime </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get last modification time of the key on disk.</p>
<p>You will get 0 when the key was not read already.</p>
<p>Everytime you change value or comment and <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> the key the mtime will be updated. When you <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> the key, the atime is set appropriate.</p>
<p>Not changed keys may not even passed to <a class="el" href="group__backend.html#ga2d86ff43b693d59d4b82b597756e9e23">kdbSet_backend()</a> so it will not update this time, even after <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>.</p>
<p>It is possible that other keys written to disc influence this time if the backend is not grained enough.</p>
<p>If you add or remove a key the key thereunder in the hierarchy will update the mtime if written with <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> to disc.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>Key to get information from. </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga481d8997187992fe4bbf288bc8ef4db7">keySetMTime()</a> </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the last modification time </dd>
<dd>
(time_t)-1 on NULL pointer </dd></dl>
</div>
</div>
<a class="anchor" id="ga4fbbf04b1a2c5928dfcec939972e7347"></a><!-- doxytag: member="keymeta.c::keyGetType" ref="ga4fbbf04b1a2c5928dfcec939972e7347" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">type_t keyGetType </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the key data type.</p>
<p>See type_t for the type definition.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#gab92003db4b938594df48807c16766bf7">keySetType()</a> </dd>
<dd>
<a class="el" href="group__keytest.html#ga9526b371087564e43e3dff8ad0dac949">keyIsBinary()</a> and <a class="el" href="group__keytest.html#gaea7670778abd07fee0fe8ac12a149190">keyIsString()</a> </dd>
<dd>
<a class="el" href="group__keytest.html#gac0a10c602d52a35f81347e8a32312017">keyIsDir()</a> is not related to the type system </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>key where to get the type. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the key type </dd>
<dd>
KEY_TYPE_UNDEFINED on keys without type </dd>
<dd>
-1 on NULL pointer </dd></dl>
</div>
</div>
<a class="anchor" id="gacaa5060e67b03f50ae49a3620c54bc46"></a><!-- doxytag: member="keymeta.c::keyGetUID" ref="gacaa5060e67b03f50ae49a3620c54bc46" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uid_t keyGetUID </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the user ID of a key.</p>
<h2><a class="anchor" id="UID">
UID</a></h2>
<p>The user ID is a unique identification for every user present on a system. Keys will belong to root (0) as long as you did not get their real UID with <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>.</p>
<p>Although usually the same, the UID of a key is not related to its owner.</p>
<p>A fresh key will have (uid_t)-1 also known as the user nobody. It means that the key is not related to a user ID at the moment.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the system's UID of the key </dd>
<dd>
(uid_t)-1 on NULL key or currently unknown ID </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga46a95e81d7d7f4e3eb59e60e5f3738c0">keyGetGID()</a>, <a class="el" href="group__keymeta.html#gab5f284f5ecd261e0a290095f50ba1af7">keySetUID()</a>, <a class="el" href="group__keyname.html#ga6d612841c829a638a8fbbbd4a31cc54a">keyGetOwner()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga6e14e5f1de26e1318100631a149f2984"></a><!-- doxytag: member="keymeta.c::keyRemove" ref="ga6e14e5f1de26e1318100631a149f2984" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keyRemove </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Permanently remove a key after committing to database.</p>
<p>This functions sets a flag that the key needs to be removed. It also sets a flag that it is not synced.</p>
<p>Remove the key instead of writing it in the key database when doing <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> and related functions.</p>
<p>This key will be ignored and it is save to delete it afterwards. To be sure that it was removed, check if it needs sync with <a class="el" href="group__keytest.html#gaf247df0de7aca04b32ef80e39ef12950">keyNeedSync()</a>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Delete in elektra terminology means to free memory, remove means to free permanent storage.</dd></dl>
<dl class="warning"><dt><b>Warning:</b></dt><dd>You should not change a key's remove status once it belongs to a keyset. See <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> for more information.</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keytest.html#gaae91159815480fbb3b3d9d7fa85e77b9">keyNeedRemove()</a>, <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>, <a class="el" href="group__kdbhighlevel.html#gaf9adbbeb3f49c63fb2f89930445c8060">kdbRemove()</a> </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>1 on success </dd>
<dd>
-1 on NULL pointer </dd></dl>
</div>
</div>
<a class="anchor" id="ga995d8b84731673c88c7c01f3fed538b9"></a><!-- doxytag: member="keymeta.c::keySetATime" ref="ga995d8b84731673c88c7c01f3fed538b9" args="(Key *key, time_t atime)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetATime </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">time_t </td>
<td class="paramname"> <em>atime</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Update the atime information for a key.</p>
<p>When you do manual sync of keys you might also update the atime to make them indistinguishable.</p>
<p>It can also be useful if you work with keys not using a keydatabase.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>The Key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>atime</em> </td><td>The new access time for the key </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga6b05da399c3c78904969ef39f191b0eb">keyGetATime()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga9f502ecab8ab43f0b17220fcc95f3fa5"></a><!-- doxytag: member="keymeta.c::keySetCTime" ref="ga9f502ecab8ab43f0b17220fcc95f3fa5" args="(Key *key, time_t ctime)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetCTime </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">time_t </td>
<td class="paramname"> <em>ctime</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Update the ctime information for a key.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>The Key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>ctime</em> </td><td>The new change metadata time for the key </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga2c213c120cbe02201278ef7fb8cd94be">keyGetCTime()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaae575bd86a628a15ee45baa860522e75"></a><!-- doxytag: member="keymeta.c::keySetDir" ref="gaae575bd86a628a15ee45baa860522e75" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetDir </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set mode so that key will be recognized as directory.</p>
<p>The function will add all executable bits.</p>
<ul>
<li>Mode 0200 will be translated to 0311</li>
<li>Mode 0400 will be translated to 0711</li>
<li>Mode 0664 will be translated to 0775</li>
</ul>
<p>The macro KEY_DEF_DIR (defined to 0111) will be used for that.</p>
<p>The executable bits show that child keys are allowed and listable. There is no way to have child keys which are not listable for anyone, but it is possible to restrict listing the keys to the owner only.</p>
<ul>
<li>Mode 0000 means that it is a key not read or writable to anyone.</li>
<li>Mode 0111 means that it is a directory not read or writable to anyone. But it is recognized as directory to anyone.</li>
</ul>
<p>For more about mode see <a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a>.</p>
<p>It is not possible to access keys below a not executable key. If a key is not writeable and executable <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> will fail to access the keys below. If a key is not readable and executable <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> will fail to access the keys below.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key to set permissions to be recognized as directory. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga9e3d0fb3f7ba906e067727b9155d22e3"></a><!-- doxytag: member="keymeta.c::keySetGID" ref="ga9e3d0fb3f7ba906e067727b9155d22e3" args="(Key *key, gid_t gid)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetGID </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">gid_t </td>
<td class="paramname"> <em>gid</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the group ID of a key.</p>
<p>See <a class="el" href="group__keymeta.html#GID">GID</a> for more information about group IDs.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>gid</em> </td><td>is the group ID </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL key </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga46a95e81d7d7f4e3eb59e60e5f3738c0">keyGetGID()</a>, <a class="el" href="group__keymeta.html#gab5f284f5ecd261e0a290095f50ba1af7">keySetUID()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga8803037e35b9da1ce492323a88ff6bc3"></a><!-- doxytag: member="keymeta.c::keySetMode" ref="ga8803037e35b9da1ce492323a88ff6bc3" args="(Key *key, mode_t mode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetMode </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">mode_t </td>
<td class="paramname"> <em>mode</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the key mode permissions.</p>
<p>The mode consists of 9 individual bits for mode permissions. In the following explanation the octal notation with leading zero will be used.</p>
<p>Default is 0664 (octal) for keys and 0775 for directory keys which used <a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a>.</p>
<p>The defaults are defined with the macros KEY_DEF_MODE and KEY_DEF_DIR.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>libelektra 0.7.0 only allows 0775 (directory keys) and 0664 (other keys). More will be added later in a sense of the description below.</dd></dl>
<h2><a class="anchor" id="mode">
Mode</a></h2>
<p>0000 is the most restrictive mode. No user might read, write or execute the key.</p>
<p>Reading the key means to get the value and comment by <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> or all highlevel methods.</p>
<p>Writing the key means to set the value and comment by <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> or all highlevel methods.</p>
<p>Execute the key means to make a step deeper in the hierarchy. But you must be able to read the key to be able to list the keys below. See also <a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a> in that context. But you must be able to write the key to be able to add or remove keys below.</p>
<p>0777 is the most relaxing mode. Every user is allowed to read, write and execute the key, if he is allowed to execute and read all keys below.</p>
<p>0700 allows every action for the current user, identified by the uid. See <a class="el" href="group__keymeta.html#gacaa5060e67b03f50ae49a3620c54bc46">keyGetUID()</a> and <a class="el" href="group__keymeta.html#gab5f284f5ecd261e0a290095f50ba1af7">keySetUID()</a>.</p>
<p>To be more specific for the user the single bits can elect the mode for read, write and execute. 0100 only allows executing which gives the information that it is a directory for that user, but not accessable. 0200 only allows reading. This information may be combined to 0300, which allows execute and reading of the directory. Last 0400 decides about the writing permissions.</p>
<p>The same as above is also valid for the 2 other octal digits. 0070 decides about the group permissions, in that case full access. Groups are identified by the gid. See <a class="el" href="group__keymeta.html#ga46a95e81d7d7f4e3eb59e60e5f3738c0">keyGetGID()</a> and <a class="el" href="group__keymeta.html#ga9e3d0fb3f7ba906e067727b9155d22e3">keySetGID()</a>. In that example everyone with a different uid, but the gid of the the key, has full access.</p>
<p>0007 decides about the world permissions. This is taken into account when neighter the uid nor the gid matches. So that example would allow everyone with a different uid and gid of that key gains full access.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key to set mode permissions </td></tr>
<tr><td valign="top"></td><td valign="top"><em>mode</em> </td><td>the mode permissions </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL key </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#gabc0cec592ce3b77e9bc33dbc8e8f6bdc">keyGetMode()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga481d8997187992fe4bbf288bc8ef4db7"></a><!-- doxytag: member="keymeta.c::keySetMTime" ref="ga481d8997187992fe4bbf288bc8ef4db7" args="(Key *key, time_t mtime)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetMTime </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">time_t </td>
<td class="paramname"> <em>mtime</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Update the mtime information for a key.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>The Key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>mtime</em> </td><td>The new modification time for the key </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga57689eb5691679071463b777ae786ae9">keyGetMTime()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gab92003db4b938594df48807c16766bf7"></a><!-- doxytag: member="keymeta.c::keySetType" ref="gab92003db4b938594df48807c16766bf7" args="(Key *key, type_t newType)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetType </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">type_t </td>
<td class="paramname"> <em>newType</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set a new key type.</p>
<p>This method is usually not needed, unless you are working with more semantic value types, or want to force a specific value type for a key. It is not usually needed because the data type is automatically set when setting the key value.</p>
<p>See type_t for the type defintion.</p>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment"><span class="comment">// here we define the new type</span>
<span class="keyword">enum</span>
{
KEY_TYPE_COLOR=KEY_TYPE_STRING+4
};
<span class="comment">// here we make a new key with the type</span>
Key *k1 = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/sw/oyranos/current/color1"</span>,
KEY_VALUE, <span class="stringliteral">"#4B52CA"</span>,
KEY_COMMENT, <span class="stringliteral">"a custom color"</span>,
KEY_TYPE, KEY_TYPE_COLOR,
KEY_END);
<span class="comment">// lets check if it is really correct type</span>
<span class="keywordflow">if</span> (<a class="code" href="group__keymeta.html#ga4fbbf04b1a2c5928dfcec939972e7347">keyGetType</a>(k1) == KEY_TYPE_COLOR) printf (<span class="stringliteral">"correct type"</span>);
</pre></div></dd></dl>
<p>When using type_t::KEY_TYPE_DIR, this method will not set mode permissions to the key. You'll have to set it manually after <a class="el" href="group__keymeta.html#gab92003db4b938594df48807c16766bf7">keySetType()</a>, calling <a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a> with appropriate permissions. Or use the <a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a>.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga4fbbf04b1a2c5928dfcec939972e7347">keyGetType()</a> </dd>
<dd>
<a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a> to see that the directory concept is independent of types </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>newType</em> </td><td>contains the new type </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on sucess </dd>
<dd>
-1 on NULL pointer and when newType >= KEY_TYPE_MAX </dd></dl>
</div>
</div>
<a class="anchor" id="gab5f284f5ecd261e0a290095f50ba1af7"></a><!-- doxytag: member="keymeta.c::keySetUID" ref="gab5f284f5ecd261e0a290095f50ba1af7" args="(Key *key, uid_t uid)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keySetUID </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uid_t </td>
<td class="paramname"> <em>uid</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the user ID of a key.</p>
<p>See <a class="el" href="group__keymeta.html#UID">UID</a> for more information about user IDs.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>uid</em> </td><td>the user ID to set </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL key </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keymeta.html#ga9e3d0fb3f7ba906e067727b9155d22e3">keySetGID()</a>, <a class="el" href="group__keymeta.html#gacaa5060e67b03f50ae49a3620c54bc46">keyGetUID()</a>, <a class="el" href="group__keyname.html#ga6d612841c829a638a8fbbbd4a31cc54a">keyGetOwner()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gab8189add5e562bdb148675ee595bd95b"></a><!-- doxytag: member="keymeta.c::keyStat" ref="gab8189add5e562bdb148675ee595bd95b" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keyStat </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Only stat a key instead of receiving value, comment and key type.</p>
<p>Only stat the key in the database when doing <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>. The key may not have any value, comment or key type set.</p>
<p>It is not possible to revert the action on per-key basis. When you want to remove the flag you have to pass option_t::KDB_O_NOSTAT to the next <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keytest.html#ga3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a>, <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>1 on succuess </dd>
<dd>
-1 on NULL pointer </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
