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