# Database API.

## Files
file | rpmdb.h
| Access RPM indices using Berkeley DB interface(s).

file | rpmlib.h
| In Memoriam: Steve Taylor <staylor@redhat.com> was here, now he's not.

## Functions
rpmop | rpmdbOp (rpmdb db, rpmdbOpX opx)
| Retrieve operation timestamp from rpm database.
int | rpmdbSetChrootDone (rpmdb db, int chrootDone)
| Set chrootDone flag, i.e.
rpmdb | rpmdbUnlink (rpmdb db, const char *msg)
| Unreference a database instance.
rpmdb | rpmdbLink (rpmdb db, const char *msg)
| Reference a database instance.
int | rpmdbOpen (const char *prefix, rpmdb *dbp, int mode, int perms)
| Open rpm database.
int | rpmdbInit (const char *prefix, int perms)
| Initialize database.
int | rpmdbVerify (const char *prefix)
| Verify database components.
int | rpmdbClose (rpmdb db)
| Close all database indices and free rpmdb.
int | rpmdbSync (rpmdb db)
| Sync all database indices.
int | rpmdbOpenAll (rpmdb db)
| Open all database indices.
int | rpmdbCountPackages (rpmdb db, const char *name)
| Return number of instances of package in rpm database.
unsigned int | rpmdbGetIteratorOffset (rpmdbMatchIterator mi)
| Return header join key for current position of rpm database iterator.
int | rpmdbGetIteratorCount (rpmdbMatchIterator mi)
| Return number of elements in rpm database iterator.
unsigned int | rpmdbGetIteratorFileNum (rpmdbMatchIterator mi)
int | rpmdbAppendIterator (rpmdbMatchIterator mi, const int *hdrNums, int nHdrNums)
| Append items to set of package instances to iterate.
int | rpmdbPruneIterator (rpmdbMatchIterator mi, int *hdrNums, int nHdrNums, int sorted)
| Remove items from set of package instances to iterate.
int | rpmdbSetIteratorRE (rpmdbMatchIterator mi, rpmTag tag, rpmMireMode mode, const char *pattern)
| Add pattern to iterator selector.
int | rpmdbSetIteratorRewrite (rpmdbMatchIterator mi, int rewrite)
| Prepare iterator for lazy writes.
int | rpmdbSetIteratorModified (rpmdbMatchIterator mi, int modified)
| Modify iterator to mark header for lazy write on release.
int | rpmdbSetHdrChk (rpmdbMatchIterator mi, rpmts ts, rpmRC(*hdrchk)(rpmts ts, const void *uh, size_t uc, char **msg))
| Modify iterator to verify retrieved header blobs.
rpmdbMatchIterator | rpmdbInitIterator (rpmdb db, rpmTag rpmtag, const void *keyp, size_t keylen)
| Return database iterator.
Header | rpmdbNextIterator (rpmdbMatchIterator mi)
| Return next package header from iteration.
int | rpmdbCheckSignals (void)
| Check for and exit on termination signals.
int | rpmdbCheckTerminate (int terminate)
| Check rpmdb signal handler for trapped signal and/or requested exit, clean up any open iterators and databases on termination condition.
rpmdbMatchIterator | rpmdbFreeIterator (rpmdbMatchIterator mi)
| Destroy rpm database iterator.
int | rpmdbAdd (rpmdb db, int iid, Header h, rpmts ts, rpmRC(*hdrchk)(rpmts ts, const void *uh, size_t uc, char **msg))
| Add package header to rpm database and indices.
int | rpmdbRemove (rpmdb db, int rid, unsigned int hdrNum, rpmts ts, rpmRC(*hdrchk)(rpmts ts, const void *uh, size_t uc, char **msg))
| Remove package header from rpm database and indices.
int | rpmdbRebuild (const char *prefix, rpmts ts, rpmRC(*hdrchk)(rpmts ts, const void *uh, size_t uc, char **msg))
| Rebuild database indices from package headers.

## Function Documentation

int rpmdbAdd | ( | rpmdb | db,
|  | int | iid,
|  | Header | h,
|  | rpmts | ts,
|  | rpmRC(*)(rpmts ts, const void *uh, size_t uc, char **msg) | hdrchk |
| ) |  |  |

