Elektra  0.9.6
Functions
Name Manipulation Methods

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's name (excluding owner). More...
 
const void * keyUnescapedName (const Key *key)
 Returns a Key's name, separated by NULL bytes and without backslashes for escaping. More...
 
ssize_t keyGetUnescapedNameSize (const Key *key)
 Returns the size of the Key's unescaped name including embedded and terminating NULL characters. More...
 
ssize_t keyGetName (const Key *key, char *returnedName, size_t maxSize)
 Get abbreviated Key name (excluding owner). More...
 
ssize_t keyGetUnescapedName (const Key *key, char *returnedName, size_t maxSize)
 Copies the unescaped name of a Key into returnedName. 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 part to the Key's name. 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 unescaped Key's name where the basename starts. More...
 
ssize_t keyGetBaseNameSize (const Key *key)
 Calculates number of bytes needed to store basename of key (including NULL terminator). More...
 
ssize_t keyGetBaseName (const Key *key, char *returned, size_t maxSize)
 Copy the Key's basename to returned. 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 to the name of key. More...
 
ssize_t keySetBaseName (Key *key, const char *baseName)
 Sets baseName as the new basename for key. More...
 
elektraNamespace keyGetNamespace (const Key *key)
 Returns the elektraNamespace for a Key. 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:

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
nameThe key name that is processed
canonicalNameOutput buffer for the canonical name
canonicalSizePtrPointer to size of canonicalName
offsetOffset into canonicalName
usizePtrOutput 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
partA single key name part, i.e. contained '/' will be escaped, '\0' terminates part
escapedPartOutput 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
canonicalNameThe canonical name to unescape
unescapedNameOutput 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
nameThe escaped key name to check
isCompleteWhether or not name is supposed to be a complete key name
Return values
#trueIf name is a valid key name.
#falseOtherwise

◆ keyAddBaseName()

ssize_t keyAddBaseName ( Key *  key,
const char *  baseName 
)

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:

Key * k = keyNew ("user:/my/long", KEY_END);
keyAddBaseName (k, "myname");
printf ("%s\n", keyName (k)); // will print user:/my/long/myname
keyDel (k);
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:509
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:150
@ KEY_END
Definition: kdbenum.c:97
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition: elektra/keyname.c:254
ssize_t keyAddBaseName(Key *key, const char *baseName)
Adds baseName to the name of key.
Definition: elektra/keyname.c:1609

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), ".");
ssize_t keySetName(Key *key, const char *newName)
Set a new name to a Key.
Definition: elektra/keyname.c:493
const char * keyBaseName(const Key *key)
Returns a pointer to the unescaped Key's name where the basename starts.
Definition: elektra/keyname.c:1263
Parameters
keythe Key to add the basename to
baseNamethe string to append to the Key's name
Returns
the size in bytes of the Key's new name including the NULL terminator
Return values
-1if the Key has no name
-1on NULL pointers
-1if Key was inserted into KeySet before
-1if the Key was read-only
-1on memory allocation errors
Since
1.0.0
See also
keySetBaseName() for setting the basename of a Key
keySetName() for setting the name of a Key

◆ keyAddName()

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

Add an already escaped name part to the Key's name.

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);
ssize_t keyAddName(Key *key, const char *newName)
Add an already escaped name part to the Key's name.
Definition: elektra/keyname.c:564

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 \
Precondition
key MUST be a valid #Key
Parameters
keythe Key where a name should be added
newNamethe new name to add to the name of key
Returns
new size of the escaped name of key
Return values
-1if key == NULL or newName == NULL
-1newName is not a valid escaped name
-1key is read-only
Since
1.0.0
See also
keySetName() for setting a Key's name
keyAddBaseName() for adding a basename to a Key

◆ keyBaseName()

const char* keyBaseName ( const Key *  key)

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

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

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. You should use keySetBaseName() instead.
Do not assume that keyBaseName() points to the same region as keyName() does.
Parameters
keythe Key to obtain the basename from
Returns
a pointer to the Key's basename
Return values
""when the Key has no (base)name
0on NULL pointer
Since
1.0.0
See also
keyGetBaseName() for getting a copy of the Key's basename
keyGetBaseNameSize() for getting the size of the Key's basename
keyName() for getting a pointer to the Key's name

◆ keyGetBaseName()

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

Copy the Key's basename to returned.

The copy will include a NULL terminator which will be considered for the returned size. Nothing will be copied if maxSize is smaller than the size of the basename.

Some examples:

  • basename of system:/some/keyname is keyname
  • basename of "user:/tmp/some key" is "some key"
