smdb.h revision 363466
1/* 2 * Copyright (c) 1999-2002, 2018 Proofpoint, 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.42 2013-11-22 20:51: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# if NDBM 22# include <ndbm.h> 23# endif 24 25# if NEWDB 26# include "sm/bdb.h" 27# endif 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 45typedef struct database_struct SMDB_DATABASE; 46typedef struct cursor_struct SMDB_CURSOR; 47typedef 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 60typedef 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 76typedef 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 91typedef 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 108typedef 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** 123** Returns: 124** 0 - Success, otherwise errno. 125** 126*/ 127 128typedef int (*db_put_func) __P((SMDB_DATABASE *db, 129 SMDB_DBENT *key, 130 SMDB_DBENT *data, unsigned int flags)); 131 132/* 133** DB_SYNC_FUNC -- Flush any cached information to disk. 134** 135** Parameters: 136** db -- The database to sync. 137** flags -- sync options: 138** 139** Returns: 140** 0 - Success, otherwise errno. 141** 142*/ 143 144typedef int (*db_sync_func) __P((SMDB_DATABASE *db, unsigned int flags)); 145 146/* 147** DB_SET_OWNER_FUNC -- Set the owner and group of the database files. 148** 149** Parameters: 150** db -- The database to set. 151** uid -- The UID for the new owner (-1 for no change) 152** gid -- The GID for the new owner (-1 for no change) 153** 154** Returns: 155** 0 - Success, otherwise errno. 156** 157*/ 158 159typedef int (*db_set_owner_func) __P((SMDB_DATABASE *db, uid_t uid, gid_t gid)); 160 161/* 162** DB_CURSOR -- Obtain a cursor for sequential access 163** 164** Parameters: 165** db -- The database to use. 166** cursor -- The address of a cursor pointer. 167** flags -- sync options: 168** 169** Returns: 170** 0 - Success, otherwise errno. 171** 172*/ 173 174typedef int (*db_cursor_func) __P((SMDB_DATABASE *db, 175 SMDB_CURSOR **cursor, unsigned int flags)); 176 177typedef int (*db_lockfd_func) __P((SMDB_DATABASE *db)); 178 179struct database_struct 180{ 181 db_close_func smdb_close; 182 db_del_func smdb_del; 183 db_fd_func smdb_fd; 184 db_get_func smdb_get; 185 db_put_func smdb_put; 186 db_sync_func smdb_sync; 187 db_set_owner_func smdb_set_owner; 188 db_cursor_func smdb_cursor; 189 db_lockfd_func smdb_lockfd; 190 void *smdb_impl; 191}; 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 204typedef 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 218typedef 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 238typedef 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 /* NOT USED by any application */ 248#define SMDB_CURSOR_GET_LAST 1 /* NOT USED by any application */ 249#define SMDB_CURSOR_GET_NEXT 2 250#define SMDB_CURSOR_GET_RANGE 3 /* NOT USED by any application */ 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 266typedef int (*db_cursor_put_func) __P((SMDB_CURSOR *cursor, 267 SMDB_DBENT *key, 268 SMDB_DBENT *data, 269 unsigned int flags)); 270 271 272 273struct 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 283struct database_params_struct 284{ 285 unsigned int smdbp_num_elements; 286 unsigned int smdbp_cache_size; 287 bool smdbp_allow_dup; 288}; 289 290typedef struct database_params_struct SMDB_DBPARAMS; 291 292struct 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 299typedef struct database_user_struct SMDB_USER_INFO; 300 301struct entry_struct 302{ 303 void *data; 304 size_t size; 305}; 306 307typedef char *SMDB_DBTYPE; 308typedef 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_IMPL "implicit" 317# define SMDB_TYPE_IMPL_LEN 9 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# define SMDB_TYPE_CDB "cdb" 325# define SMDB_TYPE_CDB_LEN 4 326 327# define SMDB_IS_TYPE_HASH(type) (strncmp(type, SMDB_TYPE_HASH, SMDB_TYPE_HASH_LEN) == 0) 328# define SMDB_IS_TYPE_BTREE(type) (strncmp(type, SMDB_TYPE_BTREE, SMDB_TYPE_BTREE_LEN) == 0) 329# define SMDB_IS_TYPE_NDBM(type) (strncmp(type, SMDB_TYPE_NDBM, SMDB_TYPE_NDBM_LEN) == 0) 330# define SMDB_IS_TYPE_CDB(type) (strncmp(type, SMDB_TYPE_CDB, SMDB_TYPE_CDB_LEN) == 0) 331 332# define SMDB_IS_TYPE_DEFAULT(t) (((t) == SMDB_TYPE_DEFAULT) \ 333 || (strncmp(type, SMDB_TYPE_IMPL, SMDB_TYPE_IMPL_LEN) == 0) \ 334 ) 335 336# if CDB >= 2 337# define SMCDB_FILE_EXTENSION "db" 338# else 339# define SMCDB_FILE_EXTENSION "cdb" 340# endif 341# define SMDB1_FILE_EXTENSION "db" 342# define SMDB2_FILE_EXTENSION "db" 343# define SMNDB_DIR_FILE_EXTENSION "dir" 344 345/* 346** These are flags 347*/ 348 349/* Flags for put */ 350# define SMDBF_NO_OVERWRITE 0x00000001 351 352typedef int (smdb_open_func) __P((SMDB_DATABASE **, char *, int, int, long, SMDB_DBTYPE, SMDB_USER_INFO *, SMDB_DBPARAMS *)); 353 354extern SMDB_DATABASE *smdb_malloc_database __P((void)); 355extern void smdb_free_database __P((SMDB_DATABASE *)); 356extern smdb_open_func smdb_open_database; 357# if NEWDB 358extern smdb_open_func smdb_db_open; 359# else 360# define smdb_db_open NULL 361# endif 362# if NDBM 363extern smdb_open_func smdb_ndbm_open; 364# else 365# define smdb_ndbm_open NULL 366# endif 367extern int smdb_add_extension __P((char *, int, char *, char *)); 368extern int smdb_setup_file __P((char *, char *, int, long, 369 SMDB_USER_INFO *, struct stat *)); 370extern int smdb_lock_file __P((int *, char *, int, long, char *)); 371extern int smdb_unlock_file __P((int)); 372extern int smdb_filechanged __P((char *, char *, int, 373 struct stat *)); 374extern void smdb_print_available_types __P((bool)); 375extern bool smdb_is_db_type __P((const char *)); 376extern char *smdb_db_definition __P((SMDB_DBTYPE)); 377extern int smdb_lock_map __P((SMDB_DATABASE *, int)); 378extern int smdb_unlock_map __P((SMDB_DATABASE *)); 379 380# if CDB 381extern smdb_open_func smdb_cdb_open; 382# else 383# define smdb_cdb_open NULL 384# endif 385#endif /* ! _SMDB_H_ */ 386