\hypertarget{group__keytest}{
\section{Key :: Methods for Making Tests}
\label{group__keytest}\index{Key :: Methods for Making Tests@{Key :: Methods for Making Tests}}
}


Methods to do various tests on Keys.  


\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp} (const \hyperlink{struct__Key}{Key} $\ast$k1, const \hyperlink{struct__Key}{Key} $\ast$k2)
\item 
int \hyperlink{group__keytest_ga6a994eebd4b1c253d4912fa80df16506}{keyClearSync} (\hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{keyNeedSync} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_gafe49cfb61c2accb3073131c23a56fb14}{keyIsSystem} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_ga373acc20c6209357045891f4b0c70041}{keyIsUser} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{keyIsBelow} (const \hyperlink{struct__Key}{Key} $\ast$key, const \hyperlink{struct__Key}{Key} $\ast$check)
\item 
int \hyperlink{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{keyIsDirectBelow} (const \hyperlink{struct__Key}{Key} $\ast$key, const \hyperlink{struct__Key}{Key} $\ast$check)
\item 
int \hyperlink{group__keytest_ga6bb0f95ac34ce9c42d61bb35a76139d0}{keyRel} (const \hyperlink{struct__Key}{Key} $\ast$key, const \hyperlink{struct__Key}{Key} $\ast$check)
\item 
int \hyperlink{group__keytest_gaa25f699f592031c1a0abc1504d14e13e}{keyIsInactive} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{keyIsDir} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_ga9526b371087564e43e3dff8ad0dac949}{keyIsBinary} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
int \hyperlink{group__keytest_gaea7670778abd07fee0fe8ac12a149190}{keyIsString} (const \hyperlink{struct__Key}{Key} $\ast$key)
\item 
\hyperlink{group__key_ga91fb3178848bd682000958089abbaf40}{keyswitch\_\-t} \hyperlink{group__keytest_gab98168409d302fdb65692f6e26f17945}{keyCompare} (const \hyperlink{struct__Key}{Key} $\ast$key1, const \hyperlink{struct__Key}{Key} $\ast$key2)
\end{DoxyCompactItemize}


\subsection{Detailed Description}
Methods to do various tests on Keys. To use them: 
\begin{DoxyCode}
#include <kdb.h>
\end{DoxyCode}
 

