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

Collaboration diagram for Name Manipulation Methods:

Functions
const char *	keyName (const Key *key)
	Returns a pointer to the abbreviated real internal `key` name. More...

ssize_t	keyGetNameSize (const Key *key)
	Bytes needed to store the key name without owner. More...

const void *	keyUnescapedName (const Key *key)
	Returns a keyname which is null separated and does not use backslash for escaping. More...

ssize_t	keyGetUnescapedNameSize (const Key *key)
	return size of unescaped name with embedded and terminating null characters More...

ssize_t	keyGetName (const Key key, char returnedName, size_t maxSize)
	Get abbreviated key name (without owner name). More...

ssize_t	keyGetUnescapedName (const Key key, char returnedName, size_t maxSize)
	Copies the unescaped name of a key into provided buffer. More...

ssize_t	keySetName (Key key, const char newName)
	Set a new name to a key. More...

ssize_t	keyAddName (Key key, const char newName)
	Add an already escaped name to the keyname. More...

int	keyReplacePrefix (Key key, const Key oldPrefix, const Key *newPrefix)
	Replaces a prefix of the key name of `key`. More...

bool	elektraKeyNameValidate (const char *name, bool isComplete)
	Takes an escaped key name and validates it. More...

void	elektraKeyNameCanonicalize (const char name, char canonicalName, size_t canonicalSizePtr, size_t offset, size_t *usizePtr)
	Takes a valid (non-)canonical key name and produces its canonical form. More...

void	elektraKeyNameUnescape (const char canonicalName, char unescapedName)
	Takes a canonical key name and unescapes it. More...

const char *	keyBaseName (const Key *key)
	Returns a pointer to the internal unescaped key name where the `basename` starts. More...

ssize_t	keyGetBaseNameSize (const Key *key)
	Calculates number of bytes needed to store basename of `key`. More...

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

size_t	elektraKeyNameEscapePart (const char part, char *escapedPart)
	Takes a single key name part and produces its escaped form. More...

ssize_t	keyAddBaseName (Key key, const char baseName)
	Adds `baseName` (that will be escaped) to the current key name. More...

ssize_t	keySetBaseName (Key key, const char baseName)
	Sets `baseName` as the new basename for `key`. More...

elektraNamespace	keyGetNamespace (const Key *key)
	For currently valid namespaces see elektraNamespace. More...

ssize_t	keySetNamespace (Key *key, elektraNamespace ns)
	Changes the namespace of a key. More...

Detailed Description

Methods to do various operations on Key names.

To use them:

#include <kdb.h>

These functions make it easier for C programmers to work with key names.

Terminology of Key Names

A key name (see keySetName() and keyName()) defines the place of a key within the key database. To be unique, it is always absolute and canonical.
Key names are composed out of many key name parts split by a separator. These key name parts do not contain an unescaped separator.
A key base name (see keySetBaseName() and keyAddBaseName()) is the last part of the key name.
A C-String is a null terminated sequence of characters. So \0 (null-character) must not occur within a C-String.

Namespaces: A namespace denotes the place the key comes from:

spec:/something for specification of other keys.
proc:/something for in-memory keys, e.g. commandline.
dir:/something for dir keys in current working directory
system:/something for system keys in /etc or /
user:/something for user keys in home directory
user:username/something for other users (deprecated: kdbGet() + kdbSet() currently unsupported)
/something for cascading keys (actually refers to one of the above, see also ksLookup())
Note
The rules are currently not formally specified and are subject of change in the next major release. So, always prefer:
- To use keySetName() and keyAddName() to get the canonified version of the keyname
- To use keySetBaseName() and keyAddBaseName() to get an escaped key name part.
- Not to escape or canonify with your own algorithms!
- To use keyUnescapedName() and keyBaseName() to have access to the key name without escape sequences (key name parts are null terminated)
- Not to unescape the strings yourself!
Syntax for Key Names
Key names and key name parts have following goals:
- The C-String passed to keySetName() and keyAddName() may be any C-String.
- The key name parts (e.g. keySetBaseName(), keyBaseName()) may be any C-String. Escaping is needed to achieve both goals.
Semantics for Key Name Parts
- % denotes an empty key name part.
Canonicalization for Key Names
- / (slash) is the separator between key name parts.
- // is shortened to /
- trailing / (slashes) are removed
- . (dot) and .. (dot-dot) is removed in an canonical key name, with following rules:
  - /./ is shortened to /
  - _/../ is shortened to _
