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 <rpmlib.h>
  10
  11 #include "fprint.h"
  12
  13 typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem;
  14 typedef /*@abstract@*/ struct _dbiIndex * dbiIndex;
  15
  16 /* this will break if sizeof(int) != 4 */
  17 /** \ingroup dbi
  18  * A single item from an index database (i.e. the "data returned").
  19  * Note: In rpm-3.0.4 and earlier, this structure was passed by value,
  20  * and was identical to the "data saved" structure below.
  21  */
  22 struct _dbiIndexItem {
  23     unsigned int hdrNum;                /*!< header instance in db */
  24     unsigned int tagNum;                /*!< tag index in header */
  25     unsigned int fpNum;                 /*!< finger print index */
  26     unsigned int dbNum;                 /*!< database index */
  27 };
  28
  29 /** \ingroup dbi
  30  * A single item in an index database (i.e. the "data saved").
  31  */
  32 struct _dbiIR {
  33     unsigned int recOffset;             /*!< byte offset of header in db */
  34     unsigned int fileNumber;            /*!< file array index */
  35 };
  36 typedef struct _dbiIR * DBIR_t;
  37
  38 /** \ingroup dbi
  39  * Items retrieved from the index database.
  40  */
  41 struct _dbiIndexSet {
  42 /*@owned@*/ struct _dbiIndexItem * recs; /*!< array of records */
  43     int count;                          /*!< number of records */
  44 };
  45
  46 /* XXX hack to get prototypes correct */
  47 #if !defined(DB_VERSION_MAJOR)
  48 #define DB_ENV  void
  49 #define DBC     void
  50 #define DBT     void
  51 #define DB_LSN  void
  52 #endif
  53
  54 /** \ingroup dbi
  55  * Private methods for accessing an index database.
  56  */
  57 struct _dbiVec {
  58     int dbv_major;                      /*!< Berkeley db version major */
  59     int dbv_minor;                      /*!< Berkeley db version minor */
  60     int dbv_patch;                      /*!< Berkeley db version patch */
  61
  62 /** \ingroup dbi
  63  * Return handle for an index database.
  64  * @param rpmdb         rpm database
  65  * @param rpmtag        rpm tag
  66  * @return              0 on success
  67  */
  68     int (*open) (rpmdb rpmdb, int rpmtag, /*@out@*/ dbiIndex * dbip);
  69
  70 /** \ingroup dbi
  71  * Close index database, and destroy database handle.
  72  * @param dbi           index database handle
  73  * @param flags         (unused)
  74  * @return              0 on success
  75  */
  76     int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags);
  77
  78 /** \ingroup dbi
  79  * Flush pending operations to disk.
  80  * @param dbi           index database handle
  81  * @param flags         (unused)
  82  * @return              0 on success
  83  */
  84     int (*sync) (dbiIndex dbi, unsigned int flags);
  85
  86 /** \ingroup dbi
  87  * Open database cursor.
  88  * @param dbi           index database handle
  89  * @param dbcp          address of database cursor
  90  * @param flags         (unused)
  91  */
  92     int (*copen) (dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags);
  93
  94 /** \ingroup dbi
  95  * Close database cursor.
  96  * @param dbi           index database handle
  97  * @param dbcursor      database cursor
  98  * @param flags         (unused)
  99  */
 100     int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags);
 101
 102 /** \ingroup dbi
 103  * Delete (key,data) pair(s) using db->del or dbcursor->c_del.
 104  * @param dbi           index database handle
 105  * @param dbcursor      database cursor
 106  * @param keyp          key data
 107  * @param keylen        key data length
 108  * @param flags         (unused)
 109  * @return              0 on success
 110  */
 111     int (*cdel) (dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, unsigned int flags);
 112
 113 /** \ingroup dbi
 114  * Retrieve (key,data) pair using db->get or dbcursor->c_get.
 115  * @param dbi           index database handle
 116  * @param dbcursor      database cursor
 117  * @param keypp         address of key data
 118  * @param keylenp       address of key data length
 119  * @param datapp        address of data pointer
 120  * @param datalenp      address of data length
 121  * @param flags         (unused)
 122  * @return              0 on success
 123  */
 124     int (*cget) (dbiIndex dbi, DBC * dbcursor,
 125                         /*@out@*/ void ** keypp, /*@out@*/ size_t * keylenp,
 126                         /*@out@*/ void ** datapp, /*@out@*/ size_t * datalenp,
 127                         unsigned int flags);
 128
 129 /** \ingroup dbi
 130  * Store (key,data) pair using db->put or dbcursor->c_put.
 131  * @param dbi           index database handle
 132  * @param dbcursor      database cursor
 133  * @param keyp          key data
 134  * @param keylen        key data length
 135  * @param datap         data pointer
 136  * @param datalen       data length
 137  * @param flags         (unused)
 138  * @return              0 on success
 139  */
 140     int (*cput) (dbiIndex dbi, DBC * dbcursor,
 141                         const void * keyp, size_t keylen,
 142                         const void * datap, size_t datalen,
 143                         unsigned int flags);
 144
 145 /** \ingroup dbi
 146  * Retrieve count of (possible) duplicate items using dbcursor->c_count.
 147  * @param dbi           index database handle
 148  * @param dbcursor      database cursor
 149  * @param countp        address of count
 150  * @param flags         (unused)
 151  * @return              0 on success
 152  */
 153     int (*ccount) (dbiIndex dbi, DBC * dbcursor,
 154                         /*@out@*/ unsigned int * countp,
 155                         unsigned int flags);
 156
 157 /** \ingroup dbi
 158  * Is database byte swapped?
 159  * @param dbi           index database handle
 160  * @return              0 no
 161  */
 162     int (*byteswapped) (dbiIndex dbi);
 163
 164 /** \ingroup dbi
 165  * Save statistics in database handle.
 166  * @param dbi           index database handle
 167  * @param flags         retrieve statistics that don't require traversal?
 168  * @return              0 on success
 169  */
 170     int (*stat) (dbiIndex dbi, unsigned int flags);
 171
 172 };
 173
 174 /** \ingroup dbi
 175  * Describes an index database (implemented on Berkeley db3 functionality).
 176  */
 177 struct _dbiIndex {
 178 /*@null@*/ const char * dbi_root;
 179 /*@null@*/ const char * dbi_home;
 180 /*@null@*/ const char * dbi_file;
 181 /*@null@*/ const char * dbi_subfile;
 182
 183     int                 dbi_ecflags;    /*!< db_env_create flags */
 184     int                 dbi_cflags;     /*!< db_create flags */
 185     int                 dbi_oeflags;    /*!< common (db,dbenv}->open flags */
 186     int                 dbi_eflags;     /*!< dbenv->open flags */
 187     int                 dbi_oflags;     /*!< db->open flags */
 188     int                 dbi_tflags;     /*!< dbenv->txn_begin flags */
 189
 190     int                 dbi_type;       /*!< db index type */
 191     unsigned            dbi_mode;       /*!< mode to use on open */
 192     int                 dbi_perms;      /*!< file permission to use on open */
 193     long                dbi_shmkey;     /*!< shared memory base key */
 194     int                 dbi_api;        /*!< Berkeley API type */
 195
 196     int                 dbi_verify_on_close;
 197     int                 dbi_tear_down;  /*!< tear down dbenv on close */
 198     int                 dbi_use_cursors;/*!< access with cursors? (always) */
 199     int                 dbi_use_dbenv;  /*!< use db environment? */
 200     int                 dbi_get_rmw_cursor;
 201     int                 dbi_no_fsync;   /*!< no-op fsync for db */
 202     int                 dbi_no_dbsync;  /*!< don't call dbiSync */
 203     int                 dbi_lockdbfd;   /*!< do fcntl lock on db fd */
 204     int                 dbi_temporary;  /*!< non-persistent */
 205     int                 dbi_debug;
 206
 207 /*@null@*/ char *       dbi_host;
 208     long                dbi_cl_timeout;
 209     long                dbi_sv_timeout;
 210
 211         /* dbenv parameters */
 212     int                 dbi_lorder;
 213 /*@null@*/ void         (*db_errcall) (const char *db_errpfx, char *buffer);
 214 /*@shared@*/ FILE *     dbi_errfile;
 215     const char *        dbi_errpfx;
 216     int                 dbi_verbose;
 217     int                 dbi_region_init;
 218     int                 dbi_tas_spins;
 219         /* mpool sub-system parameters */
 220     int                 dbi_mp_mmapsize;        /*!< (10Mb) */
 221     int                 dbi_mp_size;    /*!< (128Kb) */
 222         /* lock sub-system parameters */
 223     unsigned int        dbi_lk_max;
 224     unsigned int        dbi_lk_detect;
 225     int                 dbi_lk_nmodes;
 226     unsigned char       *dbi_lk_conflicts;
 227         /* log sub-system parameters */
 228     unsigned int        dbi_lg_max;
 229     unsigned int        dbi_lg_bsize;
 230         /* transaction sub-system parameters */
 231     unsigned int        dbi_tx_max;
 232 #if 0
 233     int                 (*dbi_tx_recover) (DB_ENV *dbenv, DBT *log_rec, DB_LSN *lsnp, int redo, void *info);
 234 #endif
 235         /* dbinfo parameters */
 236     int                 dbi_cachesize;  /*!< */
 237     int                 dbi_pagesize;   /*!< (fs blksize) */
 238 /*@null@*/ void *       (*dbi_malloc) (size_t nbytes);
 239         /* hash access parameters */
 240     unsigned int        dbi_h_ffactor;  /*!< */
 241 /*@null@*/ unsigned int (*dbi_h_hash_fcn) (const void *bytes, unsigned int length);
 242     unsigned int        dbi_h_nelem;    /*!< */
 243     unsigned int        dbi_h_flags;    /*!< DB_DUP, DB_DUPSORT */
 244 /*@null@*/ int          (*dbi_h_dup_compare_fcn) (const DBT *, const DBT *);
 245         /* btree access parameters */
 246     int                 dbi_bt_flags;
 247     int                 dbi_bt_minkey;
 248 /*@null@*/ int          (*dbi_bt_compare_fcn) (const DBT *, const DBT *);
 249 /*@null@*/ int          (*dbi_bt_dup_compare_fcn) (const DBT *, const DBT *);
 250 /*@null@*/ size_t       (*dbi_bt_prefix_fcn) (const DBT *, const DBT *);
 251         /* recno access parameters */
 252     int                 dbi_re_flags;
 253     int                 dbi_re_delim;
 254     unsigned int        dbi_re_len;
 255     int                 dbi_re_pad;
 256     const char *        dbi_re_source;
 257         /* queue access parameters */
 258     unsigned int        dbi_q_extentsize;
 259
 260 /*@kept@*/ rpmdb        dbi_rpmdb;
 261     int         dbi_rpmtag;             /*!< rpm tag used for index */
 262     int         dbi_jlen;               /*!< size of join key */
 263
 264     unsigned int dbi_lastoffset;        /*!< db1 with falloc.c needs this */
 265
 266 /*@only@*//*@null@*/ void * dbi_db;     /*!< dbi handle */
 267 /*@only@*//*@null@*/ void * dbi_dbenv;  /*!< */
 268 /*@only@*//*@null@*/ void * dbi_dbinfo; /*!< */
 269 /*@only@*//*@null@*/ void * dbi_rmw;    /*!< db cursor (with DB_WRITECURSOR) */
 270 /*@only@*//*@null@*/ void * dbi_stats;  /*!< */
 271
 272 /*@observer@*/ const struct _dbiVec * dbi_vec;  /*!< private methods */
 273
 274 };
 275
 276 /** \ingroup rpmdb
 277  * Describes the collection of index databases used by rpm.
 278  */
 279 struct rpmdb_s {
 280 /*@owned@*/ const char *db_root;        /*!< path prefix */
 281 /*@owned@*/ const char *db_home;        /*!< directory path */
 282     int                 db_flags;
 283     int                 db_mode;        /*!< open mode */
 284     int                 db_perms;       /*!< open permissions */
 285     int                 db_api;         /*!< Berkeley API type */
 286     int                 db_remove_env;
 287     int                 db_filter_dups;
 288 /*@owned@*/ const char *db_errpfx;
 289     void                (*db_errcall) (const char *db_errpfx, char *buffer);
 290 /*@shared@*/ FILE *     db_errfile;
 291 /*@only@*/ void *       (*db_malloc) (size_t nbytes);
 292 /*@only@*/ void *       (*db_realloc) (/*@only@*//*@null@*/ void * ptr,
 293                                                 size_t nbytes);
 294     void                (*db_free) (/*@only@*/ void * ptr);
 295     int                 db_ndbi;
 296     dbiIndex            *_dbi;
 297 };
 298
 299 /* for RPM's internal use only */
 300
 301 /** \ingroup rpmdb
 302  */
 303 enum rpmdbFlags {
 304         RPMDB_FLAG_JUSTCHECK    = (1 << 0),
 305         RPMDB_FLAG_MINIMAL      = (1 << 1),
 306         RPMDB_FLAG_CHROOT       = (1 << 2)
 307 };
 308
 309 #ifdef __cplusplus
 310 extern "C" {
 311 #endif
 312
 313 /*@-exportlocal@*/
 314 /** \ingroup db3
 315  * Return new configured index database handle instance.
 316  * @param rpmdb         rpm database
 317  */
 318 /*@only@*/ /*@null@*/ dbiIndex db3New(/*@keep@*/ rpmdb rpmdb, int rpmtag);
 319
 320 /** \ingroup db3
 321  * Destroy index database handle instance.
 322  * @param dbi           index database handle
 323  * @return              NULL always
 324  */
 325 /*@null@*/ dbiIndex db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi);
 326
 327 /** \ingroup db3
 328  * Format db3 open flags for debugging print.
 329  * @param dbflags               db open flags
 330  * @param print_dbenv_flags     format db env flags instead?
 331  * @return                      formatted flags (static buffer)
 332  */
 333 /*@exposed@*/ extern const char *const prDbiOpenFlags(int dbflags,
 334                                                 int print_dbenv_flags);
 335
 336 /** \ingroup dbi
 337  * Return handle for an index database.
 338  * @param rpmdb         rpm database
 339  * @param rpmtag        rpm tag
 340  * @param flags         (unused)
 341  * @return              index database handle
 342  */
 343 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(/*@null@*/ rpmdb rpmdb, int rpmtag,
 344                 unsigned int flags);
 345
 346 /** \ingroup dbi
 347  * @param dbi           index database handle
 348  * @param dbiflags      DBI_WRITECURSOR or DBI_ITERATOR
 349  */
 350 int dbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int dbiflags);
 351 int XdbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int dbiflags, const char *f, unsigned int l);
 352 #define dbiCopen(_a,_b,_c) \
 353         XdbiCopen(_a, _b, _c, __FILE__, __LINE__)
 354
 355 #define DBI_WRITECURSOR         (1 << 0)
 356 #define DBI_ITERATOR            (1 << 1)
 357
 358 /** \ingroup dbi
 359  * @param dbi           index database handle
 360  * @param flags         (unused)
 361  */
 362 int dbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags);
 363 int XdbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags, const char *f, unsigned int l);
 364 #define dbiCclose(_a,_b,_c) \
 365         XdbiCclose(_a, _b, _c, __FILE__, __LINE__)
 366
 367 /** \ingroup dbi
 368  * Delete (key,data) pair(s) from index database.
 369  * @param dbi           index database handle
 370  * @param keyp          key data
 371  * @param keylen        key data length
 372  * @param flags         (unused)
 373  * @return              0 on success
 374  */
 375 int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 376         unsigned int flags);
 377
 378 /** \ingroup dbi
 379  * Retrieve (key,data) pair from index database.
 380  * @param dbi           index database handle
 381  * @param keypp         address of key data
 382  * @param keylenp       address of key data length
 383  * @param datapp        address of data pointer
 384  * @param datalenp      address of data length
 385  * @param flags         (unused)
 386  * @return              0 on success
 387  */
 388 int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp,
 389         /*@null@*/ size_t * keylenp,
 390         /*@null@*/ void ** datapp,
 391         /*@null@*/ size_t * datalenp,
 392         unsigned int flags);
 393
 394 /** \ingroup dbi
 395  * Store (key,data) pair in index database.
 396  * @param dbi           index database handle
 397  * @param keyp          key data
 398  * @param keylen        key data length
 399  * @param datap         data pointer
 400  * @param datalen       data length
 401  * @param flags         (unused)
 402  * @return              0 on success
 403  */
 404 int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 405         const void * datap, size_t datalen, unsigned int flags);
 406
 407 /** \ingroup dbi
 408  * Retrieve count of (possible) duplicate items.
 409  * @param dbi           index database handle
 410  * @param dbcursor      database cursor
 411  * @param countp        address of count
 412  * @param flags         (unused)
 413  * @return              0 on success
 414  */
 415 int dbiCount(dbiIndex dbi, DBC * dbcursor, /*@out@*/ unsigned int * countp,
 416         unsigned int flags);
 417
 418 /** \ingroup dbi
 419  * Verify (and close) index database.
 420  * @param dbi           index database handle
 421  * @param flags         (unused)
 422  * @return              0 on success
 423  */
 424 int dbiVerify(/*@only@*/ dbiIndex dbi, unsigned int flags);
 425
 426 /** \ingroup dbi
 427  * Close index database.
 428  * @param dbi           index database handle
 429  * @param flags         (unused)
 430  * @return              0 on success
 431  */
 432 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags);
 433
 434 /** \ingroup dbi
 435  * Flush pending operations to disk.
 436  * @param dbi           index database handle
 437  * @param flags         (unused)
 438  * @return              0 on success
 439  */
 440 int dbiSync (dbiIndex dbi, unsigned int flags);
 441
 442 /** \ingroup dbi
 443  * Is database byte swapped?
 444  * @param dbi           index database handle
 445  * @return              0 no
 446  */
 447 int dbiByteSwapped(dbiIndex dbi);
 448
 449 /** \ingroup db1
 450  * Return base file name for db1 database (legacy).
 451  * @param rpmtag        rpm tag
 452  * @return              base file name of db1 database
 453  */
 454 char * db1basename(int rpmtag);
 455 /*@=exportlocal@*/
 456
 457 /** \ingroup rpmdb
 458  */
 459 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi);
 460
 461 /** \ingroup rpmdb
 462  * @param rpmdb         rpm database
 463  */
 464 int rpmdbFindFpList(/*@null@*/ rpmdb rpmdb, fingerPrint * fpList,
 465                 /*@out@*/dbiIndexSet * matchList, int numItems);
 466
 467 /** \ingroup dbi
 468  * Destroy set of index database items.
 469  * @param set   set of index database items
 470  */
 471 void dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set);
 472
 473 /** \ingroup dbi
 474  * Count items in index database set.
 475  * @param set   set of index database items
 476  * @return      number of items
 477  */
 478 unsigned int dbiIndexSetCount(dbiIndexSet set);
 479
 480 /** \ingroup dbi
 481  * Return record offset of header from element in index database set.
 482  * @param set   set of index database items
 483  * @param recno index of item in set
 484  * @return      record offset of header
 485  */
 486 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno);
 487
 488 /** \ingroup dbi
 489  * Return file index from element in index database set.
 490  * @param set   set of index database items
 491  * @param recno index of item in set
 492  * @return      file index
 493  */
 494 unsigned int dbiIndexRecordFileNumber(dbiIndexSet set, int recno);
 495
 496 #ifdef __cplusplus
 497 }
 498 #endif
 499
 500 #endif  /* H_RPMDB */