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