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

Variables
RPM_PUBLIC_API const unsigned char	rpm_header_magic [8]
RPM_PUBLIC_API int	headerPutBin (Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutString (Header h, rpmTagVal tag, const char *val)
RPM_PUBLIC_API int	headerPutStringArray (Header h, rpmTagVal tag, const char **val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutChar (Header h, rpmTagVal tag, const char *val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutUint8 (Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutUint16 (Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutUint32 (Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size)
RPM_PUBLIC_API int	headerPutUint64 (Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size)

RPMRC
RPM_PUBLIC_API rpmRC	headerCheck (rpmts ts, const void uh, size_t uc, char *msg)
RPM_PUBLIC_API rpmRC	rpmReadHeader (rpmts ts, FD_t fd, Header hdrp, char *msg)
RPM_PUBLIC_API 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()

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

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

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

RPM_PUBLIC_API Header headerCopy ( Header h )

Duplicate a header.

Parameters

h header

Returns: new header instance

◆ headerCopyTags()

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

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

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

RPM_PUBLIC_API char * headerFormat	(	Header	h,
		const char *	fmt,
		errmsg_t *	errmsg )

Return output formatted according to given rpm-queryformat(7) string. 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()

RPM_PUBLIC_API Header headerFree ( Header h )

Dereference a header instance.

Parameters

h header

Returns: NULL always

◆ headerFreeIterator()

RPM_PUBLIC_API HeaderIterator headerFreeIterator ( HeaderIterator hi )

Destroy header tag iterator.

Parameters

hi	header tag iterator

Returns: NULL always

◆ headerGet()

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

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

RPM_PUBLIC_API unsigned int headerGetInstance ( Header h )

Return header instance, ie is the header from rpmdb.

Parameters

h header

Returns: rpmdb record number or 0

◆ headerGetNumber()

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

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

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

RPM_PUBLIC_API HeaderIterator headerInitIterator ( Header h )

Create header tag iterator.

Parameters

h header

Returns: header tag iterator

◆ headerIsEntry()

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

RPM_PUBLIC_API int headerIsSource ( Header h )

Check if header is a source or binary package header

Parameters

h header

Returns: 0 == binary, 1 == source

◆ headerLink()

RPM_PUBLIC_API Header headerLink ( Header h )

Reference a header instance.

Parameters

h header

Returns: new header reference

◆ headerMod()

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

RPM_PUBLIC_API Header headerNew ( void )

Create new (empty) header instance.

Returns: header

◆ headerNext()

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

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

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

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

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

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

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

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

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

RPM_PUBLIC_API 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

RPM_PUBLIC_API const unsigned char rpm_header_magic[8]

extern

Header magic value

Files

Enumerations

Functions

Variables

RPMRC

Detailed Description

Enumeration Type Documentation

◆ headerGetFlags_e

◆ hMagic

◆ rpmTagReturnType_e

◆ rpmTagType_e

Function Documentation

◆ headerAddI18NString()

◆ headerCheck()

◆ headerConvert()

◆ headerCopy()

◆ headerCopyTags()

◆ headerDel()

◆ headerExport()

◆ headerFormat()

◆ headerFree()

◆ headerFreeIterator()

◆ headerGet()

◆ headerGetAsString()

◆ headerGetInstance()

◆ headerGetNumber()

◆ headerGetString()

◆ headerImport()

◆ headerInitIterator()

◆ headerIsEntry()

◆ headerIsSource()

◆ headerLink()

◆ headerMod()

◆ headerNew()

◆ headerNext()

◆ headerNextTag()

◆ headerPut()

◆ headerPutBin()

◆ headerRead()

◆ headerReload()

◆ headerSizeof()

◆ headerWrite()

◆ rpmReadHeader()

◆ rpmReadPackageFile()

Variable Documentation

◆ rpm_header_magic