usr/src/cmd/sendmail/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.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_ */