Meta Data proposal+compatibility

Meta data proposal+compatibility methods. More...

Collaboration diagram for Meta Data proposal+compatibility:

Functions
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 *returnedComment, size_t maxSize)
	Get the key comment. More...
ssize_t	keySetComment (Key *key, const char *newComment)
	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 *ka, const Key *kb)
	Compare the order metadata of two keys. More...
void	elektraMetaArrayAdd (Key *key, const char *metaName, const char *value)
	creates an metadata array or appends another element to an existing metadata array e.g. More...
KeySet *	elektraMetaArrayToKS (const Key *key, const char *metaName)
	Create a KeySet from a metakey array. More...
int	elektraSortTopology (KeySet *ks, Key **array)
	topological sorting More...
char *	elektraMetaArrayToString (const Key *key, const char *metaName, const char *delim)
	returns the metakey array as a string separated by delim More...

Detailed Description

Meta data proposal+compatibility methods.

In versions before Elektra 0.8 only limited metadata was available. Now any metadata can be added. These API methods are implementations of the 0.7 API using 0.8 metadata.

Additionally, new suggestions can be made here.

It is planned that these methods will be generated from doc/METADATA.ini and moved to a separate library. Currently, you should better avoid the methods and directly use metainfo instead.

Function Documentation

elektraKeyCmpOrder()

int elektraKeyCmpOrder	(	const Key *	ka,
		const Key *	kb
	)

Compare the order metadata of two keys.

Returns

a number less than, equal to or greater than zero if the order of k1 is found, respectively, to be less than, to match, or be greater than the order of k2. If one key is NULL, but the other isn't, the key which is not NULL is considered to be greater. If both keys are NULL, they are considered to be equal. If one key does have an order metadata but the other has not, the key with the metadata is considered greater. If no key has metadata, they are considered to be equal.

Parameters

ka	key to compare with
kb	other key to compare with

elektraMetaArrayAdd()

void elektraMetaArrayAdd	(	Key *	key,
		const char *	metaName,
		const char *	value
	)

creates an metadata array or appends another element to an existing metadata array e.g.

Key *key = keyNew("user/test", KEY_END); elektraMetaArrayAdd(key, "test", "val0"); key now has "test/#0" with value "val0" as metadata elektraMetaArrayAdd(key, "test", "val1"); appends "test/#1" with value "val1" to key

Parameters

key	the key the metadata should be added to
metaName	the name of the metakey array parent
value	the value of the newly appended metakey

elektraMetaArrayToKS()

KeySet* elektraMetaArrayToKS	(	const Key *	key,
		const char *	metaName
	)

Create a KeySet from a metakey array.

For example, the following function call

elektraMetaArrayToKS(
        keyNew ("/a", KEY_VALUE, "b, c",
                KEY_META, "dep",    "#1",
                KEY_META, "dep/#0", "/b",
                KEY_META, "dep/#1", "/c", KEY_END),
        "dep");

returns a KeySet containing the keys dep with value #1, "dep/#0" with value "/b" and "dep/#1" with value "/c".

If no meta key array is found, null is returned. The returned KeySet must be freed with ksDel

Returns

a keyset containing all the metakeys of the metakey array

Parameters

key	the key containing the metakey array
metaName	the name of the metakey array parent

elektraMetaArrayToString()

char* elektraMetaArrayToString	(	const Key *	key,
		const char *	metaName,
		const char *	delim
	)

returns the metakey array as a string separated by delim

Parameters

key	the key containing the metakey array
metaName	the name of the metakey array parent
delim	delimiter for the records in the returned string

Returns

a string containing all metakey values separated by "delim"

elektraSortTopology()

int elektraSortTopology	(	KeySet *	ks,
		Key **	array
	)

topological sorting

Parameters

array	the array where the sorted keys will be stored in topological order. Nothing will be written into an array if
ks	is the keyset that should be sorted. Dependencies and order is defined by metakeys.

• the "dep/#" metakeys e.g. the Key *k = keyNew ("/a", KEY_VALUE, "b, c", KEY_META, "dep", "#1", KEY_META, "dep/#0", "/b", KEY_META, "dep/#1", "/c", KEY_END), "dep"); depends on Key "/b" and Key "/c".
• if "order" metakeys are defined for the keys the algorithm tries to resolves them by that order using lexical comparison. You should prefer #0 array syntax.

Duplicated and reflexive dep entries are ignored.

The algorithm used is a mixture of Kahn and BFS. Furthermore the algorithm does not use recursion.

First a BFS with the keys sorted by "order" is used. Then all dependencies (recursively) of every key is collected.

Return values

1	on success
0	for cycles
-1	for invalid dependencies

keyComment()

const char* keyComment

(

const Key *

key

)

Return a pointer to the real internal key comment.

