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