rpmdb/rpmdb.h

   1 #ifndef H_RPMDB
   2 #define H_RPMDB
   3
   4 /** \ingroup rpmdb dbi db1 db3
   5  * \file rpmdb/rpmdb.h
   6  * Access RPM indices using Berkeley DB interface(s).
   7  */
   8
   9 #include <rpmlib.h>
  10
  11 #include "fprint.h"
  12
  13 /**
  14  */
  15 typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem;
  16
  17 /**
  18  */
  19 typedef /*@abstract@*/ struct _dbiIndex * dbiIndex;
  20
  21 /* this will break if sizeof(int) != 4 */
  22 /** \ingroup dbi
  23  * A single item from an index database (i.e. the "data returned").
  24  * Note: In rpm-3.0.4 and earlier, this structure was passed by value,
  25  * and was identical to the "data saved" structure below.
  26  */
  27 struct _dbiIndexItem {
  28     unsigned int hdrNum;                /*!< header instance in db */
  29     unsigned int tagNum;                /*!< tag index in header */
  30     unsigned int fpNum;                 /*!< finger print index */
  31     unsigned int dbNum;                 /*!< database index */
  32 };
  33
  34 #ifdef DYING
  35 /** \ingroup dbi
  36  * A single item in an index database (i.e. the "data saved").
  37  */
  38 struct _dbiIR {
  39 /*@unused@*/ unsigned int recOffset;    /*!< byte offset of header in db */
  40 /*@unused@*/ unsigned int fileNumber;   /*!< file array index */
  41 };
  42 /*@-typeuse@*/
  43 typedef struct _dbiIR * DBIR_t;
  44 /*@=typeuse@*/
  45 #endif  /* DYING */
  46
  47 /** \ingroup dbi
  48  * Items retrieved from the index database.
  49  */
  50 struct _dbiIndexSet {
  51 /*@owned@*/ struct _dbiIndexItem * recs; /*!< array of records */
  52     int count;                          /*!< number of records */
  53 };
  54
  55 /* XXX hack to get prototypes correct */
  56 #if !defined(DB_VERSION_MAJOR)
  57 #define DB      void
  58 #define DB_ENV  void
  59 #define DBC     void
  60 #define DBT     void
  61 #define DB_LSN  void
  62 #endif
  63
  64 /** \ingroup dbi
  65  * Private methods for accessing an index database.
  66  */
  67 struct _dbiVec {
  68     int dbv_major;                      /*!< Berkeley db version major */
  69     int dbv_minor;                      /*!< Berkeley db version minor */
  70     int dbv_patch;                      /*!< Berkeley db version patch */
  71
  72 /** \ingroup dbi
  73  * Return handle for an index database.
  74  * @param rpmdb         rpm database
  75  * @param rpmtag        rpm tag
  76  * @return              0 on success
  77  */
  78     int (*open) (rpmdb rpmdb, int rpmtag, /*@out@*/ dbiIndex * dbip)
  79         /*@modifies *dbip @*/;
  80
  81 /** \ingroup dbi
  82  * Close index database, and destroy database handle.
  83  * @param dbi           index database handle
  84  * @param flags         (unused)
  85  * @return              0 on success
  86  */
  87     int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags)
  88         /*@modifies dbi, fileSystem @*/;
  89
  90 /** \ingroup dbi
  91  * Flush pending operations to disk.
  92  * @param dbi           index database handle
  93  * @param flags         (unused)
  94  * @return              0 on success
  95  */
  96     int (*sync) (dbiIndex dbi, unsigned int flags)
  97         /*@modifies fileSystem @*/;
  98
  99 /** \ingroup dbi
 100  * Open database cursor.
 101  * @param dbi           index database handle
 102  * @param dbcp          address of database cursor
 103  * @param flags         (unused)
 104  */
 105     int (*copen) (dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags)
 106         /*@modifies dbi, *dbcp @*/;
 107
 108 /** \ingroup dbi
 109  * Close database cursor.
 110  * @param dbi           index database handle
 111  * @param dbcursor      database cursor
 112  * @param flags         (unused)
 113  */
 114     int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
 115         /*@modifies dbi, *dbcursor @*/;
 116
 117 /** \ingroup dbi
 118  * Delete (key,data) pair(s) using db->del or dbcursor->c_del.
 119  * @param dbi           index database handle
 120  * @param dbcursor      database cursor
 121  * @param keyp          key data
 122  * @param keylen        key data length
 123  * @param flags         (unused)
 124  * @return              0 on success
 125  */
 126     int (*cdel) (dbiIndex dbi, DBC * dbcursor,
 127                         const void * keyp, size_t keylen, unsigned int flags)
 128         /*@modifies *dbcursor, fileSystem @*/;
 129
 130 /** \ingroup dbi
 131  * Retrieve (key,data) pair using db->get or dbcursor->c_get.
 132  * @param dbi           index database handle
 133  * @param dbcursor      database cursor
 134  * @param keypp         address of key data
 135  * @param keylenp       address of key data length
 136  * @param datapp        address of data pointer
 137  * @param datalenp      address of data length
 138  * @param flags         (unused)
 139  * @return              0 on success
 140  */
 141     int (*cget) (dbiIndex dbi, DBC * dbcursor,
 142                         /*@null@*/ void ** keypp, /*@null@*/ size_t * keylenp,
 143                         /*@null@*/ void ** datapp, /*@null@*/ size_t * datalenp,
 144                         unsigned int flags)
 145         /*@modifies *dbcursor, *keypp, *keylenp, *datapp, *datalenp,
 146                 fileSystem @*/;
 147
 148 /** \ingroup dbi
 149  * Store (key,data) pair using db->put or dbcursor->c_put.
 150  * @param dbi           index database handle
 151  * @param dbcursor      database cursor
 152  * @param keyp          key data
 153  * @param keylen        key data length
 154  * @param datap         data pointer
 155  * @param datalen       data length
 156  * @param flags         (unused)
 157  * @return              0 on success
 158  */
 159     int (*cput) (dbiIndex dbi, DBC * dbcursor,
 160                         const void * keyp, size_t keylen,
 161                         const void * datap, size_t datalen,
 162                         unsigned int flags)
 163         /*@modifies *dbcursor, fileSystem @*/;
 164
 165 /** \ingroup dbi
 166  * Retrieve count of (possible) duplicate items using dbcursor->c_count.
 167  * @param dbi           index database handle
 168  * @param dbcursor      database cursor
 169  * @param countp        address of count
 170  * @param flags         (unused)
 171  * @return              0 on success
 172  */
 173     int (*ccount) (dbiIndex dbi, DBC * dbcursor,
 174                         /*@out@*/ unsigned int * countp,
 175                         unsigned int flags)
 176         /*@modifies *dbcursor @*/;
 177
 178 /** \ingroup dbi
 179  * Is database byte swapped?
 180  * @param dbi           index database handle
 181  * @return              0 no
 182  */
 183     int (*byteswapped) (dbiIndex dbi)
 184         /*@*/;
 185
 186 /** \ingroup dbi
 187  * Save statistics in database handle.
 188  * @param dbi           index database handle
 189  * @param flags         retrieve statistics that don't require traversal?
 190  * @return              0 on success
 191  */
 192     int (*stat) (dbiIndex dbi, unsigned int flags)
 193         /*@modifies dbi @*/;
 194
 195 };
 196
 197 /** \ingroup dbi
 198  * Describes an index database (implemented on Berkeley db3 functionality).
 199  */
 200 struct _dbiIndex {
 201 /*@null@*/ const char * dbi_root;       /*!< chroot(2) component of path */
 202 /*@null@*/ const char * dbi_home;       /*!< directory component of path */
 203 /*@null@*/ const char * dbi_file;       /*!< file component of path */
 204 /*@null@*/ const char * dbi_subfile;
 205 /*@null@*/ const char * dbi_tmpdir;     /*!< temporary directory */
 206
 207     int                 dbi_ecflags;    /*!< db_env_create flags */
 208     int                 dbi_cflags;     /*!< db_create flags */
 209     int                 dbi_oeflags;    /*!< common (db,dbenv}->open flags */
 210     int                 dbi_eflags;     /*!< dbenv->open flags */
 211     int                 dbi_oflags;     /*!< db->open flags */
 212     int                 dbi_tflags;     /*!< dbenv->txn_begin flags */
 213
 214     int                 dbi_type;       /*!< db index type */
 215     unsigned            dbi_mode;       /*!< mode to use on open */
 216     int                 dbi_perms;      /*!< file permission to use on open */
 217     long                dbi_shmkey;     /*!< shared memory base key */
 218     int                 dbi_api;        /*!< Berkeley API type */
 219
 220     int                 dbi_verify_on_close;
 221     int                 dbi_tear_down;  /*!< tear down dbenv on close */
 222     int                 dbi_use_cursors;/*!< access with cursors? (always) */
 223     int                 dbi_use_dbenv;  /*!< use db environment? */
 224     int                 dbi_permit_dups;/*!< permit duplicate entries? */
 225     int                 dbi_get_rmw_cursor;
 226     int                 dbi_no_fsync;   /*!< no-op fsync for db */
 227     int                 dbi_no_dbsync;  /*!< don't call dbiSync */
 228     int                 dbi_lockdbfd;   /*!< do fcntl lock on db fd */
 229     int                 dbi_temporary;  /*!< non-persistent */
 230     int                 dbi_debug;
 231
 232 /*@null@*/ char *       dbi_host;
 233     long                dbi_cl_timeout;
 234     long                dbi_sv_timeout;
 235
 236         /* dbenv parameters */
 237     int                 dbi_lorder;
 238 /*@unused@*/ /*@null@*/ void            (*db_errcall) (const char *db_errpfx, char *buffer)
 239         /*@modifies fileSystem @*/;
 240 /*@unused@*/ /*@shared@*/ FILE *        dbi_errfile;
 241     const char *        dbi_errpfx;
 242     int                 dbi_verbose;
 243     int                 dbi_region_init;
 244     int                 dbi_tas_spins;
 245         /* mpool sub-system parameters */
 246     int                 dbi_mp_mmapsize;        /*!< (10Mb) */
 247     int                 dbi_mp_size;    /*!< (128Kb) */
 248         /* lock sub-system parameters */
 249     unsigned int        dbi_lk_max;
 250     unsigned int        dbi_lk_detect;
 251 /*@unused@*/ int        dbi_lk_nmodes;
 252 /*@unused@*/ unsigned char * dbi_lk_conflicts;
 253         /* log sub-system parameters */
 254     unsigned int        dbi_lg_max;
 255     unsigned int        dbi_lg_bsize;
 256         /* transaction sub-system parameters */
 257     unsigned int        dbi_tx_max;
 258 #if 0
 259     int                 (*dbi_tx_recover) (DB_ENV *dbenv, DBT *log_rec,
 260                                 DB_LSN *lsnp, int redo, void *info)
 261         /*@modifies fileSystem @*/;
 262 #endif
 263         /* dbinfo parameters */
 264     int                 dbi_cachesize;  /*!< */
 265     int                 dbi_pagesize;   /*!< (fs blksize) */
 266 /*@unused@*/ /*@null@*/ void *  (*dbi_malloc) (size_t nbytes)
 267         /*@*/;
 268         /* hash access parameters */
 269     unsigned int        dbi_h_ffactor;  /*!< */
 270 /*@null@*/ unsigned int (*dbi_h_hash_fcn) (DB *, const void *bytes, unsigned int length) /*@*/;
 271     unsigned int        dbi_h_nelem;    /*!< */
 272     unsigned int        dbi_h_flags;    /*!< DB_DUP, DB_DUPSORT */
 273 /*@null@*/ int          (*dbi_h_dup_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
 274         /* btree access parameters */
 275     int                 dbi_bt_flags;
 276     int                 dbi_bt_minkey;
 277 /*@null@*/ int          (*dbi_bt_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
 278 /*@null@*/ int          (*dbi_bt_dup_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
 279 /*@null@*/ size_t       (*dbi_bt_prefix_fcn) (DB *, const DBT *, const DBT *) /*@*/;
 280         /* recno access parameters */
 281     int                 dbi_re_flags;
 282     int                 dbi_re_delim;
 283     unsigned int        dbi_re_len;
 284     int                 dbi_re_pad;
 285     const char *        dbi_re_source;
 286         /* queue access parameters */
 287     unsigned int        dbi_q_extentsize;
 288
 289 /*@kept@*/ rpmdb        dbi_rpmdb;
 290     rpmTag      dbi_rpmtag;             /*!< rpm tag used for index */
 291     int         dbi_jlen;               /*!< size of join key */
 292
 293     unsigned int dbi_lastoffset;        /*!< db1 with falloc.c needs this */
 294
 295 /*@only@*//*@null@*/ void * dbi_db;     /*!< Berkeley DB handle */
 296 /*@only@*//*@null@*/ void * dbi_dbenv;  /*!< Berkeley DB_ENV handle */
 297 /*@only@*//*@null@*/ void * dbi_dbinfo; /*!< (unused) */
 298 /*@only@*//*@null@*/ void * dbi_rmw;    /*!< db cursor (with DB_WRITECURSOR) */
 299 /*@only@*//*@null@*/ void * dbi_stats;  /*!< Berkeley db statistics */
 300
 301 /*@observer@*/ const struct _dbiVec * dbi_vec;  /*!< private methods */
 302
 303 };
 304
 305 /** \ingroup rpmdb
 306  * Describes the collection of index databases used by rpm.
 307  */
 308 struct rpmdb_s {
 309 /*@owned@*/ const char * db_root;/*!< path prefix */
 310 /*@owned@*/ const char * db_home;/*!< directory path */
 311     int         db_flags;
 312     int         db_mode;        /*!< open mode */
 313     int         db_perms;       /*!< open permissions */
 314     int         db_api;         /*!< Berkeley API type */
 315 /*@owned@*/ const char * db_errpfx;
 316     int         db_remove_env;
 317     int         db_filter_dups;
 318     int         db_chrootDone;  /*!< If chroot(2) done, ignore db_root. */
 319     void (*db_errcall) (const char *db_errpfx, char *buffer)
 320         /*@*/;
 321 /*@shared@*/ FILE *     db_errfile;
 322 /*@only@*/ void * (*db_malloc) (size_t nbytes)
 323         /*@*/;
 324 /*@only@*/ void * (*db_realloc) (/*@only@*//*@null@*/ void * ptr,
 325                                                 size_t nbytes)
 326         /*@*/;
 327     void (*db_free) (/*@only@*/ void * ptr)
 328         /*@modifies *ptr @*/;
 329     int         db_ndbi;        /*!< No. of tag indices. */
 330     dbiIndex *  _dbi;           /*!< Tag indices. */
 331 };
 332
 333 /* for RPM's internal use only */
 334
 335 /** \ingroup rpmdb
 336  */
 337 enum rpmdbFlags {
 338         RPMDB_FLAG_JUSTCHECK    = (1 << 0),
 339         RPMDB_FLAG_MINIMAL      = (1 << 1),
 340 /*@-enummemuse@*/
 341         RPMDB_FLAG_CHROOT       = (1 << 2)
 342 /*@=enummemuse@*/
 343 };
 344
 345 #ifdef __cplusplus
 346 extern "C" {
 347 #endif
 348
 349 /*@-exportlocal@*/
 350 /** \ingroup db3
 351  * Return new configured index database handle instance.
 352  * @param rpmdb         rpm database
 353  */
 354 /*@only@*/ /*@null@*/ dbiIndex db3New(/*@keep@*/ rpmdb rpmdb, int rpmtag)
 355         /*@*/;
 356
 357 /** \ingroup db3
 358  * Destroy index database handle instance.
 359  * @param dbi           index database handle
 360  * @return              NULL always
 361  */
 362 /*@null@*/ dbiIndex db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi)
 363         /*@*/;
 364
 365 /** \ingroup db3
 366  * Format db3 open flags for debugging print.
 367  * @param dbflags               db open flags
 368  * @param print_dbenv_flags     format db env flags instead?
 369  * @return                      formatted flags (static buffer)
 370  */
 371 /*@-redecl@*/
 372 /*@exposed@*/ extern const char *const prDbiOpenFlags(int dbflags,
 373                                                 int print_dbenv_flags)
 374         /*@*/;
 375 /*@=redecl@*/
 376
 377 /** \ingroup dbi
 378  * Return handle for an index database.
 379  * @param db            rpm database
 380  * @param rpmtag        rpm tag
 381  * @param flags         (unused)
 382  * @return              index database handle
 383  */
 384 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(/*@null@*/ rpmdb db, int rpmtag,
 385                 unsigned int flags)
 386         /*@modifies db @*/;
 387
 388 /** \ingroup dbi
 389  * @param dbi           index database handle
 390  * @param dbiflags      DBI_WRITECURSOR or DBI_ITERATOR
 391  */
 392 int dbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int dbiflags)
 393         /*@modifies dbi, *dbcp @*/;
 394
 395 #define DBI_WRITECURSOR         (1 << 0)
 396 #define DBI_ITERATOR            (1 << 1)
 397
 398 /** \ingroup dbi
 399  * @param dbi           index database handle
 400  * @param flags         (unused)
 401  */
 402 int dbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
 403         /*@modifies dbi, *dbcursor @*/;
 404
 405 /** \ingroup dbi
 406  * Delete (key,data) pair(s) from index database.
 407  * @param dbi           index database handle
 408  * @param keyp          key data
 409  * @param keylen        key data length
 410  * @param flags         (unused)
 411  * @return              0 on success
 412  */
 413 int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 414                 unsigned int flags)
 415         /*@modifies *dbcursor, fileSystem @*/;
 416
 417 /** \ingroup dbi
 418  * Retrieve (key,data) pair from index database.
 419  * @param dbi           index database handle
 420  * @param keypp         address of key data
 421  * @param keylenp       address of key data length
 422  * @param datapp        address of data pointer
 423  * @param datalenp      address of data length
 424  * @param flags         (unused)
 425  * @return              0 on success
 426  */
 427 int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp,
 428                 /*@null@*/ size_t * keylenp,
 429                 /*@null@*/ void ** datapp,
 430                 /*@null@*/ size_t * datalenp,
 431                 unsigned int flags)
 432         /*@modifies *dbcursor, **keypp, *keylenp, **datapp, *datalenp,
 433                 fileSystem @*/;
 434
 435 /** \ingroup dbi
 436  * Store (key,data) pair in index database.
 437  * @param dbi           index database handle
 438  * @param keyp          key data
 439  * @param keylen        key data length
 440  * @param datap         data pointer
 441  * @param datalen       data length
 442  * @param flags         (unused)
 443  * @return              0 on success
 444  */
 445 int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 446                 const void * datap, size_t datalen, unsigned int flags)
 447         /*@modifies *dbcursor, fileSystem @*/;
 448
 449 /** \ingroup dbi
 450  * Retrieve count of (possible) duplicate items.
 451  * @param dbi           index database handle
 452  * @param dbcursor      database cursor
 453  * @param countp        address of count
 454  * @param flags         (unused)
 455  * @return              0 on success
 456  */
 457 /*@unused@*/
 458 int dbiCount(dbiIndex dbi, DBC * dbcursor, /*@out@*/ unsigned int * countp,
 459                 unsigned int flags)
 460         /*@modifies *dbcursor, fileSystem @*/;
 461
 462 /** \ingroup dbi
 463  * Verify (and close) index database.
 464  * @param dbi           index database handle
 465  * @param flags         (unused)
 466  * @return              0 on success
 467  */
 468 int dbiVerify(/*@only@*/ dbiIndex dbi, unsigned int flags)
 469         /*@modifies dbi, fileSystem @*/;
 470
 471 /** \ingroup dbi
 472  * Close index database.
 473  * @param dbi           index database handle
 474  * @param flags         (unused)
 475  * @return              0 on success
 476  */
 477 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags)
 478         /*@modifies dbi, fileSystem @*/;
 479
 480 /** \ingroup dbi
 481  * Flush pending operations to disk.
 482  * @param dbi           index database handle
 483  * @param flags         (unused)
 484  * @return              0 on success
 485  */
 486 int dbiSync (dbiIndex dbi, unsigned int flags)
 487         /*@modifies fileSystem @*/;
 488
 489 /** \ingroup dbi
 490  * Is database byte swapped?
 491  * @param dbi           index database handle
 492  * @return              0 no
 493  */
 494 int dbiByteSwapped(dbiIndex dbi)
 495         /*@*/;
 496
 497 /** \ingroup db1
 498  * Return base file name for db1 database (legacy).
 499  * @param rpmtag        rpm tag
 500  * @return              base file name of db1 database
 501  */
 502 char * db1basename(int rpmtag)
 503         /*@*/;
 504 /*@=exportlocal@*/
 505
 506 /** \ingroup rpmdb
 507  */
 508 /*@unused@*/
 509 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi)
 510         /*@*/;
 511
 512 /** \ingroup rpmdb
 513  * @param db            rpm database
 514  */
 515 int rpmdbFindFpList(/*@null@*/ rpmdb db, fingerPrint * fpList,
 516                 /*@out@*/ dbiIndexSet * matchList, int numItems)
 517         /*@modifies db, *matchList @*/;
 518
 519 /** \ingroup dbi
 520  * Destroy set of index database items.
 521  * @param set   set of index database items
 522  * @return      NULL always
 523  */
 524 /*@null@*/ dbiIndexSet dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set)
 525         /*@modifies set @*/;
 526
 527 /** \ingroup dbi
 528  * Count items in index database set.
 529  * @param set   set of index database items
 530  * @return      number of items
 531  */
 532 unsigned int dbiIndexSetCount(dbiIndexSet set)
 533         /*@*/;
 534
 535 /** \ingroup dbi
 536  * Return record offset of header from element in index database set.
 537  * @param set   set of index database items
 538  * @param recno index of item in set
 539  * @return      record offset of header
 540  */
 541 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno)
 542         /*@*/;
 543
 544 /** \ingroup dbi
 545  * Return file index from element in index database set.
 546  * @param set   set of index database items
 547  * @param recno index of item in set
 548  * @return      file index
 549  */
 550 unsigned int dbiIndexRecordFileNumber(dbiIndexSet set, int recno)
 551         /*@*/;
 552
 553 #ifdef __cplusplus
 554 }
 555 #endif
 556
 557 #endif  /* H_RPMDB */