Provided by: elektra-doc_0.8.14-5.1ubuntu2_all bug

NAME

       meta - Meta data proposal+compatibility methods.

SYNOPSIS

   Functions
       const char * keyOwner (const Key *key)
           Return a pointer to the real internal key owner.
       ssize_t keyGetOwnerSize (const Key *key)
           Return the size of the owner of the Key with concluding 0.
       ssize_t keyGetOwner (const Key *key, char *returnedOwner, size_t maxSize)
           Return the owner of the key.
       ssize_t keySetOwner (Key *key, const char *newOwner)
           Set the owner of a key.
       const char * keyComment (const Key *key)
           Return a pointer to the real internal key comment.
       ssize_t keyGetCommentSize (const Key *key)
           Calculates number of bytes needed to store a key comment, including final NULL.
       ssize_t keyGetComment (const Key *key, char *returnedComment, size_t maxSize)
           Get the key comment.
       ssize_t keySetComment (Key *key, const char *newComment)
           Set a comment for a key.
       uid_t keyGetUID (const Key *key)
           Get the user ID of a key.
       int keySetUID (Key *key, uid_t uid)
           Set the user ID of a key.
       gid_t keyGetGID (const Key *key)
           Get the group ID of a key.
       int keySetGID (Key *key, gid_t gid)
           Set the group ID of a key.
       int keySetDir (Key *key)
           Set mode so that key will be recognized as directory.
       mode_t keyGetMode (const Key *key)
           Return the key mode permissions.
       int keySetMode (Key *key, mode_t mode)
           Set the key mode permissions.
       time_t keyGetATime (const Key *key)
           Get last time the key data was read from disk.
       int keySetATime (Key *key, time_t atime)
           Update the atime information for a key.
       time_t keyGetMTime (const Key *key)
           Get last modification time of the key on disk.
       int keySetMTime (Key *key, time_t mtime)
           Update the mtime information for a key.
       time_t keyGetCTime (const Key *key)
           Get last time the key metadata was changed from disk.
       int keySetCTime (Key *key, time_t ctime)
           Update the ctime information for a key.
       int elektraKeyCmpOrder (const Key *ka, const Key *kb)
           Compare the order metadata of two keys.

Detailed Description

       Meta data proposal+compatibility methods.

       In versions before Elektra 0.8 only meta data as listed here was available. Now any meta
       data can be added. These API methods are implementations of the 0.7 API using 0.8 meta
       data.

       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

   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

   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

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

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

   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 = malloc (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()

   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

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

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

   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

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

   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 = malloc (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()

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

   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

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

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

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

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

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

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

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

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

       Parameters:
           key the key to set mode permissions
           mode the mode permissions

       Return values:
           0 on success
           -1 on NULL key

       See also:
           keyGetMode()

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

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

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

Author

       Generated automatically by Doxygen for Elektra from the source code.