Add package header to rpm database and indices.

Parameters:

  | db | rpm database
  | iid | install transaction id (iid = 0 or -1 to skip)
  | h | header
  | ts | (unused) transaction set (or NULL)
  | (*hdrchk) | (unused) headerCheck() vector (or NULL)

Returns:
  0 on success

int rpmdbAppendIterator | ( | rpmdbMatchIterator | mi,
|  | const int * | hdrNums,
|  | int | nHdrNums |
| ) |  |  |

Append items to set of package instances to iterate.

Parameters:

  | mi | rpm database iterator
  | hdrNums | array of package instances
  | nHdrNums | number of elements in array

Returns:
  0 on success, 1 on failure (bad args)

int rpmdbCheckSignals | ( | void |  | ) |

Check for and exit on termination signals.

int rpmdbCheckTerminate | ( | int | terminate | ) |

Check rpmdb signal handler for trapped signal and/or requested exit, clean up any open iterators and databases on termination condition.

On non-zero exit any open references to rpmdb are invalid and cannot be accessed anymore, calling process should terminate immediately.

Parameters:

  | terminate | 0 to only check for signals, 1 to terminate anyway

Returns:
  0 to continue, 1 if termination cleanup was done.

int rpmdbClose | ( | rpmdb | db | ) |

Close all database indices and free rpmdb.

Parameters:

  | db | rpm database

Returns:
  0 on success

int rpmdbCountPackages | ( | rpmdb | db,
|  | const char * | name |
| ) |  |  |

Return number of instances of package in rpm database.

Parameters:

  | db | rpm database
  | name | rpm package name

Returns:
  number of instances

rpmdbMatchIterator rpmdbFreeIterator | ( | rpmdbMatchIterator | mi | ) |

Destroy rpm database iterator.

Parameters:

  | mi | rpm database iterator

Returns:
  NULL always

int rpmdbGetIteratorCount | ( | rpmdbMatchIterator | mi | ) |

Return number of elements in rpm database iterator.

Parameters:

  | mi | rpm database iterator

Returns:
  number of elements

unsigned int rpmdbGetIteratorFileNum | ( | rpmdbMatchIterator | mi | ) |

unsigned int rpmdbGetIteratorOffset | ( | rpmdbMatchIterator | mi | ) |

Return header join key for current position of rpm database iterator.

Parameters:

  | mi | rpm database iterator

Returns:
  current header join key

int rpmdbInit | ( | const char * | prefix,
|  | int | perms |
| ) |  |  |

Initialize database.

Parameters:

  | prefix | path to top of install tree
  | perms | database permissions

Returns:
  0 on success

rpmdbMatchIterator rpmdbInitIterator | ( | rpmdb | db,
|  | rpmTag | rpmtag,
|  | const void * | keyp,
|  | size_t | keylen |
| ) |  |  |

Return database iterator.

Parameters:

  | db | rpm database
  | rpmtag | rpm tag
  | keyp | key data (NULL for sequential access)
  | keylen | key data length (0 will use strlen(keyp))

Returns:
  NULL on failure

rpmdb rpmdbLink | ( | rpmdb | db,
|  | const char * | msg |
| ) |  |  |

Reference a database instance.

Parameters:

  | db | rpm database
  | msg |

Returns:
  new rpm database reference

Header rpmdbNextIterator | ( | rpmdbMatchIterator | mi | ) |

Return next package header from iteration.

Parameters:

  | mi | rpm database iterator

Returns:
  NULL on end of iteration.

rpmop rpmdbOp | ( | rpmdb | db,
|  | rpmdbOpX | opx |
| ) |  |  |

Retrieve operation timestamp from rpm database.

Parameters:

  | db | rpm database
  | opx | operation timestamp index

Returns:
  pointer to operation timestamp.

int rpmdbOpen | ( | const char * | prefix,
|  | rpmdb * | dbp,
|  | int | mode,
|  | int | perms |
| ) |  |  |

Open rpm database.

Parameters:

  | prefix | path to top of install tree

Return values:

  | dbp | address of rpm database

Parameters:

  | mode | open(2) flags: O_RDWR or O_RDONLY (O_CREAT also)
  | perms | database permissions

