.TH "keyname" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
keyname \- Name Manipulation Methods
.PP
Methods to do various operations on Key names\&.  

.SS "Functions"

.in +1c
.ti -1c
.RI "const char * \fBkeyName\fP (const Key *key)"
.br
.RI "\fIReturns a pointer to the abbreviated real internal \fCkey\fP name\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetNameSize\fP (const Key *key)"
.br
.RI "\fIBytes needed to store the key name without owner\&. \fP"
.ti -1c
.RI "const void * \fBkeyUnescapedName\fP (const Key *key)"
.br
.RI "\fIReturns a keyname which is null separated and does not use backslash for escaping\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetUnescapedNameSize\fP (const Key *key)"
.br
.RI "\fIreturn size of unescaped name with embedded and terminating null characters \fP"
.ti -1c
.RI "ssize_t \fBkeyGetName\fP (const Key *key, char *returnedName, size_t maxSize)"
.br
.RI "\fIGet abbreviated key name (without owner name)\&. \fP"
.ti -1c
.RI "ssize_t \fBkeySetName\fP (Key *key, const char *newName)"
.br
.RI "\fISet a new name to a key\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetFullNameSize\fP (const Key *key)"
.br
.RI "\fIBytes needed to store the key name including user domain and ending NULL\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetFullName\fP (const Key *key, char *returnedName, size_t maxSize)"
.br
.RI "\fIGet key full name, including the user domain name\&. \fP"
.ti -1c
.RI "const char * \fBkeyBaseName\fP (const Key *key)"
.br
.RI "\fIReturns a pointer to the internal unescaped key name where the \fCbasename\fP starts\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetBaseNameSize\fP (const Key *key)"
.br
.RI "\fICalculates number of bytes needed to store basename of \fCkey\fP\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetBaseName\fP (const Key *key, char *returned, size_t maxSize)"
.br
.RI "\fICalculate the basename of a key name and put it in \fCreturned\fP finalizing the string with NULL\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyAddBaseName\fP (Key *key, const char *baseName)"
.br
.RI "\fIAdds \fCbaseName\fP (that will be escaped) to the current key name\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyAddName\fP (Key *key, const char *newName)"
.br
.RI "\fIAdd a already escaped name to the keyname\&. \fP"
.ti -1c
.RI "ssize_t \fBkeySetBaseName\fP (Key *key, const char *baseName)"
.br
.RI "\fISets \fCbaseName\fP as the new basename for \fCkey\fP\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
Methods to do various operations on Key names\&. 

To use them: 
.PP
.nf
#include <kdb\&.h>

.fi
.PP
.PP
These functions make it easier for C programmers to work with key names\&.
.PP
\fBTerminology of Key Names\fP
.RS 4

.IP "\(bu" 2
A \fIkey name\fP (see \fBkeySetName()\fP and \fBkeyName()\fP) defines the place of a key within the key database\&. To be unique, it is always absolute and canonical\&.
.IP "\(bu" 2
Key names are composed out of many \fIkey name parts\fP split by a separator\&. These \fIkey name parts\fP do not contain a unescaped separator\&.
.IP "\(bu" 2
A \fIkey base name\fP (see \fBkeySetBaseName()\fP and \fBkeyAddBaseName()\fP) is the last part of the key name\&.
.IP "\(bu" 2
A \fIC-String\fP is a null terminated sequence of characters\&. So \\0 (null-character) must not occur within a C-String\&.
.PP
.RE
.PP
\fBNamespaces\fP
.RS 4
A namespace denotes the place the key comes from:
.RE
.PP
.IP "\(bu" 2
\fCspec/something\fP for specification of other keys\&.
.IP "\(bu" 2
\fCproc/something\fP for in-memory keys, e\&.g\&. commandline\&.
.IP "\(bu" 2
\fCdir/something\fP for dir keys in current working directory
.IP "\(bu" 2
\fCsystem/something\fP for system keys in /etc or /
.IP "\(bu" 2
\fCuser/something\fP for user keys in home directory
.IP "\(bu" 2
\fCuser:username/something\fP for other users (deprecated: \fBkdbGet()\fP + \fBkdbSet()\fP currently unsupported)
.IP "\(bu" 2
\fC/something\fP for cascading keys (actually refers to one of the above, see also \fBksLookup()\fP)
.PP
\fBNote:\fP
.RS 4
The rules are currently not formally specified and are subject of change in the next major release\&. So, always prefer:
.IP "  \(bu" 4
To use \fBkeySetName()\fP and \fBkeyAddName()\fP to get the canonified version of the keyname
.IP "  \(bu" 4
To use \fBkeySetBaseName()\fP and \fBkeyAddBaseName()\fP to get an escaped key name part\&.
.IP "  \(bu" 4
Not to escape or canonify with your own algorithms!
.IP "  \(bu" 4
To use \fBkeyUnescapedName()\fP and \fBkeyBaseName()\fP to have access to the key name without escape sequences (key name parts are null terminated)
.IP "  \(bu" 4
Not to unescape the strings yourself!
.PP
.RE
.PP
\fBSyntax for Key Names\fP
.RS 4
Key names and key name parts have following goals:
.IP "  \(bu" 4
The C-String passed to \fBkeySetName()\fP and \fBkeyAddName()\fP may be any C-String\&.
.IP "  \(bu" 4
The \fIkey name parts\fP (e\&.g\&. \fBkeySetBaseName()\fP, \fBkeyBaseName()\fP) may be any C-String\&. Escaping is needed to achieve both goals\&.
.PP
.RE
.PP
\fBSemantics for Key Name Parts\fP
.RS 4

