| Maximum RPM: Taking the Red Hat Package Manager to the Limit | ||
|---|---|---|
| Prev | Chapter 21. A Guide to the RPM Library API | Next |
There are more than sixty different functions in rpmlib. The tasks they perform range from low-level database record traversal, to high-level package manipulation. We've grouped the functions into different categories for easy reference.
The functions in this section perform rpmlib's basic error handling. All error handling centers on the use of specific status codes. The status codes are defined in rpmlib.h and are of the form RPMERR_xxx, where xxx is the name of the error.
#include <rpm/rpmlib.h>
int rpmErrorCode(void);
This function returns the error code set by the last rpmlib function that failed. Should only be used in an error callback function defined by rpmErrorSetCallBack().
#include <rpm/rpmlib.h>
char *rpmErrorString(void);
This function returns the error string set by the last rpmlib function that failed. Should only be used in an error callback function defined by rpmErrorSetCallBack().
#include <rpm/rpmlib.h>
rpmErrorCallBackType rpmErrorSetCallback(rpmErrorCallBackType);
This function sets the current error callback function to the error callback function passed to it. The previous error callback function is returned.
The following functions are used to obtain information about a package file.
It should be noted that most information is returned in the form of a Header structure. This data structure is widely used throughout rpmlib. We will discuss more header-related functions in Section 21.2.13 and Section 21.2.14.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmReadPackageInfo(int fd,
Header * signatures,
Header * hdr);
Given an open package on fd, read in the header and signature. This function operates as expected with both socket and pipe file descriptors passed as fd. Safe on nonseekable fds. When the function returns, fd is left positioned at the start of the package's archive section.
If either signatures or hdr are NULL, information for the NULL parameter will not be passed back to the caller. Otherwise, they will return the package's signatures and header, respectively.
This function returns the following status values:
0 — Success.
1 — Bad magic numbers found in package.
2 — Other error.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmReadPackageHeader(int fd,
Header * hdr,
int * isSource,
int * major,
int * minor);
Given an open package on fd, read in the header. This function operates as expected with both socket and pipe file descriptors passed as fd. Safe on nonseekable fds. When the function returns, fd is left positioned at the start of the package's archive section.
If hdr, isSource, major, or minor are NULL, information for the NULL parameter(s) will not be passed back to the caller. Otherwise, they will return the package's header (hdr), information on whether the package is a source package file or not (isSource), and the package format's major and minor revision number (major and minor, respectively).
This function returns the following status values:
0 — Success.
1 — Bad magic numbers found in package.
2 — Other error.
The following functions are used to get, set, and interpret RPM's internal variables. Variables are set according to various pieces of system information, as well as from rpmrc files. They control various aspects of RPM's operation.
The variables have symbolic names in the form RPMVAR_xxx, where xxx is the name of the variable. All variable names are defined in rpmlib.h.
#include <rpm/rpmlib.h>
char *rpmGetVar(int var);
This function returns the value of the variable specified in var.
On error, the function returns NULL.
#include <rpm/rpmlib.h>
int rpmGetBooleanVar(int var);
This function looks up the variable specified in var and returns a 0 or 1 depending on the variable's value.
On error, the function returns 0.
#include <rpm/rpmlib.h>
void rpmSetVar(int var,
char *val);
This function sets the variable specified in var to the value passed in val. It is also possible for val to be NULL.
The functions in this section are all related to rpmrc information — the rpmrc files as well as the variables set from those files. This information also includes the architecture and operating system information based on rpmrc file entries.
#include <rpm/rpmlib.h>
int rpmReadConfigFiles(char * file,
char * arch,
char * os,
int building);
This function reads rpmrc files according to the following rules:
Always read /usr/lib/rpmrc.
If file is specified, read it.
If file is not specified, read /etc/rpmrc and ~/.rpmrc.
Every rpmrc file entry is used with rpmSetVar() to set the appropriate RPM variable. Part of the normal rpmrc file processing also includes setting the architecture and operating system variables for the system executing this function. These default settings can be overridden by entering architecture and/or operating system information in arch and os, respectively. This information will still go through the normal rpmrc translation process.
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.
#include <rpm/rpmlib.h>
char *rpmGetOsName(void);
This function returns the name of the operating system, as determined by rpmlib's normal rpmrc file processing.
#include <rpm/rpmlib.h>
char *rpmGetArchName(void);
This function returns the name of the architecture, as determined by rpmlib's normal rpmrc file processing.
#include <rpm/rpmlib.h>
int rpmShowRC(FILE *f);
This function writes all variable names and their values to the file f. Always returns 0.
#include <rpm/rpmlib.h>
int rpmArchScore(char * arch);
This function returns the "distance" 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 rpmOsScore(char * os);
This function returns the "distance" 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.
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.
#include <rpm/rpmlib.h>
int rpmdbOpen(char * root,
rpmdb * dbp,
int mode,
int perms);
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.
The function returns 1 on error, 0 on success.
#include <rpm/rpmlib.h>
void rpmdbClose(rpmdb db);
This function closes the RPM database specified by the rpmdb structure db. The db structure is also freed.
#include <rpm/rpmlib.h>
int rpmdbInit(char * root,
int perms);
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.
The function returns 1 on error, 0 on success.
#include <rpm/rpmlib.h>
int rpmdbRebuild(char * root);
This function rebuilds the RPM database located in RPMVAR_DBPATH. If root is specified, it is prepended to RPMVAR_DBPATH prior to rebuilding.
The function returns 1 on error, 0 on success.
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.
It should be noted 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 Section 21.2.13 and Section 21.2.14.
#include <rpm/rpmlib.h>
unsigned int rpmdbFirstRecNum(rpmdb db);
This function returns the record number of the first record in the database specified by db.
On error, it returns 0.
#include <rpm/rpmlib.h>
unsigned int rpmdbNextRecNum(rpmdb db,
unsigned int lastOffset);
This function returns the record number of the record following the record number passed in lastOffset, in the database specified by db.
On error, this function returns 0.
#include <rpm/rpmlib.h>
Header rpmdbGetRecord(rpmdb db,
unsigned int offset);
This function returns the record at the record number specified by offset from the database specified by db.
This function returns NULL on error.
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.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
void dbiFreeIndexRecord(dbiIndexSet set);
This function frees the database index set specified by set.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindByFile(rpmdb db,
char * filespec,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the package which owns the file specified by filespec. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindByGroup(rpmdb db,
char * group,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the packages which are members of the group specified by group. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindPackage(rpmdb db,
char * name,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the packages with the package name (not label) specified by name. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindByProvides(rpmdb db,
char * provides,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the packages which provide the provides information specified by provides. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindByRequiredBy(rpmdb db,
char * requires,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the packages which require the requires information specified by requires. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
#include <rpm/rpmlib.h>
#include <rpm/dbindex.h>
int rpmdbFindByConflicts(rpmdb db,
char * conflicts,
dbiIndexSet * matches);
This function searches the RPM database specified by db for the packages which conflict with the conflicts information specified by conflicts. It returns matching records in matches.
This function returns the following status values:
-1 — An error occurred reading a database record.
0 — The search completed normally.
1 — The search term was not found.
These functions perform the operations most RPM users are familiar with. Functions that install and erase packages are here, along with a few related lower-level support functions.
#include <rpm/rpmlib.h>
int rpmInstallSourcePackage(char * root,
int fd,
char ** specFile,
rpmNotifyFunction notify,
char * labelFormat);
This function installs the source package file specified by fd. If root is not NULL, it is prepended to the variables RPMVAR_SOURCEDIR and RPMVAR_SPECDIR prior to the actual installation. If specFile is not NULL, the complete path and filename of the just-installed spec file is returned.
The notify parameter is used to specify a progress-tracking function that will be called during the installation. Please refer to Section 21.2.8.3 for more information on this parameter.
The labelFormat parameter can be used to specify how the package label should be formatted. It is used when printing the package label once the package install is ready to proceed. If labelformat is NULL, the package label is not printed.
This function returns the following status values:
0 — The source package was installed successfully.
1 — The source package file contained incorrect magic numbers.
2 — Another type of error occurred.
#include <rpm/rpmlib.h>
int rpmInstallPackage(char * rootdir,
rpmdb db,
int fd,
char * prefix,
int flags,
rpmNotifyFunction notify,
char * labelFormat,
char * netsharedPath);
This function installs the binary package specified by fd. If a path is specified in rootdir, the package will be installed with that path acting as the root directory. If a path is specified in prefix, it will be used as the prefix for relocatable packages. The RPM database specified by db is updated to reflect the newly installed package.
The flags parameter is used to control the installation behavior. The flags are defined in rpmlib.h and take the form RPMINSTALL_xxx, where xxx is the name of the flag.
The following flags are currently defined:
RPMINSTALL_REPLACEPKG — Install the package even if it is already installed.
RPMINSTALL_REPLACEFILES — Install the package even if it will replace files owned by another package.
RPMINSTALL_TEST — Perform all install-time checks, but do not actually install the package.
RPMINSTALL_UPGRADE — Install the package, and remove all older versions of the package.
RPMINSTALL_UPGRADETOOLD — Install the package, even if the package is an older version of an already-installed package.
RPMINSTALL_NODOCS — Do not install the package's documentation files.
RPMINSTALL_NOSCRIPTS — Do not execute the package's install- and erase-time (in the case of an upgrade) scripts.
RPMINSTALL_NOARCH — Do not perform architecture compatibility tests.
RPMINSTALL_NOOS — Do not perform operating system compatibility tests.
The notify parameter is used to specify a progress tracking function that will be called during the installation. Please refer to Section 21.2.8.3 for more information on this parameter.
The labelFormat parameter can be used to specify how the package label should be formatted. This information is used when printing the package label once the package install is ready to proceed. It is used when printing the package label once the package install is ready to proceed. If labelformat is NULL, the package label is not printed.
The netsharedPath parameter is used to specify that part of the local filesystem that is shared with other systems. If there is more than one path that is shared, the paths should be separated with a colon.
This function returns the following status values:
0 — The binary package was installed successfully.
1 — The binary package file contained incorrect magic numbers.
2 — Another type of error occurred.
#include <rpm/rpmlib.h>
typedef void (*rpmNotifyFunction)(const unsigned long amount,
const unsigned long total);
A function can be passed to rpmIstallSourcePackage or rpmInstallPackage via the notify parameter. The function will be called at regular intervals during the installation, and will have two parameters passed to it:
amount — The number of bytes of the install that have been completed so far.
total — The total number of bytes that will be installed.
This function permits the creation of a dynamically updating progress meter during package installation.
#include <rpm/rpmlib.h>
int rpmRemovePackage(char * root,
rpmdb db,
unsigned int offset,
int flags);
This function removes the package at record number offset in the RPM database specified by db. If root is specified, it is used as the path to a directory that will serve as the root directory while the package is being removed.
The flags parameter is used to control the package removal behavior. The flags that may be passed are defined in rpmlib.h, and are of the form RPMUNINSTALL_xxx, where xxx is the name of the flag.
The following flags are currently defined:
RPMUNINSTALL_TEST — Perform all erase-time checks, but do not actually remove the package.
RPMUNINSTALL_NOSCRIPTS — Do not execute the package's erase-time scripts.
This function returns the following status values:
0 — The package was removed successfully.
1 — The package removal failed.
The functions in this section perform the verification operations necessary to ensure that the files comprising a package have not been modified since they were installed.
Verification takes place on three distinct levels:
On the file-by-file level.
On a package-wide level, through the use of the %verifyscript verification script.
On an inter-package level, through RPM's normal dependency processing.
Because of this, there are two functions to perform each specific verification operation.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmVerifyFile(char * root,
Header h,
int filenum,
int * result);
This function verifies the filenum'th file from the package whose header is h. If root is specified, it is used as the path to a directory that will serve as the root directory while the file is being verified. The results of the file verification are returned in result, and consist of a number of flags. Each flag that is set indicates a verification failure.
The flags are defined in rpmlib.h, and are of the form RPMVERIFY_xxx, where xxx is the name of the data that failed verification.
This function returns 0 on success, and 1 on failure.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmVerifyScript(char * root,
Header h,
int err);
This function executes the %verifyscript verification script for the package whose header is h. err must contain a valid file descriptor. If rpmIsVerbose() returns true, the %verifyscript verification script will direct all status messages to err.
This function returns 0 on success, 1 on failure.
The functions in this section are used to perform the various dependency-related operations supported by rpmlib.
Dependency processing is entirely separate from normal package-based operations. The package installation and removal functions do not perform any dependency processing themselves. Therefore, dependency processing is somewhat different from other aspects of rpmlib's operation.
Dependency processing centers around the rpmDependencies data structure. The operations that are to be performed against the RPM database (adding, removing, and upgrading packages) are performed against this data structure, using functions that are described below. These functions simply populate the data structure according to the operation being performed. They do not perform the actual operation on the package. This is an important point to keep in mind.
Once the data structure has been completely populated, a dependency check function is called to determine if there are any dependency-related problems. The result is a structure of dependency conflicts. This structure, rpmDependencyConflict, is defined in rpmlib.h.
Note that it is necessary to free both the conflicts structure and the rpmDependencies structure when they are no longer needed. However, free() should not be used — special functions for this are provided, and will be discussed in this section.
#include <rpm/rpmlib.h>
rpmDependencies rpmdepDependencies(rpmdb db);
This function returns an initialized rpmDependencies structure. The dependency checking to be done will be based on the RPM database specified in the db parameter. If this parameter is NULL, the dependency checking will be done as if an empty RPM database was being used.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void rpmdepAddPackage(rpmDependencies rpmdep,
Header h);
This function adds the installation of the package whose header is h, to the rpmDependencies data structure, rpmdep.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void rpmdepUpgradePackage(rpmDependencies rpmdep,
Header h);
This function adds the upgrading of the package whose header is h, to the rpmDependencies data structure, rpmdep. It is similar to rpmdepAddPackage(), but older versions of the package are removed.
#include <rpm/rpmlib.h>
void rpmdepRemovePackage(rpmDependencies rpmdep,
int dboffset);
This function adds the removal of the package whose RPM database offset is dboffset, to the rpmDependencies data structure, rpmdep.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void rpmdepAvailablePackage(rpmDependencies rpmdep,
Header h,
void * key);
This function adds the package whose header is h, to the rpmDependencies structure, rpmdep.
The key parameter can be anything that uniquely identifies the package being added. It will be returned as part of the rpmDependencyConflict structure returned by rpmdepCheck(), specifically in that structure's suggestedPackage element.
#include <rpm/rpmlib.h>
int rpmdepCheck(rpmDependencies rpmdep,
struct rpmDependencyConflict ** conflicts,
int * numConflicts);
This function performs a dependency check on the rpmDependencies structure rpmdep. It returns an array of size numConflicts, pointed to by conflicts.
This function returns 0 on success, and 1 on error.
#include <rpm/rpmlib.h>
void rpmdepFreeConflicts(struct rpmDependencyConflict * conflicts,
int numConflicts);
This function frees the dependency conflict information of size numConflicts pointed to by conflicts.
#include <rpm/rpmlib.h>
void rpmdepDone(rpmDependencies rpmdep);
This function frees the rpmDependencies structure pointed to by rpmdep.
The functions in this section are used to control the amount of diagnostic output produced by other rpmlib functions. The rpmlib library can produce a wealth of diagnostic output, making it easy to see what is going on at any given time.
There are several different verbosity levels defined in rpmlib.h. Their symbolic names are of the form RPMMESS_xxx, where xxx is the name of the verbosity level. It should be noted that the numeric values of the verbosity levels increase with a decrease in verbosity.
Unless otherwise set, the default verbosity level is RPMMESS_NORMAL.
#include <rpm/rpmlib.h>
void rpmIncreaseVerbosity(void);
This function is used to increase the current verbosity level by one.
#include <rpm/rpmlib.h>
void rpmSetVerbosity(int level);
This function is used to set the current verbosity level to level. Note that no range checking is done to level.
#include <rpm/rpmlib.h>
int rpmGetVerbosity(void);
This function returns the current verbosity level.
#include <rpm/rpmlib.h>
int rpmIsVerbose(void);
This function checks the current verbosity level and returns 1 if the current level is set to RPMMESS_VERBOSE or a level of higher verbosity. Otherwise, it returns 0.
#include <rpm/rpmlib.h>
int rpmIsDebug(void);
This function checks the current verbosity level and returns 1 if the current level is set to RPMMESS_DEBUG, or a level of higher verbosity. Otherwise, it returns 0.
The functions in this section deal with the verification of package signatures. A package file may contain more than one type of signature. For example, a package may contain a signature that contains the package's size, as well as a signature that contains cryptographically-derived data that can be used to prove the package's origin.
Each type of signature has its own tag value. These tag values are defined in rpmlib.h and are of the form RPMSIGTAG_xxx, where xxx is the type of signature.
#include <rpm/rpmlib.h>
int rpmVerifySignature(char *file,
int_32 sigTag,
void *sig,
int count,
char *result);
This function verifies the signature of the package pointed to by file. The result of the verification is stored in result, in a format suitable for printing.
The sigTag parameter specifies the type of signature to be checked. The sig parameter specifies the signature against which the package is to be verified. The count parameter specifies the size of the signature; at present, this parameter is only used for PGP-based signatures.
This function returns the following values:
RPMSIG_OK — The signature verified correctly.
RPMSIG_UNKNOWN — The signature type is unknown.
RPMSIG_BAD — The signature did not verify correctly.
RPMSIG_NOKEY — The key required to check this signature is not available.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void rpmFreeSignature(Header h);
This function frees the signature h.
The header is one of the key data structures in rpmlib. The functions in this section perform basic manipulations of the header.
The header is actually a data structure. It is not necessary to fully understand the actual data structure. However, it is necessary to understand the basic concepts on which the header is based.
The header serves as a kind of miniature database. The header can be searched for specific information, which can be retrieved easily. Like a database, the information contained in the header can be of varying sizes.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
Header headerRead(int fd,
int magicp);
This function reads a header from file fd, converting it from network byte order to the host system's byte order. If magicp is defined to be HEADER_MAGIC_YES, headerRead() will expect header magic numbers, and will return an error if they are not present. Likewise, if magicp is defined to be HEADER_MAGIC_NO, headerRead() will not check the header's magic numbers, and will return an error if they are present.
On error, this function returns NULL.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void headerWrite(int fd,
Header h,
int magicp);
This function writes the header h, to file fd, converting it from host byte order to network byte order. If magicp is defined to be HEADER_MAGIC_YES, headerWrite() will add the appropriate magic numbers to the header being written. If magicp is defined to be HEADER_MAGIC_NO, headerWrite() will not include magic numbers.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
Header headerCopy(Header h);
This function returns a copy of header h.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
unsigned int headerSizeof(Header h,
int magicp);
This function returns the number of bytes the header h takes up on disk. Note that in versions of RPM prior to 2.3.3, this function also changes the location of the data in the header. The result is that pointers from headerGetEntry() will no longer be valid. Therefore, any pointers acquired before calling headerSizeof() should be discarded.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
Header headerNew(void);
This function returns a new header.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void headerFree(Header h);
This function deallocates the header specified by h.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void headerDump(Header h,
FILE *f,
int flags);
This function prints the structure of the header h, to the file f. If the flags parameter is defined to be HEADER_DUMP_INLINE, the header's data is also printed.
The functions in this section provide the basic operations necessary to manipulate header entries. The following header entry types are currently defined:
RPM_NULL_TYPE — This type is not used.
RPM_CHAR_TYPE — The entry contains a single character.
RPM_INT8_TYPE — The entry contains an eight-bit integer.
RPM_INT16_TYPE — The entry contains a sixteen-bit integer.
RPM_INT32_TYPE — The entry contains a thirty-two-bit integer.
RPM_INT64_TYPE — The entry contains a sixty-four-bit integer.
RPM_STRING_TYPE — The entry contains a null-terminated character string.
RPM_BIN_TYPE — The entry contains binary data that will not be interpreted by rpmlib.
RPM_STRING_ARRAY_TYPE — The entry contains an array of null-terminated strings.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int headerGetEntry(Header h,
int_32 tag,
int_32 *type,
void **p,
int_32 *c);
This function retrieves the entry matching tag from header h. The type of the entry is returned in type, a pointer to the data is returned in p, and the size of the data is returned in c. Both type and c may be null, in which case that data will not be returned. Note that if the entry type is RPM_STRING_ARRAY_TYPE, you must issue a free() on p when done with the data.
This function returns 1 on sucess, and 0 on failure.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int headerAddEntry(Header h,
int_32 tag,
int_32 type,
void *p,
int_32 c);
This function adds a new entry to the header h. The entry's tag is specified by the tag parameter, and the entry's type is specified by the type parameter.
The entry's data is pointed to by p, and the size of the data is specified by c.
This function always returns 1.
Note: In versions of RPM prior to 2.3.3, headerAddEntry() will only work successfully with headers produced by headerCopy() and headerNew(). In particular, headerAddEntry() is not supported when used to add entries to a header produced by headerRead(). Later versions of RPM lift this restriction.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int headerIsEntry(Header h,
int_32 tag);
This function returns 1 if an entry with tag tag is present in header h. If the tag is not present, this function returns 0.
Iterators are used as a means to step from entry to entry, through an entire header. The functions in this section are used to create, use, and free iterators.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
HeaderIterator headerInitIterator(Header h);
This function returns a newly-created iterator for the header h.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int headerNextIterator(HeaderIterator iter,
int_32 *tag,
int_32 *type,
void **p,
int_32 *c);
This function steps to the next entry in the header specified when the iterator iter was created with headerInitIterator(). The next entry's tag, type, data, and size are returned in tag, type, p, and c, respectively. Note that if the entry type is RPM_STRING_ARRAY_TYPE, you must issue a free() on p when done with the data.
This function returns 1 if successful, and 0 if there are no more entries in the header.
#include <rpm/rpmlib.h>
#include <rpm/header.h>
void headerFreeIterator(HeaderIterator iter);
This function frees the resources used by the iterator iter.