\subsection{Function Documentation}
\hypertarget{group__keytest_ga6a994eebd4b1c253d4912fa80df16506}{
\index{keytest@{keytest}!keyClearSync@{keyClearSync}}
\index{keyClearSync@{keyClearSync}!keytest@{keytest}}
\subsubsection[{keyClearSync}]{\setlength{\rightskip}{0pt plus 5cm}int keyClearSync (
\begin{DoxyParamCaption}
\item[{{\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga6a994eebd4b1c253d4912fa80df16506}
Clear flags of a key.

\begin{Desc}
\item[\hyperlink{todo__todo000001}{Todo}]Should be done only in \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} part of plugins.\end{Desc}


If you want to get the current flags, just call it with semiflag set to 0.


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
-\/1 on null key 

new flags for that key otherwise 
\end{DoxyReturn}
\hypertarget{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{
\index{keytest@{keytest}!keyCmp@{keyCmp}}
\index{keyCmp@{keyCmp}!keytest@{keytest}}
\subsubsection[{keyCmp}]{\setlength{\rightskip}{0pt plus 5cm}int keyCmp (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ k1, }
\item[{const {\bf Key} $\ast$}]{ k2}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}
Compare two keys.

\begin{DoxyReturn}{Returns}
a number less than, equal to or greater than zero if k1 is found, respectively, to be less than, to match, or be greater than k2.
\end{DoxyReturn}
The comparison is based on a strcmp of the keynames, and iff they match a strcmp of the owner will be used to distuingish. If even this matches the keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.

\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp()} defines the sorting order for a KeySet.

The following 3 points are the rules for null values. They only take account when none of the preceding rules matched.


\begin{DoxyItemize}
\item A null pointer will be found to be smaller than every other key. If both are null pointers, 0 is returned.
\end{DoxyItemize}


\begin{DoxyItemize}
\item A null name will be found to be smaller than every other name. If both are null names, 0 is returned.
\end{DoxyItemize}


\begin{DoxyItemize}
\item No owner will be found to be smaller then every other owner. If both don't have a owner, 0 is returned.
\end{DoxyItemize}

\begin{DoxyNote}{Note}
the owner will only be used if the names are equal.
\end{DoxyNote}
Often is enough to know if the other key is less then or greater then the other one. But Sometimes you need more precise information, see \hyperlink{group__keytest_ga6bb0f95ac34ce9c42d61bb35a76139d0}{keyRel()}.

Given any Keys k1 and k2 constructed with \hyperlink{group__key_gaf6893c038b3ebee90c73a9ea8356bebf}{keyNew()}, following equation hold true:


\begin{DoxyCode}
// keyCmp(0,0) == 0
// keyCmp(k1,0) ==  1
// keyCmp(0,k2) == -1
\end{DoxyCode}


You can write similar equation for the other rules.

Here are some more examples with equation: 
\begin{DoxyCode}
Key *k1 = keyNew("user/a", KEY_END);
Key *k2 = keyNew("user/b", KEY_END);

// keyCmp(k1,k2) < 0
// keyCmp(k2,k1) > 0
\end{DoxyCode}



\begin{DoxyCode}
Key *k1 = keyNew("user/a", KEY_OWNER, "markus", KEY_END);
Key *k2 = keyNew("user/a", KEY_OWNER, "max", KEY_END);

// keyCmp(k1,k2) < 0
// keyCmp(k2,k1) > 0
\end{DoxyCode}


\begin{DoxyWarning}{Warning}
Do not try to strcmp the \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} yourself because the used strcmp implementation is allowed to differ from simple ascii comparison.
\end{DoxyWarning}

\begin{DoxyParams}{Parameters}
\item[{\em k1}]the first key object to compare with \item[{\em k2}]the second key object to compare with\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey()}, \hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ksAppend()} will compare keys when appending 

\hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ksLookup()} will compare keys during searching 
\end{DoxySeeAlso}
\hypertarget{group__keytest_gab98168409d302fdb65692f6e26f17945}{
\index{keytest@{keytest}!keyCompare@{keyCompare}}
\index{keyCompare@{keyCompare}!keytest@{keytest}}
\subsubsection[{keyCompare}]{\setlength{\rightskip}{0pt plus 5cm}{\bf keyswitch\_\-t} keyCompare (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key1, }
\item[{const {\bf Key} $\ast$}]{ key2}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gab98168409d302fdb65692f6e26f17945}
Compare 2 keys.

The returned flags bit array has 1s (differ) or 0s (equal) for each key meta info compared, that can be logically ORed using {\ttfamily \hyperlink{group__key_ga91fb3178848bd682000958089abbaf40}{keyswitch\_\-t}} flags. \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ad6127fc38f96410bf7c8f6e93b0397da}{KEY\_\-NAME }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_\-VALUE }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a77ca60362fa8daca8d5347db4385068b}{KEY\_\-OWNER }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac29427bb47cc31689d02912e36161ee3}{KEY\_\-COMMENT }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a28f01a87d65f065172f734c9c9446c0e}{KEY\_\-UID }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac0628bbaba7c837ca73323681393d15f}{KEY\_\-GID }, \hyperlink{group__key_gga91fb3178848bd682000958089abbaf40a1b0a91ff3a855d6993930ebf0abaa518}{KEY\_\-MODE } and

\begin{DoxyParagraph}{A very simple example would be}

\begin{DoxyCode}
Key *key1, *key;
uint32_t changes;

// omited key1 and key2 initialization and manipulation

changes=keyCompare(key1,key2);

if (changes == 0) printf("key1 and key2 are identicall\n");

if (changes & KEY_VALUE)
        printf("key1 and key2 have different values\n");
 
if (changes & KEY_UID)
        printf("key1 and key2 have different UID\n");
\end{DoxyCode}

\end{DoxyParagraph}
\begin{DoxyParagraph}{Example of very powerful specific Key lookup in a KeySet:}

\begin{DoxyCode}
KDB *handle = kdbOpen();
KeySet *ks=ksNew(0);
Key *base = keyNew ("user/sw/MyApp/something", KEY_END);
Key *current;
uint32_t match;
uint32_t interests;


kdbGetByName(handle, ks, "user/sw/MyApp", 0);

// we are interested only in key type and access permissions
interests=(KEY_TYPE | KEY_MODE);

ksRewind(ks);   // put cursor in the begining
while ((curren=ksNext(ks))) {
        match=keyCompare(current,base);
        
        if ((~match & interests) == interests)
                printf("Key %s has same type and permissions of base key",
      keyName(current));

        // continue walking in the KeySet....
}

// now we want same name and/or value
interests=(KEY_NAME | KEY_VALUE);