Parameters
keythe Key to extract basename from
returneda pre-allocated buffer for storing the basename
maxSizesize of the buffer returned
Returns
number of bytes copied to returned
Return values
1when Key's name is empty
-1on NULL pointers
-1when maxSize is 0 or larger than SSIZE_MAX
-1when maxSize is smaller than the size of the Key's basename
Since
1.0.0
See also
keyBaseName() for getting a pointer to the Key's basename
keyGetBaseNameSize() for getting the size of a Key's basename
keyName(), keyGetName() for getting a pointer / copy of the whole name
keySetName() for setting a Key's name

◆ keyGetBaseNameSize()

ssize_t keyGetBaseNameSize ( const Key *  key)

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
Parameters
keythe Key to get the size of the basename from
Returns
size in bytes of the Key's basename including NULL terminator
Return values
-1if the Key's basename is NULL
Since
1.0.0
See also
keyBaseName() for getting a pointer to a Key's basename
keyGetBaseName() for getting a copy of a Key's basename
keyName(), keyGetName() for getting a pointer / copy of the whole name
keySetName() for setting a Key's name

◆ keyGetName()

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

Get abbreviated Key name (excluding owner).

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. elektraMalloc() is not as failure tolerant and would try to allocate memory accordingly.

char *getBack = elektraMalloc (keyGetNameSize(key));
keyGetName(key, getBack, keyGetNameSize(key));
ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize)
Get abbreviated Key name (excluding owner).
Definition: elektra/keyname.c:379
ssize_t keyGetNameSize(const Key *key)
Bytes needed to store the Key's name (excluding owner).
Definition: elektra/keyname.c:280
void * elektraMalloc(size_t size)
Allocate memory for Elektra.
Definition: internal.c:274
Parameters
keythe Key to get the name from
returnedNamepre-allocated buffer to write the Key's name
maxSizemaximum number of bytes that will fit in returnedName, including the NULL terminator
Returns
number of bytes written to returnedName
Return values
1when only NULL terminator was written
-1when Key's name is longer than maxSize or maxSize is 0 or maxSize is greater than SSIZE_MAX
-1key or returnedName is NULL pointer
Since
1.0.0
See also
keyGetNameSize() for getting the size of a Key's name
keyName() for getting a pointer to a Key's name
keyGetBaseName() for getting a Key's base name
keyGetNamespace() for getting the namespace of a Key's name

◆ keyGetNameSize()

ssize_t keyGetNameSize ( const Key *  key)

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.

Parameters
keythe Key to get the name size from
Returns
number of bytes needed, including NULL terminator, to store Key's name (excluding owner)
Return values
1if Key has no name
-1on NULL pointer
Since
1.0.0
See also
keyGetName() for getting the Key's name
keyGetUnescapedNameSize() for getting the size of the unescaped name

◆ keyGetNamespace()

elektraNamespace keyGetNamespace ( const Key *  key)

Returns the elektraNamespace for a Key.

To handle every namespace a Key could have, you can use the following snippet:

switch (keyGetNamespace (k))
{
printf ("spec namespace\n");
break;
printf ("proc namespace\n");
break;
printf ("dir namespace\n");
break;
printf ("user namespace\n");
break;
printf ("system namespace\n");
break;
printf ("no key\n");
break;
printf ("metakey\n");
break;
printf ("cascading key\n");
break;
}
@ KEY_NS_SPEC
spec contains the specification of the other namespaces
Definition: kdbenum.c:140
@ KEY_NS_CASCADING
cascading key, starts with /, abstract name for any of the namespaces below
Definition: kdbenum.c:138
@ KEY_NS_NONE
no key given as parameter to keyGetNamespace()
Definition: kdbenum.c:137
@ KEY_NS_PROC
proc contains process-specific configuration
Definition: kdbenum.c:141
@ KEY_NS_SYSTEM
system key is shared for a computer system
Definition: kdbenum.c:144
@ KEY_NS_USER
user key in the home directory of the current user
Definition: kdbenum.c:143
@ KEY_NS_DIR
dir contains configuration from a specific directory
Definition: kdbenum.c:142
@ KEY_NS_META
metakey, i.e. any key name not under other categories
Definition: kdbenum.c:139
elektraNamespace keyGetNamespace(const Key *key)
Returns the elektraNamespace for a Key.
Definition: elektra/keyname.c:1723

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);
}
elektraNamespace
Elektra currently supported Key namespaces.
Definition: kdbenum.c:136
Note
This method might be extended. There is no guarantee that a Key with a specific namespace will retain that namespace after recompilation. 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 when recompiling.
Parameters
keythe Key to get the namespace from
Returns
the namespace of the Key
Return values
KEY_NS_NONEif Key is NULL
Since
1.0.0
See also
keySetNamespace() for setting a Key's namespace