This is a much more efficient version of keyGetComment() and you should use it if you are responsible enough to not mess up things. You are not allowed to change anything in the memory region the returned pointer points to.

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

key=keyNew(0);
keySetComment(key,"");
keyComment(key); // you would expect "" here
keyDel(key);

See keySetComment() for more information on comments.

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 keyComment() method to set a new value. Use keySetComment() instead.

Parameters

key	the key object to work with

Returns

a pointer to the internal managed comment

Return values

""	when there is no comment
0	on NULL pointer

See also

keyGetCommentSize() for size and keyGetComment() as alternative

keyGetATime()

time_t keyGetATime

(

const Key *

key

)

Get last time the key data was read from disk.

Deprecated:

This API is obsolete.

Every kdbGet() might update the access time of a key. You get information when the key was read the last time from the database.

You will get 0 when the key was not read already.

Beware that multiple copies of keys with keyDup() might have different atimes because you kdbGet() one, but not the other. You can use this information to decide which key is the latest.

Parameters

key	Key to get information from.

Returns

the time you got the key with kdbGet()

Return values

0	on key that was never kdbGet()
(time_t)-1	on NULL pointer

See also

keySetATime()

kdbGet()

keyGetComment()

ssize_t keyGetComment	(	const Key *	key,
		char *	returnedComment,
		size_t	maxSize
	)

Get the key comment.

Comments

A Key comment is description for humans what this key is for. It may be a textual explanation of valid values, when and why a user or administrator changed the key or any other text that helps the user or administrator related to that key.

Don't depend on a comment in your program. A user is always allowed to remove or change it in any way he wants to. But you are allowed or even encouraged to always show the content of the comment to the user and allow him to change it.

Parameters

key	the key object to work with
returnedComment	pre-allocated memory to copy the comments to
maxSize	number of bytes that will fit returnedComment

Returns

the number of bytes actually copied to returnedString, including final NULL

Return values

1	if the string is empty
-1	on NULL pointer
-1	if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX

See also

keyGetCommentSize(), keySetComment()

keyGetCommentSize()

ssize_t keyGetCommentSize

(

const Key *

key

)

Calculates number of bytes needed to store a key comment, including final NULL.

Use this method to know to size for allocated memory to retrieve a key comment.

See keySetComment() for more information on comments.

For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.

 char *buffer;
 buffer = elektraMalloc (keyGetCommentSize (key));
// use this buffer to store the comment
// pass keyGetCommentSize (key) for maxSize

Parameters

key	the key object to work with

Returns

number of bytes needed

Return values

1	if there is no comment
-1	on NULL pointer

See also

keyGetComment(), keySetComment()

keyGetCTime()

time_t keyGetCTime

(

const Key *

key

)

Get last time the key metadata was changed from disk.

Deprecated:

This API is obsolete.

You will get 0 when the key was not read already.

Any changed field in metadata will influence the ctime of a key.

This time is not updated if only value or comment are changed.

Not changed keys will not update this time, even after kdbSet().

It is possible that other keys written to disc influence this time if the backend is not grained enough.

Parameters

key	Key to get information from.

See also

keySetCTime()

Return values

(time_t)-1

on NULL pointer

Returns

the metadata change time

keyGetGID()

gid_t keyGetGID

(

const Key *

key

)

Get the group ID of a key.

Deprecated:

This API is obsolete.

GID

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

Unlike UID users might change their group. This makes it possible to share configuration between some users.

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.

Parameters

key	the key object to work with

Returns

the system's GID of the key

Return values

(gid_t)-1

on NULL key or currently unknown ID

See also

keySetGID(), keyGetUID()

keyGetMode()

mode_t keyGetMode

(

const Key *

key

)

Return the key mode permissions.

Deprecated:

This API is obsolete.

Default is 0664 (octal) for keys and 0775 for directory keys which used keySetDir().

The defaults are defined with the macros KDB_FILE_MODE and KDB_DIR_MODE.

For more information about the mode permissions see Modes.

Parameters

key	the key object to work with

Returns

mode permissions of the key

Return values

KDB_FILE_MODE	as defaults
(mode_t)-1	on NULL pointer

See also

keySetMode()

keyGetMTime()

time_t keyGetMTime

(

const Key *

key

)

Get last modification time of the key on disk.

Deprecated:

This API is obsolete.

You will get 0 when the key was not read already.

Everytime you change value or comment and kdbSet() the key the mtime will be updated. When you kdbGet() the key, the atime is set appropriate.

Not changed keys may not even passed to kdbSet_backend() so it will not update this time, even after kdbSet().

It is possible that other keys written to disc influence this time if the backend is not grained enough.

If you add or remove a key the key thereunder in the hierarchy will update the mtime if written with kdbSet() to disc.

Parameters

key	Key to get information from.

See also

keySetMTime()

Returns

the last modification time

Return values