// we don't really need ksRewind(), since previous loop achieved end of KeySet
ksRewind(ks);
while ((current=ksNext(ks))) {
        match=keyCompare(current,base);

        if ((~match & interests) == interests) {
                printf("Key %s has same name, value, and sync status
                        of base key",keyName(current));
        }
        // continue walking in the KeySet....
}

keyDel(base);
ksDel(ks);
kdbClose (handle);
\end{DoxyCode}

\end{DoxyParagraph}
\begin{DoxyReturn}{Returns}
a bit array pointing the differences 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em key1}]first key \item[{\em key2}]second key \end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__key_ga91fb3178848bd682000958089abbaf40}{keyswitch\_\-t} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{
\index{keytest@{keytest}!keyIsBelow@{keyIsBelow}}
\index{keyIsBelow@{keyIsBelow}!keytest@{keytest}}
\subsubsection[{keyIsBelow}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsBelow (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{const {\bf Key} $\ast$}]{ check}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}
Check if the key check is below the key key or not.

Example: \begin{DoxyVerb}
key user/sw/app
check user/sw/app/key
\end{DoxyVerb}


returns true because check is below key

Example: \begin{DoxyVerb}
key user/sw/app
check user/sw/app/folder/key
\end{DoxyVerb}


returns also true because check is indirect below key


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em check}]the key to find the relative position of \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if check is below key 

