Merge from vendor branch CVS:
[dragonfly.git] / contrib / sendmail-8.13.8 / include / libsmdb / smdb.h
1 /*
2  * Copyright (c) 1999-2002 Sendmail, Inc. and its suppliers.
3  *      All rights reserved.
4  *
5  * By using this file, you agree to the terms and conditions set
6  * forth in the LICENSE file which can be found at the top level of
7  * the sendmail distribution.
8  *
9  *      $Id: smdb.h,v 8.41 2002/09/24 19:53:28 ca Exp $
10  *
11  */
12
13 #ifndef _SMDB_H_
14 # define _SMDB_H_
15
16 # include <sys/types.h>
17 # include <sys/stat.h>
18 # include <sm/gen.h>
19 # include <sm/errstring.h>
20
21 # ifdef NDBM
22 #  include <ndbm.h>
23 # endif /* NDBM */
24
25 # ifdef NEWDB
26 #  include "sm/bdb.h"
27 # endif /* NEWDB */
28
29 /*
30 **  Some size constants
31 */
32
33 #define SMDB_MAX_USER_NAME_LEN  1024
34
35 /*
36 **  This file defines the abstraction for database lookups. It is pretty
37 **  much a copy of the db2 interface with the exception that every function
38 **  returns 0 on success and non-zero on failure. The non-zero return code
39 **  is meaningful.
40 **
41 **  I'm going to put the function comments in this file since the interface
42 **  MUST be the same for all inheritors of this interface.
43 */
44
45 typedef struct database_struct SMDB_DATABASE;
46 typedef struct cursor_struct SMDB_CURSOR;
47 typedef struct entry_struct SMDB_DBENT;
48
49 /*
50 **  DB_CLOSE_FUNC -- close the database
51 **
52 **      Parameters:
53 **              db -- The database to close.
54 **
55 **      Returns:
56 **              0 - Success, otherwise errno.
57 **
58 */
59
60 typedef int (*db_close_func) __P((SMDB_DATABASE *db));
61
62 /*
63 **  DB_DEL_FUNC -- removes a key and data pair from the database
64 **
65 **      Parameters:
66 **              db -- The database to close.
67 **              key -- The key to remove.
68 **              flags -- delete options. There are currently no defined
69 **                       flags for delete.
70 **
71 **      Returns:
72 **              0 - Success, otherwise errno.
73 **
74 */
75
76 typedef int (*db_del_func) __P((SMDB_DATABASE *db,
77                            SMDB_DBENT *key, unsigned int flags));
78
79 /*
80 **  DB_FD_FUNC -- Returns a pointer to a file used for the database.
81 **
82 **      Parameters:
83 **              db -- The database to close.
84 **              fd -- A pointer to store the returned fd in.
85 **
86 **      Returns:
87 **              0 - Success, otherwise errno.
88 **
89 */
90
91 typedef int (*db_fd_func) __P((SMDB_DATABASE *db, int* fd));
92
93 /*
94 **  DB_GET_FUNC -- Gets the data associated with a key.
95 **
96 **      Parameters:
97 **              db -- The database to close.
98 **              key -- The key to access.
99 **              data -- A place to store the returned data.
100 **              flags -- get options. There are currently no defined
101 **                       flags for get.
102 **
103 **      Returns:
104 **              0 - Success, otherwise errno.
105 **
106 */
107
108 typedef int (*db_get_func) __P((SMDB_DATABASE *db,
109                            SMDB_DBENT *key,
110                            SMDB_DBENT *data, unsigned int flags));
111
112 /*
113 **  DB_PUT_FUNC -- Sets some data according to the key.
114 **
115 **      Parameters:
116 **              db -- The database to close.
117 **              key -- The key to use.
118 **              data -- The data to store.
119 **              flags -- put options:
120 **                      SMDBF_NO_OVERWRITE - Return an error if key alread
121 **                                           exists.
122 **                      SMDBF_ALLOW_DUP - Allow duplicates in btree maps.
123 **
124 **      Returns:
125 **              0 - Success, otherwise errno.
126 **
127 */
128
129 typedef int (*db_put_func) __P((SMDB_DATABASE *db,
130                            SMDB_DBENT *key,
131                            SMDB_DBENT *data, unsigned int flags));
132
133 /*
134 **  DB_SYNC_FUNC -- Flush any cached information to disk.
135 **
136 **      Parameters:
137 **              db -- The database to sync.
138 **              flags -- sync options:
139 **
140 **      Returns:
141 **              0 - Success, otherwise errno.
142 **
143 */
144
145 typedef int (*db_sync_func) __P((SMDB_DATABASE *db, unsigned int flags));
146
147 /*
148 **  DB_SET_OWNER_FUNC -- Set the owner and group of the database files.
149 **
150 **      Parameters:
151 **              db -- The database to set.
152 **              uid -- The UID for the new owner (-1 for no change)
153 **              gid -- The GID for the new owner (-1 for no change)
154 **
155 **      Returns:
156 **              0 - Success, otherwise errno.
157 **
158 */
159
160 typedef int (*db_set_owner_func) __P((SMDB_DATABASE *db, uid_t uid, gid_t gid));
161
162 /*
163 **  DB_CURSOR -- Obtain a cursor for sequential access
164 **
165 **      Parameters:
166 **              db -- The database to use.
167 **              cursor -- The address of a cursor pointer.
168 **              flags -- sync options:
169 **
170 **      Returns:
171 **              0 - Success, otherwise errno.
172 **
173 */
174
175 typedef int (*db_cursor_func) __P((SMDB_DATABASE *db,
176                               SMDB_CURSOR **cursor, unsigned int flags));
177
178 typedef int (*db_lockfd_func) __P((SMDB_DATABASE *db));
179
180 struct database_struct
181 {
182         db_close_func           smdb_close;
183         db_del_func             smdb_del;
184         db_fd_func              smdb_fd;
185         db_get_func             smdb_get;
186         db_put_func             smdb_put;
187         db_sync_func            smdb_sync;
188         db_set_owner_func       smdb_set_owner;
189         db_cursor_func          smdb_cursor;
190         db_lockfd_func          smdb_lockfd;
191         void                    *smdb_impl;
192 };
193 /*
194 **  DB_CURSOR_CLOSE -- Close a cursor
195 **
196 **      Parameters:
197 **              cursor -- The cursor to close.
198 **
199 **      Returns:
200 **              0 - Success, otherwise errno.
201 **
202 */
203
204 typedef int (*db_cursor_close_func) __P((SMDB_CURSOR *cursor));
205
206 /*
207 **  DB_CURSOR_DEL -- Delete the key/value pair of this cursor
208 **
209 **      Parameters:
210 **              cursor -- The cursor.
211 **              flags -- flags
212 **
213 **      Returns:
214 **              0 - Success, otherwise errno.
215 **
216 */
217
218 typedef int (*db_cursor_del_func) __P((SMDB_CURSOR *cursor,
219                                         unsigned int flags));
220
221 /*
222 **  DB_CURSOR_GET -- Get the key/value of this cursor.
223 **
224 **      Parameters:
225 **              cursor -- The cursor.
226 **              key -- The current key.
227 **              value -- The current value
228 **              flags -- flags
229 **
230 **      Returns:
231 **              0 - Success, otherwise errno.
232 **              SMDBE_LAST_ENTRY - This is a success condition that
233 **                                 gets returned when the end of the
234 **                                 database is hit.
235 **
236 */
237
238 typedef int (*db_cursor_get_func) __P((SMDB_CURSOR *cursor,
239                                   SMDB_DBENT *key,
240                                   SMDB_DBENT *data,
241                                   unsigned int flags));
242
243 /*
244 **  Flags for DB_CURSOR_GET
245 */
246
247 #define SMDB_CURSOR_GET_FIRST   0
248 #define SMDB_CURSOR_GET_LAST    1
249 #define SMDB_CURSOR_GET_NEXT    2
250 #define SMDB_CURSOR_GET_RANGE   3
251
252 /*
253 **  DB_CURSOR_PUT -- Put the key/value at this cursor.
254 **
255 **      Parameters:
256 **              cursor -- The cursor.
257 **              key -- The current key.
258 **              value -- The current value
259 **              flags -- flags
260 **
261 **      Returns:
262 **              0 - Success, otherwise errno.
263 **
264 */
265
266 typedef int (*db_cursor_put_func) __P((SMDB_CURSOR *cursor,
267                                   SMDB_DBENT *key,
268                                   SMDB_DBENT *data,
269                                   unsigned int flags));
270
271
272
273 struct cursor_struct
274 {
275         db_cursor_close_func    smdbc_close;
276         db_cursor_del_func      smdbc_del;
277         db_cursor_get_func      smdbc_get;
278         db_cursor_put_func      smdbc_put;
279         void                    *smdbc_impl;
280 };
281
282
283 struct database_params_struct
284 {
285         unsigned int    smdbp_num_elements;
286         unsigned int    smdbp_cache_size;
287         bool            smdbp_allow_dup;
288 };
289
290 typedef struct database_params_struct SMDB_DBPARAMS;
291
292 struct database_user_struct
293 {
294         uid_t   smdbu_id;
295         gid_t   smdbu_group_id;
296         char    smdbu_name[SMDB_MAX_USER_NAME_LEN];
297 };
298
299 typedef struct database_user_struct SMDB_USER_INFO;
300
301 struct entry_struct
302 {
303         void    *data;
304         size_t  size;
305 };
306
307 typedef char *SMDB_DBTYPE;
308 typedef unsigned int SMDB_FLAG;
309
310 /*
311 **  These are types of databases.
312 */
313
314 # define SMDB_TYPE_DEFAULT      NULL
315 # define SMDB_TYPE_DEFAULT_LEN  0
316 # define SMDB_TYPE_HASH         "hash"
317 # define SMDB_TYPE_HASH_LEN     5
318 # define SMDB_TYPE_BTREE        "btree"
319 # define SMDB_TYPE_BTREE_LEN    6
320 # define SMDB_TYPE_NDBM         "dbm"
321 # define SMDB_TYPE_NDBM_LEN     4
322
323 /*
324 **  These are flags
325 */
326
327 /* Flags for put */
328 # define SMDBF_NO_OVERWRITE     0x00000001
329 # define SMDBF_ALLOW_DUP        0x00000002
330
331
332 extern SMDB_DATABASE    *smdb_malloc_database __P((void));
333 extern void             smdb_free_database __P((SMDB_DATABASE *));
334 extern int              smdb_open_database __P((SMDB_DATABASE **, char *, int,
335                                                 int, long, SMDB_DBTYPE,
336                                                 SMDB_USER_INFO *,
337                                                 SMDB_DBPARAMS *));
338 # ifdef NEWDB
339 extern int              smdb_db_open __P((SMDB_DATABASE **, char *, int, int,
340                                           long, SMDB_DBTYPE, SMDB_USER_INFO *,
341                                           SMDB_DBPARAMS *));
342 # endif /* NEWDB */
343 # ifdef NDBM
344 extern int              smdb_ndbm_open __P((SMDB_DATABASE **, char *, int, int,
345                                             long, SMDB_DBTYPE,
346                                             SMDB_USER_INFO *,
347                                             SMDB_DBPARAMS *));
348 # endif /* NDBM */
349 extern int              smdb_add_extension __P((char *, int, char *, char *));
350 extern int              smdb_setup_file __P((char *, char *, int, long,
351                                              SMDB_USER_INFO *, struct stat *));
352 extern int              smdb_lock_file __P((int *, char *, int, long, char *));
353 extern int              smdb_unlock_file __P((int));
354 extern int              smdb_filechanged __P((char *, char *, int,
355                                               struct stat *));
356 extern void             smdb_print_available_types __P((void));
357 extern char             *smdb_db_definition __P((SMDB_DBTYPE));
358 extern int              smdb_lock_map __P((SMDB_DATABASE *, int));
359 extern int              smdb_unlock_map __P((SMDB_DATABASE *));
360 #endif /* ! _SMDB_H_ */