.IP "  \(bu" 4
% denotes an empty key name part\&.
.PP
.RE
.PP
\fBCanonicalization for Key Names\fP
.RS 4

.IP "  \(bu" 4
/ (slash) is the separator between key name parts\&.
.IP "  \(bu" 4
// is shortened to /
.IP "  \(bu" 4
trailing / (slashes) are removed
.IP "  \(bu" 4
\&. (dot) and \&.\&. (dot-dot) is removed in an canonical key name, with following rules:
.IP "    \(bu" 6
/\&./ is shortened to /
.IP "    \(bu" 6
_/\&.\&./ is shortened to _
.PP

.PP
.RE
.PP
\fBConventions for key names\fP
.RS 4

.IP "  \(bu" 4
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\&.
.IP "  \(bu" 4
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)
.IP "  \(bu" 4
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)
.IP "  \(bu" 4
If any key name part starts with \&. (dot) it means the key is inactive, see \fBkeyIsInactive()\fP\&.
.PP
.RE
.PP
\fBEscaping rules\fP
.RS 4

.IP "  \(bu" 4
\\ (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\&.
.IP "  \(bu" 4
Stray escape characters are only possible in the end of the string\&.
.IP "  \(bu" 4
\\/ allows one to escape / (any uneven number of \\)\&. Does not introduce a new part\&.
.IP "  \(bu" 4
Any uneven number N of \\ before / allows you to escape / with the N/2 of \\ prefixed\&. Does not introduce a new part\&.
.IP "  \(bu" 4
\\\\/ allows one to use \\ as character before / and introduces a new part\&.
.IP "  \(bu" 4
Any even number N of \\ before / allows you to have N/2 of \\ prefixed before a / which introduces a new part\&.
.IP "  \(bu" 4
Use \\\&. and \\\&.\&. if you want your key name part to represent \&. and \&.\&.
.IP "  \(bu" 4
\\\\\&. and \\\\\&.\&. allows us to use \\ as character before \&. and \&.\&. (and so on)
.IP "  \(bu" 4
Use \\% if you want your key name part to start with % (and does not represent an empty name)
.IP "  \(bu" 4
Using \\\\% allows one to use \\ as character before % (and so on)
.PP
.RE
.PP
\fBSemantics for Key Name Specifications\fP
.RS 4

.IP "  \(bu" 4
_ denotes that the key name part is arbitrary (syntax as described above)\&.
.IP "  \(bu" 4
# denotes that the key name part has array syntax\&.
.IP "  \(bu" 4
names surrounded by % (e\&.g\&. %profile%) denotes a placeholder\&.
.PP
.RE
.PP
\fBUsage of Key Names\fP
.RS 4
When using Elektra to store your application's configuration and state, please keep in mind the following rules:
.IP "  \(bu" 4
Avoid to have your applications root right under \fCsystem\fP or \fCuser\fP\&. (rationale: it would make the hierarchy too flat\&.)
.IP "  \(bu" 4
Avoid the usage of characters other then a-z, 0-9 and _\&. (rationale: it would allow too many similar, confusing names\&.) (exceptions: if the user or a technology, decide about parts of the key name, this restriction does not apply, e\&.g\&. if the wlan essid is used as part of the key name)
.IP "  \(bu" 4
It is suggested to make your application look for default keys under \fC/sw/myapp/#/%/\fP where # is a major version number, e\&.g\&. #3 for the 4th version and % is a profile (% for default profile)\&. This way, from a sysadmin perspective, it will be possible to copy the \fCsystem/sw/myapp/#3/%/\fP tree to something like \fCsystem/sw/myapp/#3/old/\fP and keep system clean and organized\&. Additionally, it is possible to start the old version of the app, using \fC/sw/myapp/#2\fP\&. 
.PP
.RE
.PP

.PP

.SH "Function Documentation"
.PP 
.SS "ssize_t keyAddBaseName (Key * key, const char * baseName)"

.PP
Adds \fCbaseName\fP (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\&.
.PP
Assumes that \fCkey\fP is a directory and will append \fCbaseName\fP to it\&. The function adds the path separator for concatenating\&.
.PP
So if \fCkey\fP has name \fC'system/dir1/dir2'\fP and this method is called with \fCbaseName\fP \fC'mykey'\fP, the resulting key will have the name \fC'system/dir1/dir2/mykey'\fP\&.
.PP
When \fCbaseName\fP is 0 nothing will happen and the size of the name is returned\&.
.PP
The escaping rules apply as in \fBabove \fP\&.
.PP
A simple example is: 
.PP
.nf
Key * k = keyNew("user/my/long", KEY_END);
keyAddBaseName(k, "myname");
printf ("%s\n", keyName(k)); // will print user/my/long/myname
keyDel(k);

.fi
.PP
 E\&.g\&. if you add \&. it will be escaped: 
.PP
.nf
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), "\&.");

