rpmdb/rpmdb.h

   1 #ifndef H_RPMDB
   2 #define H_RPMDB
   3 /*@-bounds@*/
   4
   5 /** \ingroup rpmdb dbi db1 db3
   6  * \file rpmdb/rpmdb.h
   7  * Access RPM indices using Berkeley DB interface(s).
   8  */
   9
  10 #include <assert.h>
  11 #include <rpmlib.h>
  12 #include <db.h>
  13
  14 /*@-exportlocal@*/
  15 /*@unchecked@*/
  16 extern int _rpmdb_debug;
  17 /*@=exportlocal@*/
  18
  19 #ifdef  NOTYET
  20 /** \ingroup rpmdb
  21  * Database of headers and tag value indices.
  22  */
  23 typedef /*@abstract@*/ /*@refcounted@*/ struct rpmdb_s * rpmdb;
  24
  25 /** \ingroup rpmdb
  26  * Database iterator.
  27  */
  28 typedef /*@abstract@*/ struct _rpmdbMatchIterator * rpmdbMatchIterator;
  29 #endif
  30
  31 /**
  32  * Tag value pattern match mode.
  33  */
  34 typedef enum rpmMireMode_e {
  35     RPMMIRE_DEFAULT     = 0,    /*!< regex with \., .* and ^...$ added */
  36     RPMMIRE_STRCMP      = 1,    /*!< strings  using strcmp(3) */
  37     RPMMIRE_REGEX       = 2,    /*!< regex(7) patterns through regcomp(3) */
  38     RPMMIRE_GLOB        = 3     /*!< glob(7) patterns through fnmatch(3) */
  39 } rpmMireMode;
  40
  41 /**
  42  */
  43 typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem;
  44
  45 /** \ingroup rpmdb
  46  * A single element (i.e. inverted list from tag values) of a database.
  47  */
  48 typedef /*@abstract@*/ struct _dbiIndexSet * dbiIndexSet;
  49
  50 /**
  51  */
  52 typedef /*@abstract@*/ struct _dbiIndex * dbiIndex;
  53
  54 /* this will break if sizeof(int) != 4 */
  55 /** \ingroup dbi
  56  * A single item from an index database (i.e. the "data returned").
  57  * Note: In rpm-3.0.4 and earlier, this structure was passed by value,
  58  * and was identical to the "data saved" structure below.
  59  */
  60 struct _dbiIndexItem {
  61     unsigned int hdrNum;                /*!< header instance in db */
  62     unsigned int tagNum;                /*!< tag index in header */
  63     unsigned int fpNum;                 /*!< finger print index */
  64 };
  65
  66 /** \ingroup dbi
  67  * Items retrieved from the index database.
  68  */
  69 struct _dbiIndexSet {
  70 /*@owned@*/ struct _dbiIndexItem * recs; /*!< array of records */
  71     int count;                          /*!< number of records */
  72 };
  73
  74 /** \ingroup dbi
  75  * Private methods for accessing an index database.
  76  */
  77 struct _dbiVec {
  78     int dbv_major;                      /*!< Berkeley db version major */
  79     int dbv_minor;                      /*!< Berkeley db version minor */
  80     int dbv_patch;                      /*!< Berkeley db version patch */
  81
  82 /** \ingroup dbi
  83  * Return handle for an index database.
  84  * @param rpmdb         rpm database
  85  * @param rpmtag        rpm tag
  86  * @return              0 on success
  87  */
  88     int (*open) (rpmdb rpmdb, rpmTag rpmtag, /*@out@*/ dbiIndex * dbip)
  89         /*@globals fileSystem @*/
  90         /*@modifies *dbip, fileSystem @*/;
  91
  92 /** \ingroup dbi
  93  * Close index database, and destroy database handle.
  94  * @param dbi           index database handle
  95  * @param flags         (unused)
  96  * @return              0 on success
  97  */
  98     int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags)
  99         /*@globals fileSystem @*/
 100         /*@modifies dbi, fileSystem @*/;
 101
 102 /** \ingroup dbi
 103  * Flush pending operations to disk.
 104  * @param dbi           index database handle
 105  * @param flags         (unused)
 106  * @return              0 on success
 107  */
 108     int (*sync) (dbiIndex dbi, unsigned int flags)
 109         /*@globals fileSystem @*/
 110         /*@modifies fileSystem @*/;
 111
 112 /** \ingroup dbi
 113  * Associate secondary database with primary.
 114  * @param dbi           index database handle
 115  * @param dbisecondary  secondary index database handle
 116  * @param callback      create secondary key from primary (NULL if DB_RDONLY)
 117  * @param flags         DB_CREATE or 0
 118  * @return              0 on success
 119  */
 120     int (*associate) (dbiIndex dbi, dbiIndex dbisecondary,
 121                 int (*callback) (DB *, const DBT *, const DBT *, DBT *),
 122                 unsigned int flags)
 123         /*@globals fileSystem @*/
 124         /*@modifies dbi, fileSystem @*/;
 125
 126 /** \ingroup dbi
 127  * Return join cursor for list of cursors.
 128  * @param dbi           index database handle
 129  * @param curslist      NULL terminated list of database cursors
 130  * @retval dbcp         address of join database cursor
 131  * @param flags         DB_JOIN_NOSORT or 0
 132  * @return              0 on success
 133  */
 134     int (*join) (dbiIndex dbi, DBC ** curslist, /*@out@*/ DBC ** dbcp,
 135                 unsigned int flags)
 136         /*@globals fileSystem @*/
 137         /*@modifies dbi, *dbcp, fileSystem @*/;
 138
 139 /** \ingroup dbi
 140  * Open database cursor.
 141  * @param dbi           index database handle
 142  * @param txnid         database transaction handle
 143  * @retval dbcp         address of new database cursor
 144  * @param dbiflags      DB_WRITECURSOR or 0
 145  * @return              0 on success
 146  */
 147     int (*copen) (dbiIndex dbi, /*@null@*/ DB_TXN * txnid,
 148                         /*@out@*/ DBC ** dbcp, unsigned int dbiflags)
 149         /*@globals fileSystem @*/
 150         /*@modifies dbi, *txnid, *dbcp, fileSystem @*/;
 151
 152 /** \ingroup dbi
 153  * Close database cursor.
 154  * @param dbi           index database handle
 155  * @param dbcursor      database cursor
 156  * @param flags         (unused)
 157  * @return              0 on success
 158  */
 159     int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
 160         /*@globals fileSystem @*/
 161         /*@modifies dbi, *dbcursor, fileSystem @*/;
 162
 163 /** \ingroup dbi
 164  * Duplicate a database cursor.
 165  * @param dbi           index database handle
 166  * @param dbcursor      database cursor
 167  * @retval dbcp         address of new database cursor
 168  * @param flags         DB_POSITION for same position, 0 for uninitialized
 169  * @return              0 on success
 170  */
 171     int (*cdup) (dbiIndex dbi, DBC * dbcursor, /*@out@*/ DBC ** dbcp,
 172                 unsigned int flags)
 173         /*@globals fileSystem @*/
 174         /*@modifies dbi, *dbcp, fileSystem @*/;
 175
 176 /** \ingroup dbi
 177  * Delete (key,data) pair(s) using db->del or dbcursor->c_del.
 178  * @param dbi           index database handle
 179  * @param dbcursor      database cursor (NULL will use db->del)
 180  * @param key           delete key value/length/flags
 181  * @param data          delete data value/length/flags
 182  * @param flags         (unused)
 183  * @return              0 on success
 184  */
 185     int (*cdel) (dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 186                         unsigned int flags)
 187         /*@globals fileSystem @*/
 188         /*@modifies *dbcursor, fileSystem @*/;
 189
 190 /** \ingroup dbi
 191  * Retrieve (key,data) pair using db->get or dbcursor->c_get.
 192  * @param dbi           index database handle
 193  * @param dbcursor      database cursor (NULL will use db->get)
 194  * @param key           retrieve key value/length/flags
 195  * @param data          retrieve data value/length/flags
 196  * @param flags         (unused)
 197  * @return              0 on success
 198  */
 199     int (*cget) (dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 200                         unsigned int flags)
 201         /*@globals fileSystem @*/
 202         /*@modifies *dbcursor, *key, *data, fileSystem @*/;
 203
 204 /** \ingroup dbi
 205  * Retrieve (key,data) pair using dbcursor->c_pget.
 206  * @param dbi           index database handle
 207  * @param dbcursor      database cursor
 208  * @param key           secondary retrieve key value/length/flags
 209  * @param pkey          primary retrieve key value/length/flags
 210  * @param data          primary retrieve data value/length/flags
 211  * @param flags         DB_NEXT, DB_SET, or 0
 212  * @return              0 on success
 213  */
 214     int (*cpget) (dbiIndex dbi, /*@null@*/ DBC * dbcursor,
 215                 DBT * key, DBT * pkey, DBT * data, unsigned int flags)
 216         /*@globals fileSystem @*/
 217         /*@modifies *dbcursor, *key, *pkey, *data, fileSystem @*/;
 218
 219 /** \ingroup dbi
 220  * Store (key,data) pair using db->put or dbcursor->c_put.
 221  * @param dbi           index database handle
 222  * @param dbcursor      database cursor (NULL will use db->put)
 223  * @param key           store key value/length/flags
 224  * @param data          store data value/length/flags
 225  * @param flags         (unused)
 226  * @return              0 on success
 227  */
 228     int (*cput) (dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 229                         unsigned int flags)
 230         /*@globals fileSystem @*/
 231         /*@modifies *dbcursor, fileSystem @*/;
 232
 233 /** \ingroup dbi
 234  * Retrieve count of (possible) duplicate items using dbcursor->c_count.
 235  * @param dbi           index database handle
 236  * @param dbcursor      database cursor
 237  * @param countp        address of count
 238  * @param flags         (unused)
 239  * @return              0 on success
 240  */
 241     int (*ccount) (dbiIndex dbi, DBC * dbcursor,
 242                         /*@out@*/ unsigned int * countp,
 243                         unsigned int flags)
 244         /*@globals fileSystem @*/
 245         /*@modifies *dbcursor, fileSystem @*/;
 246
 247 /** \ingroup dbi
 248  * Is database byte swapped?
 249  * @param dbi           index database handle
 250  * @return              0 no
 251  */
 252     int (*byteswapped) (dbiIndex dbi)
 253         /*@globals fileSystem @*/
 254         /*@modifies fileSystem @*/;
 255
 256 /** \ingroup dbi
 257  * Save statistics in database handle.
 258  * @param dbi           index database handle
 259  * @param flags         retrieve statistics that don't require traversal?
 260  * @return              0 on success
 261  */
 262     int (*stat) (dbiIndex dbi, unsigned int flags)
 263         /*@globals fileSystem @*/
 264         /*@modifies dbi, fileSystem @*/;
 265
 266 };
 267
 268 /** \ingroup dbi
 269  * Describes an index database (implemented on Berkeley db3 functionality).
 270  */
 271 struct _dbiIndex {
 272 /*@null@*/
 273     const char * dbi_root;      /*!< chroot(2) component of path */
 274 /*@null@*/
 275     const char * dbi_home;      /*!< directory component of path */
 276 /*@null@*/
 277     const char * dbi_file;      /*!< file component of path */
 278 /*@null@*/
 279     const char * dbi_subfile;
 280 /*@null@*/
 281     const char * dbi_tmpdir;    /*!< temporary directory */
 282
 283     int dbi_ecflags;            /*!< db_env_create flags */
 284     int dbi_cflags;             /*!< db_create flags */
 285     int dbi_oeflags;            /*!< common (db,dbenv}->open flags */
 286     int dbi_eflags;             /*!< dbenv->open flags */
 287     int dbi_oflags;             /*!< db->open flags */
 288     int dbi_tflags;             /*!< dbenv->txn_begin flags */
 289
 290     int dbi_type;               /*!< db index type */
 291     unsigned dbi_mode;          /*!< mode to use on open */
 292     int dbi_perms;              /*!< file permission to use on open */
 293     long dbi_shmkey;            /*!< shared memory base key */
 294     int dbi_api;                /*!< Berkeley API type */
 295
 296     int dbi_verify_on_close;
 297     int dbi_use_dbenv;          /*!< use db environment? */
 298     int dbi_permit_dups;        /*!< permit duplicate entries? */
 299     int dbi_no_fsync;           /*!< no-op fsync for db */
 300     int dbi_no_dbsync;          /*!< don't call dbiSync */
 301     int dbi_lockdbfd;           /*!< do fcntl lock on db fd */
 302     int dbi_temporary;          /*!< non-persistent */
 303     int dbi_debug;
 304     int dbi_byteswapped;
 305
 306 /*@null@*/
 307     char * dbi_host;
 308     unsigned long dbi_cl_timeout;
 309     unsigned long dbi_sv_timeout;
 310
 311         /* dbenv parameters */
 312     int dbi_lorder;
 313 /*@unused@*/
 314     void (*db_errcall) (const char *db_errpfx, char *buffer)
 315         /*@globals fileSystem @*/
 316         /*@modifies fileSystem @*/;
 317 /*@unused@*/ /*@shared@*/
 318     FILE *      dbi_errfile;
 319     const char * dbi_errpfx;
 320     int dbi_verbose;
 321     int dbi_region_init;
 322     int dbi_tas_spins;
 323         /* mpool sub-system parameters */
 324     int dbi_mp_mmapsize;        /*!< (10Mb) */
 325     int dbi_mp_size;    /*!< (128Kb) */
 326         /* lock sub-system parameters */
 327     unsigned int dbi_lk_max;
 328     unsigned int dbi_lk_detect;
 329 /*@unused@*/ int dbi_lk_nmodes;
 330 /*@unused@*/ unsigned char * dbi_lk_conflicts;
 331         /* log sub-system parameters */
 332     unsigned int dbi_lg_max;
 333     unsigned int dbi_lg_bsize;
 334         /* transaction sub-system parameters */
 335     unsigned int dbi_tx_max;
 336 #if 0
 337     int (*dbi_tx_recover) (DB_ENV *dbenv, DBT *log_rec,
 338                                 DB_LSN *lsnp, int redo, void *info)
 339         /*@globals fileSystem @*/
 340         /*@modifies fileSystem @*/;
 341 #endif
 342         /* dbinfo parameters */
 343     int dbi_cachesize;          /*!< */
 344     int dbi_pagesize;           /*!< (fs blksize) */
 345 /*@unused@*/ /*@null@*/
 346     void * (*dbi_malloc) (size_t nbytes)
 347         /*@*/;
 348         /* hash access parameters */
 349     unsigned int dbi_h_ffactor; /*!< */
 350     unsigned int (*dbi_h_hash_fcn) (DB *, const void *bytes,
 351                                 unsigned int length)
 352         /*@*/;
 353     unsigned int dbi_h_nelem;   /*!< */
 354     unsigned int dbi_h_flags;   /*!< DB_DUP, DB_DUPSORT */
 355     int (*dbi_h_dup_compare_fcn) (DB *, const DBT *, const DBT *)
 356         /*@*/;
 357         /* btree access parameters */
 358     int dbi_bt_flags;
 359     int dbi_bt_minkey;
 360     int (*dbi_bt_compare_fcn) (DB *, const DBT *, const DBT *)
 361         /*@*/;
 362     int (*dbi_bt_dup_compare_fcn) (DB *, const DBT *, const DBT *)
 363         /*@*/;
 364     size_t (*dbi_bt_prefix_fcn) (DB *, const DBT *, const DBT *)
 365         /*@*/;
 366         /* recno access parameters */
 367     int dbi_re_flags;
 368     int dbi_re_delim;
 369     unsigned int dbi_re_len;
 370     int dbi_re_pad;
 371     const char * dbi_re_source;
 372         /* queue access parameters */
 373     unsigned int dbi_q_extentsize;
 374
 375 /*@refcounted@*/
 376     rpmdb dbi_rpmdb;            /*!< the parent rpm database */
 377     rpmTag dbi_rpmtag;          /*!< rpm tag used for index */
 378     int dbi_jlen;               /*!< size of join key */
 379
 380 /*@only@*//*@null@*/
 381     DB * dbi_db;                /*!< Berkeley DB * handle */
 382 /*@only@*//*@null@*/
 383     DB_TXN * dbi_txnid;         /*!< Bekerley DB_TXN * transaction id */
 384 /*@only@*//*@null@*/
 385     void * dbi_stats;           /*!< Berkeley db statistics */
 386
 387 /*@observer@*/
 388     const struct _dbiVec * dbi_vec;     /*!< private methods */
 389
 390 };
 391
 392 /** \ingroup rpmdb
 393  * Describes the collection of index databases used by rpm.
 394  */
 395 struct rpmdb_s {
 396 /*@owned@*/
 397     const char * db_root;/*!< path prefix */
 398 /*@owned@*/
 399     const char * db_home;/*!< directory path */
 400     int         db_flags;
 401     int         db_mode;        /*!< open mode */
 402     int         db_perms;       /*!< open permissions */
 403     int         db_api;         /*!< Berkeley API type */
 404 /*@owned@*/
 405     const char * db_errpfx;
 406     int         db_remove_env;
 407     int         db_filter_dups;
 408     int         db_chrootDone;  /*!< If chroot(2) done, ignore db_root. */
 409     void (*db_errcall) (const char *db_errpfx, char *buffer)
 410         /*@*/;
 411 /*@shared@*/
 412     FILE *      db_errfile;
 413 /*@only@*/
 414     void * (*db_malloc) (size_t nbytes)
 415         /*@*/;
 416 /*@only@*/
 417     void * (*db_realloc) (/*@only@*//*@null@*/ void * ptr,
 418                                                 size_t nbytes)
 419         /*@*/;
 420     void (*db_free) (/*@only@*/ void * ptr)
 421         /*@modifies *ptr @*/;
 422 /*@only@*/ /*@null@*/
 423     unsigned char * db_bits;    /*!< package instance bit mask. */
 424     int         db_nbits;       /*!< no. of bits in mask. */
 425     rpmdb       db_next;
 426     int         db_opens;
 427 /*@only@*/ /*@null@*/
 428     void *      db_dbenv;       /*!< Berkeley DB_ENV handle. */
 429     int         db_ndbi;        /*!< No. of tag indices. */
 430     dbiIndex * _dbi;            /*!< Tag indices. */
 431
 432 /*@refs@*/
 433     int nrefs;                  /*!< Reference count. */
 434 };
 435
 436 /* for RPM's internal use only */
 437
 438 /** \ingroup rpmdb
 439  */
 440 enum rpmdbFlags {
 441         RPMDB_FLAG_JUSTCHECK    = (1 << 0),
 442         RPMDB_FLAG_MINIMAL      = (1 << 1),
 443 /*@-enummemuse@*/
 444         RPMDB_FLAG_CHROOT       = (1 << 2)
 445 /*@=enummemuse@*/
 446 };
 447
 448 #ifdef __cplusplus
 449 extern "C" {
 450 #endif
 451
 452 /*@-exportlocal@*/
 453 /** \ingroup db3
 454  * Return new configured index database handle instance.
 455  * @param rpmdb         rpm database
 456  * @param rpmtag        rpm tag
 457  * @return              index database handle
 458  */
 459 /*@unused@*/ /*@only@*/ /*@null@*/
 460 dbiIndex db3New(rpmdb rpmdb, rpmTag rpmtag)
 461         /*@globals rpmGlobalMacroContext @*/
 462         /*@modifies rpmGlobalMacroContext @*/;
 463
 464 /** \ingroup db3
 465  * Destroy index database handle instance.
 466  * @param dbi           index database handle
 467  * @return              NULL always
 468  */
 469 /*@null@*/
 470 dbiIndex db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi)
 471         /*@*/;
 472
 473 /** \ingroup db3
 474  * Format db3 open flags for debugging print.
 475  * @param dbflags               db open flags
 476  * @param print_dbenv_flags     format db env flags instead?
 477  * @return                      formatted flags (static buffer)
 478  */
 479 /*@-redecl@*/
 480 /*@exposed@*/
 481 extern const char *const prDbiOpenFlags(int dbflags, int print_dbenv_flags)
 482         /*@*/;
 483 /*@=redecl@*/
 484
 485 /** \ingroup dbi
 486  * Return handle for an index database.
 487  * @param db            rpm database
 488  * @param rpmtag        rpm tag
 489  * @param flags         (unused)
 490  * @return              index database handle
 491  */
 492 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(/*@null@*/ rpmdb db, rpmTag rpmtag,
 493                 unsigned int flags)
 494         /*@globals rpmGlobalMacroContext, errno @*/
 495         /*@modifies db, rpmGlobalMacroContext, errno @*/;
 496
 497 /*@-globuse -mustmod @*/ /* FIX: vector annotations */
 498 /** \ingroup dbi
 499  * Open a database cursor.
 500  * @param dbi           index database handle
 501  * @param txnid         database transaction handle
 502  * @retval dbcp         returned database cursor
 503  * @param flags         DB_WRITECURSOR if writing, or 0
 504  * @return              0 on success
 505  */
 506 /*@unused@*/ static inline
 507 int dbiCopen(dbiIndex dbi, /*@null@*/ DB_TXN * txnid,
 508                 /*@out@*/ DBC ** dbcp, unsigned int flags)
 509         /*@globals fileSystem @*/
 510         /*@modifies dbi, *dbcp, fileSystem @*/
 511 {
 512     return (*dbi->dbi_vec->copen) (dbi, txnid, dbcp, flags);
 513 }
 514
 515 /** \ingroup dbi
 516  * Close a database cursor.
 517  * @param dbi           index database handle
 518  * @param dbcursor      database cursor
 519  * @param flags         (unused)
 520  * @return              0 on success
 521  */
 522 /*@unused@*/ static inline
 523 int dbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
 524         /*@globals fileSystem @*/
 525         /*@modifies dbi, *dbcursor, fileSystem @*/
 526 {
 527     return (*dbi->dbi_vec->cclose) (dbi, dbcursor, flags);
 528 }
 529
 530 /** \ingroup dbi
 531  * Duplicate a database cursor.
 532  * @param dbi           index database handle
 533  * @param dbcursor      database cursor
 534  * @retval dbcp         address of new database cursor
 535  * @param flags         DB_POSITION for same position, 0 for uninitialized
 536  * @return              0 on success
 537  */
 538 /*@unused@*/ static inline
 539 int dbiCdup(dbiIndex dbi, DBC * dbcursor, /*@out@*/ DBC ** dbcp,
 540                 unsigned int flags)
 541         /*@modifies dbi, *dbcp @*/
 542 {
 543     return (*dbi->dbi_vec->cdup) (dbi, dbcursor, dbcp, flags);
 544 }
 545
 546 /** \ingroup dbi
 547  * Delete (key,data) pair(s) from index database.
 548  * @param dbi           index database handle
 549  * @param dbcursor      database cursor (NULL will use db->del)
 550  * @param key           delete key value/length/flags
 551  * @param data          delete data value/length/flags
 552  * @param flags         (unused)
 553  * @return              0 on success
 554  */
 555 /*@unused@*/ static inline
 556 int dbiDel(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 557                 unsigned int flags)
 558         /*@globals fileSystem @*/
 559         /*@modifies *dbcursor, fileSystem @*/
 560 {
 561     assert(key->data != NULL && key->size > 0);
 562     return (dbi->dbi_vec->cdel) (dbi, dbcursor, key, data, flags);
 563 }
 564
 565 /** \ingroup dbi
 566  * Retrieve (key,data) pair from index database.
 567  * @param dbi           index database handle
 568  * @param dbcursor      database cursor (NULL will use db->get)
 569  * @param key           retrieve key value/length/flags
 570  * @param data          retrieve data value/length/flags
 571  * @param flags         (unused)
 572  * @return              0 on success
 573  */
 574 /*@unused@*/ static inline
 575 int dbiGet(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 576                 unsigned int flags)
 577         /*@globals fileSystem @*/
 578         /*@modifies *dbcursor, *key, *data, fileSystem @*/
 579 {
 580     assert((flags == DB_NEXT) || (key->data != NULL && key->size > 0));
 581     return (dbi->dbi_vec->cget) (dbi, dbcursor, key, data, flags);
 582 }
 583
 584 /** \ingroup dbi
 585  * Retrieve (key,data) pair using dbcursor->c_pget.
 586  * @param dbi           index database handle
 587  * @param dbcursor      database cursor (NULL will use db->get)
 588  * @param key           secondary retrieve key value/length/flags
 589  * @param pkey          primary retrieve key value/length/flags
 590  * @param data          primary retrieve data value/length/flags
 591  * @param flags         DB_NEXT, DB_SET, or 0
 592  * @return              0 on success
 593  */
 594 /*@unused@*/ static inline
 595 int dbiPget(dbiIndex dbi, /*@null@*/ DBC * dbcursor,
 596                 DBT * key, DBT * pkey, DBT * data, unsigned int flags)
 597         /*@globals fileSystem @*/
 598         /*@modifies *dbcursor, *key, *pkey, *data, fileSystem @*/
 599 {
 600     assert((flags == DB_NEXT) || (key->data != NULL && key->size > 0));
 601     return (dbi->dbi_vec->cpget) (dbi, dbcursor, key, pkey, data, flags);
 602 }
 603
 604 /** \ingroup dbi
 605  * Store (key,data) pair in index database.
 606  * @param dbi           index database handle
 607  * @param dbcursor      database cursor (NULL will use db->put)
 608  * @param key           store key value/length/flags
 609  * @param data          store data value/length/flags
 610  * @param flags         (unused)
 611  * @return              0 on success
 612  */
 613 /*@unused@*/ static inline
 614 int dbiPut(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 615                 unsigned int flags)
 616         /*@globals fileSystem @*/
 617         /*@modifies *dbcursor, *key, fileSystem @*/
 618 {
 619     assert(key->data != NULL && key->size > 0 && data->data != NULL && data->size > 0);
 620     return (dbi->dbi_vec->cput) (dbi, dbcursor, key, data, flags);
 621 }
 622
 623 /** \ingroup dbi
 624  * Retrieve count of (possible) duplicate items.
 625  * @param dbi           index database handle
 626  * @param dbcursor      database cursor
 627  * @param countp        address of count
 628  * @param flags         (unused)
 629  * @return              0 on success
 630  */
 631 /*@unused@*/ static inline
 632 int dbiCount(dbiIndex dbi, DBC * dbcursor, /*@out@*/ unsigned int * countp,
 633                 unsigned int flags)
 634         /*@globals fileSystem @*/
 635         /*@modifies *dbcursor, fileSystem @*/
 636 {
 637     return (*dbi->dbi_vec->ccount) (dbi, dbcursor, countp, flags);
 638 }
 639
 640 /** \ingroup dbi
 641  * Verify (and close) index database.
 642  * @param dbi           index database handle
 643  * @param flags         (unused)
 644  * @return              0 on success
 645  */
 646 /*@unused@*/ static inline
 647 int dbiVerify(/*@only@*/ dbiIndex dbi, unsigned int flags)
 648         /*@globals fileSystem @*/
 649         /*@modifies dbi, fileSystem @*/
 650 {
 651     dbi->dbi_verify_on_close = 1;
 652     return (*dbi->dbi_vec->close) (dbi, flags);
 653 }
 654
 655 /** \ingroup dbi
 656  * Close index database.
 657  * @param dbi           index database handle
 658  * @param flags         (unused)
 659  * @return              0 on success
 660  */
 661 /*@unused@*/ static inline
 662 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags)
 663         /*@globals fileSystem @*/
 664         /*@modifies dbi, fileSystem @*/
 665 {
 666     return (*dbi->dbi_vec->close) (dbi, flags);
 667 }
 668
 669 /** \ingroup dbi
 670  * Flush pending operations to disk.
 671  * @param dbi           index database handle
 672  * @param flags         (unused)
 673  * @return              0 on success
 674  */
 675 /*@unused@*/ static inline
 676 int dbiSync (dbiIndex dbi, unsigned int flags)
 677         /*@globals fileSystem @*/
 678         /*@modifies fileSystem @*/
 679 {
 680     return (*dbi->dbi_vec->sync) (dbi, flags);
 681 }
 682
 683 /** \ingroup dbi
 684  * Associate secondary database with primary.
 685  * @param dbi           index database handle
 686  * @param dbisecondary  secondary index database handle
 687  * @param callback      create secondary key from primary (NULL if DB_RDONLY)
 688  * @param flags         DB_CREATE or 0
 689  * @return              0 on success
 690  */
 691 /*@unused@*/ static inline
 692 int dbiAssociate(dbiIndex dbi, dbiIndex dbisecondary,
 693                 int (*callback) (DB *, const DBT *, const DBT *, DBT *),
 694                 unsigned int flags)
 695         /*@globals fileSystem @*/
 696         /*@modifies dbi, fileSystem @*/
 697 {
 698     return (*dbi->dbi_vec->associate) (dbi, dbisecondary, callback, flags);
 699 }
 700
 701 /** \ingroup dbi
 702  * Return join cursor for list of cursors.
 703  * @param dbi           index database handle
 704  * @param curslist      NULL terminated list of database cursors
 705  * @retval dbcp         address of join database cursor
 706  * @param flags         DB_JOIN_NOSORT or 0
 707  * @return              0 on success
 708  */
 709 /*@unused@*/ static inline
 710 int dbiJoin(dbiIndex dbi, DBC ** curslist, /*@out@*/ DBC ** dbcp,
 711                 unsigned int flags)
 712         /*@globals fileSystem @*/
 713         /*@modifies dbi, *dbcp, fileSystem @*/
 714 {
 715     return (*dbi->dbi_vec->join) (dbi, curslist, dbcp, flags);
 716 }
 717
 718 /** \ingroup dbi
 719  * Is database byte swapped?
 720  * @param dbi           index database handle
 721  * @return              0 same order, 1 swapped order
 722  */
 723 /*@unused@*/ static inline
 724 int dbiByteSwapped(dbiIndex dbi)
 725         /*@modifies dbi @*/
 726 {
 727     if (dbi->dbi_byteswapped == -1)
 728         dbi->dbi_byteswapped = (*dbi->dbi_vec->byteswapped) (dbi);
 729     return dbi->dbi_byteswapped;
 730 }
 731 /** \ingroup dbi
 732  * Is database byte swapped?
 733  * @param dbi           index database handle
 734  * @param flags         DB_FAST_STAT or 0
 735  * @return              0 on success
 736  */
 737 /*@unused@*/ static inline
 738 int dbiStat(dbiIndex dbi, unsigned int flags)
 739         /*@modifies dbi @*/
 740 {
 741     return (*dbi->dbi_vec->stat) (dbi, flags);
 742 }
 743 /*@=globuse =mustmod @*/
 744
 745 /*@=exportlocal@*/
 746
 747 /** \ingroup rpmdb
 748  */
 749 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi)
 750         /*@*/;
 751
 752 /** \ingroup dbi
 753  * Destroy set of index database items.
 754  * @param set   set of index database items
 755  * @return      NULL always
 756  */
 757 /*@null@*/ dbiIndexSet dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set)
 758         /*@modifies set @*/;
 759
 760 /** \ingroup dbi
 761  * Count items in index database set.
 762  * @param set   set of index database items
 763  * @return      number of items
 764  */
 765 unsigned int dbiIndexSetCount(dbiIndexSet set)
 766         /*@*/;
 767
 768 /** \ingroup dbi
 769  * Return record offset of header from element in index database set.
 770  * @param set   set of index database items
 771  * @param recno index of item in set
 772  * @return      record offset of header
 773  */
 774 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno)
 775         /*@*/;
 776
 777 /** \ingroup dbi
 778  * Return file index from element in index database set.
 779  * @param set   set of index database items
 780  * @param recno index of item in set
 781  * @return      file index
 782  */
 783 unsigned int dbiIndexRecordFileNumber(dbiIndexSet set, int recno)
 784         /*@*/;
 785
 786 /** \ingroup rpmdb
 787  * Tags for which rpmdb indices will be built.
 788  */
 789 /*@-exportlocal@*/
 790 /*@unchecked@*/
 791 /*@only@*/ /*@null@*/ extern int * dbiTags;
 792 /*@unchecked@*/
 793 extern int dbiTagsMax;
 794 /*@=exportlocal@*/
 795
 796 /** \ingroup rpmdb
 797  * Unreference a database instance.
 798  * @param db            rpm database
 799  * @param msg
 800  * @return              NULL always
 801  */
 802 /*@unused@*/ /*@null@*/
 803 rpmdb rpmdbUnlink (/*@killref@*/ /*@only@*/ rpmdb db, const char * msg)
 804         /*@modifies db @*/;
 805
 806 /** @todo Remove debugging entry from the ABI. */
 807 /*@-exportlocal@*/
 808 /*@null@*/
 809 rpmdb XrpmdbUnlink (/*@killref@*/ /*@only@*/ rpmdb db, const char * msg,
 810                 const char * fn, unsigned ln)
 811         /*@modifies db @*/;
 812 /*@=exportlocal@*/
 813 #define rpmdbUnlink(_db, _msg)  XrpmdbUnlink(_db, _msg, __FILE__, __LINE__)
 814
 815 /** \ingroup rpmdb
 816  * Reference a database instance.
 817  * @param db            rpm database
 818  * @param msg
 819  * @return              new rpm database reference
 820  */
 821 /*@unused@*/
 822 rpmdb rpmdbLink (rpmdb db, const char * msg)
 823         /*@modifies db @*/;
 824
 825 /** @todo Remove debugging entry from the ABI. */
 826 /*@-exportlocal@*/
 827 rpmdb XrpmdbLink (rpmdb db, const char * msg,
 828                 const char * fn, unsigned ln)
 829         /*@modifies db @*/;
 830 /*@=exportlocal@*/
 831 #define rpmdbLink(_db, _msg)    XrpmdbLink(_db, _msg, __FILE__, __LINE__)
 832
 833 /** \ingroup rpmdb
 834  * Open rpm database.
 835  * @param prefix        path to top of install tree
 836  * @retval dbp          address of rpm database
 837  * @param mode          open(2) flags:  O_RDWR or O_RDONLY (O_CREAT also)
 838  * @param perms         database permissions
 839  * @return              0 on success
 840  */
 841 int rpmdbOpen (/*@null@*/ const char * prefix, /*@null@*/ /*@out@*/ rpmdb * dbp,
 842                 int mode, int perms)
 843         /*@globals rpmGlobalMacroContext, fileSystem, internalState @*/
 844         /*@modifies *dbp, rpmGlobalMacroContext, fileSystem, internalState @*/;
 845
 846 /** \ingroup rpmdb
 847  * Initialize database.
 848  * @param prefix        path to top of install tree
 849  * @param perms         database permissions
 850  * @return              0 on success
 851  */
 852 int rpmdbInit(/*@null@*/ const char * prefix, int perms)
 853         /*@globals rpmGlobalMacroContext, fileSystem, internalState @*/
 854         /*@modifies rpmGlobalMacroContext, fileSystem, internalState @*/;
 855
 856 /** \ingroup rpmdb
 857  * Verify database components.
 858  * @param prefix        path to top of install tree
 859  * @return              0 on success
 860  */
 861 int rpmdbVerify(/*@null@*/ const char * prefix)
 862         /*@globals rpmGlobalMacroContext, fileSystem, internalState @*/
 863         /*@modifies rpmGlobalMacroContext, fileSystem, internalState @*/;
 864
 865 /**
 866  * Close a single database index.
 867  * @param db            rpm database
 868  * @param rpmtag        rpm tag
 869  * @return              0 on success
 870  */
 871 int rpmdbCloseDBI(/*@null@*/ rpmdb db, int rpmtag)
 872         /*@globals fileSystem @*/
 873         /*@modifies db, fileSystem @*/;
 874
 875 /** \ingroup rpmdb
 876  * Close all database indices and free rpmdb.
 877  * @param db            rpm database
 878  * @return              0 on success
 879  */
 880 int rpmdbClose (/*@killref@*/ /*@only@*/ /*@null@*/ rpmdb db)
 881         /*@globals fileSystem @*/
 882         /*@modifies db, fileSystem @*/;
 883
 884 /** \ingroup rpmdb
 885  * Sync all database indices.
 886  * @param db            rpm database
 887  * @return              0 on success
 888  */
 889 int rpmdbSync (/*@null@*/ rpmdb db)
 890         /*@globals fileSystem @*/
 891         /*@modifies fileSystem @*/;
 892
 893 /** \ingroup rpmdb
 894  * Open all database indices.
 895  * @param db            rpm database
 896  * @return              0 on success
 897  */
 898 /*@-exportlocal@*/
 899 int rpmdbOpenAll (/*@null@*/ rpmdb db)
 900         /*@globals rpmGlobalMacroContext @*/
 901         /*@modifies db, rpmGlobalMacroContext @*/;
 902 /*@=exportlocal@*/
 903
 904 /** \ingroup rpmdb
 905  * Return number of instances of package in rpm database.
 906  * @param db            rpm database
 907  * @param name          rpm package name
 908  * @return              number of instances
 909  */
 910 int rpmdbCountPackages(/*@null@*/ rpmdb db, const char * name)
 911         /*@globals rpmGlobalMacroContext, fileSystem @*/
 912         /*@modifies db, rpmGlobalMacroContext, fileSystem @*/;
 913
 914 /** \ingroup rpmdb
 915  * Return header join key for current position of rpm database iterator.
 916  * @param mi            rpm database iterator
 917  * @return              current header join key
 918  */
 919 unsigned int rpmdbGetIteratorOffset(/*@null@*/ rpmdbMatchIterator mi)
 920         /*@*/;
 921
 922 /** \ingroup rpmdb
 923  * Return number of elements in rpm database iterator.
 924  * @param mi            rpm database iterator
 925  * @return              number of elements
 926  */
 927 int rpmdbGetIteratorCount(/*@null@*/ rpmdbMatchIterator mi)
 928         /*@*/;
 929
 930 /** \ingroup rpmdb
 931  * Append items to set of package instances to iterate.
 932  * @param mi            rpm database iterator
 933  * @param hdrNums       array of package instances
 934  * @param nHdrNums      number of elements in array
 935  * @return              0 on success, 1 on failure (bad args)
 936  */
 937 int rpmdbAppendIterator(/*@null@*/ rpmdbMatchIterator mi,
 938                 /*@null@*/ const int * hdrNums, int nHdrNums)
 939         /*@modifies mi @*/;
 940
 941 /** \ingroup rpmdb
 942  * Remove items from set of package instances to iterate.
 943  * @note Sorted hdrNums are always passed in rpmlib.
 944  * @param mi            rpm database iterator
 945  * @param hdrNums       array of package instances
 946  * @param nHdrNums      number of elements in array
 947  * @param sorted        is the array sorted? (array will be sorted on return)
 948  * @return              0 on success, 1 on failure (bad args)
 949  */
 950 int rpmdbPruneIterator(/*@null@*/ rpmdbMatchIterator mi,
 951                 /*@null@*/ int * hdrNums, int nHdrNums, int sorted)
 952         /*@modifies mi, hdrNums @*/;
 953
 954 /** \ingroup rpmdb
 955  * Add pattern to iterator selector.
 956  * @param mi            rpm database iterator
 957  * @param tag           rpm tag
 958  * @param mode          type of pattern match
 959  * @param pattern       pattern to match
 960  * @return              0 on success
 961  */
 962 int rpmdbSetIteratorRE(/*@null@*/ rpmdbMatchIterator mi, rpmTag tag,
 963                 rpmMireMode mode, /*@null@*/ const char * pattern)
 964         /*@globals rpmGlobalMacroContext @*/
 965         /*@modifies mi, mode, rpmGlobalMacroContext @*/;
 966
 967 /** \ingroup rpmdb
 968  * Prepare iterator for lazy writes.
 969  * @note Must be called before rpmdbNextIterator() with CDB model database.
 970  * @param mi            rpm database iterator
 971  * @param rewrite       new value of rewrite
 972  * @return              previous value
 973  */
 974 int rpmdbSetIteratorRewrite(/*@null@*/ rpmdbMatchIterator mi, int rewrite)
 975         /*@modifies mi @*/;
 976
 977 /** \ingroup rpmdb
 978  * Modify iterator to mark header for lazy write on release.
 979  * @param mi            rpm database iterator
 980  * @param modified      new value of modified
 981  * @return              previous value
 982  */
 983 int rpmdbSetIteratorModified(/*@null@*/ rpmdbMatchIterator mi, int modified)
 984         /*@modifies mi @*/;
 985
 986 /** \ingroup rpmdb
 987  * Modify iterator to verify retrieved header blobs.
 988  * @param mi            rpm database iterator
 989  * @param ts            transaction set
 990  * @param (*hdrchk)     headerCheck() vector
 991  * @return              0 always
 992  */
 993 int rpmdbSetHdrChk(/*@null@*/ rpmdbMatchIterator mi, /*@null@*/ rpmts ts,
 994                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void * uh, size_t uc, const char ** msg))
 995         /*@modifies mi @*/;
 996
 997 /** \ingroup rpmdb
 998  * Return database iterator.
 999  * @param db            rpm database
1000  * @param rpmtag        rpm tag
1001  * @param keyp          key data (NULL for sequential access)
1002  * @param keylen        key data length (0 will use strlen(keyp))
1003  * @return              NULL on failure
1004  */
1005 /*@only@*/ /*@null@*/
1006 rpmdbMatchIterator rpmdbInitIterator(/*@null@*/ rpmdb db, rpmTag rpmtag,
1007                         /*@null@*/ const void * keyp, size_t keylen)
1008         /*@globals rpmGlobalMacroContext, fileSystem @*/
1009         /*@modifies db, rpmGlobalMacroContext, fileSystem @*/;
1010
1011 /** \ingroup rpmdb
1012  * Return next package header from iteration.
1013  * @param mi            rpm database iterator
1014  * @return              NULL on end of iteration.
1015  */
1016 /*@null@*/
1017 Header rpmdbNextIterator(/*@null@*/ rpmdbMatchIterator mi)
1018         /*@globals rpmGlobalMacroContext, fileSystem @*/
1019         /*@modifies mi, rpmGlobalMacroContext, fileSystem @*/;
1020
1021 /** \ingroup rpmdb
1022  * Destroy rpm database iterator.
1023  * @param mi            rpm database iterator
1024  * @return              NULL always
1025  */
1026 /*@null@*/
1027 rpmdbMatchIterator rpmdbFreeIterator(/*@only@*/ /*@null@*/rpmdbMatchIterator mi)
1028         /*@globals rpmGlobalMacroContext, fileSystem @*/
1029         /*@modifies mi, rpmGlobalMacroContext, fileSystem @*/;
1030
1031 /** \ingroup rpmdb
1032  * Add package header to rpm database and indices.
1033  * @param db            rpm database
1034  * @param iid           install transaction id (iid = 0 or -1 to skip)
1035  * @param h             header
1036  * @param ts            (unused) transaction set (or NULL)
1037  * @param (*hdrchk)     (unused) headerCheck() vector (or NULL)
1038  * @return              0 on success
1039  */
1040 int rpmdbAdd(/*@null@*/ rpmdb db, int iid, Header h, /*@null@*/ rpmts ts,
1041                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1042         /*@globals rpmGlobalMacroContext, fileSystem @*/
1043         /*@modifies db, h, rpmGlobalMacroContext, fileSystem @*/;
1044
1045 /** \ingroup rpmdb
1046  * Remove package header from rpm database and indices.
1047  * @param db            rpm database
1048  * @param rid           (unused) remove transaction id (rid = 0 or -1 to skip)
1049  * @param hdrNum        package instance number in database
1050  * @param ts            (unused) transaction set (or NULL)
1051  * @param (*hdrchk)     (unused) headerCheck() vector (or NULL)
1052  * @return              0 on success
1053  */
1054 int rpmdbRemove(/*@null@*/ rpmdb db, /*@unused@*/ int rid, unsigned int hdrNum,
1055                 /*@null@*/ rpmts ts,
1056                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1057         /*@globals rpmGlobalMacroContext, fileSystem @*/
1058         /*@modifies db, rpmGlobalMacroContext, fileSystem @*/;
1059
1060 /** \ingroup rpmdb
1061  * Rebuild database indices from package headers.
1062  * @param prefix        path to top of install tree
1063  * @param ts            transaction set (or NULL)
1064  * @param (*hdrchk)     headerCheck() vector (or NULL)
1065  * @return              0 on success
1066  */
1067 int rpmdbRebuild(/*@null@*/ const char * prefix, /*@null@*/ rpmts ts,
1068                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1069         /*@globals rpmGlobalMacroContext, fileSystem, internalState @*/
1070         /*@modifies rpmGlobalMacroContext, fileSystem, internalState @*/;
1071
1072 /**
1073  * Mergesort, same arguments as qsort(2).
1074  */
1075 /*@unused@*/
1076 int mergesort(void *base, size_t nmemb, size_t size,
1077                 int (*cmp) (const void *, const void *))
1078         /*@globals errno @*/
1079         /*@modifies base, errno @*/;
1080
1081 #ifdef __cplusplus
1082 }
1083 #endif
1084
1085 /*@=bounds@*/
1086 #endif  /* H_RPMDB */