0 if it is not below or if it is the same key 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()}, \hyperlink{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{keyIsDirectBelow()} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_ga9526b371087564e43e3dff8ad0dac949}{
\index{keytest@{keytest}!keyIsBinary@{keyIsBinary}}
\index{keyIsBinary@{keyIsBinary}!keytest@{keytest}}
\subsubsection[{keyIsBinary}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsBinary (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga9526b371087564e43e3dff8ad0dac949}
Check if a key is binary type.

The function checks if the key is a binary. Opposed to string values binary values can have '$\backslash$0' inside the value and may not be terminated by a null character. Their disadvantage is that you need to pass their size.

Make sure to use this function and don't test the binary type another way to ensure compatibility and to write less error prone programs.

\begin{DoxyReturn}{Returns}
1 if it is binary 

0 if it is not 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyvalue_ga4c0d8a4a11174197699c231e0b5c3c84}{keyGetBinary()}, \hyperlink{group__keyvalue_gaa50a5358fd328d373a45f395fa1b99e7}{keySetBinary()} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key to check \end{DoxyParams}
\hypertarget{group__keytest_gac0a10c602d52a35f81347e8a32312017}{
\index{keytest@{keytest}!keyIsDir@{keyIsDir}}
\index{keyIsDir@{keyIsDir}!keytest@{keytest}}
\subsubsection[{keyIsDir}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsDir (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gac0a10c602d52a35f81347e8a32312017}
Check if the mode for the key has access privileges.

In the filesys backend a key represented through a file has the mode 664, but a key represented through a folder 775. \hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{keyIsDir()} checks if all 3 executeable bits are set.

If any executable bit is set it will be recognized as a directory.

\begin{DoxyNote}{Note}
keyIsDir may return true even though you can't access the directory.
\end{DoxyNote}
To know if you can access the directory, you need to check, if your
\begin{DoxyItemize}
\item user ID is equal the key's user ID and the mode \& 100 is true
\item group ID is equal the key's group ID and the mode \& 010 is true
\item mode \& 001 is true
\end{DoxyItemize}

Accessing does not mean that you can get any value or comments below, see \hyperlink{group__keymeta_mode}{Modes} for more information.

\begin{DoxyNote}{Note}
currently mountpoints can only where \hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{keyIsDir()} is true (0.7.0) but this is likely to change.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if key is a directory, 0 otherwise 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keymeta_gaae575bd86a628a15ee45baa860522e75}{keySetDir()}, \hyperlink{group__keymeta_ga8803037e35b9da1ce492323a88ff6bc3}{keySetMode()} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{
\index{keytest@{keytest}!keyIsDirectBelow@{keyIsDirectBelow}}
\index{keyIsDirectBelow@{keyIsDirectBelow}!keytest@{keytest}}
\subsubsection[{keyIsDirectBelow}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsDirectBelow (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{const {\bf Key} $\ast$}]{ check}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}
Check if the key check is direct below the key key or not.

\begin{DoxyVerb}
Example:
key user/sw/app
check user/sw/app/key

returns true because check is below key

Example:
key user/sw/app
check user/sw/app/folder/key

does not return true, because there is only a indirect relation
\end{DoxyVerb}



\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em check}]the key to find the relative position of \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if check is below key 

0 if it is not below or if it is the same key 

-\/1 on null pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{keyIsBelow()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()}, \hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{keyGetName()} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_gaa25f699f592031c1a0abc1504d14e13e}{
\index{keytest@{keytest}!keyIsInactive@{keyIsInactive}}
\index{keyIsInactive@{keyIsInactive}!keytest@{keytest}}
\subsubsection[{keyIsInactive}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsInactive (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gaa25f699f592031c1a0abc1504d14e13e}
Check whether a key is inactive or not.

In elektra terminology any key is inactive if the it's basename starts with '.'. Inactive keys must not have any meaning to applications, they are reserved for users and administrators.

To remove a whole hierarchy in elektra, don't forget to pass option\_\-t::KDB\_\-O\_\-INACTIVE to \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} to receive the inactive keys in order to remove them.

Otherwise you should not fetch these keys.


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if the key is inactive, 0 otherwise 

-\/1 on NULL pointer or when key has no name 
\end{DoxyReturn}
\hypertarget{group__keytest_gaea7670778abd07fee0fe8ac12a149190}{
\index{keytest@{keytest}!keyIsString@{keyIsString}}
\index{keyIsString@{keyIsString}!keytest@{keytest}}
\subsubsection[{keyIsString}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsString (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gaea7670778abd07fee0fe8ac12a149190}
Check if a key is string type.

String values are null terminated and are not allowed to have any '$\backslash$0' characters inside the string.

Make sure to use this function and don't test the string type another way to ensure compatibility and to write less error prone programs.

\begin{DoxyReturn}{Returns}
1 if it is string 

0 if it is not 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keyvalue_ga41b9fac5ccddafe407fc0ae1e2eb8778}{keyGetString()}, \hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{keySetString()} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key to check \end{DoxyParams}
\hypertarget{group__keytest_gafe49cfb61c2accb3073131c23a56fb14}{
\index{keytest@{keytest}!keyIsSystem@{keyIsSystem}}
\index{keyIsSystem@{keyIsSystem}!keytest@{keytest}}
\subsubsection[{keyIsSystem}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsSystem (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gafe49cfb61c2accb3073131c23a56fb14}
Check whether a key is under the {\ttfamily system} namespace or not


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if key name begins with {\ttfamily system}, 0 otherwise 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keytest_ga373acc20c6209357045891f4b0c70041}{keyIsUser()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_ga373acc20c6209357045891f4b0c70041}{
\index{keytest@{keytest}!keyIsUser@{keyIsUser}}
\index{keyIsUser@{keyIsUser}!keytest@{keytest}}
\subsubsection[{keyIsUser}]{\setlength{\rightskip}{0pt plus 5cm}int keyIsUser (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga373acc20c6209357045891f4b0c70041}
Check whether a key is under the {\ttfamily user} namespace or not.


\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if key name begins with {\ttfamily user}, 0 otherwise 

-\/1 on NULL pointer 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__keytest_gafe49cfb61c2accb3073131c23a56fb14}{keyIsSystem()}, \hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{keySetName()}, \hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName()} 
\end{DoxySeeAlso}
\hypertarget{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{
\index{keytest@{keytest}!keyNeedSync@{keyNeedSync}}
\index{keyNeedSync@{keyNeedSync}!keytest@{keytest}}
\subsubsection[{keyNeedSync}]{\setlength{\rightskip}{0pt plus 5cm}int keyNeedSync (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key}
\end{DoxyParamCaption}
)}}
\label{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}
Test if a key needs to be synced to backend storage.

If any key modification took place the key will be flagged with KEY\_\-FLAG\_\-SYNC so that \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet()} knows which keys were modified and which not.

After \hyperlink{group__key_gaf6893c038b3ebee90c73a9ea8356bebf}{keyNew()} the flag will normally be set, but after \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} and \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet()} the flag will be removed. When you modify the key the flag will be set again.

In your application you can make use of that flag to know if you changed something in a key after a \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} or \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet()}.

\begin{DoxyNote}{Note}
Note that also changes in the meta data will set that flag.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__key_gaf6893c038b3ebee90c73a9ea8356bebf}{keyNew()} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 if {\ttfamily key} was changed in memory, 0 otherwise 

