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