# Header API.

## Files
file | header.h

| An rpm header carries all information about a package.
file | rpmlib.h

| In Memoriam: Steve Taylor <staylor@redhat.com> was here, now he's not.
## Typedefs
typedef enum headerGetFlags_e | headerGetFlags
| Modifier flags for headerGet() operation.
typedef enum rpmTagType_e | rpmTagType
| The basic types of data in tags from headers.
typedef enum rpmSubTagType_e | rpmSubTagType
| New rpm data types under consideration/development.
typedef enum rpmTagReturnType_e | rpmTagReturnType
| * Identify how to return the header data type.
## 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 | rpmTagType_e
| The basic types of data in tags from headers. More...
enum | rpmSubTagType_e { RPM_REGION_TYPE = -10, RPM_BIN_ARRAY_TYPE = -11, RPM_XREF_TYPE = -12 }
| New rpm data types under consideration/development. More...
enum | rpmTagReturnType_e { RPM_ANY_RETURN_TYPE = 0, RPM_SCALAR_RETURN_TYPE = 0x00010000, RPM_ARRAY_RETURN_TYPE = 0x00020000, RPM_MAPPING_RETURN_TYPE = 0x00040000, RPM_MASK_RETURN_TYPE = 0xffff0000 }
| * Identify how to return the header data type. More...
## Functions
Header | headerNew (void)
| Create new (empty) header instance.
Header | headerFree (Header h)
| Dereference a header instance.
Header | headerLink (Header h)
| Reference a header instance.
Header | headerUnlink (Header h)
| Dereference a header instance.
void | headerSort (Header h)
| Sort tags in header.
void | headerUnsort (Header h)
| Restore tags in header to original ordering.
unsigned int | headerSizeof (Header h, enum hMagic magicp)
| Return size of on-disk header representation in bytes.
int | headerVerifyInfo (int il, int dl, const void *pev, void *iv, int negate)
| Perform simple sanity and range checks on header tag(s).
void * | headerUnload (Header h)
| Convert header to on-disk representation.
Header | headerReload (Header h, rpmTag tag)
| Convert header to on-disk representation, and then reload.
Header | headerCopy (Header h)
| Duplicate a header.
Header | headerLoad (void *uh)
| Convert header to in-memory representation.
Header | headerCopyLoad (const void *uh)
| Make a copy and convert header to in-memory representation.
Header | headerRead (FD_t fd, enum hMagic magicp)
| Read (and load) header from file handle.
int | headerWrite (FD_t fd, Header h, enum hMagic magicp)
| Write (with unload) header to file handle.
int | headerIsEntry (Header h, rpmTag tag)
| Check if tag is in header.
int | headerGet (Header h, rpmTag tag, rpmtd td, headerGetFlags flags)
| Retrieve tag value.
int | headerPut (Header h, rpmtd td, headerPutFlags flags)
| Add or append tag to header.
int | headerAddI18NString (Header h, rpmTag tag, const char *string, const char *lang)
| Add locale specific tag to header.
int | headerMod (Header h, rpmtd td)
| Modify tag in header.
int | headerDel (Header h, rpmTag tag)
| Delete tag in header.
char * | headerFormat (Header h, const char *fmt, errmsg_t *errmsg)
| Return formatted output string from header tags.
void | headerCopyTags (Header headerFrom, Header headerTo, const rpmTag *tagstocopy)
| Duplicate tag values from one header into another.
HeaderIterator | headerFreeIterator (HeaderIterator hi)
| Destroy header tag iterator.
HeaderIterator | headerInitIterator (Header h)
| Create header tag iterator.
int | headerNext (HeaderIterator hi, rpmtd td)
| Return next tag contents from header.
rpmTag | headerNextTag (HeaderIterator hi)
| Return next tag number from header.
int | headerNVR (Header h, const char **np, const char **vp, const char **rp)
| Return name, version, release strings from header.
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.
char * | headerGetNEVR (Header h, const char **np)
| Return (malloc'd) header name-version-release string.
char * | headerGetNEVRA (Header h, const char **np)
| Return (malloc'd) header name-version-release.arch string.
char * | headerGetAsString (Header h, rpmTag tag)
| Return any non-array tag from header, converted to string.
const char * | headerGetString (Header h, rpmTag tag)
| Return a simple string tag from header.
rpm_color_t | headerGetColor (Header h)
| Return header color.
int | headerIsSource (Header h)
| Check if header is a source or binary package header.
unsigned int | headerGetInstance (Header h)
| Return header instance, ie is the header from rpmdb.
int | headerConvert (Header h, headerConvOps op)
| Convert header to/from (legacy) data presentation.
void | headerMergeLegacySigs (Header h, const Header sigh)
| Translate and merge legacy signature tags into header.
Header | headerRegenSigHeader (const Header h, int noArchiveSize)
| Regenerate signature header.
## Variables
const unsigned char | rpm_header_magic [8]
| Header magic value.
int | headerPutString (Header h, rpmTag tag, const char *val)
| Type-safe methods for inserting tag data to header.
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)
## RPMRC
rpmRC | headerCheckPayloadFormat (Header h)
| Check for supported payload format in header.
rpmRC | headerCheck (rpmts ts, const void *uh, size_t uc, char **msg)
| Check header consistency, performing headerGetEntry() the hard way.
rpmRC | rpmReadHeader (rpmts ts, FD_t fd, Header *hdrp, char **msg)
| Return checked and loaded header.
rpmRC | rpmReadPackageFile (rpmts ts, FD_t fd, const char *fn, Header *hdrp)
| Return package header from file handle, verifying digests/signatures.

## Typedef Documentation

typedef enum headerGetFlags_e 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.

typedef enum rpmSubTagType_e rpmSubTagType

New rpm data types under consideration/development.

These data types may (or may not) be added to rpm at some point. In order to avoid incompatibility with legacy versions of rpm, these data (sub-)types are introduced into the header by overloading RPM_BIN_TYPE, with the binary value of the tag a 16 byte image of what should/will be in the header index, followed by per-tag private data.

typedef enum rpmTagReturnType_e rpmTagReturnType

* Identify how to return the header data type.

typedef enum rpmTagType_e rpmTagType

The basic types of data in tags from headers.

## Enumeration Type Documentation

enum 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.

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.

enum rpmSubTagType_e

New rpm data types under consideration/development.

These data types may (or may not) be added to rpm at some point. In order to avoid incompatibility with legacy versions of rpm, these data (sub-)types are introduced into the header by overloading RPM_BIN_TYPE, with the binary value of the tag a 16 byte image of what should/will be in the header index, followed by per-tag private data.

Enumerator:

  RPM_REGION_TYPE |
  RPM_BIN_ARRAY_TYPE | Todo: Implement, kinda like RPM_STRING_ARRAY_TYPE for known (but variable) length binary data.
  RPM_XREF_TYPE | Todo: Implement, intent is to to carry a (???,tagNum,valNum) cross reference to retrieve data from other tags.

Definition at line 362 of file rpmtag.h.

enum rpmTagReturnType_e

* Identify how to return the header data type.

Enumerator:

  RPM_ANY_RETURN_TYPE |
  RPM_SCALAR_RETURN_TYPE |
  RPM_ARRAY_RETURN_TYPE |
  RPM_MAPPING_RETURN_TYPE |
  RPM_MASK_RETURN_TYPE |

Definition at line 375 of file rpmtag.h.

enum rpmTagType_e

The basic types of data in tags from headers.

Definition at line 327 of file rpmtag.h.

## Function Documentation

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:

  | h | header
  | tag | tag
  | string | tag value
  | lang | locale

Returns:
  1 on success, 0 on failure

rpmRC headerCheck | ( | rpmts | ts,
|  | const void * | uh,
|  | size_t | uc,
|  | char ** | msg |
| ) |  |  |

Check header consistency, performing headerGetEntry() the hard way.

Sanity checks on the header are performed while looking for a header-only digest or signature to verify the blob. If found, the digest or signature is verified.

Parameters:

  | ts | transaction set
  | uh | unloaded header blob
  | uc | no. of bytes in blob (or 0 to disable)

Return values:

  | *msg | verification error message (or NULL)

Returns:
  RPMRC_OK on success

rpmRC headerCheckPayloadFormat | ( | Header | h | ) |

Check for supported payload format in header.

Parameters:

  | h | header to check

Returns:
  RPMRC_OK if supported, RPMRC_FAIL otherwise

int headerConvert | ( | Header | h,
|  | headerConvOps | op |
| ) |  |  |

Convert header to/from (legacy) data presentation.

Parameters:

  | h | header
  | op | operation

Returns:
  1 on success, 0 on failure

Header headerCopy | ( | Header | h | ) |

Duplicate a header.

Parameters:

  | h | header

Returns:
  new header instance

Header headerCopyLoad | ( | const void * | uh | ) |

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

Parameters:

  | uh | on-disk header blob (i.e. with offsets)

Returns:
  header

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

Duplicate tag values from one header into another.

Parameters:

  | headerFrom | source header
  | headerTo | destination header
  | tagstocopy | array of tags that are copied

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:

  | h | header
  | tag | tag

Returns:
  0 on success, 1 on failure (INCONSISTENT)

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:

  | h | header
  | fmt | format to use

Return values:

  | errmsg | error message (if any)

Returns:
  formatted output string (malloc'ed)

Header headerFree | ( | Header | h | ) |

Dereference a header instance.

Parameters:

  | h | header

Returns:
  NULL always

HeaderIterator headerFreeIterator | ( | HeaderIterator | hi | ) |

Destroy header tag iterator.

Parameters:

  | hi | header tag iterator

Returns:
  NULL always

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

Retrieve tag value.

Parameters:

  | h | header
  | tag | tag

Return values:

  | td | tag data container

Parameters:

  | flags | retrieval modifier flags

Returns:
  1 on success, 0 on failure

char* headerGetAsString | ( | Header | h,
|  | rpmTag | tag |
| ) |  |  |

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

Parameters:

  | h | header
  | tag | tag to retrieve

Returns:
  string pointer (malloced) or NULL on failure

rpm_color_t headerGetColor | ( | Header | h | ) |

Return header color.

Parameters:

  | h | header

Returns:
  header color

unsigned int headerGetInstance | ( | Header | h | ) |

Return header instance, ie is the header from rpmdb.

Parameters:

  | h | header

Returns:
  rpmdb record number or 0

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

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

Parameters:

  | h | header

Return values:

  | np | name tag value

Returns:
  name-version-release string

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

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

Parameters:

  | h | header

Return values:

  | np | name tag value

Returns:
  name-version-release string

const char* headerGetString | ( | Header | h,
|  | rpmTag | tag |
| ) |  |  |

Return a simple string tag from header.

Parameters:

  | h | header
  | tag | tag to retrieve

Returns:
  string pointer (to header memory) or NULL on failure

Referenced by main().

HeaderIterator headerInitIterator | ( | Header | h | ) |

Create header tag iterator.

Parameters:

  | h | header

Returns:
  header tag iterator

int headerIsEntry | ( | Header | h,
|  | rpmTag | tag |
| ) |  |  |

Check if tag is in header.

Parameters:

  | h | header
  | tag | tag

Returns:
  1 on success, 0 on failure

Referenced by checkSpec().

int headerIsSource | ( | Header | h | ) |

Check if header is a source or binary package header.

Parameters:

  | h | header

Returns:
  0 == binary, 1 == source

Header headerLink | ( | Header | h | ) |

Reference a header instance.

Parameters:

  | h | header

Returns:
  new header reference

Header headerLoad | ( | void * | uh | ) |

Convert header to in-memory representation.

Parameters:

  | uh | on-disk header blob (i.e. with offsets)

Returns:
  header

void headerMergeLegacySigs | ( | Header | h,
|  | const Header | sigh |
| ) |  |  |

Translate and merge legacy signature tags into header.

Todo:
  Remove headerSort() through headerInitIterator() modifies sig.

Parameters:

  | h | header
  | sigh | signature header

int headerMod | ( | Header | h,
|  | rpmtd | td |
| ) |  |  |

Modify tag in header.

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

Parameters:

  | h | header
  | td | tag data container

Returns:
  1 on success, 0 on failure

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:

  | h | header

Return values:

  | *np | name pointer (or NULL)
  | *ep | epoch pointer (or NULL)
  | *vp | version pointer (or NULL)
  | *rp | release pointer (or NULL)
  | *ap | arch pointer (or NULL)

Returns:
  0 always

Header headerNew | ( | void |  | ) |

Create new (empty) header instance.

Returns:
  header

int headerNext | ( | HeaderIterator | hi,
|  | rpmtd | td |
| ) |  |  |

Return next tag contents from header.

Parameters:

  | hi | header tag iterator

Return values:

  | td | tag data container

Returns:
  1 on success, 0 on failure

rpmTag headerNextTag | ( | HeaderIterator | hi | ) |

Return next tag number from header.

Parameters:

  | hi | header tag iterator

Returns:
  next tag, RPMTAG_NOT_FOUND to stop iteration

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

Return name, version, release strings from header.

Parameters:

  | h | header

Return values:

  | *np | name pointer (or NULL)
  | *vp | version pointer (or NULL)
  | *rp | release pointer (or NULL)

Returns:
  0 always

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

Add or append tag to header.

Parameters:

  | h | header
  | td | tag data container
  | flags | flags to control operation

Returns:
  1 on success, 0 on failure

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 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:

  | h | header
  | tag | tag to insert
  | val | pointer to value(s)
  | size | number of items in array (1 or larger)

Returns:
  1 on success, 0 on failure

int headerPutStringArray | ( | Header | h,
|  | rpmTag | tag,
|  | const char ** | 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 |
| ) |  |  |

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

Header headerRead | ( | FD_t | fd,
|  | enum hMagic | magicp |
| ) |  |  |

Read (and load) header from file handle.

Parameters:

  | fd | file handle
  | magicp | read (and verify) 8 bytes of (magic, 0)?

Returns:
  header (or NULL on error)

Header headerRegenSigHeader | ( | const Header | h,
|  | int | noArchiveSize |
| ) |  |  |

Regenerate signature header.

Todo:
  Remove headerSort() through headerInitIterator() modifies h.

Parameters:

  | h | header
  | noArchiveSize | don't copy archive size tag (pre rpm-4.1)

Returns:
  regenerated signature header

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:

  | h | header (with pointers)
  | tag | region tag

Returns:
  on-disk header (with offsets)

unsigned int headerSizeof | ( | Header | h,
|  | enum hMagic | magicp |
| ) |  |  |

Return size of on-disk header representation in bytes.

Parameters:

  | h | header
  | magicp | include size of 8 bytes for (magic, 0)?

Returns:
  size of on-disk header

void headerSort | ( | Header | h | ) |

Sort tags in header.

Parameters:

  | h | header

Header headerUnlink | ( | Header | h | ) |

Dereference a header instance.

Parameters:

  | h | header

Returns:
  new header reference

void* headerUnload | ( | Header | h | ) |

Convert header to on-disk representation.

Parameters:

  | h | header (with pointers)

Returns:
  on-disk header blob (i.e. with offsets)

void headerUnsort | ( | Header | h | ) |

Restore tags in header to original ordering.

Parameters:

  | h | header

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

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

Parameters:

  | il | no. of tags in header
  | dl | no. of bytes in header data.
  | pev | 1st element in tag array, big-endian
  | iv | failing (or last) tag element, host-endian
  | negate | negative offset expected?

Returns:
  -1 on success, otherwise failing tag element index

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

Write (with unload) header to file handle.

Parameters:

  | fd | file handle
  | h | header
  | magicp | prefix write with 8 bytes of (magic, 0)?

Returns:
  0 on success, 1 on error

rpmRC rpmReadHeader | ( | rpmts | ts,
|  | FD_t | fd,
|  | Header * | hdrp,
|  | char ** | msg |
| ) |  |  |

Return checked and loaded header.

Parameters:

  | ts | transaction set
  | fd | file handle

Return values:

  | hdrp | address of header (or NULL)
  | *msg | verification error message (or NULL)

Returns:
  RPMRC_OK on success

rpmRC rpmReadPackageFile | ( | rpmts | ts,
|  | FD_t | fd,
|  | const char * | fn,
|  | Header * | hdrp |
| ) |  |  |

Return package header from file handle, verifying digests/signatures.

Parameters:

  | ts | transaction set
  | fd | file handle
  | fn | file name

Return values:

  | hdrp | address of header (or NULL)

Returns:
  RPMRC_OK on success

Referenced by main().

## Variable Documentation

const unsigned char rpm_header_magic[8]

Header magic value.