4 /** \ingroup rpmdb dbi db1 db3
6 * Access RPM indices using Berkeley DB interface(s).
15 typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem;
19 typedef /*@abstract@*/ struct _dbiIndex * dbiIndex;
21 /* this will break if sizeof(int) != 4 */
23 * A single item from an index database (i.e. the "data returned").
24 * Note: In rpm-3.0.4 and earlier, this structure was passed by value,
25 * and was identical to the "data saved" structure below.
27 struct _dbiIndexItem {
28 unsigned int hdrNum; /*!< header instance in db */
29 unsigned int tagNum; /*!< tag index in header */
30 unsigned int fpNum; /*!< finger print index */
31 unsigned int dbNum; /*!< database index */
35 * Items retrieved from the index database.
38 /*@owned@*/ struct _dbiIndexItem * recs; /*!< array of records */
39 int count; /*!< number of records */
42 /* XXX hack to get prototypes correct */
43 #if !defined(DB_VERSION_MAJOR)
52 * Private methods for accessing an index database.
55 int dbv_major; /*!< Berkeley db version major */
56 int dbv_minor; /*!< Berkeley db version minor */
57 int dbv_patch; /*!< Berkeley db version patch */
60 * Return handle for an index database.
61 * @param rpmdb rpm database
62 * @param rpmtag rpm tag
63 * @return 0 on success
65 int (*open) (rpmdb rpmdb, int rpmtag, /*@out@*/ dbiIndex * dbip)
66 /*@globals fileSystem@*/
67 /*@modifies *dbip, fileSystem @*/;
70 * Close index database, and destroy database handle.
71 * @param dbi index database handle
72 * @param flags (unused)
73 * @return 0 on success
75 int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags)
76 /*@globals fileSystem@*/
77 /*@modifies dbi, fileSystem @*/;
80 * Flush pending operations to disk.
81 * @param dbi index database handle
82 * @param flags (unused)
83 * @return 0 on success
85 int (*sync) (dbiIndex dbi, unsigned int flags)
86 /*@globals fileSystem@*/
87 /*@modifies fileSystem @*/;
90 * Open database cursor.
91 * @param dbi index database handle
92 * @param dbcp address of database cursor
93 * @param flags (unused)
95 int (*copen) (dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags)
96 /*@globals fileSystem@*/
97 /*@modifies dbi, *dbcp, fileSystem @*/;
100 * Close database cursor.
101 * @param dbi index database handle
102 * @param dbcursor database cursor
103 * @param flags (unused)
105 int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
106 /*@globals fileSystem@*/
107 /*@modifies dbi, *dbcursor, fileSystem @*/;
110 * Delete (key,data) pair(s) using db->del or dbcursor->c_del.
111 * @param dbi index database handle
112 * @param dbcursor database cursor
113 * @param keyp key data
114 * @param keylen key data length
115 * @param flags (unused)
116 * @return 0 on success
118 int (*cdel) (dbiIndex dbi, DBC * dbcursor,
119 const void * keyp, size_t keylen, unsigned int flags)
120 /*@globals fileSystem@*/
121 /*@modifies *dbcursor, fileSystem @*/;
124 * Retrieve (key,data) pair using db->get or dbcursor->c_get.
125 * @param dbi index database handle
126 * @param dbcursor database cursor
127 * @param keypp address of key data
128 * @param keylenp address of key data length
129 * @param datapp address of data pointer
130 * @param datalenp address of data length
131 * @param flags (unused)
132 * @return 0 on success
134 int (*cget) (dbiIndex dbi, DBC * dbcursor,
135 /*@null@*/ void ** keypp, /*@null@*/ size_t * keylenp,
136 /*@null@*/ void ** datapp, /*@null@*/ size_t * datalenp,
138 /*@globals fileSystem@*/
139 /*@modifies *dbcursor, *keypp, *keylenp, *datapp, *datalenp,
143 * Store (key,data) pair using db->put or dbcursor->c_put.
144 * @param dbi index database handle
145 * @param dbcursor database cursor
146 * @param keyp key data
147 * @param keylen key data length
148 * @param datap data pointer
149 * @param datalen data length
150 * @param flags (unused)
151 * @return 0 on success
153 int (*cput) (dbiIndex dbi, DBC * dbcursor,
154 const void * keyp, size_t keylen,
155 const void * datap, size_t datalen,
157 /*@globals fileSystem@*/
158 /*@modifies *dbcursor, fileSystem @*/;
161 * Retrieve count of (possible) duplicate items using dbcursor->c_count.
162 * @param dbi index database handle
163 * @param dbcursor database cursor
164 * @param countp address of count
165 * @param flags (unused)
166 * @return 0 on success
168 int (*ccount) (dbiIndex dbi, DBC * dbcursor,
169 /*@out@*/ unsigned int * countp,
171 /*@globals fileSystem@*/
172 /*@modifies *dbcursor, fileSystem @*/;
175 * Is database byte swapped?
176 * @param dbi index database handle
179 int (*byteswapped) (dbiIndex dbi)
180 /*@globals fileSystem@*/
181 /*@modifies fileSystem@*/;
184 * Save statistics in database handle.
185 * @param dbi index database handle
186 * @param flags retrieve statistics that don't require traversal?
187 * @return 0 on success
189 int (*stat) (dbiIndex dbi, unsigned int flags)
190 /*@globals fileSystem@*/
191 /*@modifies dbi, fileSystem @*/;
196 * Describes an index database (implemented on Berkeley db3 functionality).
199 /*@null@*/ const char * dbi_root; /*!< chroot(2) component of path */
200 /*@null@*/ const char * dbi_home; /*!< directory component of path */
201 /*@null@*/ const char * dbi_file; /*!< file component of path */
202 /*@null@*/ const char * dbi_subfile;
203 /*@null@*/ const char * dbi_tmpdir; /*!< temporary directory */
205 int dbi_ecflags; /*!< db_env_create flags */
206 int dbi_cflags; /*!< db_create flags */
207 int dbi_oeflags; /*!< common (db,dbenv}->open flags */
208 int dbi_eflags; /*!< dbenv->open flags */
209 int dbi_oflags; /*!< db->open flags */
210 int dbi_tflags; /*!< dbenv->txn_begin flags */
212 int dbi_type; /*!< db index type */
213 unsigned dbi_mode; /*!< mode to use on open */
214 int dbi_perms; /*!< file permission to use on open */
215 long dbi_shmkey; /*!< shared memory base key */
216 int dbi_api; /*!< Berkeley API type */
218 int dbi_verify_on_close;
219 int dbi_tear_down; /*!< tear down dbenv on close */
220 int dbi_use_cursors;/*!< access with cursors? (always) */
221 int dbi_use_dbenv; /*!< use db environment? */
222 int dbi_permit_dups;/*!< permit duplicate entries? */
223 int dbi_get_rmw_cursor;
224 int dbi_no_fsync; /*!< no-op fsync for db */
225 int dbi_no_dbsync; /*!< don't call dbiSync */
226 int dbi_lockdbfd; /*!< do fcntl lock on db fd */
227 int dbi_temporary; /*!< non-persistent */
231 /*@null@*/ char * dbi_host;
235 /* dbenv parameters */
237 /*@unused@*/ /*@null@*/ void (*db_errcall) (const char *db_errpfx, char *buffer)
238 /*@globals fileSystem@*/
239 /*@modifies fileSystem @*/;
240 /*@unused@*/ /*@shared@*/ FILE * dbi_errfile;
241 const char * dbi_errpfx;
245 /* mpool sub-system parameters */
246 int dbi_mp_mmapsize; /*!< (10Mb) */
247 int dbi_mp_size; /*!< (128Kb) */
248 /* lock sub-system parameters */
249 unsigned int dbi_lk_max;
250 unsigned int dbi_lk_detect;
251 /*@unused@*/ int dbi_lk_nmodes;
252 /*@unused@*/ unsigned char * dbi_lk_conflicts;
253 /* log sub-system parameters */
254 unsigned int dbi_lg_max;
255 unsigned int dbi_lg_bsize;
256 /* transaction sub-system parameters */
257 unsigned int dbi_tx_max;
259 int (*dbi_tx_recover) (DB_ENV *dbenv, DBT *log_rec,
260 DB_LSN *lsnp, int redo, void *info)
261 /*@globals fileSystem@*/
262 /*@modifies fileSystem @*/;
264 /* dbinfo parameters */
265 int dbi_cachesize; /*!< */
266 int dbi_pagesize; /*!< (fs blksize) */
267 /*@unused@*/ /*@null@*/ void * (*dbi_malloc) (size_t nbytes)
269 /* hash access parameters */
270 unsigned int dbi_h_ffactor; /*!< */
271 /*@null@*/ unsigned int (*dbi_h_hash_fcn) (DB *, const void *bytes, unsigned int length) /*@*/;
272 unsigned int dbi_h_nelem; /*!< */
273 unsigned int dbi_h_flags; /*!< DB_DUP, DB_DUPSORT */
274 /*@null@*/ int (*dbi_h_dup_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
275 /* btree access parameters */
278 /*@null@*/ int (*dbi_bt_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
279 /*@null@*/ int (*dbi_bt_dup_compare_fcn) (DB *, const DBT *, const DBT *) /*@*/;
280 /*@null@*/ size_t (*dbi_bt_prefix_fcn) (DB *, const DBT *, const DBT *) /*@*/;
281 /* recno access parameters */
284 unsigned int dbi_re_len;
286 const char * dbi_re_source;
287 /* queue access parameters */
288 unsigned int dbi_q_extentsize;
290 /*@refcounted@*/ rpmdb dbi_rpmdb;
291 rpmTag dbi_rpmtag; /*!< rpm tag used for index */
292 int dbi_jlen; /*!< size of join key */
294 unsigned int dbi_lastoffset; /*!< db1 with falloc.c needs this */
296 /*@only@*//*@null@*/ void * dbi_db; /*!< Berkeley DB handle */
297 /*@only@*//*@null@*/ void * dbi_dbenv; /*!< Berkeley DB_ENV handle */
298 /*@only@*//*@null@*/ void * dbi_dbinfo; /*!< (unused) */
299 /*@only@*//*@null@*/ void * dbi_rmw; /*!< db cursor (with DB_WRITECURSOR) */
300 /*@only@*//*@null@*/ void * dbi_stats; /*!< Berkeley db statistics */
302 /*@observer@*/ const struct _dbiVec * dbi_vec; /*!< private methods */
307 * Describes the collection of index databases used by rpm.
310 /*@owned@*/ const char * db_root;/*!< path prefix */
311 /*@owned@*/ const char * db_home;/*!< directory path */
313 int db_mode; /*!< open mode */
314 int db_perms; /*!< open permissions */
315 int db_api; /*!< Berkeley API type */
316 /*@owned@*/ const char * db_errpfx;
319 int db_chrootDone; /*!< If chroot(2) done, ignore db_root. */
320 void (*db_errcall) (const char *db_errpfx, char *buffer)
322 /*@shared@*/ FILE * db_errfile;
323 /*@only@*/ void * (*db_malloc) (size_t nbytes)
325 /*@only@*/ void * (*db_realloc) (/*@only@*//*@null@*/ void * ptr,
328 void (*db_free) (/*@only@*/ void * ptr)
329 /*@modifies *ptr @*/;
330 int db_ndbi; /*!< No. of tag indices. */
331 dbiIndex * _dbi; /*!< Tag indices. */
333 /*@refs@*/ int nrefs; /*!< Reference count. */
336 /* for RPM's internal use only */
341 RPMDB_FLAG_JUSTCHECK = (1 << 0),
342 RPMDB_FLAG_MINIMAL = (1 << 1),
344 RPMDB_FLAG_CHROOT = (1 << 2)
354 * Return new configured index database handle instance.
355 * @param rpmdb rpm database
357 /*@only@*/ /*@null@*/ dbiIndex db3New(rpmdb rpmdb, int rpmtag)
358 /*@globals rpmGlobalMacroContext @*/
359 /*@modifies rpmGlobalMacroContext @*/;
362 * Destroy index database handle instance.
363 * @param dbi index database handle
364 * @return NULL always
366 /*@null@*/ dbiIndex db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi)
370 * Format db3 open flags for debugging print.
371 * @param dbflags db open flags
372 * @param print_dbenv_flags format db env flags instead?
373 * @return formatted flags (static buffer)
376 /*@exposed@*/ extern const char *const prDbiOpenFlags(int dbflags,
377 int print_dbenv_flags)
382 * Return handle for an index database.
383 * @param db rpm database
384 * @param rpmtag rpm tag
385 * @param flags (unused)
386 * @return index database handle
388 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(/*@null@*/ rpmdb db, int rpmtag,
393 * @param dbi index database handle
394 * @param flags DBI_WRITECURSOR, DBI_ITERATOR or 0
396 int dbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags)
397 /*@globals fileSystem@*/
398 /*@modifies dbi, *dbcp, fileSystem @*/;
400 #define DBI_WRITECURSOR (1 << 0)
401 #define DBI_ITERATOR (1 << 1)
404 * @param dbi index database handle
405 * @param flags (unused)
407 int dbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags)
408 /*@globals fileSystem@*/
409 /*@modifies dbi, *dbcursor, fileSystem @*/;
412 * Delete (key,data) pair(s) from index database.
413 * @param dbi index database handle
414 * @param keyp key data
415 * @param keylen key data length
416 * @param flags (unused)
417 * @return 0 on success
419 int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
421 /*@globals fileSystem@*/
422 /*@modifies *dbcursor, fileSystem @*/;
425 * Retrieve (key,data) pair from index database.
426 * @param dbi index database handle
427 * @param keypp address of key data
428 * @param keylenp address of key data length
429 * @param datapp address of data pointer
430 * @param datalenp address of data length
431 * @param flags (unused)
432 * @return 0 on success
434 int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp,
435 /*@null@*/ size_t * keylenp,
436 /*@null@*/ void ** datapp,
437 /*@null@*/ size_t * datalenp,
439 /*@globals fileSystem@*/
440 /*@modifies *dbcursor, **keypp, *keylenp, **datapp, *datalenp,
444 * Store (key,data) pair in index database.
445 * @param dbi index database handle
446 * @param keyp key data
447 * @param keylen key data length
448 * @param datap data pointer
449 * @param datalen data length
450 * @param flags (unused)
451 * @return 0 on success
453 int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
454 const void * datap, size_t datalen, unsigned int flags)
455 /*@globals fileSystem@*/
456 /*@modifies *dbcursor, fileSystem @*/;
459 * Retrieve count of (possible) duplicate items.
460 * @param dbi index database handle
461 * @param dbcursor database cursor
462 * @param countp address of count
463 * @param flags (unused)
464 * @return 0 on success
467 int dbiCount(dbiIndex dbi, DBC * dbcursor, /*@out@*/ unsigned int * countp,
469 /*@globals fileSystem@*/
470 /*@modifies *dbcursor, fileSystem @*/;
473 * Verify (and close) index database.
474 * @param dbi index database handle
475 * @param flags (unused)
476 * @return 0 on success
478 int dbiVerify(/*@only@*/ dbiIndex dbi, unsigned int flags)
479 /*@globals fileSystem@*/
480 /*@modifies dbi, fileSystem @*/;
483 * Close index database.
484 * @param dbi index database handle
485 * @param flags (unused)
486 * @return 0 on success
488 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags)
489 /*@globals fileSystem@*/
490 /*@modifies dbi, fileSystem @*/;
493 * Flush pending operations to disk.
494 * @param dbi index database handle
495 * @param flags (unused)
496 * @return 0 on success
498 int dbiSync (dbiIndex dbi, unsigned int flags)
499 /*@globals fileSystem@*/
500 /*@modifies fileSystem @*/;
503 * Is database byte swapped?
504 * @param dbi index database handle
507 int dbiByteSwapped(dbiIndex dbi)
511 * Return base file name for db1 database (legacy).
512 * @param rpmtag rpm tag
513 * @return base file name of db1 database
515 char * db1basename(int rpmtag)
522 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi)
526 * @param db rpm database
528 int rpmdbFindFpList(/*@null@*/ rpmdb db, fingerPrint * fpList,
529 /*@out@*/ dbiIndexSet * matchList, int numItems)
530 /*@globals fileSystem@*/
531 /*@modifies db, *matchList, fileSystem @*/;
534 * Destroy set of index database items.
535 * @param set set of index database items
536 * @return NULL always
538 /*@null@*/ dbiIndexSet dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set)
542 * Count items in index database set.
543 * @param set set of index database items
544 * @return number of items
546 unsigned int dbiIndexSetCount(dbiIndexSet set)
550 * Return record offset of header from element in index database set.
551 * @param set set of index database items
552 * @param recno index of item in set
553 * @return record offset of header
555 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno)
559 * Return file index from element in index database set.
560 * @param set set of index database items
561 * @param recno index of item in set
564 unsigned int dbiIndexRecordFileNumber(dbiIndexSet set, int recno)