 |
Elektra 0.11.0
|
|
Elektra 0.11.0
|
Key is an essential class that encapsulates key name , value and metainfo . More...
#include <key.hpp>
Public Member Functions | |
| Key () | |
Constructs a key with the name /. More... | |
| Key (ckdb::Key *k) | |
| Constructs a key out of a C key. More... | |
| Key (Key &k) | |
| Takes a reference of another key. More... | |
| Key (Key const &k) | |
| Takes a reference of another key. More... | |
| Key (const char *keyName,...) | |
| A practical way to fully create a Key object in one step. More... | |
| Key (const std::string keyName,...) | |
| A practical way to fully create a Key object in one step. More... | |
| Key (const char *keyName, va_list ap) | |
| A practical way to fully create a Key object in one step. More... | |
| void | operator++ (int) const |
| Increment the reference counter of a Key object. More... | |
| void | operator++ () const |
| Increment the reference counter of a Key object. More... | |
| void | operator-- (int) const |
| Decrement the reference counter of a Key object. More... | |
| void | operator-- () const |
| Decrement the reference counter of a Key object. More... | |
| uint16_t | getReferenceCounter () const |
| Return the current reference counter value of a Key object. More... | |
| Key & | operator= (ckdb::Key *k) |
| Assign a C key. More... | |
| Key & | operator= (const Key &k) |
| Assign a key. More... | |
| void | copy (const Key &other, elektraCopyFlags flags=KEY_CP_ALL) |
| Copy or clear a key. More... | |
| void | clear () |
| Clears/Invalidates a key. More... | |
| Key * | operator-> () |
| ckdb::Key * | getKey () const |
| Passes out the raw key pointer. More... | |
| ckdb::Key * | operator* () const |
| Is an abbreviation for getKey. More... | |
| ckdb::Key * | release () |
| Passes out the raw key pointer and resets internal key handle. More... | |
| Key | dup (elektraCopyFlags flags=KEY_CP_ALL) const |
| ~Key () | |
| Destructs the key. More... | |
| std::string | getName () const |
Returns a pointer to the abbreviated real internal key name. More... | |
| ssize_t | getNameSize () const |
| Bytes needed to store the Key's name (excluding owner). More... | |
| std::string | getBaseName () const |
| Returns a pointer to the unescaped Key's name where the basename starts. More... | |
| ssize_t | getBaseNameSize () const |
Calculates number of bytes needed to store basename of key (including NULL terminator). More... | |
| void | setName (const std::string &newName) |
| Set a new name to a Key. More... | |
| void | setBaseName (const std::string &baseName) |
| Sets a base name for a key. More... | |
| void | addBaseName (const std::string &baseName) |
| Adds a base name for a key. More... | |
| void | delBaseName () |
| Delete the baseName of a key. More... | |
| bool | operator== (const Key &k) const |
| Compare the name of two Keys. More... | |
| bool | operator!= (const Key &k) const |
| Compare the name of two Keys. More... | |
| bool | operator< (const Key &other) const |
| Compare the name of two Keys. More... | |
| bool | operator<= (const Key &other) const |
| Compare the name of two Keys. More... | |
| bool | operator> (const Key &other) const |
| Compare the name of two Keys. More... | |
| bool | operator>= (const Key &other) const |
| Compare the name of two Keys. More... | |
| bool | isNull () const |
| Checks if C++ wrapper has an underlying key. More... | |
| operator bool () const | |
| This is for loops and lookups only. More... | |
| template<class T > | |
| T | get () const |
| Get a key value. More... | |
| template<class T > | |
| void | set (T x) |
| Set a key value. More... | |
| std::string | getString () const |
| void | setString (const char *newString) |
Set the value for key as newStringValue. More... | |
| ssize_t | getStringSize () const |
| Returns the number of bytes needed to store the key value, including the NULL terminator. More... | |
| func_t | getFunc () const |
| Elektra can store function pointers as binary. More... | |
| const void * | getValue () const |
Return a pointer to the real internal key value. More... | |
| std::string | getBinary () const |
Copy the binary value of a Key into returnedBinary. More... | |
| ssize_t | getBinarySize () const |
| Returns the number of bytes needed to store the key value, including the NULL terminator. More... | |
| ssize_t | setBinary (const void *newBinary, size_t dataSize) |
Set the value of a Key to the binary value newBinary. More... | |
| bool | hasMeta (const std::string &metaName) const |
| template<class T > | |
| T | getMeta (const std::string &metaName) const |
Returns the Key for a metadata entry with name metaName. More... | |
| template<class T > | |
| void | setMeta (const std::string &metaName, T x) |
| Set metadata for key. More... | |
| void | delMeta (const std::string &metaName) |
| Delete metadata for key. More... | |
| void | copyMeta (const Key &other, const std::string &metaName) |
Do a shallow copy of metadata with name metaName from source to dest. More... | |
| void | copyAllMeta (const Key &other) |
| Do a shallow copy of all metadata from source to dest. More... | |
| bool | isValid () const |
| ElektraNamespace | getNamespace () const |
| ssize_t | setNamespace (ElektraNamespace ns) const |
| Set the namespace of the key. More... | |
| bool | isCascading () const |
| Determines if the key is in cascading namespace. More... | |
| bool | isSpec () const |
| Determines if the key is in spec namespace. More... | |
| bool | isProc () const |
| Determines if the key is in proc namespace. More... | |
| bool | isDir () const |
| Determines if the key is in dir namespace. More... | |
| bool | isUser () const |
| Determines if the key is in user namespace. More... | |
| bool | isSystem () const |
| Determines if the key is in system namespace. More... | |
| bool | isString () const |
Check if the value of key is of string type. More... | |
| bool | isBinary () const |
Check if the value of a key is of binary type. More... | |
| bool | isBelow (std::string const &name) const |
Check if the Key check is below the Key key or not. More... | |
| bool | isBelow (const Key &k) const |
Check if the Key check is below the Key key or not. More... | |
| bool | isBelowOrSame (std::string const &name) const |
| Check if a key is below or same. More... | |
| bool | isBelowOrSame (const Key &k) const |
| Check if a key is below or same. More... | |
| bool | isDirectBelow (std::string const &name) const |
Check whether the Key check is directly below the Key key. More... | |
| bool | isDirectBelow (const Key &k) const |
Check whether the Key check is directly below the Key key. More... | |
| bool | isNameLocked () const |
| bool | isValueLocked () const |
| bool | isMetaLocked () const |
Key is an essential class that encapsulates key name , value and metainfo .
To use it include:
Key properties are:
Key structure is not defined in kdb.h, only declared. So you can only declare pointers to Keys in your program, and allocate and free memory for them with keyNew() and keyDel() respectively.This class is an wrapper for an optional, refcounted ckdb::Key. It is like an shared_ptr<ckdb::Key>, but the shared_ptr functionality is already within the Key and exposed with this wrapper.
|
inline |
|
inline |
|
inline |
Takes a reference of another key.
The key will not be copied, but the reference counter will be increased.
| k | the key to work with |
|
inline |
Takes a reference of another key.
The key will not be copied, but the reference counter will be increased.
| k | the key to work with |
|
inlineexplicit |
A practical way to fully create a Key object in one step.
To just get a key object, simple do:
keyNew() allocates memory for a key object and keyDel() cleans everything up.
If you want the key object to contain a name, value, comment and other meta info read on.
You can call keyNew() in many different ways depending on the attribute tags you pass as parameters. Tags are represented as elektraKeyFlags values, and tell keyNew() which Key attribute comes next. The Key attribute tags are the following:
keyName is 0.KEY_BINARY
Allows one to change the key to a binary key. Make sure that you also pass KEY_SIZE before you set the value. Otherwise it will be cut off with first \0 in the string. So this flag toggle from keySetString() to keySetBinary(). If no value (nor size) is given, it will be a NULL key.
name is a valid Key name | name | a valid name to the key (see keySetName()) |
| NULL | on allocation error or if an invalid name was passed (see keySetName()). |
| KeyInvalidName | if key could not be constructed |
| keyName | the name of the new key |
|
inlineexplicit |
A practical way to fully create a Key object in one step.
To just get a key object, simple do:
keyNew() allocates memory for a key object and keyDel() cleans everything up.
If you want the key object to contain a name, value, comment and other meta info read on.
You can call keyNew() in many different ways depending on the attribute tags you pass as parameters. Tags are represented as elektraKeyFlags values, and tell keyNew() which Key attribute comes next. The Key attribute tags are the following:
keyName is 0.KEY_BINARY
Allows one to change the key to a binary key. Make sure that you also pass KEY_SIZE before you set the value. Otherwise it will be cut off with first \0 in the string. So this flag toggle from keySetString() to keySetBinary(). If no value (nor size) is given, it will be a NULL key.
name is a valid Key name | name | a valid name to the key (see keySetName()) |
| NULL | on allocation error or if an invalid name was passed (see keySetName()). |
| KeyInvalidName | if key could not be constructed |
| keyName | the name of the new key |
|
inlineexplicit |
A practical way to fully create a Key object in one step.
To just get a key object, simple do:
keyNew() allocates memory for a key object and keyDel() cleans everything up.
If you want the key object to contain a name, value, comment and other meta info read on.
You can call keyNew() in many different ways depending on the attribute tags you pass as parameters. Tags are represented as elektraKeyFlags values, and tell keyNew() which Key attribute comes next. The Key attribute tags are the following:
keyName is 0.KEY_BINARY
Allows one to change the key to a binary key. Make sure that you also pass KEY_SIZE before you set the value. Otherwise it will be cut off with first \0 in the string. So this flag toggle from keySetString() to keySetBinary(). If no value (nor size) is given, it will be a NULL key.
name is a valid Key name | name | a valid name to the key (see keySetName()) |
| NULL | on allocation error or if an invalid name was passed (see keySetName()). |
| KeyInvalidName | if key could not be constructed |
| keyName | the name of the new key |
| ap | the variable argument list pointer |
|
inline |
Destructs the key.
|
inline |
Adds a base name for a key.
Adds baseName to the name of key. baseName will be escaped before adding it to the name of key. No other part of the Key's name will be affected.
Assumes that key is a directory and will append baseName to it. The function adds the path separator for concatenating.
If key has the 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:
| -1 | if the Key has no name |
| -1 | on NULL pointers |
| -1 | if Key was inserted into KeySet before |
| -1 | if the Key was read-only |
| -1 | on memory allocation errors |
| KeyInvalidName | if the name is not valid |
|
inline |
Clears/Invalidates a key.
Afterwards the object is empty again.
Will clear all internal data of a Key. After this call you will receive a fresh Key - with no value, metadata or name.
The reference counter will stay unmodified.
key's name is "/" key's metadata is empty| key | the Key that should be cleared |
| 0 | on success |
| -1 | on NULL pointer |
|
inline |
Copy or clear a key.
Depending on the chosen flags keyCopy() only copies certain parts of source into dest.
source to dest.source to dest.source to dest. Additionally, if source is a binary key (keyIsBinary()), dest will also be marked as binary. This means that even if KEY_CP_META is not set, the binary meta key will be copied with KEY_CP_VALUE.source to dest, but only, if source is not a binary key (keyIsBinary()). If source is binary, keyCopy() fails. If dest is binary, it will still be marked as binary after the copy. This cannot be used together with KEY_CP_VALUE. The main purpose of KEY_CP_STRING is for copying into known string keys. It ensure that you don't accidentally convert string keys into binary keys.There is also the shorthand KEY_CP_ALL. It is equivalent to KEY_CP_NAME | KEY_CP_VALUE | KEY_CP_META, i.e. all key data supported by keyCopy() will be copied from source to dest.
Use this function when you need to copy into an existing key, e.g. because it was passed by a pointer in a function you can do so:
Most often you will want to duplicate an existing key. For this purpose the alias keyDup() exists. Calling
is equivalent to
The reference counter will not be changed for both keys. Affiliation to keysets are also not affected.
Since metadata uses copy-on-write semantics there is only a constant memory cost to copying metadata.
When you pass a NULL-pointer as source the pieces of dest specified by flags will be cleared.
Calling keyCopy (dest, NULL, KEY_CP_ALL) is different from calling keyClear(). The key will not be fully reset, the reference counter and internal flags will remain unchanged. Additionally, keyCopy() respects keyLock() state, while keyClear() always works.
dest must be a valid Key (created with keyNew) dest must not have read-only flags set source must be a valid Key or NULL | dest | the key which will be written to |
| source | the key which should be copied or NULL to clear the data of dest |
| flags | specifies which parts of the key should be copied |
dest | NULL | on memory allocation problems |
| NULL | when a part of dest that should be modified (e.g. name, value) was marked read-only, e.g. the name of dest will be read-only if dest is part of a KeySet |
| NULL | when dest is NULL |
| NULL | when both KEY_CP_VALUE and KEY_CP_STRING are set in flags |
| NULL | when both KEY_CP_STRING is set in flags and source is a binary key (keyIsBinary()) |
|
inline |
Do a shallow copy of all metadata from source to dest.
The key dest will additionally have all metadata the source had. Metadata not present in source will not be changed. Metadata which was present in source and dest will be overwritten. If the dest Key is read-only it will not be changed.
For example the metadata type is copied into the Key k:
The main purpose of this function is for plugins or applications which want to add the same metadata to n keys. When you do that with keySetMeta() it will take n times the memory for the key. This can be considerable amount of memory for many keys with some metadata for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta():
dest's metadata is not read-only | dest | the destination where the metadata should be copied too |
| source | the key where the metadata should be copied from |
| 1 | if metadata was successfully copied |
| 0 | if source did not have any metadata |
| -1 | on null pointer of dest or source |
| -1 | on memory problems |
dest to source
|
inline |
Do a shallow copy of metadata with name metaName from source to dest.
Afterwards source and dest will have the same metadata referred with metaName. If the Key with name metaName doesn't exist in source - it gets deleted in dest.
For example the metadata type is copied into the Key k.
The main purpose of this function is for plugins or applications, which want to add the same metadata to n keys. When you do that keySetMeta() will take n times the memory for the key. This can be a considerable amount of memory for many keys with some metadata for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta().
dest's metadata is not read-only | dest | the destination where the metadata should be copied to |
| source | the key where the metadata should be copied from |
| metaName | the name of the metadata Key which should be copied |
| 1 | if was successfully copied |
| 0 | if the metadata in dest was removed too |
| -1 | on null pointers (source or dest) |
| -1 | on memory problems |
| -1 | if metadata is read-only |
dest to src
|
inline |
Delete the baseName of a key.
| KeyInvalidName | if the name is not valid |
|
inline |
Delete metadata for key.
|
inline |
|
inline |
Get a key value.
You can write your own template specialication, e.g.:
It should be the same as get().
| KeyException | on null key or not a valid size |
| KeyTypeMismatch | if key holds binary data and not a string |
This method tries to serialise the string to the given type.
|
inline |
Returns a pointer to the unescaped Key's 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 the Key has no basename. The reason is
There is also support for really empty basenames:
| key | the Key to obtain the basename from |
| "" | when the Key has no (base)name |
| 0 | on NULL pointer |
|
inline |
Calculates number of bytes needed to store basename of key (including NULL terminator).
Key names consisting of only root names (e.g. "system:/" or "user:/" or "user:domain" ) do not have basenames. In this case the function will return 1, because only a NULL terminator is needed for storage.
Basenames are denoted as:
system:/some/thing/basename -> basename user:domain/some/thing/base\/name > base\/name | key | the Key to get the size of the basename from |
|
inline |
Copy the binary value of a Key into returnedBinary.
| "" | on null pointers (size == 0) and on data only containing \0 |
| KeyException | on invalid binary size |
| KeyTypeMismatch | if key is string and not a binary |
If the type is not binary -1 will be returned.
When the binary data is empty (this is not the same as ""!) 0 will be returned and returnedBinary will not be changed.
For string values see keyGetString() and keyIsString().
When returnedBinary is too small to hold the data (maximum size is given by maxSize), the returnedBinary will not be changed and -1 is returned.
| key | the Key object to get the binary value from |
| returnedBinary | pre-allocated memory to store a copy of the Key's value |
| maxSize | number of bytes of pre-allocated memory in returnedBinary |
returnedBinary | 0 | if the binary is empty |
| -1 | on NULL pointers |
| -1 | if maxSize is 0, too small for the value or larger than SSIZE_MAX |
| -1 | if the Key's value is a string |
|
inline |
Returns the number of bytes needed to store the key value, including the NULL terminator.
It returns the correct size, independent of the Key Type. If the value is binary there might be '\0' values in it.
For an empty string you need one byte to store the ending NULL. For that reason 1 is returned. This is not true for binary data, so 0 will be returned.
A binary key has no '\0' termination. String types are null-terminated, and the terminator will be considered for the length.
This method can be used with elektraMalloc() before keyGetString() or keyGetBinary() is called.
key's value (including NULL terminators)| key | the Key object to get the size of the value from |
| 1 | when there is no data and type is a string |
| 0 | when there is no data and type is binary |
| -1 | on null pointer |
|
inline |
Elektra can store function pointers as binary.
This function returns such a function pointer.
| KeyTypeMismatch | if no binary data found, or binary data has not correct length |
|
inline |
Passes out the raw key pointer.
This pointer can be used to directly change the underlying key object.
|
inline |
Returns the Key for a metadata entry with name metaName.
You are not allowed to modify the resulting key.
If metaName does not start with 'meta:/', it will be prefixed with 'meta:/'.
key contains metadata metaName is prefixed with "meta:/"| key | the Key from which to get metadata |
| metaName | the name of the meta information you want the Key from. |
| 0 | if key or metaName is NULL |
| 0 | if no such metaName is found |
You can specify your own template specialisation:
| KeyTypeConversion | if metadata could not be parsed |
If no meta is available:
|
inline |
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().
| "" | when there is no keyName. The reason is |
Valid key names are:
spec:/something for specification of other keys.proc:/something for in-memory keys, e.g. commandline.dir:/something for dir keys in current working directorysystem:/something for system keys in /etc or /user:/something for user keys in home directoryuser:username/something for other users (deprecated: kdbGet() + kdbSet() currently unsupported)/something for cascading keys (actually refers to one of the above, see also ksLookup())| key | the Key you want to get the name from |
| "" | when Key's name is empty |
| 0 | on NULL pointer |
| KeyException | if key is null |
|
inline |
Bytes needed to store the Key's name (excluding owner).
For an empty Key name you need one byte to store the ending NULL. For that reason, 1 is returned when the name is empty.
| key | the Key to get the name size from |
| 1 | if Key has no name |
| -1 | on NULL pointer |
|
inline |
|
inline |
Return the current reference counter value of a Key object.
| key | the Key whose reference counter to retrieve |
key's reference counter | -1 | on NULL pointer |
|
inline |
It should be the same as get().
| KeyException | on null key or not a valid size |
| KeyTypeMismatch | if key holds binary data and not a string |
|
inline |
Returns the number of bytes needed to store the key value, including the NULL terminator.
It returns the correct size, independent of the Key Type. If the value is binary there might be '\0' values in it.
For an empty string you need one byte to store the ending NULL. For that reason 1 is returned. This is not true for binary data, so 0 will be returned.
A binary key has no '\0' termination. String types are null-terminated, and the terminator will be considered for the length.
This method can be used with elektraMalloc() before keyGetString() or keyGetBinary() is called.
key's value (including NULL terminators)| key | the Key object to get the size of the value from |
| 1 | when there is no data and type is a string |
| 0 | when there is no data and type is binary |
| -1 | on null pointer |
|
inline |
Return a pointer to the real internal key value.
This is a much more efficient version of keyGetString() keyGetBinary(). You should use it if you are responsible enough to not mess up things. You are not allowed to modify anything in the returned string. If you need a copy of the Value, consider to use keyGetString() or keyGetBinary() instead.
If key is string (keyIsString()), you may cast the returned as a "char *" because you'll get a NULL terminated regular string.
keyValue() returns "" in string mode when there is no value. The reason is
If the data is binary, the size of the value must be determined by keyGetValueSize(), any strlen() operations are not suitable to determine the size.
keyValue() returns 0 in binary mode when there is no value. The reason is
key is not NULL and has stored data | key | the Key from which to get the value |
| "" | when there is no value and Key is not binary |
| 0 | where there is no value and Key is binary |
| 0 | on NULL pointer |
|
inline |
| true | if there is a metadata with given name |
| false | if no such metadata exists |
|
inline |
Check if the Key check is below the Key key or not.
| k | the other key |
Example:
key user:/sw/app check user:/sw/app/key
returns true because check is below key
Example:
key user:/sw/app check user:/sw/app/folder/key
returns also true because check is indirectly below key
Obviously, there is no Key above a namespace (e.g. user, system, /):
key * check user
| key | the Key object to check against |
| check | the Key object for which it should be checked whether it is below key |
| 1 | if check is below key |
| 0 | if it is not below or if it is the same key |
| -1 | if key or check is null |
|
inline |
Check if the Key check is below the Key key or not.
| name | the name of the other key |
Example:
key user:/sw/app check user:/sw/app/key
returns true because check is below key
Example:
key user:/sw/app check user:/sw/app/folder/key
returns also true because check is indirectly below key
Obviously, there is no Key above a namespace (e.g. user, system, /):
key * check user
| key | the Key object to check against |
| check | the Key object for which it should be checked whether it is below key |
| 1 | if check is below key |
| 0 | if it is not below or if it is the same key |
| -1 | if key or check is null |
|
inline |
Check if a key is below or same.
| k | the other key |
| key | the key object to work with |
|
inline |
Check if a key is below or same.
| name | the name of the other key |
| key | the key object to work with |
|
inline |
Check if the value of a key is of binary type.
The function checks if the value of key is binary. Contrary to string values binary values can have '\0' inside the value and may not be terminated by a null character. Their disadvantage is that you need to pass their size.
Make sure to use this function and don't test the binary type another way to ensure compatibility and to write less error prone programs.
| key | the Key to check |
| 1 | if the value of key is binary |
| 0 | if the value of key is not binary |
| -1 | on NULL pointer |
|
inline |
Determines if the key is in cascading namespace.
| true | if it is a cascading key |
| false | otherwise |
|
inline |
Determines if the key is in dir namespace.
| true | if it is a dir key |
| false | otherwise |
|
inline |
Check whether the Key check is directly below the Key key.
| k | the other key |
Example: key user:/sw/app check user:/sw/app/key
returns true because check is directly below key
Example: key user:/sw/app check user:/sw/app/folder/key
does not return true, because it is only indirectly below
| key | the Key object to check against |
| check | the Key object for which it should be checked whether it is directly below key |
| 1 | if check is directly below key |
| 0 | if check is not directly below key or if it is the same |
| -1 | on null pointer |
|
inline |
Check whether the Key check is directly below the Key key.
| name | the name of the other key |
Example: key user:/sw/app check user:/sw/app/key
returns true because check is directly below key
Example: key user:/sw/app check user:/sw/app/folder/key
does not return true, because it is only indirectly below
| key | the Key object to check against |
| check | the Key object for which it should be checked whether it is directly below key |
| 1 | if check is directly below key |
| 0 | if check is not directly below key or if it is the same |
| -1 | on null pointer |
|
inline |
|
inline |
|
inline |
Checks if C++ wrapper has an underlying key.
|
inline |
Determines if the key is in proc namespace.
| true | if it is a proc key |
| false | otherwise |
|
inline |
Determines if the key is in spec namespace.
| true | if it is a spec key |
| false | otherwise |
|
inline |
Check if the value of key is of string type.
String values are null terminated and are not allowed to have any '\0' characters inside the string.
Make sure to use this function and don't test the string type another way to ensure compatibility and to write less error prone programs.
| key | the Key to check |
| 1 | if the value of key is string |
| 0 | if the value of key is not string |
| -1 | on NULL pointer |
|
inline |
Determines if the key is in system namespace.
| true | if it is a system key |
| false | otherwise |
|
inline |
Determines if the key is in user namespace.
| true | if it is a user key |
| false | otherwise |
|
inline |
An invalid key has no name. The name of valid keys either start with user or system.
| true | if the key has a valid name |
| false | if the key has an invalid name |
|
inline |
|
inline |
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | != 0 |
|
inline |
Is an abbreviation for getKey.
Passes out the raw key pointer. This pointer can be used to directly change the underlying key object.
|
inline |
Increment the reference counter of a Key object.
As long as the reference counter is non-zero, keyDel() operations on key will be a no-op and return an error code.
Elektra's system for reference counting is not based on a concept of shared ownership. It is more similar to a shared lock, where the counter is used to keep track of how many clients hold the lock.
Initially, the reference counter will be 0. This is can be interpreted as the lock being unlocked. When you increment the reference counter, the lock becomes locked and keyDel() is blocked and fails. Only when the reference counter is fully decremented back down to 0 again, will keyDel() work again.
UINT16_MAX - 1. UINT16_MAX is reserved as an error code.key's reference counter is > 0 key's reference counter is <= UINT16_MAX - 1| key | the Key object whose reference counter should be increased |
| UINT16_MAX | on NULL pointer |
| UINT16_MAX | when the reference counter already was the maximum value UINT16_MAX - 1, the reference counter will not be modified in this case |
|
inline |
Increment the reference counter of a Key object.
As long as the reference counter is non-zero, keyDel() operations on key will be a no-op and return an error code.
Elektra's system for reference counting is not based on a concept of shared ownership. It is more similar to a shared lock, where the counter is used to keep track of how many clients hold the lock.
Initially, the reference counter will be 0. This is can be interpreted as the lock being unlocked. When you increment the reference counter, the lock becomes locked and keyDel() is blocked and fails. Only when the reference counter is fully decremented back down to 0 again, will keyDel() work again.
UINT16_MAX - 1. UINT16_MAX is reserved as an error code.key's reference counter is > 0 key's reference counter is <= UINT16_MAX - 1| key | the Key object whose reference counter should be increased |
| UINT16_MAX | on NULL pointer |
| UINT16_MAX | when the reference counter already was the maximum value UINT16_MAX - 1, the reference counter will not be modified in this case |
|
inline |
Decrement the reference counter of a Key object.
As long as the reference counter is non-zero, keyDel() operations on key will be a no-op and return an error code.
key's reference counter is >= 0 key's reference counter is < SSIZE_MAX| key | the Key object whose reference counter should get decreased |
| UINT16_MAX | on NULL pointer |
| 0 | when the reference counter already was the minimum value 0, the reference counter will not be modified in this case |
|
inline |
Decrement the reference counter of a Key object.
As long as the reference counter is non-zero, keyDel() operations on key will be a no-op and return an error code.
key's reference counter is >= 0 key's reference counter is < SSIZE_MAX| key | the Key object whose reference counter should get decreased |
| UINT16_MAX | on NULL pointer |
| 0 | when the reference counter already was the minimum value 0, the reference counter will not be modified in this case |
|
inline |
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | < 0 |
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | <= 0 |
|
inline |
Assign a C key.
Will call del() on the old key.
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | == 0 |
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | > 0 |
|
inline |
Compare the name of two Keys.
The comparison is based on a memcmp of the Key's names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for NULL values:
If the name is equal then:
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.
k1 and k2 have been properly initialized via keyNew() or are NULL k1 and k2 cannot be used in the same KeySet| <0 | if k1 < k2 |
| 0 | if k1 == k2 |
| >0 | if k1 > k2 |
| true | >= 0 |
|
inline |
Passes out the raw key pointer and resets internal key handle.
| 0 | if no key is held (null pointer), no action is done then. |
|
inline |
Set a key value.
Set the value for key as newStringValue. The function will allocate and save a private copy of newStringValue, so the parameter can be freed after the call.
String values will be saved in backend storage in UTF-8 universal encoding, regardless of the program's current encoding (if the iconv plugin is available).
newStringValue is a NULL terminated string newStringValue meta:/binary is cleared| key | the Key for which to set the string value |
| newStringValue | NULL-terminated string to be set as key's value |
| 1 | if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination) |
| -1 | if key is a NULL pointer |
This method tries to deserialise the string to the given type.
|
inline |
Sets a base name for a key.
Sets baseName as the new basename for key. Only the basename of the Key will be affected.
A simple example is:
All text after the last '/' in the Key's name is erased and baseName is appended. If baseName is 0 (NULL), then the last part of the Key's name is removed without replacement. The root name of the Key will not be removed though.
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 0 (NULL), the resulting key name will be "system:/dir1/dir2". If baseName is empty, the resulting key name will be "system:/dir1/dir2/%", where "%" denotes an empty base name, as also shown in the following code:
keySetBaseName() does proper escaping on the supplied name argument.
You can use character sequences as baseName (e.g. "." (dot), ".." (dot-dot), "%" (empty basename)). They will be properly escaped and will not have their usual meaning.
If you want to add to the basename instead of changing it, use keyAddBaseName(). If you do not want any escaping, use keyAddName().
| -1 | if Key is NULL |
| -1 | if Key was inserted into KeySet before |
| -1 | if Key is read-only |
| -1 | on allocation errors |
| KeyInvalidName | if the name is not valid |
|
inline |
Set the value of a Key to the binary value newBinary.
A private copy of newBinary will be allocated and saved inside key, so the parameter can be deallocated after the call.
Binary values might be encoded in another way than string values depending on the plugin. Typically character encodings should not take place on binary data. Consider using a string Key instead, if encoding should occur.
When newBinary is a NULL pointer the value will be freed and 0 will be returned.
Read-only keys will stay unchanged after calling this function.
dataSize matches the length of newBinary newBinary is not NULL and dataSize > 0 key is not read-only key's value set exactly to the data in newBinary key's metadata| key | the Key object where the value should be set |
| newBinary | a pointer to any binary data or NULL (to clear the stored value) |
| dataSize | number of bytes to copy from newBinary |
| 0 | when the internal binary was freed and is now a null pointer |
| -1 | if key is NULL |
| -1 | when dataSize is 0 (and newBinary not NULL) or larger than SSIZE_MAX |
| -1 | if key is read-only |
|
inline |
Set metadata for key.
Set a new metadata Key. Will set a new metadata pair with name metaName and value newMetaString.
Will add a new metadata Key, if metaName was unused until now.
It will modify an existing Pair of metadata if metaName was already present.
It will remove a metadata Key if newMetaString is 0.
If metaName does not start with 'meta:/', it will be prefixed with 'meta:/'.
metaName is prefixed with "meta:/" key's metadata is not read-only key's metadata Keyset for metaName is newMetaString | key | Key whose metadata should be set |
| metaName | name of the metadata Key that should be set |
| newMetaString | new value for the metadata Key |
newMetaString if metadata has been successfully added | 0 | if the meta-information for metaName was removed |
| -1 | if key or metaName is 0 |
| -1 | if system is out of memory |
| -1 | if metaName is not a valid metadata name |
Use delMeta() to avoid these issues.
|
inline |
Set a new name to a Key.
A valid name is one of the forms:
spec:/something for specification of other keys.proc:/something for in-memory keys, e.g. commandline.dir:/something for dir keys in current working directorysystem:/something for system keys in /etc or /user:/something for user keys in home directoryuser:username/something for other users (deprecated: kdbGet() + kdbSet() currently unsupported)/something for cascading keys (actually refers to one of the above, see also ksLookup())An invalid name either has an invalid namespace or a wrongly escaped \ at the end of the name.
See key names for the exact rules.
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 paths. A valid name will be build out of the (valid) name what you pass, e.g. user:///sw/../sw//././MyApp -> user:/sw/MyApp
Trailing slashes will be stripped.
On invalid names, the name stays unchanged.
| -1 | if key or keyName is NULL or keyName is empty or invalid |
| -1 | if Key was inserted to a KeySet before |
| -1 | if Key name is read-only |
| KeyInvalidName | if the name is not valid |
|
inline |
Set the namespace of the key.
|
inline |
Set the value for key as newStringValue.
The function will allocate and save a private copy of newStringValue, so the parameter can be freed after the call.
String values will be saved in backend storage in UTF-8 universal encoding, regardless of the program's current encoding (if the iconv plugin is available).
newStringValue is a NULL terminated string newStringValue meta:/binary is cleared| key | the Key for which to set the string value |
| newStringValue | NULL-terminated string to be set as key's value |
| 1 | if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination) |
| -1 | if key is a NULL pointer |
1.9.1