xref: /illumos-gate/usr/src/cmd/sendmail/include/libsmdb/smdb.h (revision 2a8bcb4efb45d99ac41c94a75c396b362c414f7f)
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 #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_ */
361