.fi
.PP
 
.PP
\fBSee also:\fP
.RS 4
\fBkeySetBaseName()\fP to set a base name 
.PP
\fBkeySetName()\fP to set a new name\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.br
\fIbaseName\fP the string to append to the name 
.RE
.PP
\fBReturns:\fP
.RS 4
the size in bytes of the new key name including the ending NULL 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI-1\fP if the key had no name 
.br
\fI-1\fP on NULL pointers 
.br
\fI-1\fP if key was inserted to a keyset before 
.RE
.PP

.SS "ssize_t keyAddName (Key * key, const char * newName)"

.PP
Add a already escaped name to the keyname\&. The same way as in \fBkeySetName()\fP this method finds the canonical pathname:
.IP "\(bu" 2
it will ignore /\&./
.IP "\(bu" 2
it will remove a level when /\&.\&./ is used
.IP "\(bu" 2
it will remove multiple slashes ////
.PP
.PP
For example: 
.PP
.nf
Key *k = keyNew("user/x/r", KEY_END);
keyAddName(k, "\&.\&./y/a//\&./\&./z");
assert(!strcmp(keyName(k), "user/x/y/a/z"));
keyDel(k);

.fi
.PP
 Unlike \fBkeySetName()\fP it adds relative to the previous name and cannot change the namespace of a key\&. For example: 
.PP
.nf
Key *n = keyNew("user/away", KEY_END);
keyAddName(n, "\&.\&./\&.\&./\&.\&./new/name");
assert(!strcmp(keyName(n), "user/new/name"));
keyDel(n);

.fi
.PP
 The passed name needs to be valid according the \fBkey name rules \fP\&. It is not allowed to:
.IP "\(bu" 2
be empty
.IP "\(bu" 2
end with unequal number of \\
.PP
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key where a name should be added 
.br
\fInewName\fP the new name to append
.RE
.PP
\fBSince:\fP
.RS 4
0\&.8\&.11
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIsize\fP of the new key 
.br
\fI-1\fP if key is a null pointer or did not have a valid name before 
.br
\fI-1\fP if newName is not a valid escaped name 
.br
\fI-1\fP on allocation errors 
.br
\fI-1\fP if key was inserted to a keyset before 
.br
\fI0\fP if nothing was done because newName had only slashes, is too short, is empty or is null 
.RE
.PP

.SS "const char* keyBaseName (const Key * key)"

