Page 305
Page 306
In this chapter, we'll explore the functions used internally by RPM. These functions are available for anyone to use, making it possible to add RPM functionality to new and existing programs. Rather than continually refer to "the RPM library" throughout this chapter, we'll use the name of the library's main include file—rpmlib.
A number of files make up rpmlib. First and foremost, of course, is the rpmlib library, librpm.a. This library contains all the functions required to implement all the basic functions contained in RPM.
The remaining files define the various data structures, parameters, and symbols used by rpmlib:
In general, rpmlib.h will always be required. When using rpmlib's header-related
functions, header.h will be required, while the database-related functions will require
dbindex.h. As each function is described in this chapter, we'll provide the function's prototype as well as the
#include statements the function requires.
There are more than 60 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.
This function returns the error code set by the last rpmlib function that failed. It should only be used in an error callback function defined by rpmErrorSetCallBack():
#include <rpm/rpmlib.h> int rpmErrorCode(void);
Page 307
This function returns the error string set by the last rpmlib function that failed. It should only be used in an error callback function defined by rpmErrorSetCallBack():
#include <rpm/rpmlib.h> char *rpmErrorString(void);
This function sets the current error callback function to the error callback function passed to it. The previous error callback function is returned:
#include <rpm/rpmlib.h> rpmErrorCallBackType rpmErrorSetCallback(rpmErrorCallBackType);
The functions described in this section are used to obtain information about a package file.
Note 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 sections 21.2.13 and 21.2.14.
Given an open package on fd, read in the header and signature:
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmReadPackageInfo(int fd,
Header * signatures,
Header * hdr);
This function operates as expected, with both socket and pipe file descriptors passed as fd. It is safe to use 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 is NULL, information for the NULL parameter will not be passed back to the caller. Otherwise, signatures and hdr 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
Page 308
Given an open package on fd, read in the header:
#include <rpm/rpmlib.h>
#include <rpm/header.h>
int rpmReadPackageHeader(int fd,
Header * hdr,
int * isSource,
int * major,
int * minor);
This function operates as expected, with both socket and pipe file descriptors passed as fd. It is 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 is 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 (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. The 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.
This function returns the value of the variable specified in var:
#include <rpm/rpmlib.h> char *rpmGetVar(int var);
On error, the function returns NULL.
Page 309
This function looks up the variable specified in var and returns 0 or 1, depending on the variable's value:
#include <rpm/rpmlib.h> int rpmGetBooleanVar(int var);
On error, the function returns 0.
This function sets the variable specified in var to the value passed in val. It is also possible for val to be NULL:
#include <rpm/rpmlib.h>
void rpmSetVar(int var,
char *val);
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.
This function:
#include <rpm/rpmlib.h>
int rpmReadConfigFiles(char * file,
char * arch,
char * os,
int building);
reads rpmrc files according to the following rules:
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.