1Key :: Basic Methods(3) Library Functions Manual Key :: Basic Methods(3)
2
6 Key :: Basic Methods - Key construction and initialization methods.
7 Enumerations
10 enum KeyType { KEY_TYPE_UNDEFINED = 0, KEY_TYPE_DIR = 1, KEY_TYPE_LINK
11 = 2, KEY_TYPE_BINARY = 20, KEY_TYPE_STRING = 40 }
12 Key data types.
13 enum KeyNamespace { KEY_NS_SYSTEM = 1, KEY_NS_USER = 2 }
14 Elektra currently supported Key namespaces.
15 enum KeySwitch { KEY_SWITCH_TYPE = 1, KEY_SWITCH_NAME = 1<<1,
16 KEY_SWITCH_VALUE = 1<<2, KEY_SWITCH_OWNER = 1<<5, KEY_SWITCH_DOMAIN
17 = KEY_SWITCH_OWNER, KEY_SWITCH_COMMENT = 1<<6, KEY_SWITCH_UID =
18 1<<7, KEY_SWITCH_GID = 1<<8, KEY_SWITCH_MODE = 1<<10,
19 KEY_SWITCH_TIME = 1<<11, KEY_SWITCH_NEEDSYNC = 1<<12,
20 KEY_SWITCH_UMODE = 1<<15, KEY_SWITCH_ISSYSTEM = 1<<23,
21 KEY_SWITCH_ISUSER = 1<<24, KEY_SWITCH_FLAG = 1<<31, KEY_SWITCH_END
22 = 0 }
23 Switches to denote the various Key attributes in methods throughout
24 this library.
25 Functions
27 Key * keyNew (const char *keyName,...)
28 A practical way to fully create a Key object in one step.
29 int keyDel (Key *key)
30 A destructor for Key objects.
31 int keyDup (const Key *source, Key *dest)
32 Duplicate a key in memory.
33 int keyInit (Key *key)
34 Initializes the Key object with some default values.
35 int keyClose (Key *key)
36 Finishes the usage of a Key object.
37
39 Key construction and initialization methods.
40 To use them:
42 #include <kdb.h>
44 A Key is the essential class that encapsulates key name , value and
47 metainfo . Key properties are:
48 · Key name
50 · Key value
52 · Data type
54 · Key comment
56 · User domain (the user that owns the key)
58 · UID, GID and filesystem-like access permissions
60 · Access, change and modification times
62 · A general flag
64 Described here the methods to allocate and free the key.
66
68 enum KeyType
69 Key data types.
70 Key type values grow from the semantically poor to the semantically
72 rich. The gaps between them is for user-defined types.
73 If your application needs value types with more semantics, like Color,
75 Font, etc, you can still use it. You'll have to define a new type
76 number in the scope of your application, and force the type with
77 keySetType(), or keyNew().
78 The type number is a value between 0 and 255. If your user-defined type
80 >= KEY_TYPE_STRING, it will be still treated as a string (in the terms
81 of Unicode handling). If KEY_TYPE_BINARY <= type < KEY_TYPE_STRING,
82 Elektra will handle it as a binary value, will not make Unicode
83 handling and will save it hex-encoded.
84 See also:
86 keyGetType()
87 keySetType() for an example of how to define custom types
89 Enumerator:
91 KEY_TYPE_UNDEFINED
93 Undefined key type
94 KEY_TYPE_DIR
96 A directory key
97 KEY_TYPE_LINK
99 A symbolink link key. This gap is for special key meta types,
100 that can't go into regular files.
101 KEY_TYPE_BINARY
103 A binary key. This gap is for binary data types that have some
104 semantics that somebody can invent in the future
105 KEY_TYPE_STRING
107 A string key
108 Definition at line 93 of file kdb.h.
110 enum KeyNamespace
112 Elektra currently supported Key namespaces.
113 See also:
115 kdbGetRootKeys(), keyGetNamespace(), keyNameGetNamespace()
116 Enumerator:
118 KEY_NS_SYSTEM
120 The system keys
121 KEY_NS_USER
123 The user keys
124 Definition at line 116 of file kdb.h.
126 enum KeySwitch
128 Switches to denote the various Key attributes in methods throughout
129 this library.
130 See also:
132 keyNew()
133 keyCompare()
135 kdbMonitorKey(), kdbMonitorKeys(), the diffMask parameter
137 keyGetFlag(), keySetFlag()
139 Enumerator:
141 KEY_SWITCH_TYPE
143 Flag for the key type
144 KEY_SWITCH_NAME
146 Flag for the key name
147 KEY_SWITCH_VALUE
149 Flag for the key data
150 KEY_SWITCH_OWNER
152 Flag for the key user domain
153 KEY_SWITCH_DOMAIN
155 An alias
156 KEY_SWITCH_COMMENT
158 Flag for the key comment
159 KEY_SWITCH_UID
161 Flag for the key UID
162 KEY_SWITCH_GID
164 Flag for the key GID
165 KEY_SWITCH_MODE
167 Flag for the key permissions
168 KEY_SWITCH_TIME
170 Flag for the key change time
171 KEY_SWITCH_NEEDSYNC
173 Flags that key needs syncronization
174 KEY_SWITCH_UMODE
176 Flag for key permissions based on umask
177 KEY_SWITCH_ISSYSTEM
179 Flag to denote a 'system' key
180 KEY_SWITCH_ISUSER
182 Flag to denote a 'user' key
183 KEY_SWITCH_FLAG
185 General purpose flag that has semantics only to your app
186 KEY_SWITCH_END
188 Used as a parameter terminator to keyNew()
189 Definition at line 156 of file kdb.h.
191
193 Key* keyNew (const char * keyName, ...)
194 A practical way to fully create a Key object in one step.
195 This function tries to mimic the C++ way for constructors.
197 Due to ABI compatibility, the Key structure is not defined in kdb.h,
199 only declared. So you can only declare pointers to Keys in your
200 program, and allocate and free memory for them with keyNew() and
201 keyDel() respectively. See http://tldp.org/HOWTO/Program-Library-
202 HOWTO/shared-libraries.html#AEN135
203 You can call it in many different ways depending on the attribute tags
205 you pass as parameters. Tags are represented as the KeySwitch values,
206 and tell keyNew() which Key attribute comes next.
207 The simplest and minimum way to use it is with no tags, only a key
209 name:
210 Key *nullKey,*emptyNamedKey;
212 // Create a key that has no name, is completely empty, but is initialized
214 nullKey=keyNew(KEY_SWITCH_END);
215 // Create and initialize a key with a name and nothing else
217 emptyNamedKey=keyNew('user/some/example',KEY_SWITCH_END);
218 keyNew() allocates memory for a key object and then calls keyInit().
221 After that, it processes the given argument list.
222 The Key attribute tags are the following:
224 · KeySwitch::KEY_SWITCH_TYPE
226 Next parameter is a type of the value from KeyType or a custom type.
227 You must use this tag before KeySwitch::KEY_SWITCH_VALUE, otherwise
228 KeyType::KEY_TYPE_STRING is assumed.
229 · KeySwitch::KEY_SWITCH_VALUE
231 Next parameter is a pointer to the value that will be set to the key
232 If no KeySwitch::KEY_SWITCH_TYPE was used before,
233 KeySwitch::KEY_TYPE_STRING is assumed. If KEY_SWITCH_TYPE was
234 previously passed with a KEY_TYPE_BINARY or any other custom binary
235 type (see keySetType()) as parameter, one parameter is needed to
236 define the binary value size. See the example bellow.
237 · KeySwitch::KEY_SWITCH_UID, KeySwitch::KEY_SWITCH_GID
239 Next parameter is taken as the UID (uid_t) or GID (gid_t) that will
240 be defined on the key. See keySetUID() and keySetGID().
241 · KeySwitch::KEY_SWITCH_MODE
243 Next parameter is taken as access permissions (mode_t) to the key.
244 See keySetAccess().
245 · KeySwitch::KEY_SWITCH_UMODE
247 Next parameter is taken as user's umask, and will be used to
248 calculate and set key's access permissions. If used after
249 KEY_TYPE_DIR with KEY_SWITCH_TYPE, keySetDir() will be used. See
250 keySetAccess(). Do not use this switch with KEY_SWITCH_MODE.
251 · KeySwitch::KEY_SWITCH_DOMAIN
253 Next parameter is the user domain. See keySetOwner().
254 · KeySwitch::KEY_SWITCH_COMMENT
256 Next parameter is a comment. See keySetComment().
257 · KeySwitch::KEY_SWITCH_NEEDSYNC
259 Next parameter is a KDBHandle. Makes keyNew() retrieve the Key from
260 the backend with kdbGetKey(). In the same keyNew() call you can use
261 this tag in conjunction with any other, which will make keyNew()
262 modify only some attributes after retrieving the key, and return it
263 to you. Order of parameters do matter. If the internal call to
264 kdbGetKey() failed, you'll still have a valid, but flagged, key.
265 Check with keyGetFlag(), and errno. You will have to kdbOpen() before
266 using keyNew() with this tag.
267 · KeySwitch::KEY_SWITCH_END
269 Must be the last parameter passed to keyNew(). It is always
270 required, unless the keyName is NULL too.
271 Example:.RS 4
273 KeySet *ks=ksNew();
276 kdbOpen();
278 ksAppend(ks,keyNew(KEY_SWITCH_END)); // an empty key
280 ksAppend(ks,keyNew('user/sw', // a simple key
282 KEY_SWITCH_END)); // no more args
283 ksAppend(ks,keyNew('system/sw',
285 KEY_SWITCH_NEEDSYNC, handle, // a key retrieved from storage
286 KEY_SWITCH_END)); // end of args
287 ksAppend(ks,keyNew('user/tmp/ex1',
289 KEY_SWITCH_VALUE,'some data', // with a simple value
290 KEY_SWITCH_END)); // end of args
291 ksAppend(ks,keyNew('user/tmp/ex2',
293 KEY_SWITCH_VALUE,'some data', // with a simple value
294 KEY_SWITCH_MODE,0777, // permissions
295 KEY_SWITCH_END)); // end of args
296 ksAppend(ks,keyNew('user/tmp/ex3',
298 KEY_SWITCH_TYPE,KEY_TYPE_LINK, // only type
299 KEY_SWITCH_VALUE,'system/mtp/x', // link destination
300 KEY_SWITCH_MODE,0654, // weird permissions
301 KEY_SWITCH_END)); // end of args
302 ksAppend(ks,keyNew('user/tmp/ex4',
304 KEY_SWITCH_TYPE,KEY_TYPE_BINARY, // key type
305 KEY_SWITCH_VALUE,'some data',7, // value that will be truncated in 7 bytes
306 KEY_SWITCH_COMMENT,'value is truncated',
307 KEY_SWITCH_DOMAIN,'root', // owner (not uid) is root
308 KEY_SWITCH_UID,0, // root uid
309 KEY_SWITCH_END)); // end of args
310 ksAppend(ks,keyNew('user/tmp/ex5',
312 KEY_SWITCH_TYPE,KEY_TYPE_DIR, // dir key with...
313 KEY_SWITCH_TYPE,KEY_TYPE_BINARY, // ...a binary value
314 KEY_SWITCH_VALUE,'some data',7, // value that will be truncated in 7 bytes
315 KEY_SWITCH_COMMENT,'value is truncated',
316 KEY_SWITCH_DOMAIN,'root', // owner (not uid) is root
317 KEY_SWITCH_UID,0, // root uid
318 KEY_SWITCH_END)); // end of args
319 ksAppend(ks,keyNew('user/env/alias/ls', // a key we know we have
321 KEY_SWITCH_NEEDSYNC, handle, // retrieve from storage, passing the KDB handle
322 KEY_SWITCH_END)); // do nothing more
323 ksAppend(ks,keyNew('user/env/alias/ls', // same key
325 KEY_SWITCH_NEEDSYNC, handle, // retrieve from storage
326 KEY_SWITCH_DOMAIN,'root', // set new owner (not uid) as root
327 KEY_SWITCH_COMMENT,'new comment', // set new comment
328 KEY_SWITCH_END)); // end of args
329 ksToStream(ks,stdout,KDB_O_XMLHEADERS);
331 ksDel(ks);
333 kdbClose();
334 Parameters:
337 keyName a valid name to the key, or NULL to get a simple
338 initialized, but really empty, object
339 See also:
341 keyDel()
342 Returns:
344 a pointer to a new allocated and initialized Key object, or NULL if
345 an invalid keyName was passed (see keySetName()).
346 Definition at line 373 of file key.c.
348 References kdbGetKey(), KEY_SWITCH_COMMENT, KEY_SWITCH_DOMAIN,
350 KEY_SWITCH_FLAG, KEY_SWITCH_GID, KEY_SWITCH_MODE, KEY_SWITCH_NEEDSYNC,
351 KEY_SWITCH_TYPE, KEY_SWITCH_UID, KEY_SWITCH_UMODE, KEY_SWITCH_VALUE,
352 KEY_TYPE_BINARY, KEY_TYPE_DIR, KEY_TYPE_STRING, KEY_TYPE_UNDEFINED,
353 keyInit(), keyIsDir(), keySetAccess(), keySetComment(), keySetDir(),
354 keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetString(),
355 keySetType(), keySetUAccess(), and keySetUID().
356 Referenced by commandEdit(), commandGet(), commandList(),
358 commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(),
359 kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(),
360 kdbRemove(), kdbRename_default(), kdbSetValue(), and keyUnserialize().
361 int keyDel (Key * key)
363 A destructor for Key objects.
364 Every key created by keyNew() must be deleted with keyDel(). It will
366 keyClose() and free() the key pointer.
367 There is the keyFree() macro if you prefer this method name.
369 See also:
371 keyNew()
372 Returns:
374 whatever is returned by keyClose()
375 Definition at line 490 of file key.c.
377 References keyClose().
379 Referenced by commandEdit(), commandGet(), commandList(),
381 commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(),
382 kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(),
383 kdbRemove(), kdbRename_default(), kdbSetValue(), ksClose(), and
384 ksCompare().
385 int keyDup (const Key * source, Key * dest)
387 Duplicate a key in memory.
388 Both keys have to be initialized with keyInit(). If you have set any
390 dynamic allocated memory for dest, make sure that you keyClose() it
391 before keyDup().
392 All private attributes of the source key will be copied, including its
394 context on a KeySet, and nothing will be shared between both keys.
395 Memory will be allocated as needed for dynamic properties as value,
397 comment, etc.
398 Parameters:
400 source has to be an initializised source Key
401 dest will be the new copy of the Key
402 Returns:
404 0 on success
405 See also:
407 keyClose(), keyInit()
408 Definition at line 2572 of file key.c.
410 References _Key::comment, _Key::data, _Key::dataSize, _Key::flags,
412 _Key::key, KEY_SWITCH_NEEDSYNC, keySetComment(), keySetName(),
413 keySetOwner(), keySetRaw(), and _Key::userDomain.
414 Referenced by kdbMonitorKey_default(), and kdbRename_default().
416 int keyInit (Key * key)
418 Initializes the Key object with some default values.
419 This function should not be used by backends or applications, use
421 keyNew() instead.
422 keyInit() sets the key to a clear state. It uses memset to clear the
424 memory. The type of the key is KeyType::KEY_TYPE_UNDEFINED afterwards.
425 uid, gid and access masks are set with the current values of your
427 system.
428 keyNew() and keyDel() are better ways to deal with initialization than
430 keyInit() and keyClose()
431 Example.RS 4
433 Key *key=keyNew('system/some/name');
436 // Use the key
437 keyClose(key);
438 keyInit(key);
439 // Reuse the key
440 keyDel(key);
441 See also:
444 keyClose() to free the memory allocated within that function.
445 keyNew() and keyDel() for construction and destruction of Keys
447 Returns:
449 always 0;
450 Definition at line 3173 of file key.c.
452 References _Key::flags, _Key::gid, KEY_TYPE_UNDEFINED, keySetUAccess(),
454 _Key::type, and _Key::uid.
455 Referenced by keyNew().
457 int keyClose (Key * key)
459 Finishes the usage of a Key object.
460 The key must be keyInit() before any attempt to close it.
462 Frees all internally allocated memory like value, comment, and leave
464 the Key object ready to be keyInit()ed to reuse, or deallocated.
465 All internal states of the key will be NULL. After this process there
467 is no information inside the key.
468 keyNew() and keyDel() are better ways to deal with initialization than
470 keyInit() and keyClose()
471 See also:
473 keyInit() how to allocate internal memory and an example
474 keyNew() and keyDel() for construction and destruction of Keys
476 Returns:
478 always 0;
479 Definition at line 3218 of file key.c.
481 References _Key::comment, _Key::data, _Key::key, and _Key::userDomain.
483 Referenced by keyDel().
485Elektra Project 25 Mar 2007 Key :: Basic Methods(3)