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.

Files

Typedefs

Enumerations

Functions

Variables

RPMRC

Detailed Description

Typedef Documentation

◆ rpmSubTagType

◆ rpmTagType

Enumeration Type Documentation

◆ headerGetFlags_e

◆ hMagic

◆ rpmSubTagType_e

◆ rpmTagReturnType_e

◆ rpmTagType_e

Function Documentation

◆ headerAddI18NString()

◆ headerCheck()

◆ headerConvert()

◆ headerCopy()

◆ headerCopyLoad()

◆ headerCopyTags()

◆ headerDel()

◆ headerExport()

◆ headerFormat()

◆ headerFree()

◆ headerFreeIterator()

◆ headerGet()

◆ headerGetAsString()

◆ headerGetInstance()

◆ headerGetString()

◆ headerImport()

◆ headerInitIterator()

◆ headerIsEntry()

◆ headerIsSource()

◆ headerLink()

◆ headerLoad()

◆ headerMod()

◆ headerNew()

◆ headerNext()

◆ headerNextTag()

◆ headerPut()

◆ headerPutBin()

◆ headerPutChar()

◆ headerPutString()

◆ headerPutStringArray()

◆ headerPutUint16()

◆ headerPutUint32()

◆ headerPutUint64()

◆ headerPutUint8()

◆ headerRead()

◆ headerReload()

◆ headerSizeof()

◆ headerUnload()

◆ headerWrite()

◆ rpmReadHeader()

◆ rpmReadPackageFile()

Variable Documentation

◆ rpm_header_magic