| Elektra 0.11.0

Functions
Name Manipulation Methods
Key

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

## Functions
const char * | keyName (const Key *key)
| Returns a pointer to the abbreviated real internal `key` name.
ssize_t | keyGetNameSize (const Key *key)
| Bytes needed to store the Key's name (excluding owner).
const void * | keyUnescapedName (const Key *key)
| Returns a Key's name, separated by NULL bytes and without backslashes for escaping.
ssize_t | keyGetUnescapedNameSize (const Key *key)
| Returns the size of the Key's unescaped name including embedded and terminating NULL characters.
ssize_t | keyGetName (const Key *key, char *returnedName, size_t maxSize)
| Get abbreviated Key name (excluding owner).
ssize_t | keyGetUnescapedName (const Key *key, char *returnedName, size_t maxSize)
| Copies the unescaped name of a Key into `returnedName`.
ssize_t | keySetName (Key *key, const char *newName)
| Set a new name to a Key.
ssize_t | keyAddName (Key *key, const char *newName)
| Add an already escaped name part to the Key's name.
int | keyReplacePrefix (Key *key, const Key *oldPrefix, const Key *newPrefix)
| Replaces a prefix of the key name of `key`.
bool | elektraKeyNameValidate (const char *name, bool isComplete)
| Takes an escaped key name and validates it.
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.
void | elektraKeyNameUnescape (const char *canonicalName, char *unescapedName)
| Takes a canonical key name and unescapes it.
const char * | keyBaseName (const Key *key)
| Returns a pointer to the unescaped Key's name where the basename starts.
ssize_t | keyGetBaseNameSize (const Key *key)
| Calculates number of bytes needed to store basename of `key` (including NULL terminator).
ssize_t | keyGetBaseName (const Key *key, char *returned, size_t maxSize)
| Copy the Key's basename to `returned`.
size_t | elektraKeyNameEscapePart (const char *part, char **escapedPart)
| Takes a single key name part and produces its escaped form.
ssize_t | keyAddBaseName (Key *key, const char *baseName)
| Adds `baseName` to the name of `key`.
ssize_t | keySetBaseName (Key *key, const char *baseName)
| Sets `baseName` as the new basename for `key`.
elektraNamespace | keyGetNamespace (const Key *key)
| Returns the elektraNamespace for a Key.
ssize_t | keySetNamespace (Key *key, elektraNamespace ns)
| Changes the namespace of a Key.
int | elektraIsArrayPart (const char *namePart)
| Checks if the given key name part is an array part.

## 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

## ◆ elektraIsArrayPart()

int elektraIsArrayPart | ( | const char * | namePart | ) |

Checks if the given key name part is an array part.

The return value of this function can safely be treated as a boolean.

Parameters

  namePart | an arbitrary string that shall be checked

Returns
  if `namePart` is an array part, the index of the first digit in `namePart`, or 0 otherwise

## ◆ 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` 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);
keyDel
int keyDel(Key *key)
A destructor for Key objects.
Definition key.c:459
keyNew
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition key.c:144
keyName
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition elektra/keyname.c:429
keyAddBaseName
ssize_t keyAddBaseName(Key *key, const char *baseName)
Adds baseName to the name of key.
Definition elektra/keyname.c:1724

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), ".");
keySetName
ssize_t keySetName(Key *key, const char *newName)
Set a new name to a Key.
Definition elektra/keyname.c:678
keyBaseName
const char * keyBaseName(const Key *key)
Returns a pointer to the unescaped Key's name where the basename starts.
Definition elektra/keyname.c:1394

Parameters

  key | the Key to add the basename to
  baseName | the 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

  -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

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

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

  key | the Key where a name should be added
  newName | the new name to add to the name of `key`

Returns
  new size of the escaped name of `key`

Return values

  -1 | if `key == NULL` or `newName == NULL`
  -1 | `newName` is not a valid escaped name
  -1 | `key` 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

  key | the Key to obtain the basename from

Returns
  a pointer to the Key's basename

