1Key :: Meta Info ManipulatioLnibMreatrhyodFsu(n3cK)teiyon:s: MMaentuaalInfo Manipulation Methods(3)
2
3
4

NAME

6       Key :: Meta Info Manipulation Methods - Methods to do various
7       operations on Key metainfo.
8
9
10   Functions
11       ssize_t keySetOwner (Key *key, const char *userDomain)
12           Set the user domain of a key.
13       ssize_t keyGetOwnerSize (const Key *key)
14           Return the size of the user domain of the Key.
15       ssize_t keyGetOwner (const Key *key, char *returned, size_t maxSize)
16           Return the user domain of the key.
17       char * keyStealOwner (const Key *key)
18           Return a pointer to the real internal key owner or user domain.
19       ssize_t keySetComment (Key *key, const char *newComment)
20           Set a comment for a key.
21       ssize_t keyGetCommentSize (const Key *key)
22           Calculates number of bytes needed to store a key comment, including
23           final NULL.
24       ssize_t keyGetComment (const Key *key, char *returnedDesc, size_t
25           maxSize)
26           Get the key comment.
27       char * keyStealComment (const Key *key)
28           Return a pointer to the real internal key comment.
29       uid_t keyGetUID (const Key *key)
30           Get the user ID of a key.
31       int keySetUID (Key *key, uid_t uid)
32           Set the user ID of a key.
33       gid_t keyGetGID (const Key *key)
34           Get the system's group ID of a key.
35       int keySetGID (Key *key, gid_t gid)
36           Set the system's group ID of a key.
37       mode_t keyGetAccess (const Key *key)
38           Return the key filesystem-like access permissions.
39       int keySetAccess (Key *key, mode_t mode)
40           Set the key filesystem-like access permissions.
41       int keySetUAccess (Key *key, mode_t umask)
42           Set the key filesystem-like access permissions based on umask.
43       time_t keyGetMTime (const Key *key)
44           Get last modification time of the key on disk.
45       time_t keyGetATime (const Key *key)
46           Get last time the key data was read from disk.
47       time_t keyGetCTime (const Key *key)
48           Get last time the key was stated from disk.
49       int keySetFlag (Key *key)
50           Set a general flag in the Key.
51       int keyClearFlag (Key *key)
52           Clear the general flag in the Key.
53       int keyGetFlag (const Key *key)
54           Get the general flag from the Key.
55

Detailed Description

57       Methods to do various operations on Key metainfo.
58
59       To use them:
60
61       #include <kdb.h>
62
63
64       Key metainfo are:
65
66       · Comment about the key
67
68       · User domain
69
70       · UID, GID and filesystem-like access permissions
71
72       · Access, change and modification times
73
74       · A general flag
75
76       The comment can contain userdata which directly belong to that key.
77
78       User domain is the user that owns the key. It only works for the user/
79       hierachy.
80
81       Every user and group of your System has a uniqe ID. These values are
82       used in the keys too. They are very important for the access. See man 2
83       chown.
84
85       With the access mode you can choose if a user, group or the world can
86       access your key. See man 2 chmod.
87

Function Documentation

