The building argument should be set to 1 only if a package is being built when this function is called. Since most rpmlib-based applications will probably not duplicate RPM's package-building capabilities, building should normally be set to 0.

21.2.4.2. rpmGetOsName()—Return Operating System Name

This function returns the name of the operating system, as determined by rpmlib's normal rpmrc file processing:

#include  <rpm/rpmlib.h>



char  *rpmGetOsName(void);

21.2.4.3. rpmGetArchName()—Return Architecture Name

This function returns the name of the architecture, as determined by rpmlib's normal rpmrc file processing:

#include  <rpm/rpmlib.h>



char  *rpmGetArchName(void);

21.2.4.4. rpmShowRC()—Print All rpmrc-Derived Variables

This function writes all variable names and their values to the file f. It always returns 0:

#include    <rpm/rpmlib.h>



int   rpmShowRC(FILE *f);

21.2.4.5. rpmArchScore()—Return Architecture Compatibility Score

This function returns the level of compatibility between the architecture whose name is specified in arch and the current architecture. Returns 0 if the two architectures are incompatible. The smaller the number returned, the more compatible the two architectures are:

#include   <rpm/rpmlib.h>



int   rpmArchScore(char * arch);

21.2.4.6. rpmOsScore()—Return Operating System Compatibility Score

This function returns the level of compatibility between the operating system whose name is specified in os and the current operating system. Returns 0 if the two operating systems are incompatible. The smaller the number returned, the more compatible the two operating systems are:

#include   <rpm/rpmlib.h>



int   rpmOsScore(char * os);

21.2.5. RPM Database Manipulation

The functions in this section perform the basic operations on the RPM database. This includes opening and closing the database, as well as creating the database. A function also exists to rebuild a database that has been corrupted.

Every function that accesses the RPM database in some fashion makes use of the rpmdb structure. This structure is used as a handle to refer to a particular RPM database.

21.2.5.1. rpmdbOpen()—Open RPM Database

This function opens the RPM database located in RPMVAR_DBPATH, returning the rpmdb structure dbp. If root is specified, it is prepended to RPMVAR_DBPATH prior to opening. The mode and perms parameters are identical to open(2)'s flags and mode parameters, respectively:

#include   <rpm/rpmlib.h>



int   rpmdbOpen(char * root,

               rpmdb * dbp,

                int mode,

                 int perms);

The function returns 1 on error, and 0 on success.

21.2.5.2. rpmdbClose()—Close RPM Database

This function closes the RPM database specified by the rpmdb structure db. The db structure is also freed:

#include   <rpm/rpmlib.h>



void   rpmdbClose(rpmdb db);

21.2.5.3. rpmdbInit()—Create RPM Database

This function creates a new RPM database to be located in RPMVAR_DBPATH. If the database already exists, it is left unchanged. If root is specified, it is prepended to RPMVAR_DBPATH prior to creation. The perms parameter is identical to open(2)'s mode parameter:

#include  <rpm/rpmlib.h>



int  rpmdbInit(char * root,

              int perms);

The function returns 1 on error, and 0 on success.

21.2.5.4. rpmdbRebuild()—Rebuild RPM Database

This function rebuilds the RPM database located in RPMVAR_DBPATH. If root is specified, it is prepended to RPMVAR_DBPATH prior to rebuilding:

#include  <rpm/rpmlib.h>



int  rpmdbRebuild(char * root);

The function returns 1 on error, and 0 on success.

21.2.6. RPM Database Traversal

The following functions are used to traverse the RPM database. Also described in this section is a function to retrieve a database record by its record number.

Note that database records are returned in the form of a Header structure. This data structure is widely used throughout rpmlib. We will discuss more header-related functions in sections 21.2.13 and 21.2.14.

21.2.6.1. rpmdbFirstRecNum()—Begin RPM Database Traversal

This function returns the record number of the first record in the database specified by db:

#include   <rpm/rpmlib.h>



unsigned  int   rpmdbFirstRecNum(rpmdb db);

On error, it returns 0.

21.2.6.2. rpmdbNextRecNum()—Traverse to Next RPM Database Record

This function returns the record number of the record following the record number passed in lastOffset, in the database specified by db:

#include   <rpm/rpmlib.h>



unsigned  int  rpmdbNextRecNum(rpmdb db,

                                   unsigned int lastOffset);

On error, this function returns 0.

21.2.6.3. rpmdbGetRecord()—Return Record from RPM Database

This function returns the record at the record number specified by offset from the database specified by db:

#include   <rpm/rpmlib.h>



Header   rpmdbGetRecord(rpmdb db,

                      unsigned int offset);

This function returns NULL on error.

21.2.7. RPM Database Search

The functions in this section search the various parts of the RPM database. They all return a structure of type dbiIndexSet, which contains the records that match the search term. Here is the definition of the structure, as found in <rpm/dbindex.h>:

typedef struct {

    dbiIndexRecord * recs;

    int count;

} dbiIndexSet;

Each dbiIndexRecord is also defined in <rpm/dbindex.h>, as follows:

typedef struct {

     unsigned int recOffset;

    unsigned int fileNumber;

} dbiIndexRecord;

The recOffset element is the offset of the record from the start of the database file. The fileNumber element is only used by rpmdbFindByFile().

Keep in mind that the rpmdbFindxxx() search functions each return dbiIndexSet structures, which must be freed with dbiFreeIndexRecord() when no longer needed.

21.2.7.1. dbiFreeIndexRecord()—Free Database Index

This function frees the database index set specified by set:

#include  <rpm/rpmlib.h>

#include  <rpm/dbindex.h>



void   dbiFreeIndexRecord(dbiIndexSet set);

21.2.7.2. rpmdbFindByFile()—Search RPM Database by File

This function searches the RPM database specified by db for the package that owns the file specified by filespec. It returns matching records in matches:

#include   <rpm/rpmlib.h>

#include   <rpm/dbindex.h>



int   rpmdbFindByFile(rpmdb db,

                    char * filespec,

               dbiIndexSet * matches);

This function returns the following status values:

-1—An error occurred while reading a database record.
0—The search completed normally.
1—The search term was not found.