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_ */