(time_t)-1

on NULL pointer

keyGetUID()

uid_t keyGetUID

(

const Key *

key

)

Get the user ID of a key.

Deprecated:

This API is obsolete.

UID

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

Although usually the same, the UID of a key is not related to its owner.

A fresh key will have no UID.

Parameters

key	the key object to work with

Returns

the system's UID of the key

Return values

(uid_t)-1

on NULL key

See also

keyGetGID(), keySetUID(), keyGetOwner()

keySetATime()

int keySetATime	(	Key *	key,
		time_t	atime
	)

Update the atime information for a key.

Deprecated:

This API is obsolete.

When you do manual sync of keys you might also update the atime to make them indistinguishable.

It can also be useful if you work with keys not using a keydatabase.

Parameters

key	The Key object to work with
atime	The new access time for the key

Return values

0	on success
-1	on NULL pointer

See also

keyGetATime()

keySetComment()

ssize_t keySetComment	(	Key *	key,
		const char *	newComment
	)

Set a comment for a key.

A key comment is like a configuration file comment. See keySetComment() for more information.

Parameters

key	the key object to work with
newComment	the comment, that can be freed after this call.

Returns

the number of bytes actually saved including final NULL

Return values

0	when the comment was freed (newComment NULL or empty string)
-1	on NULL pointer or memory problems

See also

keyGetComment()

keySetCTime()

int keySetCTime	(	Key *	key,
		time_t	ctime
	)

Update the ctime information for a key.

Deprecated:

This API is obsolete.

Parameters

key	The Key object to work with
ctime	The new change metadata time for the key

Return values

0	on success
-1	on NULL pointer

See also

keyGetCTime()

keySetDir()

int keySetDir

(

Key *

key

)

Set mode so that key will be recognized as directory.

Deprecated:

This API is obsolete.

The function will add all executable bits.

• Mode 0200 will be translated to 0311
• Mode 0400 will be translated to 0711
• Mode 0664 will be translated to 0775

The macro KDB_DIR_MODE (defined to 0111) will be used for that.

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.

• Mode 0000 means that it is a key not read or writable to anyone.
• Mode 0111 means that it is a directory not read or writable to anyone. But it is recognized as directory to anyone.

For more about mode see keySetMode().

It is not possible to access keys below a not executable key. If a key is not writeable and executable kdbSet() will fail to access the keys below. If a key is not readable and executable kdbGet() will fail to access the keys below.

Parameters

key	the key to set permissions to be recognized as directory.

Return values

0	on success
-1	on NULL pointer

See also

keySetMode()

keySetGID()

int keySetGID	(	Key *	key,
		gid_t	gid
	)

Set the group ID of a key.

Deprecated:

This API is obsolete.

See GID for more information about group IDs.

Parameters

key	the key object to work with
gid	is the group ID

Return values

0	on success
-1	on NULL key

See also

keyGetGID(), keySetUID()

keySetMode()

int keySetMode	(	Key *	key,
		mode_t	mode
	)

Set the key mode permissions.

Deprecated:

This API is obsolete. It is only a mapping to keySetMeta(key, "mode", str) which should be preferred.

The mode consists of 9 individual bits for mode permissions. In the following explanation the octal notation with leading zero will be used.

Default is 0664 (octal) for keys and 0775 for directory keys which used keySetDir().

The defaults are defined with the macros KDB_FILE_MODE and KDB_DIR_MODE.

Note

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.

Modes

0000 is the most restrictive mode. No user might read, write or execute the key.

Reading the key means to get the value by kdbGet().

Writing the key means to set the value by kdbSet().

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 keySetDir() in that context. But you must be able to write the key to be able to add or remove keys below.

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.

0700 allows every action for the current user, identified by the uid. See keyGetUID() and keySetUID().

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

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 keyGetGID() and keySetGID(). In that example everyone with a different uid, but the gid of the the key, has full access.

0007 decides about the world permissions. This is taken into account when neither the uid nor the gid matches. So that example would allow everyone with a different uid and gid of that key gains full access.

Parameters

key	the key to set mode permissions
mode	the mode permissions

Return values

0	on success
-1	on NULL key

See also

keyGetMode()

keySetMTime()

int keySetMTime	(	Key *	key,
		time_t	mtime
	)

Update the mtime information for a key.

Deprecated:

This API is obsolete.

Parameters

key	The Key object to work with
mtime	The new modification time for the key

Return values

0	on success

See also

keyGetMTime()

keySetUID()

int keySetUID	(	Key *	key,
		uid_t	uid
	)

Set the user ID of a key.

Deprecated:

This API is obsolete.

See UID for more information about user IDs.

Parameters

key	the key object to work with
uid	the user ID to set

Return values

0	on success
-1	on NULL key or conversion error

See also

keySetGID(), keyGetUID(), keyGetOwner()