Elektra: kdbmeta.h File Reference

Elektra 0.8.24

Functions
kdbmeta.h File Reference

metadata functions More...

`#include "kdb.h"`

## 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 (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 (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.

Copyright
  BSD License (see LICENSE.md or https://www.libelektra.org)

## 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 a 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

  key | the object to work with
  returnedOwner | a pre-allocated space to store the owner
  maxSize | maximum number of bytes that fit returned

Returns
  number of bytes written to buffer

Return values

  1 | if there is no owner
  -1 | on NULL pointers
  -1 | when 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

  key | the key object to work with

Returns
  number of bytes

Return values

  1 | if there is no owner
  -1 | on 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

  key | the key object to work with

Returns
  a pointer to internal owner

Return values

  "" | when there is no (a empty) owner
  0 | iff 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.

A 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

  key | the key object to work with
  newOwner | the string which describes the owner of the key

Returns
  the number of bytes actually saved including final NULL

Return values

  1 | when owner is freed (by setting 0 or "")
  -1 | on null pointer or memory problems

See also
  keySetName(), keyGetOwner(), keyGetFullName()