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,    /*!< strings  using strcmp(3) */
  32     RPMMIRE_REGEX       = 2,    /*!< regex(7) patterns through regcomp(3) */
  33     RPMMIRE_GLOB        = 3     /*!< glob(7) 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;            /*!< the parent rpm database */
 373     rpmTag dbi_rpmtag;          /*!< rpm tag used for index */
 374     int dbi_jlen;               /*!< size of join key */
 375
 376 /*@only@*//*@null@*/
 377     DB * dbi_db;                /*!< Berkeley DB * handle */
 378 /*@only@*//*@null@*/
 379     DB_TXN * dbi_txnid;         /*!< Bekerley DB_TXN * transaction id */
 380 /*@only@*//*@null@*/
 381     void * dbi_stats;           /*!< Berkeley db statistics */
 382
 383 /*@observer@*/
 384     const struct _dbiVec * dbi_vec;     /*!< private methods */
 385
 386 };
 387
 388 /** \ingroup rpmdb
 389  * Describes the collection of index databases used by rpm.
 390  */
 391 struct rpmdb_s {
 392 /*@owned@*/
 393     const char * db_root;/*!< path prefix */
 394 /*@owned@*/
 395     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@*/
 401     const char * db_errpfx;
 402     int         db_remove_env;
 403     int         db_filter_dups;
 404     int         db_chrootDone;  /*!< If chroot(2) done, ignore db_root. */
 405     void (*db_errcall) (const char *db_errpfx, char *buffer)
 406         /*@*/;
 407 /*@shared@*/
 408     FILE *      db_errfile;
 409 /*@only@*/
 410     void * (*db_malloc) (size_t nbytes)
 411         /*@*/;
 412 /*@only@*/
 413     void * (*db_realloc) (/*@only@*//*@null@*/ void * ptr,
 414                                                 size_t nbytes)
 415         /*@*/;
 416     void (*db_free) (/*@only@*/ void * ptr)
 417         /*@modifies *ptr @*/;
 418 /*@only@*/ /*@null@*/
 419     unsigned char * db_bits;    /*!< package instance bit mask. */
 420     int         db_nbits;       /*!< no. of bits in mask. */
 421     int         db_opens;
 422 /*@only@*/ /*@null@*/
 423     void *      db_dbenv;       /*!< Berkeley DB_ENV handle. */
 424     int         db_ndbi;        /*!< No. of tag indices. */
 425     dbiIndex * _dbi;            /*!< Tag indices. */
 426
 427 /*@refs@*/
 428     int nrefs;                  /*!< Reference count. */
 429 };
 430
 431 /* for RPM's internal use only */
 432
 433 /** \ingroup rpmdb
 434  */
 435 enum rpmdbFlags {
 436         RPMDB_FLAG_JUSTCHECK    = (1 << 0),
 437         RPMDB_FLAG_MINIMAL      = (1 << 1),
 438 /*@-enummemuse@*/
 439         RPMDB_FLAG_CHROOT       = (1 << 2)
 440 /*@=enummemuse@*/
 441 };
 442
 443 #ifdef __cplusplus
 444 extern "C" {
 445 #endif
 446
 447 /*@-exportlocal@*/
 448 /** \ingroup db3
 449  * Return new configured index database handle instance.
 450  * @param rpmdb         rpm database
 451  * @param rpmtag        rpm tag
 452  * @return              index database handle
 453  */
 454 /*@unused@*/ /*@only@*/ /*@null@*/
 455 dbiIndex db3New(rpmdb rpmdb, rpmTag rpmtag)
 456         /*@globals rpmGlobalMacroContext @*/
 457         /*@modifies rpmGlobalMacroContext @*/;
 458
 459 /** \ingroup db3
 460  * Destroy index database handle instance.
 461  * @param dbi           index database handle
 462  * @return              NULL always
 463  */
 464 /*@null@*/
 465 dbiIndex db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi)
 466         /*@*/;
 467
 468 /** \ingroup db3
 469  * Format db3 open flags for debugging print.
 470  * @param dbflags               db open flags
 471  * @param print_dbenv_flags     format db env flags instead?
 472  * @return                      formatted flags (static buffer)
 473  */
 474 /*@-redecl@*/
 475 /*@exposed@*/
 476 extern const char *const prDbiOpenFlags(int dbflags, int print_dbenv_flags)
 477         /*@*/;
 478 /*@=redecl@*/
 479
 480 /** \ingroup dbi
 481  * Return handle for an index database.
 482  * @param db            rpm database
 483  * @param rpmtag        rpm tag
 484  * @param flags         (unused)
 485  * @return              index database handle
 486  */
 487 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(/*@null@*/ rpmdb db, rpmTag rpmtag,
 488                 unsigned int flags)
 489         /*@modifies db @*/;
 490
 491 /*@-globuse -mustmod @*/ /* FIX: vector annotations */
 492 /** \ingroup dbi
 493  * Open a database cursor.
 494  * @param dbi           index database handle
 495  * @param txnid         database transaction handle
 496  * @retval dbcp         returned database cursor
 497  * @param flags         DB_WRITECURSOR if writing, or 0
 498  * @return              0 on success
 499  */
 500 /*@unused@*/ static inline
 501 int dbiCopen(dbiIndex dbi, /*@null@*/ DB_TXN * txnid,
 502                 /*@out@*/ DBC ** dbcp, unsigned int flags)
 503         /*@globals fileSystem @*/
 504         /*@modifies dbi, *dbcp, fileSystem @*/
 505 {
 506     return (*dbi->dbi_vec->copen) (dbi, txnid, dbcp, flags);
 507 }
 508
 509 /** \ingroup dbi
 510  * Close a database cursor.
 511  * @param dbi           index database handle
 512  * @param dbcursor      database cursor
 513  * @param flags         (unused)
 514  * @return              0 on success
 515  */
 516 /*@unused@*/ static inline
 517 int dbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
 518         /*@globals fileSystem @*/
 519         /*@modifies dbi, *dbcursor, fileSystem @*/
 520 {
 521     return (*dbi->dbi_vec->cclose) (dbi, dbcursor, flags);
 522 }
 523
 524 /** \ingroup dbi
 525  * Duplicate a database cursor.
 526  * @param dbi           index database handle
 527  * @param dbcursor      database cursor
 528  * @retval dbcp         address of new database cursor
 529  * @param flags         DB_POSITION for same position, 0 for uninitialized
 530  * @return              0 on success
 531  */
 532 /*@unused@*/ static inline
 533 int dbiCdup(dbiIndex dbi, DBC * dbcursor, /*@out@*/ DBC ** dbcp,
 534                 unsigned int flags)
 535         /*@modifies dbi, *dbcp @*/
 536 {
 537     return (*dbi->dbi_vec->cdup) (dbi, dbcursor, dbcp, flags);
 538 }
 539
 540 /** \ingroup dbi
 541  * Delete (key,data) pair(s) from index database.
 542  * @param dbi           index database handle
 543  * @param dbcursor      database cursor (NULL will use db->del)
 544  * @param key           delete key value/length/flags
 545  * @param data          delete data value/length/flags
 546  * @param flags         (unused)
 547  * @return              0 on success
 548  */
 549 /*@unused@*/ static inline
 550 int dbiDel(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 551                 unsigned int flags)
 552         /*@globals fileSystem @*/
 553         /*@modifies *dbcursor, fileSystem @*/
 554 {
 555     assert(key->data != NULL && key->size > 0);
 556     return (dbi->dbi_vec->cdel) (dbi, dbcursor, key, data, flags);
 557 }
 558
 559 /** \ingroup dbi
 560  * Retrieve (key,data) pair from index database.
 561  * @param dbi           index database handle
 562  * @param dbcursor      database cursor (NULL will use db->get)
 563  * @param key           retrieve key value/length/flags
 564  * @param data          retrieve data value/length/flags
 565  * @param flags         (unused)
 566  * @return              0 on success
 567  */
 568 /*@unused@*/ static inline
 569 int dbiGet(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 570                 unsigned int flags)
 571         /*@globals fileSystem @*/
 572         /*@modifies *dbcursor, *key, *data, fileSystem @*/
 573 {
 574     assert((flags == DB_NEXT) || (key->data != NULL && key->size > 0));
 575     return (dbi->dbi_vec->cget) (dbi, dbcursor, key, data, flags);
 576 }
 577
 578 /** \ingroup dbi
 579  * Retrieve (key,data) pair using dbcursor->c_pget.
 580  * @param dbi           index database handle
 581  * @param dbcursor      database cursor (NULL will use db->get)
 582  * @param key           secondary retrieve key value/length/flags
 583  * @param pkey          primary retrieve key value/length/flags
 584  * @param data          primary retrieve data value/length/flags
 585  * @param flags         DB_NEXT, DB_SET, or 0
 586  * @return              0 on success
 587  */
 588 /*@unused@*/ static inline
 589 int dbiPget(dbiIndex dbi, /*@null@*/ DBC * dbcursor,
 590                 DBT * key, DBT * pkey, DBT * data, unsigned int flags)
 591         /*@globals fileSystem @*/
 592         /*@modifies *dbcursor, *key, *pkey, *data, fileSystem @*/
 593 {
 594     assert((flags == DB_NEXT) || (key->data != NULL && key->size > 0));
 595     return (dbi->dbi_vec->cpget) (dbi, dbcursor, key, pkey, data, flags);
 596 }
 597
 598 /** \ingroup dbi
 599  * Store (key,data) pair in index database.
 600  * @param dbi           index database handle
 601  * @param dbcursor      database cursor (NULL will use db->put)
 602  * @param key           store key value/length/flags
 603  * @param data          store data value/length/flags
 604  * @param flags         (unused)
 605  * @return              0 on success
 606  */
 607 /*@unused@*/ static inline
 608 int dbiPut(dbiIndex dbi, /*@null@*/ DBC * dbcursor, DBT * key, DBT * data,
 609                 unsigned int flags)
 610         /*@globals fileSystem @*/
 611         /*@modifies *dbcursor, *key, fileSystem @*/
 612 {
 613     assert(key->data != NULL && key->size > 0 && data->data != NULL && data->size > 0);
 614     return (dbi->dbi_vec->cput) (dbi, dbcursor, key, data, flags);
 615 }
 616
 617 /** \ingroup dbi
 618  * Retrieve count of (possible) duplicate items.
 619  * @param dbi           index database handle
 620  * @param dbcursor      database cursor
 621  * @param countp        address of count
 622  * @param flags         (unused)
 623  * @return              0 on success
 624  */
 625 /*@unused@*/ static inline
 626 int dbiCount(dbiIndex dbi, DBC * dbcursor, /*@out@*/ unsigned int * countp,
 627                 unsigned int flags)
 628         /*@globals fileSystem @*/
 629         /*@modifies *dbcursor, fileSystem @*/
 630 {
 631     return (*dbi->dbi_vec->ccount) (dbi, dbcursor, countp, flags);
 632 }
 633
 634 /** \ingroup dbi
 635  * Verify (and close) index database.
 636  * @param dbi           index database handle
 637  * @param flags         (unused)
 638  * @return              0 on success
 639  */
 640 /*@unused@*/ static inline
 641 int dbiVerify(/*@only@*/ dbiIndex dbi, unsigned int flags)
 642         /*@globals fileSystem @*/
 643         /*@modifies dbi, fileSystem @*/
 644 {
 645     dbi->dbi_verify_on_close = 1;
 646     return (*dbi->dbi_vec->close) (dbi, flags);
 647 }
 648
 649 /** \ingroup dbi
 650  * Close index database.
 651  * @param dbi           index database handle
 652  * @param flags         (unused)
 653  * @return              0 on success
 654  */
 655 /*@unused@*/ static inline
 656 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags)
 657         /*@globals fileSystem @*/
 658         /*@modifies dbi, fileSystem @*/
 659 {
 660     return (*dbi->dbi_vec->close) (dbi, flags);
 661 }
 662
 663 /** \ingroup dbi
 664  * Flush pending operations to disk.
 665  * @param dbi           index database handle
 666  * @param flags         (unused)
 667  * @return              0 on success
 668  */
 669 /*@unused@*/ static inline
 670 int dbiSync (dbiIndex dbi, unsigned int flags)
 671         /*@globals fileSystem @*/
 672         /*@modifies fileSystem @*/
 673 {
 674     return (*dbi->dbi_vec->sync) (dbi, flags);
 675 }
 676
 677 /** \ingroup dbi
 678  * Associate secondary database with primary.
 679  * @param dbi           index database handle
 680  * @param dbisecondary  secondary index database handle
 681  * @param callback      create secondary key from primary (NULL if DB_RDONLY)
 682  * @param flags         DB_CREATE or 0
 683  * @return              0 on success
 684  */
 685 /*@unused@*/ static inline
 686 int dbiAssociate(dbiIndex dbi, dbiIndex dbisecondary,
 687                 int (*callback) (DB *, const DBT *, const DBT *, DBT *),
 688                 unsigned int flags)
 689         /*@globals fileSystem @*/
 690         /*@modifies dbi, fileSystem @*/
 691 {
 692     return (*dbi->dbi_vec->associate) (dbi, dbisecondary, callback, flags);
 693 }
 694
 695 /** \ingroup dbi
 696  * Return join cursor for list of cursors.
 697  * @param dbi           index database handle
 698  * @param curslist      NULL terminated list of database cursors
 699  * @retval dbcp         address of join database cursor
 700  * @param flags         DB_JOIN_NOSORT or 0
 701  * @return              0 on success
 702  */
 703 /*@unused@*/ static inline
 704 int dbiJoin(dbiIndex dbi, DBC ** curslist, /*@out@*/ DBC ** dbcp,
 705                 unsigned int flags)
 706         /*@globals fileSystem @*/
 707         /*@modifies dbi, *dbcp, fileSystem @*/
 708 {
 709     return (*dbi->dbi_vec->join) (dbi, curslist, dbcp, flags);
 710 }
 711
 712 /** \ingroup dbi
 713  * Is database byte swapped?
 714  * @param dbi           index database handle
 715  * @return              0 no
 716  */
 717 /*@unused@*/ static inline
 718 int dbiByteSwapped(dbiIndex dbi)
 719         /*@modifies dbi @*/
 720 {
 721     if (dbi->dbi_byteswapped == -1)
 722         dbi->dbi_byteswapped = (*dbi->dbi_vec->byteswapped) (dbi);
 723     return dbi->dbi_byteswapped;
 724 }
 725 /** \ingroup dbi
 726  * Is database byte swapped?
 727  * @param dbi           index database handle
 728  * @return              0 no
 729  */
 730 /*@unused@*/ static inline
 731 int dbiStat(dbiIndex dbi, unsigned int flags)
 732         /*@modifies dbi @*/
 733 {
 734     return (*dbi->dbi_vec->stat) (dbi, flags);
 735 }
 736 /*@=globuse =mustmod @*/
 737
 738 /*@=exportlocal@*/
 739
 740 /** \ingroup rpmdb
 741  */
 742 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi)
 743         /*@*/;
 744
 745 /** \ingroup dbi
 746  * Destroy set of index database items.
 747  * @param set   set of index database items
 748  * @return      NULL always
 749  */
 750 /*@null@*/ dbiIndexSet dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set)
 751         /*@modifies set @*/;
 752
 753 /** \ingroup dbi
 754  * Count items in index database set.
 755  * @param set   set of index database items
 756  * @return      number of items
 757  */
 758 unsigned int dbiIndexSetCount(dbiIndexSet set)
 759         /*@*/;
 760
 761 /** \ingroup dbi
 762  * Return record offset of header from element in index database set.
 763  * @param set   set of index database items
 764  * @param recno index of item in set
 765  * @return      record offset of header
 766  */
 767 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno)
 768         /*@*/;
 769
 770 /** \ingroup dbi
 771  * Return file index from element in index database set.
 772  * @param set   set of index database items
 773  * @param recno index of item in set
 774  * @return      file index
 775  */
 776 unsigned int dbiIndexRecordFileNumber(dbiIndexSet set, int recno)
 777         /*@*/;
 778
 779 /** \ingroup rpmdb
 780  * Tags for which rpmdb indices will be built.
 781  */
 782 /*@-exportlocal@*/
 783 /*@unchecked@*/
 784 /*@only@*/ /*@null@*/ extern int * dbiTags;
 785 /*@unchecked@*/
 786 extern int dbiTagsMax;
 787 /*@=exportlocal@*/
 788
 789 /** \ingroup rpmdb
 790  * Unreference a database instance.
 791  * @param db            rpm database
 792  * @param msg
 793  * @return              NULL always
 794  */
 795 /*@unused@*/ /*@null@*/
 796 rpmdb rpmdbUnlink (/*@killref@*/ /*@only@*/ rpmdb db, const char * msg)
 797         /*@modifies db @*/;
 798
 799 /** @todo Remove debugging entry from the ABI. */
 800 /*@-exportlocal@*/
 801 /*@null@*/
 802 rpmdb XrpmdbUnlink (/*@killref@*/ /*@only@*/ rpmdb db, const char * msg,
 803                 const char * fn, unsigned ln)
 804         /*@modifies db @*/;
 805 /*@=exportlocal@*/
 806 #define rpmdbUnlink(_db, _msg)  XrpmdbUnlink(_db, _msg, __FILE__, __LINE__)
 807
 808 /** \ingroup rpmdb
 809  * Reference a database instance.
 810  * @param db            rpm database
 811  * @param msg
 812  * @return              new rpm database reference
 813  */
 814 /*@unused@*/
 815 rpmdb rpmdbLink (rpmdb db, const char * msg)
 816         /*@modifies db @*/;
 817
 818 /** @todo Remove debugging entry from the ABI. */
 819 /*@-exportlocal@*/
 820 rpmdb XrpmdbLink (rpmdb db, const char * msg,
 821                 const char * fn, unsigned ln)
 822         /*@modifies db @*/;
 823 /*@=exportlocal@*/
 824 #define rpmdbLink(_db, _msg)    XrpmdbLink(_db, _msg, __FILE__, __LINE__)
 825
 826 /** \ingroup rpmdb
 827  * Open rpm database.
 828  * @param prefix        path to top of install tree
 829  * @retval dbp          address of rpm database
 830  * @param mode          open(2) flags:  O_RDWR or O_RDONLY (O_CREAT also)
 831  * @param perms         database permissions
 832  * @return              0 on success
 833  */
 834 int rpmdbOpen (/*@null@*/ const char * prefix, /*@null@*/ /*@out@*/ rpmdb * dbp,
 835                 int mode, int perms)
 836         /*@globals fileSystem @*/
 837         /*@modifies *dbp, fileSystem @*/;
 838
 839 /** \ingroup rpmdb
 840  * Initialize database.
 841  * @param prefix        path to top of install tree
 842  * @param perms         database permissions
 843  * @return              0 on success
 844  */
 845 int rpmdbInit(/*@null@*/ const char * prefix, int perms)
 846         /*@globals fileSystem @*/
 847         /*@modifies fileSystem @*/;
 848
 849 /** \ingroup rpmdb
 850  * Verify database components.
 851  * @param prefix        path to top of install tree
 852  * @return              0 on success
 853  */
 854 int rpmdbVerify(/*@null@*/ const char * prefix)
 855         /*@globals fileSystem @*/
 856         /*@modifies fileSystem @*/;
 857
 858 /**
 859  * Close a single database index.
 860  * @param db            rpm database
 861  * @param rpmtag        rpm tag
 862  * @return              0 on success
 863  */
 864 int rpmdbCloseDBI(/*@null@*/ rpmdb db, int rpmtag)
 865         /*@globals fileSystem @*/
 866         /*@modifies db, fileSystem @*/;
 867
 868 /** \ingroup rpmdb
 869  * Close all database indices and free rpmdb.
 870  * @param db            rpm database
 871  * @return              0 on success
 872  */
 873 int rpmdbClose (/*@killref@*/ /*@only@*/ /*@null@*/ rpmdb db)
 874         /*@globals fileSystem @*/
 875         /*@modifies db, fileSystem @*/;
 876
 877 /** \ingroup rpmdb
 878  * Sync all database indices.
 879  * @param db            rpm database
 880  * @return              0 on success
 881  */
 882 int rpmdbSync (/*@null@*/ rpmdb db)
 883         /*@globals fileSystem @*/
 884         /*@modifies fileSystem @*/;
 885
 886 /** \ingroup rpmdb
 887  * Open all database indices.
 888  * @param db            rpm database
 889  * @return              0 on success
 890  */
 891 /*@-exportlocal@*/
 892 int rpmdbOpenAll (/*@null@*/ rpmdb db)
 893         /*@modifies db @*/;
 894 /*@=exportlocal@*/
 895
 896 /** \ingroup rpmdb
 897  * Return number of instances of package in rpm database.
 898  * @param db            rpm database
 899  * @param name          rpm package name
 900  * @return              number of instances
 901  */
 902 int rpmdbCountPackages(/*@null@*/ rpmdb db, const char * name)
 903         /*@globals fileSystem @*/
 904         /*@modifies db, fileSystem @*/;
 905
 906 /** \ingroup rpmdb
 907  * Return header join key for current position of rpm database iterator.
 908  * @param mi            rpm database iterator
 909  * @return              current header join key
 910  */
 911 unsigned int rpmdbGetIteratorOffset(/*@null@*/ rpmdbMatchIterator mi)
 912         /*@*/;
 913
 914 /** \ingroup rpmdb
 915  * Return number of elements in rpm database iterator.
 916  * @param mi            rpm database iterator
 917  * @return              number of elements
 918  */
 919 int rpmdbGetIteratorCount(/*@null@*/ rpmdbMatchIterator mi)
 920         /*@*/;
 921
 922 /** \ingroup rpmdb
 923  * Append items to set of package instances to iterate.
 924  * @param mi            rpm database iterator
 925  * @param hdrNums       array of package instances
 926  * @param nHdrNums      number of elements in array
 927  * @return              0 on success, 1 on failure (bad args)
 928  */
 929 int rpmdbAppendIterator(/*@null@*/ rpmdbMatchIterator mi,
 930                 /*@null@*/ const int * hdrNums, int nHdrNums)
 931         /*@modifies mi @*/;
 932
 933 /** \ingroup rpmdb
 934  * Remove items from set of package instances to iterate.
 935  * @note Sorted hdrNums are always passed in rpmlib.
 936  * @param mi            rpm database iterator
 937  * @param hdrNums       array of package instances
 938  * @param nHdrNums      number of elements in array
 939  * @param sorted        is the array sorted? (array will be sorted on return)
 940  * @return              0 on success, 1 on failure (bad args)
 941  */
 942 int rpmdbPruneIterator(/*@null@*/ rpmdbMatchIterator mi,
 943                 /*@null@*/ int * hdrNums, int nHdrNums, int sorted)
 944         /*@modifies mi, hdrNums @*/;
 945
 946 /** \ingroup rpmdb
 947  * Add pattern to iterator selector.
 948  * @param mi            rpm database iterator
 949  * @param tag           rpm tag
 950  * @param mode          type of pattern match
 951  * @param pattern       pattern to match
 952  * @return              0 on success
 953  */
 954 int rpmdbSetIteratorRE(/*@null@*/ rpmdbMatchIterator mi, rpmTag tag,
 955                 rpmMireMode mode, /*@null@*/ const char * pattern)
 956         /*@modifies mi, mode @*/;
 957
 958 /** \ingroup rpmdb
 959  * Prepare iterator for lazy writes.
 960  * @note Must be called before rpmdbNextIterator() with CDB model database.
 961  * @param mi            rpm database iterator
 962  * @param rewrite       new value of rewrite
 963  * @return              previous value
 964  */
 965 int rpmdbSetIteratorRewrite(/*@null@*/ rpmdbMatchIterator mi, int rewrite)
 966         /*@modifies mi @*/;
 967
 968 /** \ingroup rpmdb
 969  * Modify iterator to mark header for lazy write on release.
 970  * @param mi            rpm database iterator
 971  * @param modified      new value of modified
 972  * @return              previous value
 973  */
 974 int rpmdbSetIteratorModified(/*@null@*/ rpmdbMatchIterator mi, int modified)
 975         /*@modifies mi @*/;
 976
 977 /** \ingroup rpmdb
 978  * Modify iterator to verify retrieved header blobs.
 979  * @param mi            rpm database iterator
 980  * @param ts            transaction set
 981  * @param (*hdrchk)     headerCheck() vector
 982  * @return              0 always
 983  */
 984 int rpmdbSetHdrChk(/*@null@*/ rpmdbMatchIterator mi, /*@null@*/ rpmts ts,
 985                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void * uh, size_t uc, const char ** msg))
 986         /*@modifies mi @*/;
 987
 988 /** \ingroup rpmdb
 989  * Return database iterator.
 990  * @param db            rpm database
 991  * @param rpmtag        rpm tag
 992  * @param keyp          key data (NULL for sequential access)
 993  * @param keylen        key data length (0 will use strlen(keyp))
 994  * @return              NULL on failure
 995  */
 996 /*@only@*/ /*@null@*/
 997 rpmdbMatchIterator rpmdbInitIterator(/*@null@*/ rpmdb db, rpmTag rpmtag,
 998                         /*@null@*/ const void * keyp, size_t keylen)
 999         /*@globals fileSystem @*/