.PP
Returns a pointer to the internal unescaped key name where the \fCbasename\fP starts\&. This is a much more efficient version of \fBkeyGetBaseName()\fP 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 \fBkeySetName()\fP\&. So make sure to copy the memory before the name changes\&.
.PP
\fBkeyBaseName()\fP returns '' when there is no keyBaseName\&. The reason is 
.PP
.nf
keySetName(k,"");
succeed_if_same_string(keyBaseName(k), "");
keySetName(k,"user");
succeed_if_same_string(keyBaseName(k), "");

.fi
.PP
 And there is also support for really empty basenames: 
.PP
.nf
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), "");

.fi
.PP
 
.PP
\fBNote:\fP
.RS 4
You must never use the pointer returned by \fBkeyBaseName()\fP method to change the name, but you should use \fBkeySetBaseName()\fP instead\&.
.PP
Do not assume that \fBkeyBaseName()\fP points to the same region as \fBkeyName()\fP does\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object to obtain the basename from 
.RE
.PP
\fBReturns:\fP
.RS 4
a pointer to the basename 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI''\fP when the key has no (base)name 
.br
\fI0\fP on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetBaseName()\fP, \fBkeyGetBaseNameSize()\fP 
.PP
\fBkeyName()\fP to get a pointer to the name 
.PP
\fBkeyOwner()\fP to get a pointer to the owner 
.RE
.PP

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

.PP
Calculate the basename of a key name and put it in \fCreturned\fP finalizing the string with NULL\&. Some examples:
.IP "\(bu" 2
basename of \fCsystem/some/keyname\fP is \fCkeyname\fP 
.IP "\(bu" 2
basename of \fC'user/tmp/some key'\fP is \fC'some key'\fP 
.PP
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key to extract basename from 
.br
\fIreturned\fP a pre-allocated buffer to store the basename 
.br
\fImaxSize\fP size of the \fCreturned\fP buffer 
.RE
.PP
\fBReturns:\fP
.RS 4
number of bytes copied to \fCreturned\fP 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP on empty name 
.br
\fI-1\fP on NULL pointers 
.br
\fI-1\fP when maxSize is 0 or larger than SSIZE_MAX 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyBaseName()\fP, \fBkeyGetBaseNameSize()\fP 
.PP
\fBkeyName()\fP, \fBkeyGetName()\fP, \fBkeySetName()\fP 
.RE
.PP

.SS "ssize_t keyGetBaseNameSize (const Key * key)"

.PP
Calculates number of bytes needed to store basename of \fCkey\fP\&. Key names that have only root names (e\&.g\&. \fC'system'\fP or \fC'user'\fP or \fC'user:domain'\fP ) does not have basenames, thus the function will return 1 bytes to store ''\&.
.PP
Basenames are denoted as:
.IP "\(bu" 2
\fCsystem/some/thing/basename\fP -> \fCbasename\fP 
.IP "\(bu" 2
\fCuser:domain/some/thing/base\\/name\fP > \fCbase\\/name\fP 
.PP
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
size in bytes of \fCkey's\fP basename including ending NULL 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyBaseName()\fP, \fBkeyGetBaseName()\fP 
.PP
\fBkeyName()\fP, \fBkeyGetName()\fP, \fBkeySetName()\fP 
.RE
.PP

.SS "ssize_t keyGetFullName (const Key * key, char * returnedName, size_t maxSize)"

.PP
Get key full name, including the user domain name\&. 
.PP
\fBReturns:\fP
.RS 4
number of bytes written 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP on empty name 
.br
\fI-1\fP on NULL pointers 
.br
\fI-1\fP if maxSize is 0 or larger than SSIZE_MAX 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object 
.br
\fIreturnedName\fP pre-allocated memory to write the key name 
.br
\fImaxSize\fP maximum number of bytes that will fit in returnedName, including the final NULL 
.RE
.PP

.SS "ssize_t keyGetFullNameSize (const Key * key)"

.PP
Bytes needed to store the key name including user domain and ending NULL\&. 
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
number of bytes needed to store key name including user domain 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP on empty name 
.br
\fI-1\fP on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetFullName()\fP, \fBkeyGetNameSize()\fP 
.RE
.PP

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

