rpm  4.8.1
Typedefs | Enumerations | Functions | Variables
header.h File Reference

An rpm header carries all information about a package. More...

#include <rpm/rpmio.h>
#include <rpm/rpmtypes.h>
#include <rpm/rpmtd.h>
#include <rpm/rpmutil.h>
Include dependency graph for header.h:

Go to the source code of this file.

Typedefs

typedef enum headerGetFlags_e headerGetFlags
 Modifier flags for headerGet() operation. More...
 
typedef enum headerPutFlags_e headerPutFlags
 
typedef enum headerConvOps_e headerConvOps
 

Enumerations

enum  hMagic { HEADER_MAGIC_NO = 0, HEADER_MAGIC_YES = 1 }
 Include calculation for 8 bytes of (magic, 0)? More...
 
enum  headerGetFlags_e {
  HEADERGET_DEFAULT = 0, HEADERGET_MINMEM = (1 << 0), HEADERGET_EXT = (1 << 1), HEADERGET_RAW = (1 << 2),
  HEADERGET_ALLOC = (1 << 3), HEADERGET_ARGV = (1 << 4)
}
 Modifier flags for headerGet() operation. More...
 
enum  headerPutFlags_e { HEADERPUT_DEFAULT = 0, HEADERPUT_APPEND = (1 << 0) }
 
enum  headerConvOps_e { HEADERCONV_EXPANDFILELIST = 0, HEADERCONV_COMPRESSFILELIST = 1, HEADERCONV_RETROFIT_V3 = 2 }
 

Functions

Header headerNew (void)
 Create new (empty) header instance. More...
 
Header headerFree (Header h)
 Dereference a header instance. More...
 
Header headerLink (Header h)
 Reference a header instance. More...
 
Header headerUnlink (Header h)
 Dereference a header instance. More...
 
void headerSort (Header h)
 Sort tags in header. More...
 
void headerUnsort (Header h)
 Restore tags in header to original ordering. More...
 
unsigned int headerSizeof (Header h, enum hMagic magicp)
 Return size of on-disk header representation in bytes. More...
 
int headerVerifyInfo (int il, int dl, const void *pev, void *iv, int negate)
 Perform simple sanity and range checks on header tag(s). More...
 
void * headerUnload (Header h)
 Convert header to on-disk representation. More...
 
Header headerReload (Header h, rpmTag tag)
 Convert header to on-disk representation, and then reload. More...
 
Header headerCopy (Header h)
 Duplicate a header. More...
 
Header headerLoad (void *uh)
 Convert header to in-memory representation. More...
 
Header headerCopyLoad (const void *uh)
 Make a copy and convert header to in-memory representation. More...
 
Header headerRead (FD_t fd, enum hMagic magicp)
 Read (and load) header from file handle. More...
 
int headerWrite (FD_t fd, Header h, enum hMagic magicp)
 Write (with unload) header to file handle. More...
 
int headerIsEntry (Header h, rpmTag tag)
 Check if tag is in header. More...
 
int headerGet (Header h, rpmTag tag, rpmtd td, headerGetFlags flags)
 Retrieve tag value. More...
 
int headerPut (Header h, rpmtd td, headerPutFlags flags)
 Add or append tag to header. More...
 
int headerAddI18NString (Header h, rpmTag tag, const char *string, const char *lang)
 Add locale specific tag to header. More...
 
int headerMod (Header h, rpmtd td)
 Modify tag in header. More...
 
int headerDel (Header h, rpmTag tag)
 Delete tag in header. More...
 
char * headerFormat (Header h, const char *fmt, errmsg_t *errmsg)
 Return formatted output string from header tags. More...
 
void headerCopyTags (Header headerFrom, Header headerTo, const rpmTag *tagstocopy)
 Duplicate tag values from one header into another. More...
 
HeaderIterator headerFreeIterator (HeaderIterator hi)
 Destroy header tag iterator. More...
 
