1Key :: Methods for Making TeLsitbsr(a3r)y FunctionsKMeaynu:a:lMethods for Making Tests(3)
2
3
4

NAME

6       Key :: Methods for Making Tests - Methods to do various tests on Keys.
7
8
9   Functions
10       int keyIsInitialized (const Key *key)
11           Test if key is initialized.
12       int keyNameGetNamespace (const char *keyName)
13           Return the namespace of a key name.
14       int keyGetNamespace (const Key *key)
15           Return the namespace of a key.
16       int keyIsSystem (const Key *key)
17           Check whether a key is under the system namespace or not.
18       int keyIsUser (const Key *key)
19           Check whether a key is under the user namespace or not.
20       int keyIsLink (const Key *key)
21           Check if a key is a link key.
22       int keyIsDir (const Key *key)
23           Check if a key is folder key.
24       int keyIsBin (const Key *key)
25           Check if a key is of some binary type.
26       int keyIsString (const Key *key)
27           Check if a key is of some string type.
28       int keyNeedsSync (const Key *key)
29           Test if the in-memory key object was changed after retrieved from
30           disk.
31       uint32_t keyCompare (const Key *key1, const Key *key2)
32           Compare 2 keys.
33

Detailed Description

35       Methods to do various tests on Keys.
36
37       To use them:
38
39       #include <kdb.h>
40
41

Function Documentation

