1RELIC(3) Quick Database Manager RELIC(3)
2
6 Relic - the NDBM-compatible API of QDBM
7
10 #include <relic.h>
11 #include <stdlib.h>
12 #include <sys/types.h>
13 #include <sys/stat.h>
14 #include <fcntl.h>
15 typedef struct { void *dptr; size_t dsize; } datum;
17 DBM *dbm_open(char *name, int flags, int mode);
19 void dbm_close(DBM *db);
21 int dbm_store(DBM *db, datum key, datum content, int flags);
23 int dbm_delete(DBM *db, datum key);
25 datum dbm_fetch(DBM *db, datum key);
27 datum dbm_firstkey(DBM *db);
29 datum dbm_nextkey(DBM *db);
31 int dbm_error(DBM *db);
33 int dbm_clearerr(DBM *db);
35 int dbm_rdonly(DBM *db);
37 int dbm_dirfno(DBM *db);
39 int dbm_pagfno(DBM *db);
41
44 Relic is the API which is compatible with NDBM. So, Relic wraps func‐
45 tions of Depot as API of NDBM. It is easy to port an application from
46 NDBM to QDBM. In most cases, you should only replace the includings of
47 `ndbm.h' with `relic.h' and replace the linking option `-lndbm' with
48 `-lqdbm'.
49 The original NDBM treats a database as a pair of files. One, `a direc‐
51 tory file', has a name with suffix `.dir' and stores a bit map of keys.
52 The other, `a data file', has a name with suffix `.pag' and stores
53 entities of each records. Relic creates the directory file as a mere
54 dummy file and creates the data file as a database. Relic has no
55 restriction about the size of each record. Relic cannot handle data‐
56 base files made by the original NDBM.
57 In order to use Relic, you should include `relic.h', `stdlib.h',
59 `sys/types.h', `sys/stat.h' and `fcntl.h' in the source files. Usu‐
60 ally, the following description will be near the beginning of a source
61 file.
62 #include <relic.h>
64 #include <stdlib.h>
65 #include <sys/types.h>
66 #include <sys/stat.h>
67 #include <fcntl.h>
68 A pointer to `DBM' is used as a database handle. A database handle is
70 opened with the function `dbm_open' and closed with `dbm_close'. You
71 should not refer directly to any member of a handle.
72 Structures of `datum' type is used in order to give and receive data of
74 keys and values with functions of Relic.
75 typedef struct { void *dptr; size_t dsize; } datum;
77 `dptr' specifies the pointer to the region of a key or a value.
78 `dsize' specifies the size of the region.
79 The function `dbm_open' is used in order to get a database handle.
81 DBM *dbm_open(char *name, int flags, int mode);
83 `name' specifies the name of a database. The file names are
84 concatenated with suffixes. `flags' is the same as one of
85 `open' call, although `O_WRONLY' is treated as `O_RDWR' and
86 additional flags except for `O_CREAT' and `O_TRUNC' have no
87 effect. `mode' specifies the mode of the database file as one
88 of `open' call does. The return value is the database handle or
89 `NULL' if it is not successful.
90 The function `dbm_close' is used in order to close a database handle.
92 void dbm_close(DBM *db);
94 `db' specifies a database handle. Because the region of the
95 closed handle is released, it becomes impossible to use the han‐
96 dle.
97 The function `dbm_store' is used in order to store a record.
99 int dbm_store(DBM *db, datum key, datum content, int flags);
101 `db' specifies a database handle. `key' specifies a structure
102 of a key. `content' specifies a structure of a value. `flags'
103 specifies behavior when the key overlaps, by the following val‐
104 ues: `DBM_REPLACE', which means the specified value overwrites
105 the existing one, `DBM_INSERT', which means the existing value
106 is kept. The return value is 0 if it is successful, 1 if it
107 gives up because of overlaps of the key, -1 if other error
108 occurs.
109 The function `dbm_delete' is used in order to delete a record.
111 int dbm_delete(DBM *db, datum key);
113 `db' specifies a database handle. `key' specifies a structure
114 of a key. The return value is 0 if it is successful, -1 if some
115 errors occur.
116 The function `dbm_fetch' is used in order to retrieve a record.
118 datum dbm_fetch(DBM *db, datum key);
120 `db' specifies a database handle. `key' specifies a structure
121 of a key. The return value is a structure of the result. If a
122 record corresponds, the member `dptr' of the structure is the
123 pointer to the region of the value. If no record corresponds or
124 some errors occur, `dptr' is `NULL'. `dptr' points to the
125 region related with the handle. The region is available until
126 the next time of calling this function with the same handle.
127 The function `dbm_firstkey' is used in order to get the first key of a
129 database.
130 datum dbm_firstkey(DBM *db);
132 `db' specifies a database handle. The return value is a struc‐
133 ture of the result. If a record corresponds, the member `dptr'
134 of the structure is the pointer to the region of the first key.
135 If no record corresponds or some errors occur, `dptr' is `NULL'.
136 `dptr' points to the region related with the handle. The region
137 is available until the next time of calling this function or the
138 function `dbm_nextkey' with the same handle.
139 The function `dbm_nextkey' is used in order to get the next key of a
141 database.
142 datum dbm_nextkey(DBM *db);
144 `db' specifies a database handle. The return value is a struc‐
145 ture of the result. If a record corresponds, the member `dptr'
146 of the structure is the pointer to the region of the next key.
147 If no record corresponds or some errors occur, `dptr' is `NULL'.
148 `dptr' points to the region related with the handle. The region
149 is available until the next time of calling this function or the
150 function `dbm_firstkey' with the same handle.
151 The function `dbm_error' is used in order to check whether a database
153 has a fatal error or not.
154 int dbm_error(DBM *db);
156 `db' specifies a database handle. The return value is true if
157 the database has a fatal error, false if not.
158 The function `dbm_clearerr' has no effect.
160 int dbm_clearerr(DBM *db);
162 `db' specifies a database handle. The return value is 0. The
163 function is only for compatibility.
164 The function `dbm_rdonly' is used in order to check whether a handle is
166 read-only or not.
167 int dbm_rdonly(DBM *db);
169 `db' specifies a database handle. The return value is true if
170 the handle is read-only, or false if not read-only.
171 The function `dbm_dirfno' is used in order to get the file descriptor
173 of a directory file.
174 int dbm_dirfno(DBM *db);
176 `db' specifies a database handle. The return value is the file
177 descriptor of the directory file.
178 The function `dbm_pagfno' is used in order to get the file descriptor
180 of a data file.
181 int dbm_pagfno(DBM *db);
183 `db' specifies a database handle. The return value is the file
184 descriptor of the data file.
185 Functions of Relic are thread-safe as long as a handle is not accessed
187 by threads at the same time, on the assumption that `errno', `malloc',
188 and so on are thread-safe.
189
192 qdbm(3), depot(3), curia(3), hovel(3), cabin(3), villa(3), odeum(3),
193 ndbm(3), gdbm(3)
194Man Page 2004-04-22 RELIC(3)