lib/header.h

   1 #ifndef H_HEADER
   2 #define H_HEADER
   3
   4 /** \ingroup header
   5  * \file lib/header.h
   6  *
   7  * An rpm header carries all information about a package. A header is
   8  * a collection of data elements called tags. Each tag has a data type,
   9  * and includes 1 or more values.
  10  *
  11  */
  12
  13 /* RPM - Copyright (C) 1995-2001 Red Hat Software */
  14
  15 #include <rpm/rpmio.h>
  16 #include <rpm/rpmtypes.h>
  17 #include <rpm/rpmtd.h>
  18 #include <rpm/rpmutil.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /** \ingroup header
  25  * Header magic value
  26  */
  27 extern const unsigned char rpm_header_magic[8];
  28
  29 /** \ingroup header
  30  * Include calculation for 8 bytes of (magic, 0)?
  31  */
  32 enum hMagic {
  33     HEADER_MAGIC_NO             = 0,
  34     HEADER_MAGIC_YES            = 1
  35 };
  36
  37 /** \ingroup header
  38  * Create new (empty) header instance.
  39  * @return              header
  40  */
  41 Header headerNew(void);
  42
  43 /** \ingroup header
  44  * Dereference a header instance.
  45  * @param h             header
  46  * @return              NULL always
  47  */
  48 Header headerFree( Header h);
  49
  50 /** \ingroup header
  51  * Reference a header instance.
  52  * @param h             header
  53  * @return              new header reference
  54  */
  55 Header headerLink(Header h);
  56
  57 /** \ingroup header
  58  * Return size of on-disk header representation in bytes.
  59  * @param h             header
  60  * @param magicp        include size of 8 bytes for (magic, 0)?
  61  * @return              size of on-disk header
  62  */
  63 unsigned int headerSizeof(Header h, int magicp);
  64
  65 /** \ingroup header
  66  * Convert header to on-disk representation.
  67  * @deprecated          Use headerExport() instead
  68  * @param h             header (with pointers)
  69  * @return              on-disk header blob (i.e. with offsets)
  70  */
  71 void * headerUnload(Header h);
  72
  73 /** \ingroup header
  74  * Export header to on-disk representation.
  75  * @param h             header (with pointers)
  76  * @retval bsize        on-disk header blob size in bytes
  77  * @return              on-disk header blob (i.e. with offsets)
  78  */
  79 void * headerExport(Header h, unsigned int * bsize);
  80
  81 /** \ingroup header
  82  * Convert header to on-disk representation, and then reload.
  83  * This is used to insure that all header data is in one chunk.
  84  * @param h             header (with pointers)
  85  * @param tag           region tag
  86  * @return              on-disk header (with offsets)
  87  */
  88 Header headerReload(Header h, rpmTagVal tag);
  89
  90 /** \ingroup header
  91  * Duplicate a header.
  92  * @param h             header
  93  * @return              new header instance
  94  */
  95 Header headerCopy(Header h);
  96
  97 /** \ingroup header
  98  * Convert header to in-memory representation.
  99  * @deprecated          Use headerImport() instead
 100  * @param uh            on-disk header blob (i.e. with offsets)
 101  * @return              header
 102  */
 103 Header headerLoad(void * uh);
 104
 105 /** \ingroup header
 106  * Make a copy and convert header to in-memory representation.
 107  * @deprecated          Use headerImport() instead
 108  * @param uh            on-disk header blob (i.e. with offsets)
 109  * @return              header
 110  */
 111 Header headerCopyLoad(const void * uh);
 112
 113 enum headerImportFlags_e {
 114     HEADERIMPORT_COPY           = (1 << 0), /* Make copy of blob on import? */
 115     HEADERIMPORT_FAST           = (1 << 1), /* Faster but less safe? */
 116 };
 117
 118 typedef rpmFlags headerImportFlags;
 119
 120 /** \ingroup header
 121  * Import header to in-memory representation.
 122  * @param blob          on-disk header blob (i.e. with offsets)
 123  * @param bsize         on-disk header blob size in bytes (0 if unknown)
 124  * @param flags         flags to control operation
 125  * @return              header
 126  */
 127 Header headerImport(void *blob, unsigned int bsize, headerImportFlags flags);
 128
 129 /** \ingroup header
 130  * Read (and load) header from file handle.
 131  * @param fd            file handle
 132  * @param magicp        read (and verify) 8 bytes of (magic, 0)?
 133  * @return              header (or NULL on error)
 134  */
 135 Header headerRead(FD_t fd, int magicp);
 136
 137 /** \ingroup header
 138  * Write (with unload) header to file handle.
 139  * @param fd            file handle
 140  * @param h             header
 141  * @param magicp        prefix write with 8 bytes of (magic, 0)?
 142  * @return              0 on success, 1 on error
 143  */
 144 int headerWrite(FD_t fd, Header h, int magicp);
 145
 146 /** \ingroup header
 147  * Check if tag is in header.
 148  * @param h             header
 149  * @param tag           tag
 150  * @return              1 on success, 0 on failure
 151  */
 152 int headerIsEntry(Header h, rpmTagVal tag);
 153
 154 /** \ingroup header
 155  * Modifier flags for headerGet() operation.
 156  * For consistent behavior you'll probably want to use ALLOC to ensure
 157  * the caller owns the data, but MINMEM is useful for avoiding extra
 158  * copy of data when you are sure the header wont go away.
 159  * Most of the time you'll probably want EXT too, but note that extensions
 160  * tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV
 161  * are only relevant for non-extension data.
 162  */
 163 enum headerGetFlags_e {
 164     HEADERGET_DEFAULT   = 0,        /* legacy headerGetEntry() behavior */
 165     HEADERGET_MINMEM    = (1 << 0), /* pointers can refer to header memory */
 166     HEADERGET_EXT       = (1 << 1), /* lookup extension types too */
 167     HEADERGET_RAW       = (1 << 2), /* return raw contents (no i18n lookups) */
 168     HEADERGET_ALLOC     = (1 << 3), /* always allocate memory for all data */
 169     HEADERGET_ARGV      = (1 << 4), /* return string arrays NULL-terminated */
 170 };
 171
 172 typedef rpmFlags headerGetFlags;
 173
 174 /** \ingroup header
 175  * Retrieve tag value.
 176  * @param h             header
 177  * @param tag           tag
 178  * @retval td           tag data container
 179  * @param flags         retrieval modifier flags
 180  * @return              1 on success, 0 on failure
 181  */
 182 int headerGet(Header h, rpmTagVal tag, rpmtd td, headerGetFlags flags);
 183
 184
 185 enum headerPutFlags_e {
 186     HEADERPUT_DEFAULT   = 0,
 187     HEADERPUT_APPEND    = (1 << 0),
 188 };
 189
 190 typedef rpmFlags headerPutFlags;
 191
 192 /** \ingroup header
 193  * Add or append tag to header.
 194  *
 195  * @param h             header
 196  * @param td            tag data container
 197  * @param flags         flags to control operation
 198  * @return              1 on success, 0 on failure
 199  */
 200 int headerPut(Header h, rpmtd td, headerPutFlags flags);
 201
 202 /** \ingroup header
 203  * @{
 204  * Type-safe methods for inserting tag data to header.
 205  * Tag data type is validated to match the function type, ie things like
 206  * headerPutUint32(h, RPMTAG_NAME, ...) will return failure. For non-array
 207  * types size must equal 1, and data is checked to be non-NULL. For array
 208  * types, add-or-append mode is always used.
 209  *
 210  * headerPutString() can be used on both RPM_STRING_TYPE and
 211  * RPM_STRING_ARRAY_TYPE (to add a single string into the array) tags,
 212  * for others the type must match exactly.
 213  *
 214  * These are intended to "do the right thing" in the common case, if you
 215  * need more fine grained control use headerPut() & friends instead.
 216  * @todo                Make doxygen group these meaningfully.
 217  *
 218  * @param h             header
 219  * @param tag           tag to insert
 220  * @param val           pointer to value(s)
 221  * @param size          number of items in array (1 or larger)
 222  * @return              1 on success, 0 on failure
 223  *
 224  */
 225 int headerPutBin(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
 226 int headerPutString(Header h, rpmTagVal tag, const char *val);
 227 int headerPutStringArray(Header h, rpmTagVal tag, const char **val, rpm_count_t size);
 228 int headerPutChar(Header h, rpmTagVal tag, const char *val, rpm_count_t size);
 229 int headerPutUint8(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
 230 int headerPutUint16(Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size);
 231 int headerPutUint32(Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size);
 232 int headerPutUint64(Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size);
 233 /** @} */
 234
 235 /** \ingroup header
 236  * Add locale specific tag to header.
 237  * A NULL lang is interpreted as the C locale. Here are the rules:
 238  * \verbatim
 239  *      - If the tag isn't in the header, it's added with the passed string
 240  *         as new value.
 241  *      - If the tag occurs multiple times in entry, which tag is affected
 242  *         by the operation is undefined.
 243  *      - If the tag is in the header w/ this language, the entry is
 244  *         *replaced* (like headerMod()).
 245  * \endverbatim
 246  * This function is intended to just "do the right thing". If you need
 247  * more fine grained control use headerPut() and headerMod().
 248  *
 249  * @param h             header
 250  * @param tag           tag
 251  * @param string        tag value
 252  * @param lang          locale
 253  * @return              1 on success, 0 on failure
 254  */
 255 int headerAddI18NString(Header h, rpmTagVal tag, const char * string,
 256                 const char * lang);
 257
 258 /** \ingroup header
 259  * Modify tag in header.
 260  * If there are multiple entries with this tag, the first one gets replaced.
 261  * @param h             header
 262  * @param td            tag data container
 263  * @return              1 on success, 0 on failure
 264  */
 265 int headerMod(Header h, rpmtd td);
 266
 267 /** \ingroup header
 268  * Delete tag in header.
 269  * Removes all entries of type tag from the header, returns 1 if none were
 270  * found.
 271  *
 272  * @param h             header
 273  * @param tag           tag
 274  * @return              0 on success, 1 on failure (INCONSISTENT)
 275  */
 276 int headerDel(Header h, rpmTagVal tag);
 277
 278 /** \ingroup header
 279  * Return formatted output string from header tags.
 280  * The returned string must be free()d.
 281  *
 282  * @param h             header
 283  * @param fmt           format to use
 284  * @retval errmsg       error message (if any)
 285  * @return              formatted output string (malloc'ed)
 286  */
 287 char * headerFormat(Header h, const char * fmt, errmsg_t * errmsg);
 288
 289 /** \ingroup header
 290  * Duplicate tag values from one header into another.
 291  * @param headerFrom    source header
 292  * @param headerTo      destination header
 293  * @param tagstocopy    array of tags that are copied
 294  */
 295 void headerCopyTags(Header headerFrom, Header headerTo,
 296                     const rpmTagVal * tagstocopy);
 297
 298 /** \ingroup header
 299  * Destroy header tag iterator.
 300  * @param hi            header tag iterator
 301  * @return              NULL always
 302  */
 303 HeaderIterator headerFreeIterator(HeaderIterator hi);
 304
 305 /** \ingroup header
 306  * Create header tag iterator.
 307  * @param h             header
 308  * @return              header tag iterator
 309  */
 310 HeaderIterator headerInitIterator(Header h);
 311
 312 /** \ingroup header
 313  * Return next tag contents from header.
 314  * @param hi            header tag iterator
 315  * @retval td           tag data container
 316  * @return              1 on success, 0 on failure
 317  */
 318 int headerNext(HeaderIterator hi, rpmtd td);
 319
 320 /** \ingroup header
 321  * Return next tag number from header.
 322  * @param hi            header tag iterator
 323  * @return              next tag, RPMTAG_NOT_FOUND to stop iteration
 324  */
 325 rpmTagVal headerNextTag(HeaderIterator hi);
 326
 327 /** \ingroup header
 328  * Return any non-array tag from header, converted to string
 329  * @param h             header
 330  * @param tag           tag to retrieve
 331  * @return              string pointer (malloced) or NULL on failure
 332  */
 333 char * headerGetAsString(Header h, rpmTagVal tag);
 334
 335 /** \ingroup header
 336  * Return a simple string tag from header
 337  * @param h             header
 338  * @param tag           tag to retrieve
 339  * @return              string pointer (to header memory) or NULL on failure
 340  */
 341 const char * headerGetString(Header h, rpmTagVal tag);
 342
 343 /* \ingroup header
 344  * Return a simple number tag (or extension) from header
 345  * @param h             header
 346  * @param tag           tag to retrieve
 347  * @return              numeric tag value or 0 on failure
 348  */
 349 uint64_t headerGetNumber(Header h, rpmTagVal tag);
 350
 351 /** \ingroup header
 352  * Check if header is a source or binary package header
 353  * @param h             header
 354  * @return              0 == binary, 1 == source
 355  */
 356 int headerIsSource(Header h);
 357
 358 /** \ingroup header
 359  * Return header instance, ie is the header from rpmdb.
 360  * @param h             header
 361  * @return              rpmdb record number or 0
 362  */
 363 unsigned int headerGetInstance(Header h);
 364
 365 typedef enum headerConvOps_e {
 366     HEADERCONV_EXPANDFILELIST   = 0,
 367     HEADERCONV_COMPRESSFILELIST = 1,
 368     HEADERCONV_RETROFIT_V3      = 2,
 369 } headerConvOps;
 370
 371 /** \ingroup header
 372  * Convert header to/from (legacy) data presentation
 373  * @param h             header
 374  * @param op            one of headerConvOps operations
 375  * @return              1 on success, 0 on failure
 376  */
 377 int headerConvert(Header h, int op);
 378
 379 #ifdef __cplusplus
 380 }
 381 #endif
 382
 383 #endif  /* H_HEADER */