43   int keyIsInitialized (const Key * key)
44       Test if key is initialized.
45
46       This function is more or less reliable. You'd better guarantee your
47       code is robust enough using keyNew(), keyInit(), keyDel() and
48       keyClose() everytime.
49
50       Definition at line 513 of file key.c.
51
52       References _Key::flags.
53
54   int keyNameGetNamespace (const char * keyName)
55       Return the namespace of a key name.
56
57       Currently valid namespaces are KeyNamespace::KEY_NS_SYSTEM and
58       KeyNamespace::KEY_NS_USER.
59
60       Returns:
61           KeyNamespace::KEY_NS_SYSTEM, KeyNamespace::KEY_NS_USER or 0
62
63       See also:
64           keyGetNamespace(), keyIsUser(), keyIsSystem()
65
66           KeyNamespace
67
68       Definition at line 1064 of file key.c.
69
70       References KEY_NS_SYSTEM, KEY_NS_USER, keyNameIsSystem(), and
71       keyNameIsUser().
72
73   int keyGetNamespace (const Key * key)
74       Return the namespace of a key.
75
76       Currently valid namespaces are KeyNamespace::KEY_NS_SYSTEM and
77       KeyNamespace::KEY_NS_USER.
78
79       Returns:
80           KeyNamespace::KEY_NS_SYSTEM, KeyNamespace::KEY_NS_USER or 0
81
82       See also:
83           keyNameGetNamespace(), keyIsUser(), keyIsSystem()
84
85       Definition at line 1082 of file key.c.
86
87       References _Key::flags, KEY_NS_SYSTEM, KEY_NS_USER,
88       KEY_SWITCH_ISSYSTEM, and KEY_SWITCH_ISUSER.
89
90   int keyIsSystem (const Key * key)
91       Check whether a key is under the system namespace or not.
92
93       Returns:
94           1 if key name begins with system, 0 otherwise
95
96       See also:
97           keyNameIsSystem(), keyIsUser(), keyNameIsUser()
98
99       Definition at line 1114 of file key.c.
100
101       References _Key::flags, and KEY_SWITCH_ISSYSTEM.
102
103   int keyIsUser (const Key * key)
104       Check whether a key is under the user namespace or not.
105
106       Returns:
107           1 if key name begins with user, 0 otherwise
108
109       See also:
110           keyNameIsSystem(), keyIsSystem(), keyNameIsUser()
111
112       Definition at line 1144 of file key.c.
113
114       References _Key::flags, and KEY_SWITCH_ISUSER.
115
116       Referenced by keyGetFullName(), keyGetFullRootName(),
117       keyGetFullRootNameSize(), keyGetRootNameSize(), keyToStreamBasename(),
118       and ksLookupRE().
119
120   int keyIsLink (const Key * key)
121       Check if a key is a link key.
122
123       The value of link keys is the key they point to.
124
125       Returns:
126           1 if key is a link, 0 otherwise
127
128       See also:
129           keyIsDir(), keyGetType()
130
131       Definition at line 1816 of file key.c.
132
133       References KEY_TYPE_LINK, and _Key::type.
134
135       Referenced by listAccess().
136
137   int keyIsDir (const Key * key)
138       Check if a key is folder key.
139
140       Folder keys have no value.
141
142       Returns:
143           1 if key is a folder, 0 otherwise
144
145       See also:
146           keyIsLink(), keyGetType()
147
148       Definition at line 1831 of file key.c.
149
150       References _Key::access.
151
152       Referenced by kdbSetValue(), keyNew(), keyToStreamBasename(), and
153       listAccess().
154
155   int keyIsBin (const Key * key)
156       Check if a key is of some binary type.
157
158       Returns:
159           1 if KEY_TYPE_BINARY  <= type < KEY_TYPE_STRING , 0 otherwise
160
161       See also:
162           keyGetBinary(), keySetBinary()
163
164       Definition at line 1845 of file key.c.
165
166       References KEY_TYPE_STRING, and _Key::type.
167
168       Referenced by commandGet().
169
170   int keyIsString (const Key * key)
171       Check if a key is of some string type.
172
173       Returns:
174           1 if type >= KEY_TYPE_STRING , 0 otherwise
175
176       See also:
177           keyGetString(), keySetString()
178
179       Definition at line 1857 of file key.c.
180
181       References KEY_TYPE_STRING, and _Key::type.
182
183   int keyNeedsSync (const Key * key)
184       Test if the in-memory key object was changed after retrieved from disk.
185
186       All library methods that change Key properties take care of setting a
187       'key is dirty' internal flag, that is checked by this method.
188
189       Returns:
190           1 if key was changed in memory, 0 otherwise.
191
192       Definition at line 1926 of file key.c.
193
194       References _Key::flags, and KEY_SWITCH_NEEDSYNC.
195
196       Referenced by kdbSetKeys_default().
197
198   uint32_t keyCompare (const Key * key1, const Key * key2)
199       Compare 2 keys.
200
201       The returned flags bit array has 1s (differ) or 0s (equal) for each key
202       meta info compared, that can be logically ORed using KeySwitch flags.
203       The flags you can use are KEY_SWITCH_TYPE , KEY_SWITCH_NAME ,
204       KEY_SWITCH_VALUE , KEY_SWITCH_OWNER , KEY_SWITCH_COMMENT ,
205       KEY_SWITCH_UID , KEY_SWITCH_GID , KEY_SWITCH_MODE , KEY_SWITCH_NEEDSYNC
206       and KEY_SWITCH_FLAG .
207
208       A very simple example would be.RS 4
209
210
211       Key *key1, *key;
212       uint32_t changes;
213
214       // omited key1 and key2 initialization and manipulation
215
216       changes=keyCompare(key1,key2);
217
218       if (changes == 0) printf('key1 and key2 are identicall0);
219
220       if (changes & KEY_SWITCH_VALUE)
221           printf('key1 and key2 have different values0);
222
223       if (changes & KEY_SWITCH_UID)
224           printf('key1 and key2 have different UID0);
225
226
227       Returns:
228           a bit array poiting the differences
229
230       See also:
231           ksCompare() for examples and more detailed description
232
233           KeySwitch
234
235       Example of very powerfull specific Key lookup in a KeySet:.RS 4
236
237
238       KeySet *ks=ksNew();
239       Key *base;
240       Key *current;
241       uint32_t match;
242       uint32_t interests;
243
244
245       kdbGetChildKeys(ks,'usr/sw/MyApp',KDB_O_RECURSIVE);
246
247       // assemble a key we'll use to compare our KeySet to
248       base=keyNew('user/sw/MyApp/some/deep/key',
249           KEY_SWITCH_TYPE,KEY_TYPE_LINK,
250           KEY_SWITCH_VALUE,'system/mtp/x',
251           KEY_SWITCH_MODE,0654,
252           KEY_SWITCH_END));
253
254       // we are interested only in key type and access permissions
255       interests=(KEY_SWITCH_TYPE | KEY_SWITCH_MODE);
256
257       ksRewind(ks);   // put cursor in the begining
258       while ((curren=ksNext(ks))) {
259           match=keyCompare(current,base);
260
261           if ((~match & interests) == interests)
262               printf('Key %s has same type and permissions of base key',keyStealName(current));
263
264           // continue walking in the KeySet....
265       }
266
267       // now we want same name and/or value and/or sync status
268       interests=(KEY_SWITCH_NAME | KEY_SWITCH_VALUE | KEY_SWITCH_NEEDSYNC);
269
270       // we don't really need ksRewind(), since previous loop achieved end of KeySet
271       ksRewind(ks);
272       while ((current=ksNext(ks))) {
273           match=keyCompare(current,base);
274
275           if ((~match & interests) == interests) {
276               printf('Key %s has same name, value, and sync status
277                   of base key',keyStealName(current));
278           }
279           // continue walking in the KeySet....
280       }
281
282       keyDel(base);
283       ksDel(ks);
284
285
286       Definition at line 2691 of file key.c.
287
288       References _Key::access, _Key::comment, _Key::data, _Key::dataSize,
289       _Key::flags, _Key::gid, _Key::key, KEY_SWITCH_COMMENT,
290       KEY_SWITCH_DOMAIN, KEY_SWITCH_FLAG, KEY_SWITCH_GID, KEY_SWITCH_MODE,
291       KEY_SWITCH_NAME, KEY_SWITCH_NEEDSYNC, KEY_SWITCH_TYPE, KEY_SWITCH_UID,
292       KEY_SWITCH_VALUE, _Key::type, _Key::uid, and _Key::userDomain.
293
294       Referenced by kdbMonitorKey_default(), and ksCompare().
295
296
297
298Elektra Project                   25 Mar 2007Key :: Methods for Making Tests(3)