.PP
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\&.
.PP
maxSize is limited to SSIZE_MAX\&. When this value is exceeded -1 will be returned\&. The reason for that is that any value higher is just a negative return value passed by accident\&. Of course malloc is not as failure tolerant and will try to allocate\&.
.PP
.PP
.nf
1 char *getBack = malloc (keyGetNameSize(key));
2 keyGetName(key, getBack, keyGetNameSize(key));
.fi
.PP
.PP
\fBReturns:\fP
.RS 4
number of bytes written to \fCreturnedName\fP 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP when only a null was written 
.br
\fI-1\fP when keyname is longer then maxSize or 0 or any NULL pointer 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.br
\fIreturnedName\fP pre-allocated memory to write the key name 
.br
\fImaxSize\fP maximum number of bytes that will fit in returnedName, including the final NULL 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetNameSize()\fP, \fBkeyGetFullName()\fP, \fBkeyGetFullNameSize()\fP 
.RE
.PP

.SS "ssize_t keyGetNameSize (const Key * key)"

.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
number of bytes needed, including ending NULL, to store key name without owner 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP if there is is no key Name 
.br
\fI-1\fP on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetName()\fP, \fBkeyGetFullNameSize()\fP 
.PP
\fBkeyGetUnescapedNameSize\fP to get size of unescaped name 
.RE
.PP

.SS "ssize_t keyGetUnescapedNameSize (const Key * key)"

.PP
return size of unescaped name with embedded and terminating null characters 
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object to work with
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyUnescapedName()\fP 
.PP
\fBkeyGetNameSize()\fP for size of escaped variant 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI-1\fP on null pointer 
.br
\fI0\fP if no name 
.RE
.PP

.SS "const char* keyName (const Key * key)"

.PP
Returns a pointer to the abbreviated real internal \fCkey\fP name\&. This is a much more efficient version of \fBkeyGetName()\fP 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 \fBkeySetName()\fP and similar functions\&. If you need a copy of the name, consider using \fBkeyGetName()\fP\&.
.PP
The name will be without owner, see \fBkeyGetFullName()\fP if you need the name with its owner\&.
.PP
\fBReturn values:\fP
.RS 4
\fI''\fP when there is no keyName\&. The reason is 
.PP
.nf
1 key=keyNew(0);
2 keySetName(key,"");
3 keyName(key); // you would expect "" here
4 keyDel(key);

.fi
.PP
.RE
.PP
Valid key names are:
.PP
.IP "\(bu" 2
\fCspec/something\fP for specification of other keys\&.
.IP "\(bu" 2
\fCproc/something\fP for in-memory keys, e\&.g\&. commandline\&.
.IP "\(bu" 2
\fCdir/something\fP for dir keys in current working directory
.IP "\(bu" 2
\fCsystem/something\fP for system keys in /etc or /
.IP "\(bu" 2
\fCuser/something\fP for user keys in home directory
.IP "\(bu" 2
\fCuser:username/something\fP for other users (deprecated: \fBkdbGet()\fP + \fBkdbSet()\fP currently unsupported)
.IP "\(bu" 2
\fC/something\fP for cascading keys (actually refers to one of the above, see also \fBksLookup()\fP)
.PP
\fBNote:\fP
.RS 4
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 \fBkeyName()\fP method to set a new value\&. Use \fBkeySetName()\fP instead\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
a pointer to the keyname which must not be changed\&. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI''\fP when there is no (a empty) keyname 
.br
\fI0\fP on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetNameSize()\fP for the string length 
.PP
\fBkeyGetFullName()\fP, \fBkeyGetFullNameSize()\fP to get the full name 
.PP
\fBkeyGetName()\fP as alternative to get a copy 
.PP
\fBkeyOwner()\fP to get a pointer to owner 
.PP
\fBkeyUnescapedName\fP to get an unescaped \fBKey\fP name 
.RE
.PP

.PP

.SS "ssize_t keySetBaseName (Key * key, const char * baseName)"

.PP
Sets \fCbaseName\fP as the new basename for \fCkey\fP\&. Only the baseName will be affected and no other part of the key\&.
.PP
All text after the last \fC'/'\fP in the \fCkey\fP keyname is erased and \fCbaseName\fP is appended\&.
.PP
So let us suppose \fCkey\fP has name \fC'system/dir1/dir2/key1'\fP\&. If \fCbaseName\fP is \fC'key2'\fP, the resulting key name will be \fC'system/dir1/dir2/key2'\fP\&. If \fCbaseName\fP is empty or NULL, the resulting key name will be \fC'system/dir1/dir2'\fP\&.
.PP
This function does proper escaping on the supplied name argument\&.
.PP
You can use all names to set as basename (e\&.g\&. \&. (dot), \&.\&. (dot-dot), % and '' (empty))\&. They will be properly escaped\&.
.PP
A simple example is: 
.PP
.nf
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);

