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