rpmdb/rpmdb.h

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