Elektra
0.8.8
|
Methods to do various operations on Key names. More...
Functions | |
const char * | keyName (const Key *key) |
ssize_t | keyGetNameSize (const Key *key) |
ssize_t | keyGetName (const Key *key, char *returnedName, size_t maxSize) |
ssize_t | keySetName (Key *key, const char *newName) |
ssize_t | keyGetFullNameSize (const Key *key) |
ssize_t | keyGetFullName (const Key *key, char *returnedName, size_t maxSize) |
const char * | keyBaseName (const Key *key) |
Returns a pointer to the internal unescaped key name where the basename starts. | |
ssize_t | keyGetBaseNameSize (const Key *key) |
ssize_t | keyGetBaseName (const Key *key, char *returned, size_t maxSize) |
ssize_t | keyAddBaseName (Key *key, const char *baseName) |
ssize_t | keySetBaseName (Key *key, const char *baseName) |
const char * | keyOwner (const Key *key) |
ssize_t | keyGetOwnerSize (const Key *key) |
ssize_t | keyGetOwner (const Key *key, char *returnedOwner, size_t maxSize) |
ssize_t | keySetOwner (Key *key, const char *newOwner) |
Methods to do various operations on Key names.
To use them:
These functions make it easier for C programmers to work with key names.
system
or user
. (rationale: it would make the hierarchy too flat.)/sw/myapp/#/%/
where # is a major version number, e.g. #3 for the 4th version and % is a profile (% for default profile). This way, from a sysadmin perspective, it will be possible to copy the system/sw/myapp/#3/%/
tree to something like system/sw/myapp/#3/old/
and keep system clean and organized. Additionally, it is possible to start the old version of the app, using /sw/myapp/#2
. ssize_t keyAddBaseName | ( | Key * | key, |
const char * | baseName | ||
) |
Adds baseName
(that will be escaped) to the current key name.
A new baseName will be added, no other part of the key name will be affected.
Assumes that key
is a directory and will append baseName
to it. The function adds the path separator for concatenating.
So if key
has name "system/dir1/dir2"
and this method is called with baseName
"mykey"
, the resulting key will have the name "system/dir1/dir2/mykey"
.
When baseName
is 0 nothing will happen and the size of the name is returned.
The escaping rules apply as in above .
A simple example is:
E.g. if you add . it will be escaped:
key | the key object to work with |
baseName | the string to append to the name |
-1 | if key was inserted to a keyset before |
const char* keyBaseName | ( | const Key * | key | ) |
Returns a pointer to the internal unescaped key name where the basename
starts.
This is a much more efficient version of keyGetBaseName() and you should use it if you are responsible enough to not mess up things. The name might change or even point to a wrong place after a keySetName(). So make sure to copy the memory before the name changes.
keyBaseName() returns "" when there is no keyBaseName. The reason is
And there is also support for really empty basenames:
key | the object to obtain the basename from |
ssize_t keyGetBaseName | ( | const Key * | key, |
char * | returned, | ||
size_t | maxSize | ||
) |
Calculate the basename of a key name and put it in returned
finalizing the string with NULL.
Some examples:
system/some/keyname
is keyname
"user/tmp/some key"
is "some key"
key | the key to extract basename from |
returned | a pre-allocated buffer to store the basename |
maxSize | size of the returned buffer |
returned
ssize_t keyGetBaseNameSize | ( | const Key * | key | ) |
Calculates number of bytes needed to store basename of key
.
Key names that have only root names (e.g. "system"
or "user"
or "user:domain"
) does not have basenames, thus the function will return 1 bytes to store "".
Basenames are denoted as:
system/some/thing/basename
-> basename
user:domain/some/thing/base\/name
> base\/name
key | the key object to work with |
key's
basename including ending NULL ssize_t keyGetFullName | ( | const Key * | key, |
char * | returnedName, | ||
size_t | maxSize | ||
) |
Get key full name, including the user domain name.
key | the key object |
returnedName | pre-allocated memory to write the key name |
maxSize | maximum number of bytes that will fit in returnedName, including the final NULL |
ssize_t keyGetFullNameSize | ( | const Key * | key | ) |
Bytes needed to store the key name including user domain and ending NULL.
key | the key object to work with |
ssize_t keyGetName | ( | const Key * | key, |
char * | returnedName, | ||
size_t | maxSize | ||
) |
Get abbreviated key name (without owner name).
When there is not enough space to write the name, nothing will be written and -1 will be returned.
maxSize is limited to SSIZE_MAX. When this value is exceeded -1 will be returned. The reason for that is that any value higher is just a negative return value passed by accident. Of course malloc is not as failure tolerant and will try to allocate.
returnedName
key | the key object to work with |
returnedName | pre-allocated memory to write the key name |
maxSize | maximum number of bytes that will fit in returnedName, including the final NULL |
ssize_t keyGetNameSize | ( | const Key * | key | ) |
Bytes needed to store the key name without owner.
For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.
key | the key object to work with |
ssize_t keyGetOwner | ( | const Key * | key, |
char * | returnedOwner, | ||
size_t | maxSize | ||
) |
Return the owner of the key.
user:someuser/
..... return someuser
user:some.user/
.... return some.user
user/
.... return the current userOnly 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.
key | the object to work with |
returnedOwner | a pre-allocated space to store the owner |
maxSize | maximum number of bytes that fit returned |
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().
key | the key object to work with |
const char* keyName | ( | const Key * | key | ) |
Returns a pointer to the abbreviated real internal key
name.
This is a much more efficient version of keyGetName() and can use it if you are responsible enough to not mess up things. You are not allowed to change anything in the returned array. The content of that string may change after keySetName() and similar functions. If you need a copy of the name, consider using keyGetName().
The name will be without owner, see keyGetFullName() if you need the name with its owner.
keyName() returns "" when there is no keyName. The reason is
key | the key object to work with |
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 | the key object to work with |
"" | when there is no (a empty) owner |
0 | iff key is a NULL pointer |
ssize_t keySetBaseName | ( | Key * | key, |
const char * | baseName | ||
) |
Sets baseName
as the new basename for key
.
Only the baseName will be affected and no other part of the key.
All text after the last '/'
in the key
keyname is erased and baseName
is appended.
So let us suppose key
has name "system/dir1/dir2/key1"
. If baseName
is "key2"
, the resulting key name will be "system/dir1/dir2/key2"
. If baseName
is empty or NULL, the resulting key name will be "system/dir1/dir2"
.
This function does proper escaping on the supplied name argument.
You can use all names to set as basename (e.g. . (dot), .. (dot-dot), % and "" (empty)). They will be properly escaped.
A simple example is:
If you do not want escaping, use keySetBaseName() instead. E.g. if you want to add an inactive key, use:
or when you want to add an array item, use:
key | the key object to work with |
baseName | the string used to overwrite the basename of the key |
-1 | if key was inserted to a keyset before |
ssize_t keySetName | ( | Key * | key, |
const char * | newName | ||
) |
Set a new name to a key.
A valid name is of the forms:
system/something
user/something
user:username/something
The last form has explicitly set the owner, to let the library know in which user folder to save the key. A owner is a user name. If it is not defined (the second form) current user is used.
You should always follow the guidelines for key tree structure creation.
A private copy of the key name will be stored, and the newName
parameter can be freed after this call.
.., . and / will be handled as in filesystem pathes. A valid name will be build out of the (valid) name what you pass, e.g. user///sw/../sw//././MyApp -> user/sw/MyApp
On invalid names, NULL or "" the name will be "" afterwards.
size | in bytes of this new key name including ending NULL |
0 | if newName is an empty string or a NULL pointer (name will be empty afterwards) |
-1 | if newName is invalid (name will be empty afterwards) |
-1 | if key was inserted to a keyset before |
key | the key object to work with |
newName | the new key name |
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.
key | the key object to work with |
newOwner | the string which describes the owner of the key |