Key :: Meta Info Manipulation Methods

Methods to do various operations on Key metainfo. More...

Functions
ssize_t	keySetOwner (Key *key, const char *userDomain)
	Set the user domain of a key.
ssize_t	keyGetOwnerSize (const Key *key)
	Return the size of the user domain of the Key.
ssize_t	keyGetOwner (const Key *key, char *returned, size_t maxSize)
	Return the user domain of the key.
char *	keyStealOwner (const Key *key)
	Return a pointer to the real internal key owner or user domain.
ssize_t	keySetComment (Key *key, const char *newComment)
	Set a comment for a key.
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 *returnedDesc, size_t maxSize)
	Get the key comment.
char *	keyStealComment (const Key *key)
	Return a pointer to the real internal key comment.
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 system's group ID of a key.
int	keySetGID (Key *key, gid_t gid)
	Set the system's group ID of a key.
mode_t	keyGetAccess (const Key *key)
	Return the key filesystem-like access permissions.
int	keySetAccess (Key *key, mode_t mode)
	Set the key filesystem-like access permissions.
time_t	keyGetMTime (const Key *key)
	Get last modification time of the key on disk.
time_t	keyGetATime (const Key *key)
	Get last time the key data was read from disk.
time_t	keyGetCTime (const Key *key)
	Get last time the key was stated from disk.
int	keySetFlag (Key *key)
	Set a general flag in the Key.
int	keyClearFlag (Key *key)
	Clear the general flag in the Key.
int	keyGetFlag (const Key *key)
	Get the flag from the Key.

---

Detailed Description

Methods to do various operations on Key metainfo.

To use them:

#include <kdb.h>

Key metainfo are:

• Comment about the key
• User domain
• UID, GID and filesystem-like access permissions
• Access, change and modification times
• A general flag

The comment can contain userdata which directly belong to that key.

User domain is the user that owns the key. It only works for the user/ hierachy.

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 access. See man 2 chown.

With the access mode you can choose if a user, group or the world can access your key. See man 2 chmod.

---

Function Documentation

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

Set the user domain of a key. A user domain is a user name. A private copy is stored, so the passed parameter can be freed after the call. Parameters: userDomain  the user domain (or user name) Returns: the number of bytes copied See also: keySetName(), keyGetOwner(), keyGetFullName() Definition at line 1946 of file key.c. References _Key::flags, KEY_SWITCH_DOMAIN, strblen(), and _Key::userDomain. Referenced by keyDup(), and keyNew().

ssize_t keyGetOwnerSize (  const Key *  key  )

Return the size of the user domain of the Key. Returns: number of bytes See also: keyGetOwner() Definition at line 1997 of file key.c. References strblen(), and _Key::userDomain.

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

