Debian Codegraph @

eXdbm/README

raw
1
2 Editor:
3 Fred Pesch, [email protected]
4
5 Copyright:
6 eXode Developers Team
7
8 Status of this document
9 -----------------------
10
11 This is an eXode documentation for review by eXode members and
12 other interested parties. It is a released document but may be updated,
13 replaced or obsoleted by other documents in future relases.
14
15 Abstract
16 --------
17
18 This document explains the eXdbm (eXode Database Manager) file
19 format. This is the configuration file format of the eXode clients
20 (esp. the core tools). The provided API is also explained here.
21
22 Table of contents
23 -----------------
24
25 1. Recent Changes
26
27 2. Introduction
28
29 3. eXdbm file format
30 3.1. general structure
31 3.2. special chararcters
32 3.3. comments
33 3.4. datatypes
34 3.5. variables
35 3.6. lists
36 3.7. keywords
37
38 4. Proposed API
39 4.1. new types
40 4.2. error handling
41 4.3. opening & closing a database
42 4.4. generic entry management
43 4.5. list management
44 4.6. variable management
45
46 5. Using the library
47 5.1. Installation
48 5.2. Linking programs with libeXdbm
49 5.3. Sample programs
50
51 1. Recent changes
52 -----------------
53
54 Dec-27-97:
55 - version 1.0beta1 to be released
56 - removed keyword concept (too eXode specific)
57
58 Dec-10-97:
59 - new keyword specification.
60 - few changes in the API
61 - no more disk media
62 - new error code (-1)
63
64 Oct-04-97:
65 - First draft translated and modified, renamed eXdbm
66
67 July-xx-97:
68 - First draft (was eXhcl)
69
70 2. Introduction
71 ---------------
72
73 The X Resource manager is a normal choice for Motif based
74 applications configuration but it lacks of high level data structures
75 like lists or trees. Derived from the fof's configuration file format,
76 eXdbm is an ASCII-based database format. eXdbm will be used to manage
77 the configuration files of the eXode clients. The resource files will
78 also be generated by eXconfig from the eXdbm files. The proposed API
79 for the eXdbm management follows the description of the format.
80
81 The library uses a tree of hash tables structures stored in memory,
82 favouring speed upon memory consumption. This is not a general purpose
83 database library, its efficiency is based on the fact that the databases
84 managed contain less than a few thousand entries.
85
86 Note that eXdbm is a general purpose configuration library, it can be
87 used in many other applications without relations to the eXode project.
88
89 3. eXdbm file format
90 --------------------
91
92 3.1. general structure
93 ----------------------
94
95 The eXdbm files are standard text files. Each line of text is a
96 definition (the end of line char is a delimiter).
97
98 The possible definitions are :
99 - comments
100 - variable
101 - list header
102 - list footer
103
104 An empty line doesn't contain any definition and is simply ignored.
105
106
107 3.2. special characters
108 -----------------------
109
110 The following characters are reserved :
111 - # : starts a comment
112 - " : string definition delimiter
113 - = : variable definition
114 - { : starts a list definition
115 - } : ends a list definition
116
117 Exceptions :
118
119 - in a string definition, the only reserved char are %, " and \
120 - in a comment, there is no reserved char
121
122
123 3.3. comments
124 -------------
125
126 A comment begins with the reserved char # and continues until the
127 next end of line character (this is a sh-like behaviour). Each comment is associated to the first entry definition that follows.
128
129 Ex.:
130
131 # I am a comment
132
133 Variable = 12
134
135
136 3.4. datatypes
137 --------------
138
139 The basic datatypes are :
140 - Integer : [+-][0-9]+
141 - Real numbers : [+-][0-9]+.[0-9]+[[eE][+-][0-9]+]
142 - Booleans : TRUE | FALSE
143 - Strings : "string contents"
144 - Identifiers : my_identifier (string without space)
145
146 3.5. variables
147 --------------
148
149 You can declare a variable using the syntax :
150
151 VarName = Value
152
153 Where VarName is a string (no spaces or special chars) and Value is of
154 type int, real, bool or string.
155
156 note : the type of the variable is implicit
157
158 Ex.:
159
160 DefaultBackgroundColor = "Red"
161 RefreshInterval = 1000
162 AlwaysConfirm = TRUE
163 # according to eXdbm, pi is a variable !
164 PI = 3.14159265
165
166 3.6. lists
167 ----------
168
169 A list definition starts on a new line by the name of the list
170 followed by a {. Each element of a list is a variable definition or a
171 sublist. A list is ended with a } on a new line.
172
173 note : The variable declared outside a list is called a global variable.
174
175 Ex.:
176
177 FORMAT_LIST {
178
179 TAR_GZ {
180 Description = "gzipped tar archive"
181 Magic = "\\032\\341"
182 Pattern = "*.tar.gz:*.tgz:*_tar.gz"
183 ViewCommand = "%DEFAULT"
184 EditCommand = "eXtar"
185 }
186
187 IMAGE {
188 Description = "graphic image"
189 Magic = "%NONE"
190 Pattern = "*.gif":"*.jpg":"*.tga"
191 ViewCommand = "%DEFAULT"
192 EditCommand = "gimp"
193 }
194
195 IMAGE_GIF {
196 Description = "gif image"
197 Magic = "\\0123\\0321"
198 Pattern = "*.gif"
199 ViewCommand = "%DEFAULT"
200 EditCommand = "gimp"
201 }
202 }
203
204
205 4. Provided API
206 ---------------
207
208 4.1. new types
209 --------------
210
211 DB_ID -> a database identifier
212 DB_LIST -> a list variable
213
214 4.2. error handling
215 -------------------
216
217 The eXdbm functions return 0 on error and 1 on success.
218
219 NAME
220 eXdbmGetLastError()
221 SYNOPSIS
222 int eXdbmGetLastError(void);
223 DESCRIPTION
224 Get the last error code
225 RETURN VALUE
226 An eXode error code
227
228 NAME
229 eXdbmGetErrorString()
230 SYNOPSIS
231 const char * eXdbmGetErrorString(int errorcode);
232 DESCRIPTION
233 Get an error message corresponding to the error parameter
234 RETURN VALUE
235 A string containing the error message
236
237 NAME
238 eXdbmLastLineParsed();
239 SYNOPSIS
240 int eXdbmLastLineParsed(void);
241 DESCRIPTION
242 This function returns the number of the last line parsed while reading the last database file. This is usefull to locate a parsing error.
243 EXAMPLE
244 The following code prints a detailed error message
245
246 #include <eXdbm.h>
247 #include <stdio.h>
248
249 int ret;
250 DB_ID dbid;
251 int error;
252 char *message;
253 int last_line;
254 ...
255 ret = eXdbmOpenDatabse("mydb.cfg", &dbid);
256 if(ret == -1) {
257 printf("\nAn error has occured\n);
258 /* get the error number */
259 error = eXdbmGetLastError();
260 /* get the standard error message */
261 message = eXdbmGetErrorString(error);
262 /* get the last line parsed */
263 last_line = eXdbmLastLineParsed();
264
265 /* print a detailed error message */
266 printf("Error number %d : %s\n", error, message);
267 printf("Last line parsed = %d\n", last_line);
268 }
269 ...
270
271 Example of output :
272
273 An error has occured
274 eXdbmOpenDatabase : Cannot parse variable value
275 Last line parsed = 25
276
277 RETURN VALUE
278 -1 on error
279 >0 on success
280
281 4.3. opening & closing a databases
282 ----------------------------------
283
284 NAME
285 eXdbmInit()
286 SYNOPSIS
287 int eXdbmInit(void);
288 DESCRIPTION
289 Initialize the database manager. This function must be call before any other eXdbm function call.
290 RETURN VALUE
291 -1 on error
292 >0 on success
293
294 NAME
295 eXdbmOpenDatabase()
296 SYNOPSIS
297 int eXdbmOpenDatabase(char *filename, DBID *dbid);
298 DESCRIPTION
299 Open the filename database file.
300 dbid is a pointer to an integer : an unique identifier for the opened database
301
302 RETURN VALUE
303 -1 on error
304 >0 on success
305
306 NAME
307 eXdbmNewDatabase()
308 SYNOPSIS
309 int eXdbmOpenDatabase(char *filename, DB_ID *dbid);
310 DESCRIPTION
311 Create a new database which will use the file filename.
312 dbid is a pointer to an integer : an unique identifier for the opened database
313 RETURN VALUE
314 -1 on error
315 >0 on success
316
317 NAME
318 eXdbmUpdateDatabase()
319 SYNOPSIS
320 int eXdbmUpdateDatabase(DB_ID dbid);
321 DESCRIPTION
322 Save the database identified by dbid. This assure the actual database contents is the same in memory and on disk.
323 RETURN VALUE
324 -1 on error
325 >0 on success
326
327 NAME
328 eXdbmBackupDatabase()
329 SYNOPSIS
330 int eXdbmBackupDatabase(DB_ID dbid, char *filename);
331 DESCRIPTION
332 Make a backup copy of the database identified by dbid in the file filename. This file must be writeable by the current user.
333 RETURN VALUE
334 -1 on error
335 >0 on success
336
337 NAME
338 eXdbmCloseDatabase()
339 SYNOPSIS
340 int eXdbmCloseDatabase(DBID dbid, int update)
341 DESCRIPTION
342 The function you have to call to close a database. If udate = 1 (defined as TRUE in eXdbm.h), the database file will be updated, see eXdbmUpdateDatabase().
343 RETURN VALUE
344 -1 on error
345 >0 on success
346
347 4.4. Generic entry management
348 -----------------------------
349
350 4.4.1. get the type of an entry
351 -------------------------------
352
353 NAME
354 eXdbmGetEntryType()
355 SYNOPSIS
356 int eXdbmGetEntryType(DB_ID dbid, DB_LIST list, char *entryname);
357 DESCRIPTION
358 This function returns the type of the entry identified by :
359 dbid : the database identifier
360 list : the parent's list of the entry (NULL for level 0 entry)
361 entryname : the name of the entry
362 RETURN VALUE
363 -1 (DBM_ENTRY_NOT_FOUND) on error
364 On succes, the type of the entry :
365 - DBM_ENTRY_LIST : a list entry
366 - DBM_ENTRY_VAR_INT : an integer variable
367 - DBM_ENTRY_VAR_BOOL : a boolean variable
368 - DBM_ENTRY_VAR_REAL : a real number variable
369 - DBM_ENTRY_VAR_STRING : a string variable
370 - DBM_ENTRY_VAR_ID : an identifier variable
371
372 4.4.2. Comments management
373 --------------------------
374
375 NAME
376 eXdbmGetEntryComment()
377 SYNOPSIS
378 char * eXdbmGetEntryComment(DB_ID dbid, DB_LIST list, char *entryname);
379 DESCRIPTION
380 Returns the associated comment of an entry if it exists, or NULL. The entry is specified by :
381 dbid : the database identifier
382 list : the parent's list of the entry (NULL for level 0 entry)
383 entryname : the name of the entry
384 RETURN VALUE
385 A pointer to the comment string
386 or NULL
387
388 NAME
389 eXdbmChangeEntryComment()
390 SYNOPSIS
391 int eXdbmChangeEntryComment(DB_ID dbid, DB_LIST list, char *entryname, char *comment);
392 DESCRIPTION
393 Changes the associated comment of an entry. The entry is specified by :
394 dbid : the database identifier
395 list : the parent's list of the entry (NULL for level 0 entry)
396 entryname : the name of the entry
397 comment is the new comment string
398 NOTE
399 The function allocates the memory needed for the comment and copy the string you provide.
400 You must ensure the specifier string starts with a # character. If this is not the case, eXdbm won't be able to parse the database file containing a comment that is not starting with #.
401
402 RETURN VALUE
403 -1 on error
404 >0 on success
405
406 4.4.3 delete an entry
407 ---------------------
408
409 NAME
410 eXdbmDeleteEntry()
411 SYNOPSIS
412 int eXdbmDeleteEntry(DB_ID dbid, DB_LIST list, char *entryname);
413 DESCRIPTION
414 This function deletes the entry specified by
415 dbid : the database identifier
416 list : the parent's list of the entry (NULL for level 0 entry)
417 entryname : the name of the entry
418 if the entry is a list, all the entries is contains are also destroyed, recursively.
419 RETURN VALUE
420 -1 on error
421 >0 on sucess
422
423 4.5. list management
424 --------------------
425
426 4.5.1. get a list identifier
427 ----------------------------
428
429 NAME
430 eXdbmGetList()
431 SYNOPSIS
432 DB_LIST eXdbmGetList(DB_ID dbid, DB_LIST list, char *listname);
433 DESCRIPTION
434 get the identifier of the sublist of name listname in list.
435 if list is NULL, sublistname is the name of a first level list
436 RETURN VALUE
437 A pointer to the found DB_LIST structure.
438 If the value is NULL, the Sublist doesn't exist (an error is raised,
439 the eXdbmGetError returns an error).
440
441 NAME
442 eXdbmSearchList()
443 SYNOPSIS
444 DB_LIST eXdbmSearchList(DB_ID dbid, DB_LIST list, char *listname);
445 DESCRIPTION
446 search recursively the list of name listname in list and all of its sublists.
447 If list is NULL, search in all the lists of the database.
448 NOTE
449 The behaviour of this function is hard to predict if more than one list is of name listname.
450 RETURN VALUE
451 A pointer to the found LIST structure.
452 If the value is NULL, the Sublist doesn't exist (an error is raised,
453 the eXdbmGetError returns an error).
454
455 NAME
456 eXdbmPathList()
457 SYNOPSIS
458 DB_LIST eXdbmPathList(DB_ID dbid, char *path);
459 DESCRIPTION
460 This function returns the list referenced by its full path name in the database. A pathname is a serie of list names separated by colons.
461 EXAMPLE
462
463 list:sublist:susublist
464
465 refers to the list of name subsublist defined in sublist which is defined in list.
466 NOTE
467 The root list (referenced as NULL) is implicit
468 RETURN VALUE
469 A pointer to the found LIST structure.
470 If the value is NULL, the list doesn't exist (an error is raised,
471 the eXdbmGetError returns an error).
472
473 4.5.2. create an empty list
474 ---------------------------
475
476 NAME
477 eXdbmCreateList()
478 SYNOPSIS
479 int eXdbmCreateList(DBID dbid, LIST *list, char *entryname, char *comment);
480 DESCRIPTION
481 Create an empty list of name entryname
482 list is the parent list (NULL is the new list is global)
483 comment is a string to comment the new list
484 RETURN VALUE
485 -1 on error
486 >0 on success
487
488 4.6. Variable management
489 ------------------------
490
491 In the following functions : <TYPE> must be replaced by the type of
492 the variable : Int, Real, Bool, Ident or String. <CTYPE> is the corresponding
493 C datatype.
494
495 <TYPE> <CTYPE>
496 Int int
497 Real double
498 Bool int (0 = FALSE, 1 = TRUE)
499 Ident char *
500 String char *
501
502 4.6.1. read a value
503 -------------------
504
505 NAME
506 eXdbmGetVar<TYPE>()
507 SYNOPSIS
508 int eXdbmGetVar<TYPE> (DBID dbid, DB_LIST list, char *entryname, <CTYPE>* value);
509 DESCRIPTION
510 Read the value of a variable.
511 dbid is the database ID
512 list is the parent's list
513 entry is the name of the variable. V
514 Value is a pointer to a variable of the desired C type.
515 EXAMPLE
516
517 ...
518 int ival;
519 double rval;
520 char *sval;
521 int bval;
522 char *idval;
523
524 int ret;
525 ...
526 ret = eXdbmGetVarInt(dbid, parent, "intvar", &ival);
527 ret = eXdbmGetVarBool(dbid, parent, "boolvar", &bval);
528 ret = eXdbmGetVarReal(dbid, parent, "realvar", &rval);
529 ret = eXdbmGetVarString(dbid, parent, "stringvar", &sval);
530 ret = eXdbmGetVarIdent(dbid, parent, "identvar", &idval);
531 ...
532
533 NOTE
534 If <TYPE> is String or Ident, the value pointer references a copy of the value coded by the variable. You must free() this memory when you don't need it anymore.
535
536 RETURN VALUE
537 -1 on error
538 >0 on success
539
540 4.6.2. create a variable
541 ------------------------
542
543 NAME
544 eXdbmCreateVar<TYPE>()
545 SYNOPSIS
546 int eXdbmCreateVar<TYPE>(DBID dbid, DB_LIST list, char *entryname, char *comment, <CTYPE> value);
547 DESCRIPTION
548 Add a variable to the database.
549 dbid is the database ID
550 list is the parent list of the entry (NULL is root for parent)
551 entryname is the name of the new variable
552 comment is the comment string associated to the variable (or NULL)
553 value is the value of the variable.
554 NOTE
555 The function allocates the memory needed for the comment and copy the string you provide.
556 RETURN VALUE
557 -1 on error
558 >0 on success
559
560
561 4.6.3. Modify a variable
562 ------------------------
563
564 NAME
565 eXdbmChangeVar<TYPE> ()
566 SYNOPSIS
567 int eXdbmChangeVar<TYPE>(DBID dbid, DB_LIST list, char *entryname, <CTYPE> newvalue);
568 DESCRIPTION
569 Change the value of a variable in the database.
570 dbid is the database ID
571 list is the parent list of the entry (NULL is root for parent)
572 entryname is the name of the variable to be modified
573 newvalue is the new value of the variable.
574 NOTE
575 Use eXdbmChangeEntryComment() to change the comment associated to a variable.
576 RETURN VALUE
577 -1 on error
578 >0 on success
579
580
581 5. Using the library
582 --------------------
583
584 5.1. Installation instructions
585 ------------------------------
586
587 First, get the file :
588
589 eXdbm-status-version.tar.gz
590
591 where status is : alpha, beta or empty (final)
592 version is the version number (1.0b1 is the last version)
593
594 Then uncompress the file :
595
596 gzip -d eXdbm-status-version.tar.gz
597 tar xvf eXdbm-status-version.tar
598
599 Now, cd to eXdbm-status-version/
600
601 Then type :
602
603 make
604
605 and, as root :
606
607 make install
608
609 The default installation directories are :
610
611 /usr/local/include : header files
612 /usr/local/lib : library
613 /usr/local/doc/eXdbm : documentation
614
615 You can change these defaults by modifying the LIBDIR, INCDIR and DOCDIR make variable in Makefile.orig
616
617 5.2. Linking programs with libeXdbm.a
618 -------------------------------------
619
620 This is the command line you have to use in order to link your C programs with the eXdbm library :
621
622 cc myprogram.c -I/usr/local/include -L/usr/local/lib -leXdbm -lm
623
624 NOTE :
625 Don't forget the -lm statement, eXdbm uses a few math functions.
626
627 5.3. Sample programs
628 --------------------
629
630 The following programs demonstrates the use of the eXdbm library :
631
632 - test1 (test1.c)
633
634 Basic open/update/close functions
635
636 - test2 (test2.c)
637
638 Backup function test
639
640 - test3 (test3.c)
641
642 A console oriented small database manager that uses every functions provided in the eXdbm library.
643
644