rpm: Header API.

rpm 4.20.1 The RPM Package Manager

Loading...
Searching...
No Matches
Files | Enumerations | Functions | Variables
Header API.
Querying package headers:

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

Collaboration diagram for Header API.:

## Files
file | header.h
file | rpmlib.h

## Enumerations
enum | hMagic { HEADER_MAGIC_NO = 0 , HEADER_MAGIC_YES = 1 }
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) }
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 }
enum | rpmTagReturnType_e { RPM_ANY_RETURN_TYPE = 0 , RPM_SCALAR_RETURN_TYPE = 0x00010000 , RPM_ARRAY_RETURN_TYPE = 0x00020000 , RPM_MAPPING_RETURN_TYPE }

## Functions
Header | headerNew (void)
Header | headerFree (Header h)
Header | headerLink (Header h)
unsigned int | headerSizeof (Header h, int magicp)
void * | headerExport (Header h, unsigned int *bsize)
Header | headerReload (Header h, rpmTagVal tag)
Header | headerCopy (Header h)
Header | headerImport (void *blob, unsigned int bsize, headerImportFlags flags)
Header | headerRead (FD_t fd, int magicp)
int | headerWrite (FD_t fd, Header h, int magicp)
int | headerIsEntry (Header h, rpmTagVal tag)
int | headerGet (Header h, rpmTagVal tag, rpmtd td, headerGetFlags flags)
int | headerPut (Header h, rpmtd td, headerPutFlags flags)
int | headerAddI18NString (Header h, rpmTagVal tag, const char *string, const char *lang)
int | headerMod (Header h, rpmtd td)
int | headerDel (Header h, rpmTagVal tag)
char * | headerFormat (Header h, const char *fmt, errmsg_t *errmsg)
void | headerCopyTags (Header headerFrom, Header headerTo, const rpmTagVal *tagstocopy)
HeaderIterator | headerFreeIterator (HeaderIterator hi)
HeaderIterator | headerInitIterator (Header h)
int | headerNext (HeaderIterator hi, rpmtd td)
rpmTagVal | headerNextTag (HeaderIterator hi)
char * | headerGetAsString (Header h, rpmTagVal tag)
const char * | headerGetString (Header h, rpmTagVal tag)
uint64_t | headerGetNumber (Header h, rpmTagVal tag)
int | headerIsSource (Header h)
unsigned int | headerGetInstance (Header h)
int | headerConvert (Header h, int op)

## Variables
const unsigned char | rpm_header_magic [8]
int | headerPutBin (Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size)
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)
rpmRC | rpmReadHeader (rpmts ts, FD_t fd, Header *hdrp, char **msg)
rpmRC | rpmReadPackageFile (rpmts ts, FD_t fd, const char *fn, Header *hdrp)

## Detailed Description

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

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

## ◆ hMagic

enum hMagic

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

## ◆ rpmTagReturnType_e

enum rpmTagReturnType_e

- Identify how to return the header data type.

## ◆ rpmTagType_e

enum rpmTagType_e

The basic types of data in tags from headers.

## 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)
  [out] | *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

## ◆ 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)
  [out] | 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
  [out] | 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
  [out] | td | tag data container
  | 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

## ◆ headerGetNumber()

uint64_t headerGetNumber | ( | Header | h,
|  | rpmTagVal | tag )

Return a simple number tag (or extension) from header

Parameters

  h | header
  tag | tag to retrieve

Returns
  numeric tag value or 0 on failure

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

## ◆ 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
  [out] | 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

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

## ◆ 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
  [out] | hdrp | address of header (or NULL)
  [out] | *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
  [out] | hdrp | address of header (or NULL)

Returns
  RPMRC_OK on success

## Variable Documentation

## ◆ rpm_header_magic

const unsigned char rpm_header_magic[8]
| extern

Header magic value