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