Conventions for key names
- Key name parts starting with # are array elements. Then only _ (underscore) followed by 0-9 is allowed. So we have the regular expression #[_]*[0-9]+ with the further limitation that the number of _ is defined by the number of digits-1.
- Key name parts starting with _ are reserved for special purposes (if you use this within a plugin you still have to make sure _ is escaped properly)
- Key name parts starting with @ are reserved for special purposes (if you use this within a plugin you still have to make sure @ is escaped properly)
Escaping rules
- \ (backslash) is the escape character for the situations as described here (and only these). The \ character must only be escaped, when one of the following rules apply.
- Stray escape characters are only possible in the end of the string.
- \/ allows one to escape / (any uneven number of \). Does not introduce a new part.
- Any uneven number N of \ before / allows you to escape / with the N/2 of \ prefixed. Does not introduce a new part.
- \\/ allows one to use \ as character before / and introduces a new part.
- Any even number N of \ before / allows you to have N/2 of \ prefixed before a / which introduces a new part.
- Use \. and \.. if you want your key name part to represent . and ..
- \\. and \\.. allows us to use \ as character before . and .. (and so on)
- Use \% if you want your key name part to start with % (and does not represent an empty name)
- Using \\% allows one to use \ as character before % (and so on)
Semantics for Key Name Specifications
- _ denotes that the key name part is arbitrary (syntax as described above).
- # denotes that the key name part has array syntax.
- names surrounded by % (e.g. %profile%) denotes a placeholder.

Function Documentation

◆ elektraKeyNameCanonicalize()

void elektraKeyNameCanonicalize	(	const char *	name,
		char **	canonicalName,
		size_t *	canonicalSizePtr,
		size_t	offset,
		size_t *	usizePtr
	)

Takes a valid (non-)canonical key name and produces its canonical form.

As a side-effect it can also calculate the size of the corresponding unescaped key name.

Parameters

name	The key name that is processed
canonicalName	Output buffer for the canonical name
canonicalSizePtr	Pointer to size of `canonicalName`
offset	Offset into `canonicalName`
usizePtr	Output variable for the size of the unescaped name

Precondition: name MUST be a valid (non-)canonical key name. If it is not, the result is undefined; canonicalName MUST be a valid first argument for elektraRealloc() when cast to void**; canonicalSizePtr >= offset; offset MUST be 0 or *canonicalName + offset MUST point to the zero-termintor of a valid canonical key name that starts at *canonicalName; if offset is 0 then *usizePtr MUST 0, otherwise *usizePtr MUST be the correct unescaped size of the existing canonical name in *canonicalName

See also: elektraKeyNameValidate

◆ elektraKeyNameEscapePart()

size_t elektraKeyNameEscapePart	(	const char *	part,
		char **	escapedPart
	)

Takes a single key name part and produces its escaped form.

Parameters

part	A single key name part, i.e. contained '/' will be escaped, '\0' terminates part
escapedPart	Output buffer for the escaped form

Precondition: escapedPart MUST be a valid first argument for elektraRealloc() when cast to void**

Returns: The size of the escaped form excluding the zero terminator

◆ elektraKeyNameUnescape()

void elektraKeyNameUnescape	(	const char *	canonicalName,
		char *	unescapedName
	)

Takes a canonical key name and unescapes it.

Parameters

canonicalName	The canonical name to unescape
unescapedName	Output buffer for the unescaped name

Precondition: canonicalName MUST be a canonical key name. If this is not the case, the result is undefined.; unescapedName MUST be allocated to the correct size.

See also: elektraKeyNameCanonicalize

◆ elektraKeyNameValidate()

bool elektraKeyNameValidate	(	const char *	name,
		bool	isComplete
	)

Takes an escaped key name and validates it.

Complete key names must inlcude a namespace or a leading slash.

Parameters

name	The escaped key name to check
isComplete	Whether or not `name` is supposed to be a complete key name

