Header API.
Querying package headers: | I/O

How to manipulate package headers (which carries all information about a package). More...

Collaboration diagram for Header API.:

## Files

file | header.h
| An rpm header carries all information about a package.
file | rpmlib.h
| In Memoriam: Steve Taylor stayl.nosp@m.or@r.nosp@m.edhat.nosp@m..com was here, now he's not.

## Typedefs

typedef enum rpmTagType_e | rpmTagType
| The basic types of data in tags from headers. More...
typedef enum rpmSubTagType_e | rpmSubTagType
| New rpm data types under consideration/development. More...

## 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 { RPM_NULL_TYPE = 0, RPM_CHAR_TYPE = 1, RPM_INT8_TYPE = 2, RPM_INT16_TYPE = 3, RPM_INT32_TYPE = 4, RPM_INT64_TYPE = 5, RPM_STRING_TYPE = 6, RPM_BIN_TYPE = 7, RPM_STRING_ARRAY_TYPE = 8, RPM_I18NSTRING_TYPE = 9 }
| 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 }

## 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...
unsigned int | headerSizeof (Header h, int magicp)
| Return size of on-disk header representation in bytes. More...
void * | headerUnload (Header h)
| Convert header to on-disk representation. More...
void * | headerExport (Header h, unsigned int *bsize)
| Export header to on-disk representation. More...
Header | headerReload (Header h, rpmTagVal 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 | headerImport (void *blob, unsigned int bsize, headerImportFlags flags)
| Import header to in-memory representation. More...
Header | headerRead (FD_t fd, int magicp)
| Read (and load) header from file handle. More...
int | headerWrite (FD_t fd, Header h, int magicp)
| Write (with unload) header to file handle. More...
int | headerIsEntry (Header h, rpmTagVal tag)
| Check if tag is in header. More...
int | headerGet (Header h, rpmTagVal 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, rpmTagVal 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, rpmTagVal 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 rpmTagVal *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...
rpmTagVal | headerNextTag (HeaderIterator hi)
| Return next tag number from header. More...
char * | headerGetAsString (Header h, rpmTagVal tag)
| Return any non-array tag from header, converted to string. More...
const char * | headerGetString (Header h, rpmTagVal tag)
| Return a simple string tag from header. 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, int op)
| Convert header to/from (legacy) data presentation. More...

## Variables

const unsigned char | rpm_header_magic [8]
| Header magic value. More...
int | headerPutBin (Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size)
| Type-safe methods for inserting tag data to header. More...
int | headerPutString (Header h, rpmTagVal tag, const char *val)
int | headerPutStringArray (Header h, rpmTagVal tag, const char **val, rpm_count_t size)
int | headerPutChar (Header h, rpmTagVal tag, const char *val, rpm_count_t size)
int | headerPutUint8 (Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size)
int | headerPutUint16 (Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size)
int | headerPutUint32 (Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size)
int | headerPutUint64 (Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size)

## RPMRC

rpmRC | headerCheck (rpmts ts, const void *uh, size_t uc, char **msg)
| Check header consistency, performing headerGetEntry() the hard way. More...
rpmRC | rpmReadHeader (rpmts ts, FD_t fd, Header *hdrp, char **msg)
| Return checked and loaded header. More...
rpmRC | rpmReadPackageFile (rpmts ts, FD_t fd, const char *fn, Header *hdrp)
| Return package header from file handle, verifying digests/signatures. More...

## Detailed Description

How to manipulate package headers (which carries all information about a package).

/**

## Typedef Documentation

## rpmSubTagType

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.

## rpmTagType

typedef enum rpmTagType_e rpmTagType

The basic types of data in tags from headers.

## Enumeration Type Documentation

## headerGetFlags_e

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

## rpmSubTagType_e

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 466 of file rpmtag.h.

## rpmTagReturnType_e

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 479 of file rpmtag.h.

## rpmTagType_e

enum rpmTagType_e

The basic types of data in tags from headers.

Enumerator
RPM_NULL_TYPE |
RPM_CHAR_TYPE |
RPM_INT8_TYPE |
RPM_INT16_TYPE |
RPM_INT32_TYPE |
RPM_INT64_TYPE |
RPM_STRING_TYPE |
RPM_BIN_TYPE |
RPM_STRING_ARRAY_TYPE |
RPM_I18NSTRING_TYPE |

Definition at line 431 of file rpmtag.h.

## Function Documentation

## headerAddI18NString()

int headerAddI18NString | ( | Header | h,
|  | rpmTagVal | 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

## headerCheck()

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

## headerConvert()

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

Convert header to/from (legacy) data presentation.

Parameters

  h | header
  op | one of headerConvOps operations

Returns
  1 on success, 0 on failure

## headerCopy()

Header headerCopy | ( | Header | h | ) |

Duplicate a header.

Parameters

  h | header

Returns
  new header instance

## headerCopyLoad()

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

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

Deprecated:
  Use headerImport() instead

Parameters

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

Returns
  header

## headerCopyTags()

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

Duplicate tag values from one header into another.

Parameters

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

## headerDel()

int headerDel | ( | Header | h,
|  | rpmTagVal | 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)

## headerExport()

void* headerExport | ( | Header | h,
|  | unsigned int * | bsize
| ) |  |

Export header to on-disk representation.

Parameters

  h | header (with pointers)

Return values

  bsize | on-disk header blob size in bytes

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

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

  h | header
  fmt | format to use

Return values

  errmsg | error message (if any)

Returns
  formatted output string (malloc'ed)

## headerFree()

Header headerFree | ( | Header | h | ) |

Dereference a header instance.

Parameters

  h | header

Returns
  NULL always

## headerFreeIterator()

HeaderIterator headerFreeIterator | ( | HeaderIterator | hi | ) |

Destroy header tag iterator.

Parameters

  hi | header tag iterator

Returns
  NULL always

## headerGet()

int headerGet | ( | Header | h,
|  | rpmTagVal | 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

## headerGetAsString()

char* headerGetAsString | ( | Header | h,
|  | rpmTagVal | 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

## headerGetInstance()

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

Return header instance, ie is the header from rpmdb.

Parameters

  h | header

Returns
  rpmdb record number or 0

## headerGetString()

const char* headerGetString | ( | Header | h,
|  | rpmTagVal | 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

## headerImport()

Header headerImport | ( | void * | blob,
|  | unsigned int | bsize,
|  | headerImportFlags | flags
| ) |  |

Import header to in-memory representation.

Parameters

  blob | on-disk header blob (i.e. with offsets)
  bsize | on-disk header blob size in bytes (0 if unknown)
  flags | flags to control operation

Returns
  header

## headerInitIterator()

HeaderIterator headerInitIterator | ( | Header | h | ) |

Create header tag iterator.

Parameters

  h | header

Returns
  header tag iterator

## headerIsEntry()

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

Check if tag is in header.

Parameters

  h | header
  tag | tag

Returns
  1 on success, 0 on failure

## headerIsSource()

int headerIsSource | ( | Header | h | ) |

Check if header is a source or binary package header.

Parameters

  h | header

Returns
  0 == binary, 1 == source

## headerLink()

Header headerLink | ( | Header | h | ) |

Reference a header instance.

Parameters

  h | header

Returns
  new header reference

## headerLoad()

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

Convert header to in-memory representation.

Deprecated:
  Use headerImport() instead

Parameters

  uh | on-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

  h | header
  td | tag data container

Returns
  1 on success, 0 on failure

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

  hi | header tag iterator

Return values

  td | tag data container

Returns
  1 on success, 0 on failure

## headerNextTag()

rpmTagVal headerNextTag | ( | HeaderIterator | hi | ) |

Return next tag number from header.

Parameters

  hi | header tag iterator

Returns
  next tag, RPMTAG_NOT_FOUND to stop iteration

## headerPut()

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

## headerPutBin()

int headerPutBin | ( | Header | h,
|  | rpmTagVal | tag,
|  | const uint8_t * | val,
|  | rpm_count_t | size
| ) |  |

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

## headerPutChar()

int headerPutChar | ( | Header | h,
|  | rpmTagVal | tag,
|  | const char * | val,
|  | rpm_count_t | size
| ) |  |

## headerPutString()

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

## headerPutStringArray()

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

## headerPutUint16()

int headerPutUint16 | ( | Header | h,
|  | rpmTagVal | tag,
|  | const uint16_t * | val,
|  | rpm_count_t | size
| ) |  |

## headerPutUint32()

int headerPutUint32 | ( | Header | h,
|  | rpmTagVal | tag,
|  | const uint32_t * | val,
|  | rpm_count_t | size
| ) |  |

## headerPutUint64()

int headerPutUint64 | ( | Header | h,
|  | rpmTagVal | tag,
|  | const uint64_t * | val,
|  | rpm_count_t | size
| ) |  |

## headerPutUint8()

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

## headerRead()

Header headerRead | ( | FD_t | fd,
|  | int | 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)

## headerReload()

Header headerReload | ( | Header | h,
|  | rpmTagVal | 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)

## headerSizeof()

unsigned int headerSizeof | ( | Header | h,
|  | int | 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

## headerUnload()

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

Convert header to on-disk representation.

Deprecated:
  Use headerExport() instead

Parameters

  h | header (with pointers)

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

## headerWrite()

int headerWrite | ( | FD_t | fd,
|  | Header | h,
|  | int | 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

## rpmReadHeader()

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

Return checked and loaded header.

Parameters

  ts | unused
  fd | file handle

Return values

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

Returns
  RPMRC_OK on success

## rpmReadPackageFile()

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

## Variable Documentation

## rpm_header_magic

const unsigned char rpm_header_magic[8]

Header magic value.