1000         /*@modifies db, fileSystem @*/;
1001
1002 /** \ingroup rpmdb
1003  * Return next package header from iteration.
1004  * @param mi            rpm database iterator
1005  * @return              NULL on end of iteration.
1006  */
1007 /*@null@*/
1008 Header rpmdbNextIterator(/*@null@*/ rpmdbMatchIterator mi)
1009         /*@globals fileSystem @*/
1010         /*@modifies mi, fileSystem @*/;
1011
1012 /** \ingroup rpmdb
1013  * Destroy rpm database iterator.
1014  * @param mi            rpm database iterator
1015  * @return              NULL always
1016  */
1017 /*@null@*/
1018 rpmdbMatchIterator rpmdbFreeIterator(/*@only@*/ /*@null@*/rpmdbMatchIterator mi)
1019         /*@globals fileSystem @*/
1020         /*@modifies mi, fileSystem @*/;
1021
1022 /** \ingroup rpmdb
1023  * Add package header to rpm database and indices.
1024  * @param db            rpm database
1025  * @param iid           install transaction id (iid = 0 or -1 to skip)
1026  * @param h             header
1027  * @param ts            (unused) transaction set (or NULL)
1028  * @param (*hdrchk)     (unused) headerCheck() vector (or NULL)
1029  * @return              0 on success
1030  */
1031 int rpmdbAdd(/*@null@*/ rpmdb db, int iid, Header h, /*@null@*/ rpmts ts,
1032                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1033         /*@globals fileSystem @*/
1034         /*@modifies db, h, fileSystem @*/;
1035
1036 /** \ingroup rpmdb
1037  * Remove package header from rpm database and indices.
1038  * @param db            rpm database
1039  * @param rid           (unused) remove transaction id (rid = 0 or -1 to skip)
1040  * @param hdrNum        package instance number in database
1041  * @param ts            (unused) transaction set (or NULL)
1042  * @param (*hdrchk)     (unused) headerCheck() vector (or NULL)
1043  * @return              0 on success
1044  */
1045 int rpmdbRemove(/*@null@*/ rpmdb db, /*@unused@*/ int rid, unsigned int hdrNum,
1046                 /*@null@*/ rpmts ts,
1047                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1048         /*@globals fileSystem @*/
1049         /*@modifies db, fileSystem @*/;
1050
1051 /** \ingroup rpmdb
1052  * Rebuild database indices from package headers.
1053  * @param prefix        path to top of install tree
1054  * @param ts            transaction set (or NULL)
1055  * @param (*hdrchk)     headerCheck() vector (or NULL)
1056  * @return              0 on success
1057  */
1058 int rpmdbRebuild(/*@null@*/ const char * prefix, /*@null@*/ rpmts ts,
1059                 /*@null@*/ rpmRC (*hdrchk) (rpmts ts, const void *uh, size_t uc, const char ** msg))
1060         /*@globals rpmGlobalMacroContext, fileSystem, internalState @*/
1061         /*@modifies rpmGlobalMacroContext, fileSystem, internalState @*/;
1062
1063 /**
1064  * Mergesort, same arguments as qsort(2).
1065  */
1066 /*@unused@*/
1067 int mergesort(void *base, size_t nmemb, size_t size,
1068                 int (*cmp) (const void *, const void *))
1069         /*@globals errno @*/
1070         /*@modifies base, errno @*/;
1071
1072 #ifdef __cplusplus
1073 }
1074 #endif
1075
1076 /*@=bounds@*/
1077 #endif  /* H_RPMDB */