Return values

#true	If `name` is a valid key name.
#false	Otherwise

◆ keyAddBaseName()

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:

Key * k = keyNew ("user:/my/long", KEY_END);
keyAddBaseName (k, "myname");
printf ("%s\n", keyName (k)); // will print user:/my/long/myname
keyDel (k);

E.g. if you add . it will be escaped:

        keySetName (k, "system:/valid");
        succeed_if (keyAddBaseName (k, ".") >= 0, "could not add a base name");
        succeed_if_same_string (keyName (k), "system:/valid/\\.");
        succeed_if_same_string (keyBaseName (k), ".");

See also: keySetBaseName() to set a base name; keySetName() to set a new name.

Parameters

key	the key object to work with
baseName	the string to append to the name

Returns: the size in bytes of the new key name including the ending NULL

Return values

-1	if the key had no name
-1	on NULL pointers
-1	if key was inserted to a keyset before
-1	on allocation errors

◆ keyAddName()

ssize_t keyAddName	(	Key *	key,
		const char *	newName
	)

Add an already escaped name to the keyname.

The same way as in keySetName() this method finds the canonical pathname:

it will ignore /./
it will remove a level when /../ is used
it will remove multiple slashes ////

For example:

Key * k = keyNew ("user:/x/r", KEY_END);
keyAddName (k, "../y/a//././z");
assert (!strcmp (keyName (k), "user:/x/y/a/z"));
keyDel (k);

Unlike keySetName() it adds relative to the previous name and cannot change the namespace of a key. For example:

Key * n = keyNew ("user:/away", KEY_END);
keyAddName (n, "../../../new/name");
assert (!strcmp (keyName (n), "user:/new/name"));
keyDel (n);

The passed name needs to be valid according the key name rules . It is not allowed to:

be empty
end with unequal number of \

Parameters

key	the key where a name should be added
newName	the new name to append

Precondition: key MUST be a valid #Key

Since: 0.8.11

Return values

-1	if `key == NULL`, `key` is read-only, `newName == NULL` or `newName` is not a valid escaped name

Returns: new size of the escaped name of key

◆ keyBaseName()

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

        keySetName (k, "");
        succeed_if_same_string (keyBaseName (k), "");
        keySetName (k, "user:/");
        succeed_if_same_string (keyBaseName (k), "");

And there is also support for really empty basenames:

        keySetName (k, "system:/valid");
        succeed_if (keyAddBaseName (k, "") >= 0, "could not add a base name");
        succeed_if_same_string (keyName (k), "system:/valid/%");
        succeed_if_same_string (keyBaseName (k), "");

Note: You must never use the pointer returned by keyBaseName() method to change the name, but you should use keySetBaseName() instead.; Do not assume that keyBaseName() points to the same region as keyName() does.

Parameters

key	the object to obtain the basename from

Returns: a pointer to the basename

Return values

""	when the key has no (base)name
0	on NULL pointer

See also: keyGetBaseName(), keyGetBaseNameSize(); keyName() to get a pointer to the name

◆ keyGetBaseName()

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:

basename of system:/some/keyname is keyname
basename of "user:/tmp/some key" is "some key"

Parameters

key	the key to extract basename from
returned	a pre-allocated buffer to store the basename
maxSize	size of the `returned` buffer

Returns: number of bytes copied to returned

Return values

1	on empty name
-1	on NULL pointers
-1	when maxSize is 0 or larger than SSIZE_MAX

See also: keyBaseName(), keyGetBaseNameSize(); keyName(), keyGetName(), keySetName()

◆ keyGetBaseNameSize()

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

Parameters

key	the key object to work with

Returns: size in bytes of key's basename including ending NULL

See also: keyBaseName(), keyGetBaseName(); keyName(), keyGetName(), keySetName()

◆ keyGetName()

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 elektraMalloc is not as failure tolerant and will try to allocate.

char *getBack = elektraMalloc (keyGetNameSize(key));

keyGetName(key, getBack, keyGetNameSize(key));

Returns: number of bytes written to returnedName

Return values

1	when only a null was written
-1	when keyname is longer then maxSize or 0 or any NULL pointer