89   ssize_t keySetOwner (Key * key, const char * userDomain)
90       Set the user domain of a key.
91
92       A user domain is a user name.
93
94       A private copy is stored, so the passed parameter can be freed after
95       the call.
96
97       Parameters:
98           userDomain the user domain (or user name)
99
100       Returns:
101           the number of bytes copied
102
103       See also:
104           keySetName(), keyGetOwner(), keyGetFullName()
105
106       Definition at line 2141 of file key.c.
107
108       References _Key::flags, KDB_RET_NOMEM, KEY_SWITCH_DOMAIN,
109       KEY_SWITCH_NEEDSYNC, strblen(), and _Key::userDomain.
110
111       Referenced by keyDup(), keyNew(), and keySetName().
112
113   ssize_t keyGetOwnerSize (const Key * key)
114       Return the size of the user domain of the Key.
115
116       Returns:
117           number of bytes
118
119       See also:
120           keyGetOwner()
121
122       Definition at line 2187 of file key.c.
123
124       References KDB_RET_NODOMAIN, strblen(), and _Key::userDomain.
125
126   ssize_t keyGetOwner (const Key * key, char * returned, size_t maxSize)
127       Return the user domain of the key.
128
129       · Given user:someuser/..... return someuser
130
131       · Given user:some.user/.... return some.user
132
133       · Given user/.... return the current user
134
135       Only user/... keys have user domains. For system/... keys (that doesn't
136       have user domains) nothing is returned.
137
138       Although usually the same, the user domain of a key is not related to
139       its UID. User domains are related to WHERE the key is stored on disk,
140       while UIDs are related to access controls of a key.
141
142       Parameters:
143           key the object to work with
144           returned a pre-allocated space to store the owner
145           maxSize maximum number of bytes that fit returned
146
147       Returns:
148           number of bytes written to buffer
149
150       See also:
151           keySetName(), keySetOwner(), keyStealOwner(), keyGetFullName()
152
153       Definition at line 2218 of file key.c.
154
155       References KDB_RET_NODOMAIN, KDB_RET_TRUNC, strblen(), and
156       _Key::userDomain.
157
158   char* keyStealOwner (const Key * key)
159       Return a pointer to the real internal key owner or user domain.
160
161       This is a much more efficient version of keyGetOwner() and you should
162       use it if you are responsible enough to not mess up things.
163
164       Parameters:
165           key the key object to work with
166
167       See also:
168           keyGetOwner(), keySetOwner()
169
170       Definition at line 2245 of file key.c.
171
172       References _Key::userDomain.
173
174   ssize_t keySetComment (Key * key, const char * newComment)
175       Set a comment for a key.
176
177       A key comment is like a configuration file comment. It has no size
178       limit. A private copy will be stored.
179
180       Parameters:
181           newComment the comment, that can be freed after this call.
182
183       Returns:
184           the number of bytes copied
185
186       See also:
187           keyGetComment()
188
189       Definition at line 2271 of file key.c.
190
191       References _Key::comment, _Key::commentSize, _Key::flags,
192       KDB_RET_NOMEM, KEY_SWITCH_COMMENT, KEY_SWITCH_NEEDSYNC, and strblen().
193
194       Referenced by commandSet(), keyDup(), and keyNew().
195
196   ssize_t keyGetCommentSize (const Key * key)
197       Calculates number of bytes needed to store a key comment, including
198       final NULL.
199
200       Use this method to allocate memory to retrieve a key comment.
201
202       Returns:
203           number of bytes needed
204
205       See also:
206           keyGetComment(), keySetComment()
207
208       Definition at line 2311 of file key.c.
209
210       References _Key::comment, KDB_RET_NODESC, and strblen().
211
212       Referenced by commandGet().
213
214   ssize_t keyGetComment (const Key * key, char * returnedDesc, size_t
215       maxSize)
216       Get the key comment.
217
218       A Key comment is pretty much as a comment in a text configuration file.
219
220       Parameters:
221           returnedDesc pre-allocated memory to copy the comments to
222           maxSize number of bytes that will fit returnedDesc
223
224       Returns:
225           number of bytes written
226
227       See also:
228           keyGetCommentSize(), keySetComment()
229
230       Definition at line 2333 of file key.c.
231
232       References _Key::comment, KDB_RET_NODESC, KDB_RET_TRUNC, and strblen().
233
234       Referenced by commandGet().
235
236   char* keyStealComment (const Key * key)
237       Return a pointer to the real internal key comment.
238
239       This is a much more efficient version of keyGetComment() and you should
240       use it if you are responsible enough to not mess up things.
241
242       Parameters:
243           key the key object to work with
244
245       See also:
246           keyGetCommentSize()
247
248           keyStealValue() for and example
249
250       Definition at line 2360 of file key.c.
251
252       References _Key::comment.
253
254   uid_t keyGetUID (const Key * key)
255       Get the user ID of a key.
256
257       Although usually the same, the UID of a key is not related to its user
258       domain.
259
260       Returns:
261           the system's UID of the key
262
263       See also:
264           keyGetGID(), keySetUID(), keyGetOwner()
265
266       Definition at line 2383 of file key.c.
267
268       References _Key::uid.
269
270       Referenced by listSingleKey().
271
272   int keySetUID (Key * key, uid_t uid)
273       Set the user ID of a key.
274
275       Although usually the same, the UID of a key is not related to its user
276       domain.
277
278       Returns:
279           0 on success
280
281       See also:
282           keySetGID(), keyGetUID(), keyGetOwner()
283
284       Definition at line 2399 of file key.c.
285
286       References _Key::flags, KEY_SWITCH_NEEDSYNC, KEY_SWITCH_UID, and
287       _Key::uid.
288
289       Referenced by commandSet(), and keyNew().
290
291   gid_t keyGetGID (const Key * key)
292       Get the system's group ID of a key.
293
294       Returns:
295           the system's GID of the key
296
297       See also:
298           keySetGID(), keyGetUID()
299
300       Definition at line 2415 of file key.c.
301
302       References _Key::gid.
303
304       Referenced by listSingleKey().
305
306   int keySetGID (Key * key, gid_t gid)
307       Set the system's group ID of a key.
308
309       Returns:
310           the system's GID of the key
311
312       See also:
313           keyGetGID(), keySetUID()
314
315       Definition at line 2428 of file key.c.
316
317       References _Key::flags, _Key::gid, KEY_SWITCH_GID, and
318       KEY_SWITCH_NEEDSYNC.
319
320       Referenced by commandSet(), and keyNew().
321
322   mode_t keyGetAccess (const Key * key)
323       Return the key filesystem-like access permissions.
324
325       See also:
326           keySetAccess()
327
328       Definition at line 2442 of file key.c.
329
330       References _Key::access.
331
332       Referenced by listAccess().
333
334   int keySetAccess (Key * key, mode_t mode)
335       Set the key filesystem-like access permissions.
336
337       Use this method before calling keySetDir().
338
339       Parameters:
340           key the key to set access permissions
341           mode the access permissions as for chmod(2)
342
343       See also:
344           keyGetAccess()
345
346       Definition at line 2458 of file key.c.
347
348       References _Key::access, _Key::flags, KEY_SWITCH_MODE, and
349       KEY_SWITCH_NEEDSYNC.
350
351       Referenced by commandSet(), and keyNew().
352
353   int keySetUAccess (Key * key, mode_t umask)
354       Set the key filesystem-like access permissions based on umask.
355
356       Use this method before calling keySetDir().
357
358       Parameters:
359           key the key to set access permissions
360           umask the umask for file/key creation as returned by umask(3)
361
362       See also:
363           keyGetAccess()
364
365       Definition at line 2479 of file key.c.
366
367       References _Key::access, _Key::flags, KEY_SWITCH_MODE, and
368       KEY_SWITCH_NEEDSYNC.
369
370       Referenced by keyInit(), and keyNew().
371
372   int keySetFlag (Key * key)
373       Set a general flag in the Key.
374
375       The flag has no semantics to the library, only to your application. It
376       is just a simple marker that you may use to put the key on a special
377       state that makes sense to your application.
378
379       See also:
380           keyGetFlag(), keyClearFlag()
381
382       Returns:
383           always 0
384
385       Definition at line 3085 of file key.c.
386
387       References _Key::flags, and KEY_SWITCH_FLAG.
388
389   int keyClearFlag (Key * key)
390       Clear the general flag in the Key.
391
392       The flag has no semantics to the library, only to your application. It
393       is just a simple marker that you may use to put the key on a special
394       state that makes sense to your application.
395
396       See also:
397           keyGetFlag(), keySetFlag()
398
399       Returns:
400           always 0
401
402       Definition at line 3104 of file key.c.
403
404       References _Key::flags, and KEY_SWITCH_FLAG.
405
406   int keyGetFlag (const Key * key)
407       Get the general flag from the Key.
408
409       The flag has no semantics to the library, only to your application. It
410       is just a simple marker that you may use to put the key on a special
411       state that makes sense to your application.
412
413       See also:
414           keySetFlag(), keyClearFlag()
415
416           keyNew() with KeySwitch::KEY_SWITCH_NEEDSYNC
417
418       Returns:
419           1 if flag is set, 0 otherwise
420
421       Definition at line 3124 of file key.c.
422
423       References _Key::flags, and KEY_SWITCH_FLAG.
424
425
426
427Elektra Project                   25 MaKrey20:0:7Meta Info Manipulation Methods(3)