.fi
.PP
 If you want to add and not change the basename, use \fBkeyAddBaseName()\fP instead\&. If you do not want escaping, use \fBkeyAddName()\fP instead\&.
.PP
To add an inactive key name, use: 
.PP
.nf
        keySetName (k, "system/valid");
        keySetBaseName(k, "\&.hiddenkey");
        succeed_if_same_string(keyName(k), "system/\&.hiddenkey");
        succeed_if_same_string(keyBaseName(k), "\&.hiddenkey");

.fi
.PP
 When you want to add an array item, use: 
.PP
.nf
        keySetName (k, "system/valid");
        keySetBaseName(k, "");
        succeed_if_same_string(keyName(k), "system/%");
        succeed_if_same_string(keyBaseName(k), "");

.fi
.PP
 
.PP
\fBSee also:\fP
.RS 4
\fBName Manipulation Methods\fP for more details on special names
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.br
\fIbaseName\fP the string used to overwrite the basename of the key 
.RE
.PP
\fBReturns:\fP
.RS 4
the size in bytes of the new key name 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI-1\fP on NULL pointers 
.br
\fI-1\fP if key was inserted to a keyset before 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyAddBaseName()\fP 
.PP
\fBkeySetName()\fP to set a new name 
.RE
.PP

.SS "ssize_t keySetName (Key * key, const char * newName)"

.PP
Set a new name to a key\&. A valid name is one of the forms:
.IP "\(bu" 2
\fCspec/something\fP for specification of other keys\&.
.IP "\(bu" 2
\fCproc/something\fP for in-memory keys, e\&.g\&. commandline\&.
.IP "\(bu" 2
\fCdir/something\fP for dir keys in current working directory
.IP "\(bu" 2
\fCsystem/something\fP for system keys in /etc or /
.IP "\(bu" 2
\fCuser/something\fP for user keys in home directory
.IP "\(bu" 2
\fCuser:username/something\fP for other users (deprecated: \fBkdbGet()\fP + \fBkdbSet()\fP currently unsupported)
.IP "\(bu" 2
\fC/something\fP for cascading keys (actually refers to one of the above, see also \fBksLookup()\fP)
.PP
.PP
An invalid name either has an invalid namespace or a wrongly escaped \\ at the end of the name\&.
.PP
See \fBkey names \fP for the exact rules\&.
.PP
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\&.
.PP
You should always follow the guidelines for key tree structure creation\&.
.PP
A private copy of the key name will be stored, and the \fCnewName\fP parameter can be freed after this call\&.
.PP
\&.\&., \&. and / will be handled as in filesystem pathes\&. A valid name will be build out of the (valid) name what you pass, e\&.g\&. user///sw/\&.\&./sw//\&./\&./MyApp -> user/sw/MyApp
.PP
On invalid names, NULL or '' the name will be '' afterwards\&.
.PP
\fBReturn values:\fP
.RS 4
\fIsize\fP in bytes of this new key name including ending NULL 
.br
\fI0\fP if newName is an empty string or a NULL pointer (name will be empty afterwards) 
.br
\fI-1\fP if newName is invalid (name will be empty afterwards) 
.br
\fI-1\fP if key was inserted to a keyset before 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.br
\fInewName\fP the new key name 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyNew()\fP, \fBkeySetOwner()\fP 
.PP
\fBkeyGetName()\fP, \fBkeyGetFullName()\fP, \fBkeyName()\fP 
.PP
\fBkeySetBaseName()\fP, \fBkeyAddBaseName()\fP to manipulate a name 
.RE
.PP

.SS "const void* keyUnescapedName (const Key * key)"

.PP
Returns a keyname which is null separated and does not use backslash for escaping\&. 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object to work with
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetUnescapedNameSize()\fP 
.PP
\fBkeyName()\fP for escaped variant 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP on null pointers 
.br
\fI''\fP if no name 
.RE
.PP
\fBReturns:\fP
.RS 4
the name in its unescaped form 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Elektra from the source code\&.