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 headerGetFlags_e headerGetFlags
 Modifier flags for headerGet() operation.
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  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
 

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 contents from header.
rpmTag headerNextTag (HeaderIterator hi)
 Return next tag number 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.
char * headerGetAsString (Header h, rpmTag tag)
 Return any non-array tag from header, converted to string.
const char * headerGetString (Header h, rpmTag tag)
 Return a simple string tag from header.
rpm_color_t headerGetColor (Header h)
 Return header color.
int headerIsSource (Header h)
 Check if header is a source or binary package header.
unsigned int headerGetInstance (Header h)
 Return header instance, ie is the header from rpmdb.
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.

Variables

const unsigned char rpm_header_magic [8]
 Header magic value.



int headerPutString (Header h, rpmTag tag, const char *val)
 Type-safe methods for inserting tag data to header.
int headerPutStringArray (Header h, rpmTag tag, const char **val, rpm_count_t size)
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 headerPutUint8 (Header h, rpmTag tag, uint8_t *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)

RPMRC



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

Typedef Documentation

typedef enum headerGetFlags_e headerGetFlags

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.

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 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 166 of file header.h.

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.

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

enum rpmTagType_e

The basic types of data in tags from headers.

Definition at line 327 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
char* headerGetAsString ( Header  h,
rpmTag  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
rpm_color_t headerGetColor ( Header  h  ) 

Return header color.

Parameters:
h header
Returns:
header color
unsigned int headerGetInstance ( Header  h  ) 

Return header instance, ie is the header from rpmdb.

Parameters:
h header
Returns:
rpmdb record number or 0
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
const char* headerGetString ( Header  h,
rpmTag  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

Referenced by main().

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

Parameters:
hi header tag iterator
Return values:
td tag data container
Returns:
1 on success, 0 on failure
rpmTag headerNextTag ( HeaderIterator  hi  ) 

Return next tag number from header.

Parameters:
hi header tag iterator
Returns:
next tag, RPMTAG_NOT_FOUND to stop iteration
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().

Variable Documentation

const unsigned char rpm_header_magic[8]

Header magic value.

Generated on 8 Jan 2010 for rpm by  doxygen 1.6.1