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 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	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, RPM_MASK_TYPE }
	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 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.
rpm_color_t	headerGetColor (Header h)
	Return header color.
int	headerIsSource (Header h)
	Check if header is a source or binary package header.
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.

---

Typedef Documentation

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 hMagic

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

Enumerator:

HEADER_MAGIC_NO
HEADER_MAGIC_YES

Definition at line 27 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 350 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 363 of file rpmtag.h.

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
RPM_MASK_TYPE

Definition at line 315 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

Referenced by main().

rpm_color_t headerGetColor

(

Header

h

)

Return header color.

Parameters:

h

header

Returns:

header color

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

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 from header.

Parameters:

hi

header tag iterator

Return values:

td

tag data container

Returns:

1 on success, 0 on failure

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().