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