Return values

  "" | when the Key has no (base)name
  0 | on 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

  key | the Key to extract basename from
  returned | a pre-allocated buffer for storing the basename
  maxSize | size of the buffer `returned`

Returns
  number of bytes copied to `returned`

Return values

  1 | when Key's name is empty
  -1 | on NULL pointers
  -1 | when maxSize is 0 or larger than SSIZE_MAX
  -1 | when 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

  key | the Key to get the size of the basename from

Returns
  size in bytes of the Key's basename including NULL terminator

Return values

  -1 | if the Key or 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));
keyGetName
ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize)
Get abbreviated Key name (excluding owner).
Definition elektra/keyname.c:562
keyGetNameSize
ssize_t keyGetNameSize(const Key *key)
Bytes needed to store the Key's name (excluding owner).
Definition elektra/keyname.c:457
elektraMalloc
void * elektraMalloc(size_t size)
Allocate memory for Elektra.
Definition internal.c:274

Parameters

  key | the Key to get the name from
  returnedName | pre-allocated buffer to write the Key's name
  maxSize | maximum number of bytes that will fit in returnedName, including the NULL terminator

Returns
  number of bytes written to `returnedName`

Return values

  1 | when only NULL terminator was written
  -1 | when Key's name is longer than maxSize or maxSize is 0 or maxSize is greater than SSIZE_MAX
  -1 | `key` 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

  key | the Key to get the name size from

Returns
  number of bytes needed, including NULL terminator, to store Key's name (excluding owner)

Return values

  1 | if Key has no name
  -1 | on 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))
{
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;
}
KEY_NS_SPEC
@ KEY_NS_SPEC
spec contains the specification of the other namespaces
Definition kdbenum.c:138
KEY_NS_CASCADING
@ KEY_NS_CASCADING
cascading key, starts with /, abstract name for any of the namespaces below
Definition kdbenum.c:136
KEY_NS_NONE
@ KEY_NS_NONE
no key given as parameter to keyGetNamespace()
Definition kdbenum.c:135
KEY_NS_PROC
@ KEY_NS_PROC
proc contains process-specific configuration
Definition kdbenum.c:139
KEY_NS_SYSTEM
@ KEY_NS_SYSTEM
system key is shared for a computer system
Definition kdbenum.c:142
KEY_NS_USER
@ KEY_NS_USER
user key in the home directory of the current user
Definition kdbenum.c:141
KEY_NS_DIR
@ KEY_NS_DIR
dir contains configuration from a specific directory
Definition kdbenum.c:140
KEY_NS_META
@ KEY_NS_META
metakey, i.e. any key name not under other categories
Definition kdbenum.c:137
keyGetNamespace
elektraNamespace keyGetNamespace(const Key *key)
Returns the elektraNamespace for a Key.
Definition elektra/keyname.c:1840

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
elektraNamespace
Elektra currently supported Key namespaces.
Definition kdbenum.c:134

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

  key | the Key to get the namespace from

Returns
  the namespace of the Key

Return values

  KEY_NS_NONE | if 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

  key | the Key to extract the unescaped name from
  returnedName | the buffer to write the unescaped name into
  maxSize | maximum 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

  -1 | Precondition error
  -2 | the 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

  key | the Key where to get the size of the unescaped name from

Returns
  The size of the Key's unescaped name

Return values

  -1 | on NULL pointer
  0 | if 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

  key | the 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
  0 | on 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

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

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

  key | the Key whose basename to set
  baseName | the new basename for the Key

Returns
  the size in bytes of the new key name

Return values

  -1 | if Key is NULL
  -1 | if Key was inserted into KeySet before
  -1 | if Key is read-only
  -1 | on 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

Trailing slashes will be stripped.

On invalid names, the name stays unchanged.

Returns
  size of the new Key name in bytes, including NULL terminator

Return values

  -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

Parameters

  key | the Key whose name to set
  newName | the 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

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

Returns
  the new size in bytes of the Key's namespace

Return values

  -1 | precondition 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

  key | the Key whose unescaped name to get

Returns
  the name in its unescaped form

Return values

  0 | on 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