HeaderIterator headerInitIterator (Header h)
 Create header tag iterator. More...
 
int headerNext (HeaderIterator hi, rpmtd td)
 Return next tag contents from header. More...
 
rpmTag headerNextTag (HeaderIterator hi)
 Return next tag number from header. More...
 
RPM_GNUC_DEPRECATED int headerNVR (Header h, const char **np, const char **vp, const char **rp)
 Return name, version, release strings from header. More...
 
RPM_GNUC_DEPRECATED int headerNEVRA (Header h, const char **np, uint32_t **ep, const char **vp, const char **rp, const char **ap)
 Return name, epoch, version, release, arch strings from header. More...
 
RPM_GNUC_DEPRECATED char * headerGetNEVR (Header h, const char **np)
 Return (malloc'd) header name-version-release string. More...
 
RPM_GNUC_DEPRECATED char * headerGetNEVRA (Header h, const char **np)
 Return (malloc'd) header name-version-release.arch string. More...
 
RPM_GNUC_DEPRECATED char * headerGetEVR (Header h, const char **np)
 
char * headerGetAsString (Header h, rpmTag tag)
 Return any non-array tag from header, converted to string. More...
 
const char * headerGetString (Header h, rpmTag tag)
 Return a simple string tag from header. More...
 
uint64_t headerGetNumber (Header h, rpmTag tag)
 
RPM_GNUC_DEPRECATED rpm_color_t headerGetColor (Header h)
 Return header color. More...
 
int headerIsSource (Header h)
 Check if header is a source or binary package header. More...
 
unsigned int headerGetInstance (Header h)
 Return header instance, ie is the header from rpmdb. More...
 
int headerConvert (Header h, headerConvOps op)
 Convert header to/from (legacy) data presentation. More...
 
int headerPutString (Header h, rpmTag tag, const char *val)
 Type-safe methods for inserting tag data to header. More...
 
int headerPutStringArray (Header h, rpmTag tag, const char **val, rpm_count_t size)
 
int headerPutBin (Header h, rpmTag tag, uint8_t *val, rpm_count_t size)
 
int headerPutChar (Header h, rpmTag tag, char *val, rpm_count_t size)
 
int headerPutUint8 (Header h, rpmTag tag, uint8_t *val, rpm_count_t size)
 
int headerPutUint16 (Header h, rpmTag tag, uint16_t *val, rpm_count_t size)
 
int headerPutUint32 (Header h, rpmTag tag, uint32_t *val, rpm_count_t size)
 
int headerPutUint64 (Header h, rpmTag tag, uint64_t *val, rpm_count_t size)
 

Variables

const unsigned char rpm_header_magic [8]
 Header magic value. More...
 

Detailed Description

An rpm header carries all information about a package.

A header is a collection of data elements called tags. Each tag has a data type, and includes 1 or more values.

Definition in file header.h.

Typedef Documentation

◆ headerConvOps

◆ headerGetFlags

Modifier flags for headerGet() operation.

For consistent behavior you'll probably want to use ALLOC to ensure the caller owns the data, but MINMEM is useful for avoiding extra copy of data when you are sure the header wont go away. Most of the time you'll probably want EXT too, but note that extensions tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV are only relevant for non-extension data.

◆ headerPutFlags

Enumeration Type Documentation

◆ headerConvOps_e

Enumerator
HEADERCONV_EXPANDFILELIST 
HEADERCONV_COMPRESSFILELIST 
HEADERCONV_RETROFIT_V3 

Definition at line 431 of file header.h.

◆ headerGetFlags_e

Modifier flags for headerGet() operation.

For consistent behavior you'll probably want to use ALLOC to ensure the caller owns the data, but MINMEM is useful for avoiding extra copy of data when you are sure the header wont go away. Most of the time you'll probably want EXT too, but note that extensions tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV are only relevant for non-extension data.

Enumerator
HEADERGET_DEFAULT 
HEADERGET_MINMEM 
HEADERGET_EXT 
HEADERGET_RAW 
HEADERGET_ALLOC 
HEADERGET_ARGV 

Definition at line 166 of file header.h.

◆ headerPutFlags_e

Enumerator
HEADERPUT_DEFAULT 
HEADERPUT_APPEND 

Definition at line 186 of file header.h.

◆ hMagic

enum hMagic

Include calculation for 8 bytes of (magic, 0)?

Enumerator
HEADER_MAGIC_NO 
HEADER_MAGIC_YES 

Definition at line 32 of file header.h.

Function Documentation

◆ headerAddI18NString()

int headerAddI18NString ( Header  h,
rpmTag  tag,
const char *  string,
const char *  lang 
)

Add locale specific tag to header.

A NULL lang is interpreted as the C locale. Here are the rules:

*       - If the tag isn't in the header, it's added with the passed string
*          as new value.
*       - If the tag occurs multiple times in entry, which tag is affected
*          by the operation is undefined.
*       - If the tag is in the header w/ this language, the entry is
*          *replaced* (like headerMod()).
* 

This function is intended to just "do the right thing". If you need more fine grained control use headerPut() and headerMod().

Parameters
hheader
tagtag
stringtag value
langlocale
Returns
1 on success, 0 on failure

◆ headerConvert()

int headerConvert ( Header  h,
headerConvOps  op 
)

Convert header to/from (legacy) data presentation.

Parameters
hheader
opoperation
Returns
1 on success, 0 on failure

◆ headerCopy()

Header headerCopy ( Header  h)

Duplicate a header.

Parameters
hheader
Returns
new header instance

◆ headerCopyLoad()

Header headerCopyLoad ( const void *  uh)

Make a copy and convert header to in-memory representation.

Parameters
uhon-disk header blob (i.e. with offsets)
Returns
header

◆ headerCopyTags()

void headerCopyTags ( Header  headerFrom,
Header  headerTo,
const rpmTag tagstocopy 
)

Duplicate tag values from one header into another.

Parameters
headerFromsource header
headerTodestination header
tagstocopyarray of tags that are copied

◆ headerDel()

int headerDel ( Header  h,
rpmTag  tag 
)

Delete tag in header.

Removes all entries of type tag from the header, returns 1 if none were found.

Parameters
hheader
tagtag
Returns
0 on success, 1 on failure (INCONSISTENT)

◆ headerFormat()

char* headerFormat ( Header  h,
const char *  fmt,
errmsg_t errmsg 
)

Return formatted output string from header tags.

The returned string must be free()d.

Parameters
hheader
fmtformat to use
Return values
errmsgerror message (if any)
Returns
formatted output string (malloc'ed)

◆ headerFree()

Header headerFree ( Header  h)

Dereference a header instance.

Parameters
hheader
Returns
NULL always

◆ headerFreeIterator()

HeaderIterator headerFreeIterator ( HeaderIterator  hi)

Destroy header tag iterator.

Parameters
hiheader tag iterator
Returns
NULL always

◆ headerGet()

int headerGet ( Header  h,
rpmTag  tag,
rpmtd  td,
headerGetFlags  flags 
)

Retrieve tag value.

Parameters
hheader
tagtag
Return values
tdtag data container
Parameters
flagsretrieval modifier flags
Returns
1 on success, 0 on failure

◆ headerGetAsString()

char* headerGetAsString ( Header  h,
rpmTag  tag 
)

Return any non-array tag from header, converted to string.

Parameters
hheader
tagtag to retrieve
Returns
string pointer (malloced) or NULL on failure

◆ headerGetColor()

RPM_GNUC_DEPRECATED rpm_color_t headerGetColor ( Header  h)

Return header color.

Parameters
hheader
Returns
header color

◆ headerGetEVR()

RPM_GNUC_DEPRECATED char* headerGetEVR ( Header  h,
const char **  np 
)

◆ headerGetInstance()

unsigned int headerGetInstance ( Header  h)

Return header instance, ie is the header from rpmdb.

Parameters
hheader
Returns
rpmdb record number or 0

◆ headerGetNEVR()

RPM_GNUC_DEPRECATED char* headerGetNEVR ( Header  h,
const char **  np 
)

Return (malloc'd) header name-version-release string.

Parameters
hheader
Return values
npname tag value
Returns
name-version-release string

◆ headerGetNEVRA()

RPM_GNUC_DEPRECATED char* headerGetNEVRA ( Header  h,
const char **  np 
)

Return (malloc'd) header name-version-release.arch string.

Parameters
hheader
Return values
npname tag value
Returns
name-version-release string

◆ headerGetNumber()

uint64_t headerGetNumber ( Header  h,
rpmTag  tag 
)

◆ headerGetString()

const char* headerGetString ( Header  h,
rpmTag  tag 
)

Return a simple string tag from header.

Parameters
hheader
tagtag to retrieve
Returns
string pointer (to header memory) or NULL on failure

Referenced by main().

◆ headerInitIterator()

HeaderIterator headerInitIterator ( Header  h)

Create header tag iterator.

Parameters
hheader
Returns
header tag iterator

◆ headerIsEntry()

int headerIsEntry ( Header  h,
rpmTag  tag 
)

Check if tag is in header.

Parameters
hheader
tagtag
Returns
1 on success, 0 on failure

Referenced by checkSpec().

◆ headerIsSource()

int headerIsSource ( Header  h)

Check if header is a source or binary package header.

Parameters
hheader
Returns
0 == binary, 1 == source

◆ headerLink()

Header headerLink ( Header  h)

Reference a header instance.

Parameters
hheader
Returns
new header reference

◆ headerLoad()

Header headerLoad ( void *  uh)

Convert header to in-memory representation.

Parameters
uhon-disk header blob (i.e. with offsets)
Returns
header

◆ headerMod()

int headerMod ( Header  h,
rpmtd  td 
)

Modify tag in header.

If there are multiple entries with this tag, the first one gets replaced.

Parameters
hheader
tdtag data container
Returns
1 on success, 0 on failure

◆ headerNEVRA()

RPM_GNUC_DEPRECATED int headerNEVRA ( Header  h,
const char **  np,
uint32_t **  ep,
const char **  vp,
const char **  rp,
const char **  ap 
)

Return name, epoch, version, release, arch strings from header.

Parameters
hheader
Return values
*npname pointer (or NULL)
*epepoch pointer (or NULL)
*vpversion pointer (or NULL)
*rprelease pointer (or NULL)
*aparch pointer (or NULL)
Returns
0 always

◆ headerNew()

Header headerNew ( void  )

Create new (empty) header instance.

Returns
header

◆ headerNext()

int headerNext ( HeaderIterator  hi,
rpmtd  td 
)

Return next tag contents from header.

Parameters
hiheader tag iterator
Return values
tdtag data container
Returns
1 on success, 0 on failure

◆ headerNextTag()

rpmTag headerNextTag ( HeaderIterator  hi)

Return next tag number from header.

Parameters
hiheader tag iterator
Returns
next tag, RPMTAG_NOT_FOUND to stop iteration

◆ headerNVR()

RPM_GNUC_DEPRECATED int headerNVR ( Header  h,
const char **  np,
const char **  vp,
const char **  rp 
)

Return name, version, release strings from header.

Parameters
hheader
Return values
*npname pointer (or NULL)
*vpversion pointer (or NULL)
*rprelease pointer (or NULL)
Returns
0 always

◆ headerPut()

int headerPut ( Header  h,
rpmtd  td,
headerPutFlags  flags 
)

Add or append tag to header.

Parameters
hheader
tdtag data container
flagsflags to control operation
Returns
1 on success, 0 on failure

◆ headerPutBin()

int headerPutBin ( Header  h,
rpmTag  tag,
uint8_t *  val,
rpm_count_t  size 
)

◆ headerPutChar()

int headerPutChar ( Header  h,
rpmTag  tag,
char *  val,
rpm_count_t  size 
)

◆ headerPutString()

int headerPutString ( Header  h,
rpmTag  tag,
const char *  val 
)

Type-safe methods for inserting tag data to header.

Tag data type is validated to match the function type, ie things like headerPutUint32(h, RPMTAG_NAME, ...) will return failure. For non-array types size must equal 1, and data is checked to be non-NULL. For array types, add-or-append mode is always used.

headerPutString() can be used on both RPM_STRING_TYPE and RPM_STRING_ARRAY_TYPE (to add a single string into the array) tags, for others the type must match exactly.

These are intended to "do the right thing" in the common case, if you need more fine grained control use headerPut() & friends instead.

Todo:
Make doxygen group these meaningfully.
Parameters
hheader
tagtag to insert
valpointer to value(s)
sizenumber of items in array (1 or larger)
Returns
1 on success, 0 on failure

◆ headerPutStringArray()

int headerPutStringArray ( Header  h,
rpmTag  tag,
const char **  val,
rpm_count_t  size 
)

◆ headerPutUint16()

int headerPutUint16 ( Header  h,
rpmTag  tag,
uint16_t *  val,
rpm_count_t  size 
)

◆ headerPutUint32()

int headerPutUint32 ( Header  h,
rpmTag  tag,
uint32_t *  val,
rpm_count_t  size 
)

◆ headerPutUint64()

int headerPutUint64 ( Header  h,
rpmTag  tag,
uint64_t *  val,
rpm_count_t  size 
)

◆ headerPutUint8()

int headerPutUint8 ( Header  h,
rpmTag  tag,
uint8_t *  val,
rpm_count_t  size 
)

◆ headerRead()

Header headerRead ( FD_t  fd,
enum hMagic  magicp 
)

Read (and load) header from file handle.

Parameters
fdfile handle
magicpread (and verify) 8 bytes of (magic, 0)?
Returns
header (or NULL on error)

◆ headerReload()

Header headerReload ( Header  h,
rpmTag  tag 
)

Convert header to on-disk representation, and then reload.

This is used to insure that all header data is in one chunk.

Parameters
hheader (with pointers)
tagregion tag
Returns
on-disk header (with offsets)

◆ headerSizeof()

unsigned int headerSizeof ( Header  h,
enum hMagic  magicp 
)

Return size of on-disk header representation in bytes.

Parameters
hheader
magicpinclude size of 8 bytes for (magic, 0)?
Returns
size of on-disk header

◆ headerSort()

void headerSort ( Header  h)

Sort tags in header.

Parameters
hheader

◆ headerUnlink()

Header headerUnlink ( Header  h)

Dereference a header instance.

Parameters
hheader
Returns
new header reference

◆ headerUnload()

void* headerUnload ( Header  h)

Convert header to on-disk representation.

Parameters
hheader (with pointers)
Returns
on-disk header blob (i.e. with offsets)

◆ headerUnsort()

void headerUnsort ( Header  h)

Restore tags in header to original ordering.

Parameters
hheader

◆ headerVerifyInfo()

int headerVerifyInfo ( int  il,
int  dl,
const void *  pev,
void *  iv,
int  negate 
)

Perform simple sanity and range checks on header tag(s).

Parameters
ilno. of tags in header
dlno. of bytes in header data.
pev1st element in tag array, big-endian
ivfailing (or last) tag element, host-endian
negatenegative offset expected?
Returns
-1 on success, otherwise failing tag element index

◆ headerWrite()

int headerWrite ( FD_t  fd,
Header  h,
enum hMagic  magicp 
)

Write (with unload) header to file handle.

Parameters
fdfile handle
hheader
magicpprefix write with 8 bytes of (magic, 0)?
Returns
0 on success, 1 on error

Variable Documentation

◆ rpm_header_magic

const unsigned char rpm_header_magic[8]

Header magic value.