1 .TH "Key :: Basic Methods" 3 "30 Jun 2009" "Elektra Projekt" \" -*- nroff -*-
5 Key :: Basic Methods \- Key construction and initialization methods.
12 .RI "Key * \fBkeyNew\fP (const char *keyName,...)"
15 .RI "Key * \fBkeyDup\fP (const Key *source)"
18 .RI "int \fBkeyCopy\fP (Key *dest, const Key *source)"
21 .RI "int \fBkeyDel\fP (Key *key)"
24 .RI "ssize_t \fBkeyIncRef\fP (Key *key)"
27 .RI "ssize_t \fBkeyDecRef\fP (Key *key)"
30 .RI "ssize_t \fBkeyGetRef\fP (const Key *key)"
33 .SH "Detailed Description"
35 Key construction and initialization methods.
45 A Key is the essential class that encapsulates key \fBname \fP, \fBvalue \fP and \fBmetainfo \fP. Key properties are:
57 \fBUID, GID and filesystem-like mode permissions \fP
59 \fBMode, change and modification times \fP
62 Described here the methods to allocate and free the key.
63 .SH "Function Documentation"
65 .SS "int keyCopy (Key * dest, const Key * source)"
69 Most often you may prefer \fBkeyDup()\fP which allocates a new key and returns a duplication of another key.
71 But when you need to copy into an existing key, e.g. because it was passed by a pointer in a function you can do so:
79 // the caller will see the changed key k
84 The reference counter will not change for the destination key. Affiliation to keysets are also not affected.
86 When you pass a NULL-pointer as source the data of dest will be cleaned completely and you get a fresh dest key.
93 // k is now an empty and fresh key
100 \fIdest\fP the key which will be written to
102 \fIsource\fP the key which should be copied or NULL to clean the destination key
107 -1 on failure when a NULL pointer was passed for dest or a dynamic property could not be written.
109 0 when dest was cleaned
111 1 when source was successfully copied
116 \fBkeyDup()\fP to get a duplication of a \fBKey :: Basic Methods\fP
120 .SS "ssize_t keyDecRef (Key * key)"
122 Decrement the viability of a key object.
124 The reference counter can't be decremented once it reached 0. In that situation nothing will happen and 0 will be returned.
128 the value of the new reference counter
132 0 when the key is ready to be freed
137 \fIkey\fP the key object to work with
142 \fBkeyGetRef()\fP, \fBkeyDel()\fP, \fBkeyIncRef()\fP
146 .SS "int keyDel (Key * key)"
148 A destructor for Key objects.
150 Every key created by \fBkeyNew()\fP must be deleted with \fBkeyDel()\fP.
152 It is save to delete keys which are in a keyset, the number of references will be returned then.
154 It is save to delete a nullpointer, -1 will be returned then.
158 \fIkey\fP the key object to delete
163 \fBkeyNew()\fP, keyInc(), \fBkeyGetRef()\fP
168 the value of the reference counter if the key is within keyset(s)
170 0 when the key was freed
176 .SS "Key* keyDup (const Key * source)"
178 Return a duplicate of a key.
180 Memory will be allocated as needed for dynamic properties.
182 The new key will not be member of any KeySet and will start with a new reference counter at 0. A subsequent \fBkeyDel()\fP will delete the key.
186 int f (const Key * source)
188 Key * dup = keyDup (source);
189 // work with duplicate
191 // everything related to dup is freed
192 // and source is unchanged
197 Like for a new key after \fBkeyNew()\fP a subsequent \fBksAppend()\fP makes a KeySet to take care of the lifecycle of the key.
201 int g (const Key * source, KeySet * ks)
203 Key * dup = keyDup (source);
204 // work with duplicate
205 ksAppendKey (ks, dup);
206 // ksDel(ks) will also free the duplicate
207 // source remains unchanged.
212 Duplication of keys should be preferred to \fBkeyNew()\fP, because data like owner can be filled with a copy of the key instead of asking the environment. It can also be optimized in the checks, because the keyname is known to be valid.
216 \fIsource\fP has to be an initializised source Key
221 0 failure or on NULL pointer
223 a fully copy of source on success
228 \fBksAppend()\fP, \fBkeyDel()\fP
230 keyClear(), \fBkeyNew()\fP
234 .SS "ssize_t keyGetRef (const Key * key)"
236 Return how many references the key has.
238 The references will be incremented when \fBksAppendKey()\fP or \fBksAppend()\fP uses the key and will be decremented when \fBksPop()\fP is used.
240 \fBkeyDup()\fP will reset the references for dupped key.
242 For your own applications you can use \fBkeyIncRef()\fP and keyDelRef() for reference counting. Keys with zero references will be deleted when using \fBkeyDel()\fP.
246 \fIkey\fP the key object to work with
251 the number of references
258 \fBkeyIncRef()\fP and \fBkeyDecRef()\fP
262 .SS "ssize_t keyIncRef (Key * key)"
264 Increment the viability of a key object.
266 This function is intended for applications using their own reference counter for key objects. With it you can increment the reference and thus avoid destruction of the object in a subsequent \fBkeyDel()\fP.
272 function_that_keyDec(k);
274 keyDel (k); // now really free it
278 The reference counter can't be incremented once it reached SSIZE_MAX. In that situation nothing will happen and SSIZE_MAX will be returned.
282 the value of the new reference counter
286 SSIZE_MAX when maximum exceeded
291 \fIkey\fP the key object to work with
296 \fBkeyGetRef()\fP, \fBkeyDecRef()\fP, \fBkeyDel()\fP
300 .SS "Key* keyNew (const char * keyName, ...)"
302 A practical way to fully create a Key object in one step.
304 This function tries to mimic the C++ way for constructors.
306 To just get a key object, simple do:
316 If you want the key object to contain a name, value, comment and other meta info read on.
320 When you already have a key with similar properties its easier and cheaper to \fBkeyDup()\fP the key.
323 Due to ABI compatibility, the \fCKey\fP structure is not defined in kdb.h, only declared. So you can only declare \fCpointers\fP to \fCKeys\fP in your program, and allocate and free memory for them with \fBkeyNew()\fP and \fBkeyDel()\fP respectively. See http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135
325 You can call it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as the keyswitch_t values, and tell \fBkeyNew()\fP which Key attribute comes next.
327 The simplest and minimum way to use it is with no tags, only a key name:
330 Key *nullKey,*emptyNamedKey;
332 // Create a key that has no name, is completely empty, but is initialized
336 // Is the same as above
337 nullKey=keyNew('', KEY_END);
340 // Create and initialize a key with a name and nothing else
341 emptyNamedKey=keyNew('user/some/example',KEY_END);
342 keyDel (emptyNamedKey);
347 \fBkeyNew()\fP allocates memory for a key object and cleans everything up. After that, it processes the given argument list.
349 The Key attribute tags are the following:
351 keyswitch_t::KEY_TYPE
353 Next parameter is a type of the value. Default assumed is KEY_TYPE_UNDEFINED. Set this attribute so that a subsequent KEY_VALUE can toggle to \fBkeySetString()\fP or \fBkeySetBinary()\fP regarding to \fBkeyIsString()\fP or \fBkeyIsBinary()\fP. If you don't use KEY_TYPE but a KEY_VALUE follows afterwards, KEY_TYPE_STRING will be used.
355 keyswitch_t::KEY_SIZE
357 Define a maximum length of the value. This is especially useful for setting a binary key. So make sure you use that before you KEY_VALUE for binary keys.
359 keyswitch_t::KEY_VALUE
361 Next parameter is a pointer to the value that will be set to the key If no keyswitch_t::KEY_TYPE was used before, keyswitch_t::KEY_TYPE_STRING is assumed. If KEY_TYPE was previously passed with a KEY_TYPE_BINARY, you should have passed KEY_SIZE before! Otherwise it will be cut of with first \\0 in string!
363 keyswitch_t::KEY_UID, \fCkeyswitch_t::KEY_GID\fP
365 Next parameter is taken as the UID (uid_t) or GID (gid_t) that will be defined on the key. See \fBkeySetUID()\fP and \fBkeySetGID()\fP.
367 keyswitch_t::KEY_MODE
369 Next parameter is taken as mode permissions (mode_t) to the key. See \fBkeySetMode()\fP.
373 Define that the key is a directory rather than a ordinary key. This means its executable bits in its mode are set. This option allows the key to have subkeys. See \fBkeySetDir()\fP.
375 keyswitch_t::KEY_OWNER
377 Next parameter is the owner. See \fBkeySetOwner()\fP.
379 keyswitch_t::KEY_COMMENT
381 Next parameter is a comment. See \fBkeySetComment()\fP.
383 keyswitch_t::KEY_REMOVE
385 Mark the key to be removed instead of set it. See \fBkeyRemove()\fP.
387 keyswitch_t::KEY_STAT
389 Mark the key to be stated instead of get it. See \fBkeyStat()\fP.
393 Must be the last parameter passed to \fBkeyNew()\fP. It is always required, unless the \fCkeyName\fP is 0.
402 ksAppendKey(ks,keyNew(0)); // an empty key
404 ksAppendKey(ks,keyNew('user/sw', // the name of the key
405 KEY_END)); // no more args
407 ksAppendKey(ks,keyNew('user/tmp/ex1',
408 KEY_VALUE,'some data', // set a string value
409 KEY_END)); // end of args
411 ksAppendKey(ks,keyNew('user/tmp/ex2',
412 KEY_VALUE,'some data', // with a simple value
413 KEY_MODE,0777, // permissions
414 KEY_END)); // end of args
416 ksAppendKey(ks,keyNew('user/tmp/ex4',
417 KEY_TYPE,KEY_TYPE_BINARY, // key type
418 KEY_SIZE,7, // assume binary length 7
419 KEY_VALUE,'some data', // value that will be truncated in 7 bytes
420 KEY_COMMENT,'value is truncated',
421 KEY_OWNER,'root', // owner (not uid) is root
422 KEY_UID,0, // root uid
423 KEY_END)); // end of args
425 ksAppendKey(ks,keyNew('user/tmp/ex5',
427 KEY_TYPE_DIR | KEY_TYPE_BINARY,// dir key with a binary value
429 KEY_VALUE,'some data', // value that will be truncated in 7 bytes
430 KEY_COMMENT,'value is truncated',
431 KEY_OWNER,'root', // owner (not uid) is root
432 KEY_UID,0, // root uid
433 KEY_END)); // end of args
441 The reference counter (see \fBkeyGetRef()\fP) will be initialized with 0, that means a subsequent call of \fBkeyDel()\fP will delete the key. If you append the key to a keyset the reference counter will be incremented by one (see keyInc()) and the key can't be be deleted by a \fBkeyDel()\fP.
445 Key *k = keyNew(0); // ref counter 0
446 ksAppendKey(ks, k); // ref counter of key 1
447 ksDel(ks); // key will be deleted with keyset
452 If you increment only by one with keyInc() the same as said above is valid:
456 Key *k = keyNew(0); // ref counter 0
457 keyIncRef(k); // ref counter of key 1
458 keyDel(k); // has no effect
459 keyDecRef(k); // ref counter back to 0
460 keyDel(k); // key is now deleted
465 If you add the key to more keySets:
469 Key *k = keyNew(0); // ref counter 0
470 ksAppendKey(ks1, k); // ref counter of key 1
471 ksAppendKey(ks2, k); // ref counter of key 2
472 ksDel(ks1); // ref counter of key 1
473 ksDel(ks2); // k is now deleted
478 or use keyInc() more than once:
482 Key *k = keyNew(0); // ref counter 0
483 keyIncRef(k); // ref counter of key 1
484 keyDel (k); // has no effect
485 keyIncRef(k); // ref counter of key 2
486 keyDel (k); // has no effect
487 keyDecRef(k); // ref counter of key 1
488 keyDel (k); // has no effect
489 keyDecRef(k); // ref counter is now 0
490 keyDel (k); // k is now deleted
495 they key won't be deleted by a \fBkeyDel()\fP as long refcounter is not 0.
497 The key's sync bit will always be set for any call, except:
501 // keyNeedSync() will be false
508 \fIkeyName\fP a valid name to the key, or NULL to get a simple initialized, but really empty, object
518 a pointer to a new allocated and initialized Key object, or NULL if an invalid \fCkeyName\fP was passed (see \fBkeySetName()\fP).