Returns:
  0 on success

int rpmdbOpenAll | ( | rpmdb | db | ) |

Open all database indices.

Parameters:

  | db | rpm database

Returns:
  0 on success

int rpmdbPruneIterator | ( | rpmdbMatchIterator | mi,
|  | int * | hdrNums,
|  | int | nHdrNums,
|  | int | sorted |
| ) |  |  |

Remove items from set of package instances to iterate.

Note:
  Sorted hdrNums are always passed in rpmlib.

Parameters:

  | mi | rpm database iterator
  | hdrNums | array of package instances
  | nHdrNums | number of elements in array
  | sorted | is the array sorted? (array will be sorted on return)

Returns:
  0 on success, 1 on failure (bad args)

int rpmdbRebuild | ( | const char * | prefix,
|  | rpmts | ts,
|  | rpmRC(*)(rpmts ts, const void *uh, size_t uc, char **msg) | hdrchk |
| ) |  |  |

Rebuild database indices from package headers.

Parameters:

  | prefix | path to top of install tree
  | ts | transaction set (or NULL)
  | (*hdrchk) | headerCheck() vector (or NULL)

Returns:
  0 on success

int rpmdbRemove | ( | rpmdb | db,
|  | int | rid,
|  | unsigned int | hdrNum,
|  | rpmts | ts,
|  | rpmRC(*)(rpmts ts, const void *uh, size_t uc, char **msg) | hdrchk |
| ) |  |  |

Remove package header from rpm database and indices.

Parameters:

  | db | rpm database
  | rid | (unused) remove transaction id (rid = 0 or -1 to skip)
  | hdrNum | package instance number in database
  | ts | (unused) transaction set (or NULL)
  | (*hdrchk) | (unused) headerCheck() vector (or NULL)

Returns:
  0 on success

int rpmdbSetChrootDone | ( | rpmdb | db,
|  | int | chrootDone |
| ) |  |  |

Set chrootDone flag, i.e.

has chroot(2) been performed?

Parameters:

  | db | rpm database
  | chrootDone | new chrootDone flag

Returns:
  previous chrootDone flag

int rpmdbSetHdrChk | ( | rpmdbMatchIterator | mi,
|  | rpmts | ts,
|  | rpmRC(*)(rpmts ts, const void *uh, size_t uc, char **msg) | hdrchk |
| ) |  |  |

Modify iterator to verify retrieved header blobs.

Parameters:

  | mi | rpm database iterator
  | ts | transaction set
  | (*hdrchk) | headerCheck() vector

Returns:
  0 always

int rpmdbSetIteratorModified | ( | rpmdbMatchIterator | mi,
|  | int | modified |
| ) |  |  |

Modify iterator to mark header for lazy write on release.

Parameters:

  | mi | rpm database iterator
  | modified | new value of modified

Returns:
  previous value

int rpmdbSetIteratorRE | ( | rpmdbMatchIterator | mi,
|  | rpmTag | tag,
|  | rpmMireMode | mode,
|  | const char * | pattern |
| ) |  |  |

Add pattern to iterator selector.

Parameters:

  | mi | rpm database iterator
  | tag | rpm tag
  | mode | type of pattern match
  | pattern | pattern to match

Returns:
  0 on success

int rpmdbSetIteratorRewrite | ( | rpmdbMatchIterator | mi,
|  | int | rewrite |
| ) |  |  |

Prepare iterator for lazy writes.

Note:
  Must be called before rpmdbNextIterator() with CDB model database.

Parameters:

  | mi | rpm database iterator
  | rewrite | new value of rewrite

Returns:
  previous value

int rpmdbSync | ( | rpmdb | db | ) |

Sync all database indices.

Parameters:

  | db | rpm database

Returns:
  0 on success

rpmdb rpmdbUnlink | ( | rpmdb | db,
|  | const char * | msg |
| ) |  |  |

Unreference a database instance.

Parameters:

  | db | rpm database
  | msg |

Returns:
  NULL always

int rpmdbVerify | ( | const char * | prefix | ) |

Verify database components.

Parameters:

  | prefix | path to top of install tree

Returns:
  0 on success