◆ keyGetUnescapedName()

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

Copies the unescaped name of a Key into returnedName.

It will only copy the whole name. If the buffer is too small, an error code will be returned.

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

Parameters
keythe Key to extract the unescaped name from
returnedNamethe buffer to write the unescaped name into
maxSizemaximum number of 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
returnedName must not be NULL
Returns
the actual size of the Key's unescaped name, i.e. the number of bytes copied into returnedName
Return values
-1Precondition error
-2the size of the unescaped name is greater than maxSize
Since
1.0.0
See also
keyGetUnescapedNameSize() for getting the size of the unescaped name
keyGetName() for getting the Key's escaped name

◆ keyGetUnescapedNameSize()

ssize_t keyGetUnescapedNameSize ( const Key *  key)

Returns the size of the Key's unescaped name including embedded and terminating NULL characters.

Parameters
keythe Key where to get the size of the unescaped name from
Returns
The size of the Key's unescaped name
Return values
-1on NULL pointer
0if Key has no name
Since
1.0.0
See also
keyUnescapedName() for getting a pointer to the unescaped name
keyGetUnescapedName() for getting a copy of the unescaped name
keyGetNameSize() for getting the size of the escaped 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
    keythe Key you want to get the name from
    Returns
    a pointer to the Key's name which must not be changed.
    Return values
    ""when Key's name is empty
    0on NULL pointer
    Since
    1.0.0
    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:

  1. If before calling this function key and oldPrefix had the same name, then afterwards key will have the same name as newPrefix.
  2. 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.
  3. 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
keyThe key that will be manipulated.
oldPrefixThe name of this key will be removed from the front of the name of key.
newPrefixThe name of this key will be added to the front of key, after the name of oldPrefix is removed.
Return values
-1if key, oldPrefix or newPrefix are NULL or the name of key is marked as read-only
0if key is not below (or same as) oldPrefix, i.e. there is no prefix to replace
1if 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 of the Key will be affected.

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);
ssize_t keySetBaseName(Key *key, const char *baseName)
Sets baseName as the new basename for key.
Definition: elektra/keyname.c:1667

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:

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.

If you want to add to the basename instead of changing it, use keyAddBaseName(). If you do not want any escaping, use keyAddName().

Parameters
keythe Key whose basename to set
baseNamethe new basename for the Key
Returns
the size in bytes of the new key name
Return values
-1on NULL pointers
-1if Key was inserted into KeySet before
-1if Key is read-only
-1on allocation errors
Since
1.0.0
See also
keyAddBaseName() for adding a basename instead of changing it
keyAddName() for adding a name without escaping
keySetName() for setting a completely new name
Name Manipulation Methods for more details on special names

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

Returns
size of the new Key name in bytes, including NULL terminator
Return values
-1if key or keyName is NULL or keyName is empty or invalid
-1if Key was inserted to a KeySet before
-1if Key name is read-only
Parameters
keythe Key whose name to set
newNamethe new name for the Key
Since
1.0.0
See also
keyGetName() for getting a copy of the Key's name
keyName() for getting a pointer to the Key's name
keySetBaseName(), keyAddBaseName() for manipulating the base name

◆ keySetNamespace()

ssize_t keySetNamespace ( Key *  key,
elektraNamespace  ns 
)

Changes the namespace of a Key.

The rest of the Key's name remains unchanged.

Precondition
ns MUST be a valid namespace and not KEY_NS_NONE
key MUST be a valid #Key, especially key != NULL
Parameters
keyThe #Key whose namespace will be changed
nsThe new namespace of for key
Returns
the new size in bytes of the Key's namespace
Return values
-1precondition error
Since
1.0.0
See also
keyGetNamespace() for getting a Key's namespace

◆ keyUnescapedName()

const void* keyUnescapedName ( const Key *  key)

Returns a Key's name, separated by NULL bytes and without backslashes for escaping.

Slashes are replaced with NULL bytes. Therefore unescaped names of cascading Keys start with a NULL byte. Otherwise escaped characters, e.g. non-hierarchy slashes, will be unescaped.

This name is essential if you want to iterate over parts of the Key's name, compare Key names or check relations of Keys in the hierarchy.

Parameters
keythe Key whose unescaped name to get
Returns
the name in its unescaped form
Return values
0on NULL pointers
""if Key's name is empty
Since
1.0.0
See also
keyGetUnescapedName() for getting a copy of the unescaped name
keyGetUnescapedNameSize() for getting the size of the unescaped name
keyName() for getting the escaped name of the Key