Return the user domain 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 user domains. For system/... keys (that doesn't have user domains) nothing is returned. Although usually the same, the user domain of a key is not related to its UID. User domains are related to WHERE the key is stored on disk, while UIDs are related to access controls of a key. Parameters: key  the object to work with returned  a pre-allocated space to store the owner maxSize  maximum number of bytes that fit returned Returns: number of bytes written to buffer See also: keySetName(), keySetOwner(), keyStealOwner(), keyGetFullName() Definition at line 2034 of file key.c. References strblen(), and _Key::userDomain.

char* keyStealOwner (  const Key *  key  )

Return a pointer to the real internal key owner or user domain. This is a much more efficient version of keyGetOwner() and you should use it if you are responsible enough to not mess up things. Parameters: key  the key object to work with See also: keyGetOwner(), keySetOwner() Definition at line 2066 of file key.c. References _Key::userDomain.

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

Set a comment for a key. A key comment is like a configuration file comment. It has no size limit. A private copy will be stored. Parameters: newComment  the comment, that can be freed after this call. Returns: the number of bytes copied See also: keyGetComment() Definition at line 2092 of file key.c. References _Key::comment, _Key::commentSize, _Key::flags, KEY_SWITCH_COMMENT, and strblen(). Referenced by commandSet(), keyDup(), and keyNew().

ssize_t keyGetCommentSize (  const Key *  key  )

Calculates number of bytes needed to store a key comment, including final NULL. Use this method to allocate memory to retrieve a key comment. Returns: number of bytes needed See also: keyGetComment(), keySetComment() Definition at line 2138 of file key.c. References _Key::comment, and strblen(). Referenced by commandGet().

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

Get the key comment. A Key comment is pretty much as a comment in a text configuration file. Parameters: returnedDesc  pre-allocated memory to copy the comments to maxSize  number of bytes that will fit returnedDesc Returns: number of bytes written See also: keyGetCommentSize(), keySetComment() Definition at line 2165 of file key.c. References _Key::comment, and strblen(). Referenced by commandGet().

char* keyStealComment (  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. Parameters: key  the key object to work with See also: keyGetCommentSize() keyStealValue() for and example Definition at line 2197 of file key.c. References _Key::comment.

uid_t keyGetUID (  const Key *  key  )

Get the user ID of a key. Although usually the same, the UID of a key is not related to its user domain. Returns: the system's UID of the key See also: keyGetGID(), keySetUID(), keyGetOwner() Definition at line 2282 of file key.c. References _Key::uid.

int keySetUID (  Key *  key, uid_t  uid )

Set the user ID of a key. Although usually the same, the UID of a key is not related to its user domain. Returns: 0 on success See also: keySetGID(), keyGetUID(), keyGetOwner() Definition at line 2305 of file key.c. References _Key::flags, KEY_SWITCH_UID, and _Key::uid. Referenced by commandSet(), and keyNew().

gid_t keyGetGID (  const Key *  key  )

Get the system's group ID of a key. Returns: the system's GID of the key See also: keySetGID(), keyGetUID() Definition at line 2324 of file key.c. References _Key::gid.

int keySetGID (  Key *  key, gid_t  gid )

Set the system's group ID of a key. Returns: the system's GID of the key See also: keyGetGID(), keySetUID() Definition at line 2344 of file key.c. References _Key::flags, _Key::gid, and KEY_SWITCH_GID. Referenced by commandSet(), and keyNew().

mode_t keyGetAccess (  const Key *  key  )

Return the key filesystem-like access permissions. See also: keySetAccess() Definition at line 2361 of file key.c. References _Key::access.

int keySetAccess (  Key *  key, mode_t  mode )

Set the key filesystem-like access permissions. Parameters: key  the key to set access permissions mode  the access permissions as for chmod(2) See also: keyGetAccess() Definition at line 2381 of file key.c. References _Key::access, _Key::flags, and KEY_SWITCH_MODE. Referenced by commandSet(), and keyNew().

int keySetFlag (  Key *  key  )

Set a general flag in the Key. The flag has no semantics to the library, only to your application. It is just a simple marker that you may use to put the key on a special state that makes sense to your application. See also: keyGetFlag(), keyClearFlag() Returns: always 0 Definition at line 2875 of file key.c. References _Key::flags.

int keyClearFlag (  Key *  key  )

Clear the general flag in the Key. The flag has no semantics to the library, only to your application. It is just a simple marker that you may use to put the key on a special state that makes sense to your application. See also: keyGetFlag(), keySetFlag() Returns: always 0 Definition at line 2899 of file key.c. References _Key::flags.

int keyGetFlag (  const Key *  key  )

Get the flag from the Key. The flag has no semantics to the library, only to your application. It is just a simple marker that you may use to put the key on a special state that makes sense to your application. See also: keySetFlag(), keyClearFlag() keyNew() with KeySwitch::KEY_SWITCH_NEEDSYNC Returns: 1 if flag is set, 0 otherwise Definition at line 2924 of file key.c. References _Key::flags.

---