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