Elektra  0.9.2
Functions
kdbmeta.h File Reference

metadata functions More...

#include "kdb.h"
Include dependency graph for kdbmeta.h:
This graph shows which files directly or indirectly include this file:

Functions

const char * keyOwner (const Key *key)
 Return a pointer to the real internal key owner. More...
 
ssize_t keyGetOwnerSize (const Key *key)
 Return the size of the owner of the Key with concluding 0. More...
 
ssize_t keyGetOwner (const Key *key, char *returned, size_t maxSize)
 Return the owner of the key. More...
 
ssize_t keySetOwner (Key *key, const char *owner)
 Set the owner of a key. More...
 
const char * keyComment (const Key *key)
 Return a pointer to the real internal key comment. More...
 
ssize_t keyGetCommentSize (const Key *key)
 Calculates number of bytes needed to store a key comment, including final NULL. More...
 
ssize_t keyGetComment (const Key *key, char *returnedDesc, size_t maxSize)
 Get the key comment. More...
 
ssize_t keySetComment (Key *key, const char *newDesc)
 Set a comment for a key. More...
 
uid_t keyGetUID (const Key *key)
 Get the user ID of a key. More...
 
int keySetUID (Key *key, uid_t uid)
 Set the user ID of a key. More...
 
gid_t keyGetGID (const Key *key)
 Get the group ID of a key. More...
 
int keySetGID (Key *key, gid_t gid)
 Set the group ID of a key. More...
 
int keySetDir (Key *key)
 Set mode so that key will be recognized as directory. More...
 
mode_t keyGetMode (const Key *key)
 Return the key mode permissions. More...
 
int keySetMode (Key *key, mode_t mode)
 Set the key mode permissions. More...
 
time_t keyGetATime (const Key *key)
 Get last time the key data was read from disk. More...
 
int keySetATime (Key *key, time_t atime)
 Update the atime information for a key. More...
 
time_t keyGetMTime (const Key *key)
 Get last modification time of the key on disk. More...
 
int keySetMTime (Key *key, time_t mtime)
 Update the mtime information for a key. More...
 
time_t keyGetCTime (const Key *key)
 Get last time the key metadata was changed from disk. More...
 
int keySetCTime (Key *key, time_t ctime)
 Update the ctime information for a key. More...
 
int elektraKeyCmpOrder (const Key *a, const Key *b)
 Compare the order metadata of two keys. More...
 
KeySet * elektraMetaArrayToKS (const Key *, const char *)
 Create a KeySet from a metakey array. More...
 
void elektraMetaArrayAdd (Key *, const char *, const char *)
 creates an metadata array or appends another element to an existing metadata array e.g. More...
 
char * elektraMetaArrayToString (const Key *, const char *, const char *)
 returns the metakey array as a string separated by delim More...
 
int elektraSortTopology (KeySet *, Key **)
 topological sorting More...
 

Detailed Description

metadata functions

These functions might be removed in a later version.

Function Documentation

◆ keyGetOwner()

ssize_t keyGetOwner ( const Key *  key,
char *  returnedOwner,
size_t  maxSize 
)

Return the owner of the key.

  • Given user:someuser/..... return someuser
  • Given user:some.user/.... return some.user
  • Given user/.... return the current user

Only user/... keys have an owner. For system/... keys (that doesn't have a key owner) an empty string ("") is returned.

Although usually the same, the owner of a key is not related to its UID. Owner are related to WHERE the key is stored on disk, while UIDs are related to mode controls of a key.

Parameters
keythe object to work with
returnedOwnera pre-allocated space to store the owner
maxSizemaximum number of bytes that fit returned
Returns
number of bytes written to buffer
Return values
1if there is no owner
-1on NULL pointers
-1when maxSize is 0, larger than SSIZE_MAX or too small for ownername
See also
keySetName(), keySetOwner(), keyOwner(), keyGetFullName()

◆ keyGetOwnerSize()

ssize_t keyGetOwnerSize ( const Key *  key)

Return the size of the owner of the Key with concluding 0.

The returned number can be used to allocate a string. 1 will returned on an empty owner to store the concluding 0 on using keyGetOwner().

char * buffer;
buffer = elektraMalloc (keyGetOwnerSize (key));
// use buffer and keyGetOwnerSize (key) for maxSize
Note
that -1 might be returned on null pointer, so when you directly allocate afterwards its best to check if you will pass a null pointer before.
Parameters
keythe key object to work with
Returns
number of bytes
Return values
1if there is no owner
-1on NULL pointer
See also
keyGetOwner()

◆ keyOwner()

const char* keyOwner ( const Key *  key)

Return a pointer to the real internal key owner.

This is a much more efficient version of keyGetOwner() and you should use it if you are responsible enough to not mess up things. You are not allowed to modify the returned string in any way. If you need a copy of the string, consider to use keyGetOwner() instead.

keyOwner() returns "" when there is no keyOwner. The reason is

key=keyNew(0);
keySetOwner(key,"");
keyOwner(key); // you would expect "" here
keySetOwner(key,"system");
keyOwner(key); // you would expect "" here
Note
Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by keyOwner() method to set a new value. Use keySetOwner() instead.
Parameters
keythe key object to work with
Returns
a pointer to internal owner
Return values
""when there is no (an empty) owner
0iff key is a NULL pointer
See also
keyGetOwnerSize() for the size of the string with concluding 0
keyGetOwner(), keySetOwner()
keyName() for name without owner
keyGetFullName() for name with owner

◆ keySetOwner()

ssize_t keySetOwner ( Key *  key,
const char *  newOwner 
)

Set the owner of a key.

an owner is a name of a system user related to a UID. The owner decides on which location on the disc the key goes.

A private copy is stored, so the passed parameter can be freed after the call.

Parameters
keythe key object to work with
newOwnerthe string which describes the owner of the key
Returns
the number of bytes actually saved including final NULL
Return values
1when owner is freed (by setting 0 or "")
-1on null pointer or memory problems
See also
keySetName(), keyGetOwner(), keyGetFullName()
keyOwner
const char * keyOwner(const Key *key)
Return a pointer to the real internal key owner.
Definition: owner.c:66
keyNew
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:167
keyGetOwnerSize
ssize_t keyGetOwnerSize(const Key *key)
Return the size of the owner of the Key with concluding 0.
Definition: owner.c:105
keySetOwner
ssize_t keySetOwner(Key *key, const char *newOwner)
Set the owner of a key.
Definition: owner.c:192
elektraMalloc
void * elektraMalloc(size_t size)
Allocate memory for Elektra.
Definition: internal.c:272