contrib/sendmail/include/libsmdb/smdb.h

   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
  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 **
 123 **      Returns:
 124 **              0 - Success, otherwise errno.
 125 **
 126 */
 127
 128 typedef 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
 144 typedef 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
 159 typedef 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
 174 typedef int (*db_cursor_func) __P((SMDB_DATABASE *db,
 175                               SMDB_CURSOR **cursor, unsigned int flags));
 176
 177 typedef int (*db_lockfd_func) __P((SMDB_DATABASE *db));
 178
 179 struct 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
 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       /* 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
 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_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
 352 typedef int (smdb_open_func) __P((SMDB_DATABASE **, char *, int, int, long, SMDB_DBTYPE, SMDB_USER_INFO *, SMDB_DBPARAMS *));
 353
 354 extern SMDB_DATABASE    *smdb_malloc_database __P((void));
 355 extern void             smdb_free_database __P((SMDB_DATABASE *));
 356 extern smdb_open_func   smdb_open_database;
 357 # if NEWDB
 358 extern smdb_open_func   smdb_db_open;
 359 # else
 360 #  define smdb_db_open  NULL
 361 # endif
 362 # if NDBM
 363 extern smdb_open_func   smdb_ndbm_open;
 364 # else
 365 #  define smdb_ndbm_open        NULL
 366 # endif
 367 extern int              smdb_add_extension __P((char *, int, char *, char *));
 368 extern int              smdb_setup_file __P((char *, char *, int, long,
 369                                              SMDB_USER_INFO *, struct stat *));
 370 extern int              smdb_lock_file __P((int *, char *, int, long, char *));
 371 extern int              smdb_unlock_file __P((int));
 372 extern int              smdb_filechanged __P((char *, char *, int,
 373                                               struct stat *));
 374 extern void             smdb_print_available_types __P((bool));
 375 extern bool             smdb_is_db_type __P((const char *));
 376 extern char             *smdb_db_definition __P((SMDB_DBTYPE));
 377 extern int              smdb_lock_map __P((SMDB_DATABASE *, int));
 378 extern int              smdb_unlock_map __P((SMDB_DATABASE *));
 379
 380 # if CDB
 381 extern smdb_open_func   smdb_cdb_open;
 382 # else
 383 #  define smdb_cdb_open         NULL
 384 # endif
 385 #endif /* ! _SMDB_H_ */