-\/1 on NULL pointer 
\end{DoxyReturn}
\hypertarget{group__keytest_ga6bb0f95ac34ce9c42d61bb35a76139d0}{
\index{keytest@{keytest}!keyRel@{keyRel}}
\index{keyRel@{keyRel}!keytest@{keytest}}
\subsubsection[{keyRel}]{\setlength{\rightskip}{0pt plus 5cm}int keyRel (
\begin{DoxyParamCaption}
\item[{const {\bf Key} $\ast$}]{ key, }
\item[{const {\bf Key} $\ast$}]{ check}
\end{DoxyParamCaption}
)}}
\label{group__keytest_ga6bb0f95ac34ce9c42d61bb35a76139d0}
Information about the relation in the hierarchy between two keys.

Unlike \hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp()} the number gives information about hierarchical information.


\begin{DoxyItemize}
\item If the keys are the same 0 is returned. So it is the key itself. \begin{DoxyVerb}
user/key
user/key
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyCode}
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder");
succeed_if (keyRel (key, check) == 0, "should be same");
 *
\end{DoxyCode}


\begin{DoxyNote}{Note}
this relation can be checked with \hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp()} too.
\end{DoxyNote}

\begin{DoxyItemize}
\item If the key is direct below the other one 1 is returned. That means that, in terms of hierarchy, no other key is between them -\/ it is a direct child. \begin{DoxyVerb}
user/key/folder
user/key/folder/child
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyCode}
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder/child");
succeed_if (keyRel (key, check) == 1, "should be direct below");
 *
\end{DoxyCode}



\begin{DoxyItemize}
\item If the key is below the other one, but not directly 2 is returned. This is also called grand-\/child. \begin{DoxyVerb}
user/key/folder
user/key/folder/any/depth/deeper/grand-child
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyCode}
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder/any/depth/deeper/grand-child");
succeed_if (keyRel (key, check) >= 2, "should be below (but not direct)");
succeed_if (keyRel (key, check) > 0, "should be below");
succeed_if (keyRel (key, check) >= 0, "should be the same or below");
 *
\end{DoxyCode}



\begin{DoxyItemize}
\item If a invalid or null ptr key is passed, -\/1 is returned
\end{DoxyItemize}


\begin{DoxyItemize}
\item If the keys have no relations, but are not invalid, -\/2 is returned.
\end{DoxyItemize}


\begin{DoxyItemize}
\item If the keys are in the same hierarchy, a value smaller then -\/2 is returned. It means that the key is not below. \begin{DoxyVerb}
user/key/myself
user/key/sibling
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyCode}
keySetName (key, "user/key/folder");
keySetName (check, "user/notsame/folder");
succeed_if (keyRel (key, check) < -2, "key is not below, but same namespace");
\end{DoxyCode}



\begin{DoxyCode}
\end{DoxyCode}


TODO Below is an idea how it could be extended: It could continue the search into the other direction if any (grand-\/)parents are equal.


\begin{DoxyItemize}
\item If the keys are direct below a key which is next to the key, -\/2 is returned. This is also called nephew. (TODO not implemented) \begin{DoxyVerb}
user/key/myself
user/key/sibling
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyItemize}
\item If the keys are direct below a key which is next to the key, -\/2 is returned. This is also called nephew. (TODO not implemented) \begin{DoxyVerb}
user/key/myself
user/key/sibling/nephew
\end{DoxyVerb}

\end{DoxyItemize}


\begin{DoxyItemize}
\item If the keys are below a key which is next to the key, -\/3 is returned. This is also called grand-\/nephew. (TODO not implemented) \begin{DoxyVerb}
user/key/myself
user/key/sibling/any/depth/deeper/grand-nephew
\end{DoxyVerb}

\end{DoxyItemize}

The same holds true for the other direction, but with negative values. For no relation INT\_\-MIN is returned.

\begin{DoxyNote}{Note}
to check if the keys are the same, you must use \hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp()} == 0! \hyperlink{group__keytest_ga6bb0f95ac34ce9c42d61bb35a76139d0}{keyRel()} does not give you the information if it did not find a relation or if it is the same key.
\end{DoxyNote}
\begin{DoxyReturn}{Returns}
dependend on the relation: 2.. if below 1.. if direct below 0.. if the same -\/1.. on null or invalid keys -\/2.. if none of any other relation -\/3.. if same hierarchy (none of those below) -\/4.. if sibling (in same hierarchy) -\/5.. if nephew (in same hierarchy)
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em key}]the key object to work with \item[{\em check}]the second key object to check the relation with \end{DoxyParams}
