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.
int keySetUAccess (Key *key, mode_t umask)
 Set the key filesystem-like access permissions based on umask.
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 general flag from the Key.

Detailed Description

Methods to do various operations on Key metainfo.

To use them: 

#include <kdb.h>

Key metainfo are:

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 2141 of file key.c.

References _Key::flags, KDB_RET_NOMEM, KEY_SWITCH_DOMAIN, KEY_SWITCH_NEEDSYNC, strblen(), and _Key::userDomain.

Referenced by keyDup(), keyNew(), and keySetName().

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 2187 of file key.c.

References KDB_RET_NODOMAIN, strblen(), and _Key::userDomain.

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

Return the user domain of the key.

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 2218 of file key.c.

References KDB_RET_NODOMAIN, KDB_RET_TRUNC, 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 2245 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 2271 of file key.c.

References _Key::comment, _Key::commentSize, _Key::flags, KDB_RET_NOMEM, KEY_SWITCH_COMMENT, KEY_SWITCH_NEEDSYNC, 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 2311 of file key.c.

References _Key::comment, KDB_RET_NODESC, 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 2333 of file key.c.

References _Key::comment, KDB_RET_NODESC, KDB_RET_TRUNC, 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 2360 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 2383 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 2399 of file key.c.

References _Key::flags, KEY_SWITCH_NEEDSYNC, 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 2415 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 2428 of file key.c.

References _Key::flags, _Key::gid, KEY_SWITCH_GID, and KEY_SWITCH_NEEDSYNC.

Referenced by commandSet(), and keyNew().

mode_t keyGetAccess ( const Key *  key  ) 

Return the key filesystem-like access permissions.

See also:
keySetAccess()

Definition at line 2442 of file key.c.

References _Key::access.

int keySetAccess ( Key *  key,
mode_t  mode 
)

Set the key filesystem-like access permissions.

Use this method before calling keySetDir().

Parameters:
key the key to set access permissions
mode the access permissions as for chmod(2)
See also:
keyGetAccess()

Definition at line 2458 of file key.c.

References _Key::access, _Key::flags, KEY_SWITCH_MODE, and KEY_SWITCH_NEEDSYNC.

Referenced by commandSet(), and keyNew().

int keySetUAccess ( Key *  key,
mode_t  umask 
)

Set the key filesystem-like access permissions based on umask.

Use this method before calling keySetDir().

Parameters:
key the key to set access permissions
umask the umask for file/key creation as returned by umask(3)
See also:
keyGetAccess()

Definition at line 2479 of file key.c.

References _Key::access, _Key::flags, KEY_SWITCH_MODE, and KEY_SWITCH_NEEDSYNC.

Referenced by keyInit(), 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 3085 of file key.c.

References _Key::flags, and KEY_SWITCH_FLAG.

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 3104 of file key.c.

References _Key::flags, and KEY_SWITCH_FLAG.

int keyGetFlag ( const Key *  key  ) 

Get the general 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 3124 of file key.c.

References _Key::flags, and KEY_SWITCH_FLAG.

Generated on Mon Dec 17 18:49:00 2007 for Elektra Project by  doxygen 1.5.4