Parameters

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

See also: keyGetNameSize()

◆ keyGetNameSize()

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.

Parameters

key	the key object to work with

Returns: number of bytes needed, including ending NULL, to store key name without owner

Return values

1	if there is is no key Name
-1	on NULL pointer

See also: keyGetName(); keyGetUnescapedNameSize to get size of unescaped name

◆ keyGetNamespace()

elektraNamespace keyGetNamespace ( const Key * key )

For currently valid namespaces see elektraNamespace.

To handle every possible cases (including namespaces) a key can have:

switch (keyGetNamespace (k))
{
case KEY_NS_SPEC:
        printf ("spec namespace\n");
        break;
case KEY_NS_PROC:
        printf ("proc namespace\n");
        break;
case KEY_NS_DIR:
        printf ("dir namespace\n");
        break;
case KEY_NS_USER:
        printf ("user namespace\n");
        break;
case KEY_NS_SYSTEM:
        printf ("system namespace\n");
        break;
case KEY_NS_NONE:
        printf ("no key\n");
        break;
case KEY_NS_META:
        printf ("metakey\n");
        break;
case KEY_NS_CASCADING:
        printf ("cascading key\n");
        break;
}

To loop over all valid namespaces use:

for (elektraNamespace ns = KEY_NS_FIRST; ns <= KEY_NS_LAST; ++ns)
{
        // work with namespace
        printf ("%d\n", ns);
}

Note: This method might be enhanced. You do not have any guarantee that, when for a specific name KEY_NS_META is returned today, that it still will be returned after the next recompilation. So make sure that your compiler gives you a warning for unhandled switches (gcc: -Wswitch or -Wswitch-enum if you want to handle default) and look out for those warnings.

Parameters

key	the key object to work with

Returns: the namespace of a key.

◆ keyGetUnescapedName()

ssize_t keyGetUnescapedName	(	const Key *	key,
		char *	returnedName,
		size_t	maxSize
	)

Copies the unescaped name of a key into provided buffer.

We will only copy the full name, if the buffer is to small an error code is returned.

To ensure your buffer is big enough, you can use keyGetUnescapedNameSize() to find the correct size.

Parameters

key	the Key to extract the unescaped name from
returnedName	output buffer
maxSize	maximum bytes that can be copied into `returnedName`

Precondition: key MUST be a valid #Key and key != NULL; returnedName MUST be allocated to be at least maxSize bytes big and returnedName != NULL

Return values

-1	precondition error
-2	the size of the unescaped name is bigger then `maxSize`

Returns: otherwise, the actual size of the unescaped name, i.e. the number of bytes copied into returnedName

◆ keyGetUnescapedNameSize()

ssize_t keyGetUnescapedNameSize ( const Key * key )

return size of unescaped name with embedded and terminating null characters

Parameters

key	the object to work with

See also: keyUnescapedName(); keyGetNameSize() for size of escaped variant

Return values

-1	on null pointer
0	if no name

◆ keyName()

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

Return values

""	when there is no keyName. The reason is key=keyNew(0); keySetName(key,""); keyName(key); // you would expect "" here keyDel(key);

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 directory
system:/something for system keys in /etc or /
user:/something for user keys in home directory
user:username/something for other users (deprecated: kdbGet() + kdbSet() currently unsupported)
/something for cascading keys (actually refers to one of the above, see also ksLookup())

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 keyName() method to set a new value. Use keySetName() instead.

Parameters

key the key object to work with

Returns
a pointer to the keyname which must not be changed.

Return values

"" when there is no (an empty) keyname

0 on NULL pointer

See also
keyGetNameSize() for the string length

keyGetName() as alternative to get a copy

keyUnescapedName to get an unescaped Key name

◆ keyReplacePrefix()

int keyReplacePrefix	(	Key *	key,
		const Key *	oldPrefix,
		const Key *	newPrefix
	)

Replaces a prefix of the key name of key.

The function only modifies key, if is is below (or same as) oldPrefix (see keyIsBelowOrSame()) and they both have the same namespace (this is not always the case with keyIsBelowOrSame()).

In simple terms this function operates as follows:

If before calling this function key and oldPrefix had the same name, then afterwards key will have the same name as newPrefix.
If key was in the same namespace as and below oldPrefix, then after calling this function key will be in the same namespace as and below newPrefix.
Otherwise key will not be modified.

Note: We use const Key * arguments for the prefixes instead of const char * to ensure only valid key names can be passed as arguments.

Parameters

key	The key that will be manipulated.
oldPrefix	The name of this key will be removed from the front of the name of `key`.
newPrefix	The name of this key will be added to the front of `key`, after the name of `oldPrefix` is removed.

Return values

-1	if `key`, `oldPrefix` or `newPrefix` are NULL or the name of `key` is marked as read-only
0	if `key` is not below (or same as) `oldPrefix`, i.e. there is no prefix to replace
1	if the prefix was sucessfully replaced

◆ keySetBaseName()

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.

A simple example is:

Key * k = keyNew ("user:/my/long/name", KEY_END);
keySetBaseName (k, "myname");
printf ("%s\n", keyName (k)); // will print user:/my/long/myname
keyDel (k);

All text after the last '/' in the key keyname is erased and baseName is appended. If baseName is 0 (NULL), then the last part of the keyname is removed without replacement.

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:

        keySetName (k, "system:/valid");
        keySetBaseName (k, "");
        succeed_if_same_string (keyName (k), "system:/%");
        succeed_if_same_string (keyBaseName (k), "");

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.

See also: Name Manipulation Methods for more details on special names

If you want to add and not change the basename, use keyAddBaseName() instead. If you do not want escaping, use keyAddName() instead.

See also: keyAddBaseName() to add a basename instead of changing it; keyAddName() to add a name without escaping; keySetName() to set a completely new name

Parameters

key	the key object to work with
baseName	the string used to overwrite the basename of the key

Returns: the size in bytes of the new key name

Return values

-1	on NULL pointers in key
-1	if key was inserted to a keyset before
-1	on allocation errors

◆ keySetName()

ssize_t keySetName	(	Key *	key,
		const char *	newName
	)

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 directory
system:/something for system keys in /etc or /
user:/something for user keys in home directory
user: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

On invalid names, NULL or "" the name will be "" afterwards.

Return values

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

Parameters

key	the key object to work with
newName	the new key name

See also: keyNew(); keyGetName(), keyName(); keySetBaseName(), keyAddBaseName() to manipulate a name

◆ keySetNamespace()

ssize_t keySetNamespace	(	Key *	key,
		elektraNamespace	ns
	)

Changes the namespace of a key.

The rest of the name remains unchanged.

Parameters

key	The #Key whose namespace will be changed
ns	The new namespace of for `key`

Precondition: ns MUST be a valid namespace and not KEY_NS_NONE; key MUST be a valid #Key, especially key != NULL

Return values

-1	precondition error

Returns: the new size the {key}'s escaped name

◆ keyUnescapedName()

const void* keyUnescapedName ( const Key * key )

Returns a keyname which is null separated and does not use backslash for escaping.

Slashes are replaced with null bytes. So cascading keys start with a null byte. Otherwise escaped characters, e.g. non-hierarchy slash, will be unescaped.

This name is essential if you want to iterate over parts of the key name, want to compare keynames and want to check relations of keys in the hierarchy.

Parameters

key	the object to work with

See also: keyGetUnescapedNameSize(); keyName() for escaped variant

Return values

0	on null pointers
""	if no name

Returns: the name in its unescaped form

Functions

Detailed Description

Function Documentation

◆ elektraKeyNameCanonicalize()

◆ elektraKeyNameEscapePart()

◆ elektraKeyNameUnescape()

◆ elektraKeyNameValidate()

◆ keyAddBaseName()

◆ keyAddName()

◆ keyBaseName()

◆ keyGetBaseName()

◆ keyGetBaseNameSize()

◆ keyGetName()

◆ keyGetNameSize()

◆ keyGetNamespace()

◆ keyGetUnescapedName()

◆ keyGetUnescapedNameSize()

◆ keyName()

◆ keyReplacePrefix()

◆ keySetBaseName()

◆ keySetName()

◆ keySetNamespace()

◆ keyUnescapedName()