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  * Sort tags in header.
  59  * @param h             header
  60  */
  61 void headerSort(Header h);
  62
  63 /** \ingroup header
  64  * Restore tags in header to original ordering.
  65  * @param h             header
  66  */
  67 void headerUnsort(Header h);
  68
  69 /** \ingroup header
  70  * Return size of on-disk header representation in bytes.
  71  * @param h             header
  72  * @param magicp        include size of 8 bytes for (magic, 0)?
  73  * @return              size of on-disk header
  74  */
  75 unsigned int headerSizeof(Header h, int magicp);
  76
  77 /** \ingroup header
  78  * Perform simple sanity and range checks on header tag(s).
  79  * @param il            no. of tags in header
  80  * @param dl            no. of bytes in header data.
  81  * @param pev           1st element in tag array, big-endian
  82  * @param iv            failing (or last) tag element, host-endian
  83  * @param negate        negative offset expected?
  84  * @return              -1 on success, otherwise failing tag element index
  85  */
  86 int headerVerifyInfo(int il, int dl, const void * pev, void * iv, int negate);
  87
  88 /** \ingroup header
  89  * Convert header to on-disk representation.
  90  * @deprecated          Use headerExport() instead
  91  * @param h             header (with pointers)
  92  * @return              on-disk header blob (i.e. with offsets)
  93  */
  94 void * headerUnload(Header h);
  95
  96 /** \ingroup header
  97  * Export header to on-disk representation.
  98  * @param h             header (with pointers)
  99  * @retval bsize        on-disk header blob size in bytes
 100  * @return              on-disk header blob (i.e. with offsets)
 101  */
 102 void * headerExport(Header h, unsigned int * bsize);
 103
 104 /** \ingroup header
 105  * Convert header to on-disk representation, and then reload.
 106  * This is used to insure that all header data is in one chunk.
 107  * @param h             header (with pointers)
 108  * @param tag           region tag
 109  * @return              on-disk header (with offsets)
 110  */
 111 Header headerReload(Header h, rpmTagVal tag);
 112
 113 /** \ingroup header
 114  * Duplicate a header.
 115  * @param h             header
 116  * @return              new header instance
 117  */
 118 Header headerCopy(Header h);
 119
 120 /** \ingroup header
 121  * Convert header to in-memory representation.
 122  * @deprecated          Use headerImport() instead
 123  * @param uh            on-disk header blob (i.e. with offsets)
 124  * @return              header
 125  */
 126 Header headerLoad(void * uh);
 127
 128 /** \ingroup header
 129  * Make a copy and convert header to in-memory representation.
 130  * @deprecated          Use headerImport() instead
 131  * @param uh            on-disk header blob (i.e. with offsets)
 132  * @return              header
 133  */
 134 Header headerCopyLoad(const void * uh);
 135
 136 enum headerImportFlags_e {
 137     HEADERIMPORT_COPY           = (1 << 0), /* Make copy of blob on import? */
 138     HEADERIMPORT_FAST           = (1 << 1), /* Faster but less safe? */
 139 };
 140
 141 typedef rpmFlags headerImportFlags;
 142
 143 /** \ingroup header
 144  * Import header to in-memory representation.
 145  * @param blob          on-disk header blob (i.e. with offsets)
 146  * @param bsize         on-disk header blob size in bytes (0 if unknown)
 147  * @param flags         flags to control operation
 148  * @return              header
 149  */
 150 Header headerImport(void *blob, unsigned int bsize, headerImportFlags flags);
 151
 152 /** \ingroup header
 153  * Read (and load) header from file handle.
 154  * @param fd            file handle
 155  * @param magicp        read (and verify) 8 bytes of (magic, 0)?
 156  * @return              header (or NULL on error)
 157  */
 158 Header headerRead(FD_t fd, int magicp);
 159
 160 /** \ingroup header
 161  * Write (with unload) header to file handle.
 162  * @param fd            file handle
 163  * @param h             header
 164  * @param magicp        prefix write with 8 bytes of (magic, 0)?
 165  * @return              0 on success, 1 on error
 166  */
 167 int headerWrite(FD_t fd, Header h, int magicp);
 168
 169 /** \ingroup header
 170  * Check if tag is in header.
 171  * @param h             header
 172  * @param tag           tag
 173  * @return              1 on success, 0 on failure
 174  */
 175 int headerIsEntry(Header h, rpmTagVal tag);
 176
 177 /** \ingroup header
 178  * Modifier flags for headerGet() operation.
 179  * For consistent behavior you'll probably want to use ALLOC to ensure
 180  * the caller owns the data, but MINMEM is useful for avoiding extra
 181  * copy of data when you are sure the header wont go away.
 182  * Most of the time you'll probably want EXT too, but note that extensions
 183  * tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV
 184  * are only relevant for non-extension data.
 185  */
 186 enum headerGetFlags_e {
 187     HEADERGET_DEFAULT   = 0,        /* legacy headerGetEntry() behavior */
 188     HEADERGET_MINMEM    = (1 << 0), /* pointers can refer to header memory */
 189     HEADERGET_EXT       = (1 << 1), /* lookup extension types too */
 190     HEADERGET_RAW       = (1 << 2), /* return raw contents (no i18n lookups) */
 191     HEADERGET_ALLOC     = (1 << 3), /* always allocate memory for all data */
 192     HEADERGET_ARGV      = (1 << 4), /* return string arrays NULL-terminated */
 193 };
 194
 195 typedef rpmFlags headerGetFlags;
 196
 197 /** \ingroup header
 198  * Retrieve tag value.
 199  * @param h             header
 200  * @param tag           tag
 201  * @retval td           tag data container
 202  * @param flags         retrieval modifier flags
 203  * @return              1 on success, 0 on failure
 204  */
 205 int headerGet(Header h, rpmTagVal tag, rpmtd td, headerGetFlags flags);
 206
 207
 208 enum headerPutFlags_e {
 209     HEADERPUT_DEFAULT   = 0,
 210     HEADERPUT_APPEND    = (1 << 0),
 211 };
 212
 213 typedef rpmFlags headerPutFlags;
 214
 215 /** \ingroup header
 216  * Add or append tag to header.
 217  *
 218  * @param h             header
 219  * @param td            tag data container
 220  * @param flags         flags to control operation
 221  * @return              1 on success, 0 on failure
 222  */
 223 int headerPut(Header h, rpmtd td, headerPutFlags flags);
 224
 225 /** \ingroup header
 226  * @{
 227  * Type-safe methods for inserting tag data to header.
 228  * Tag data type is validated to match the function type, ie things like
 229  * headerPutUint32(h, RPMTAG_NAME, ...) will return failure. For non-array
 230  * types size must equal 1, and data is checked to be non-NULL. For array
 231  * types, add-or-append mode is always used.
 232  *
 233  * headerPutString() can be used on both RPM_STRING_TYPE and
 234  * RPM_STRING_ARRAY_TYPE (to add a single string into the array) tags,
 235  * for others the type must match exactly.
 236  *
 237  * These are intended to "do the right thing" in the common case, if you
 238  * need more fine grained control use headerPut() & friends instead.
 239  * @todo                Make doxygen group these meaningfully.
 240  *
 241  * @param h             header
 242  * @param tag           tag to insert
 243  * @param val           pointer to value(s)
 244  * @param size          number of items in array (1 or larger)
 245  * @return              1 on success, 0 on failure
 246  *
 247  */
 248 int headerPutString(Header h, rpmTagVal tag, const char *val);
 249 int headerPutStringArray(Header h, rpmTagVal tag, const char **val, rpm_count_t size);
 250 int headerPutBin(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
 251 int headerPutChar(Header h, rpmTagVal tag, const char *val, rpm_count_t size);
 252 int headerPutUint8(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
 253 int headerPutUint16(Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size);
 254 int headerPutUint32(Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size);
 255 int headerPutUint64(Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size);
 256 /** @} */
 257
 258 /** \ingroup header
 259  * Add locale specific tag to header.
 260  * A NULL lang is interpreted as the C locale. Here are the rules:
 261  * \verbatim
 262  *      - If the tag isn't in the header, it's added with the passed string
 263  *         as new value.
 264  *      - If the tag occurs multiple times in entry, which tag is affected
 265  *         by the operation is undefined.
 266  *      - If the tag is in the header w/ this language, the entry is
 267  *         *replaced* (like headerMod()).
 268  * \endverbatim
 269  * This function is intended to just "do the right thing". If you need
 270  * more fine grained control use headerPut() and headerMod().
 271  *
 272  * @param h             header
 273  * @param tag           tag
 274  * @param string        tag value
 275  * @param lang          locale
 276  * @return              1 on success, 0 on failure
 277  */
 278 int headerAddI18NString(Header h, rpmTagVal tag, const char * string,
 279                 const char * lang);
 280
 281 /** \ingroup header
 282  * Modify tag in header.
 283  * If there are multiple entries with this tag, the first one gets replaced.
 284  * @param h             header
 285  * @param td            tag data container
 286  * @return              1 on success, 0 on failure
 287  */
 288 int headerMod(Header h, rpmtd td);
 289
 290 /** \ingroup header
 291  * Delete tag in header.
 292  * Removes all entries of type tag from the header, returns 1 if none were
 293  * found.
 294  *
 295  * @param h             header
 296  * @param tag           tag
 297  * @return              0 on success, 1 on failure (INCONSISTENT)
 298  */
 299 int headerDel(Header h, rpmTagVal tag);
 300
 301 /** \ingroup header
 302  * Return formatted output string from header tags.
 303  * The returned string must be free()d.
 304  *
 305  * @param h             header
 306  * @param fmt           format to use
 307  * @retval errmsg       error message (if any)
 308  * @return              formatted output string (malloc'ed)
 309  */
 310 char * headerFormat(Header h, const char * fmt, errmsg_t * errmsg);
 311
 312 /** \ingroup header
 313  * Duplicate tag values from one header into another.
 314  * @param headerFrom    source header
 315  * @param headerTo      destination header
 316  * @param tagstocopy    array of tags that are copied
 317  */
 318 void headerCopyTags(Header headerFrom, Header headerTo,
 319                     const rpmTagVal * tagstocopy);
 320
 321 /** \ingroup header
 322  * Destroy header tag iterator.
 323  * @param hi            header tag iterator
 324  * @return              NULL always
 325  */
 326 HeaderIterator headerFreeIterator(HeaderIterator hi);
 327
 328 /** \ingroup header
 329  * Create header tag iterator.
 330  * @param h             header
 331  * @return              header tag iterator
 332  */
 333 HeaderIterator headerInitIterator(Header h);
 334
 335 /** \ingroup header
 336  * Return next tag contents from header.
 337  * @param hi            header tag iterator
 338  * @retval td           tag data container
 339  * @return              1 on success, 0 on failure
 340  */
 341 int headerNext(HeaderIterator hi, rpmtd td);
 342
 343 /** \ingroup header
 344  * Return next tag number from header.
 345  * @param hi            header tag iterator
 346  * @return              next tag, RPMTAG_NOT_FOUND to stop iteration
 347  */
 348 rpmTagVal headerNextTag(HeaderIterator hi);
 349
 350 /** \ingroup header
 351  * Return name, version, release strings from header.
 352  * @param h             header
 353  * @retval *np          name pointer (or NULL)
 354  * @retval *vp          version pointer (or NULL)
 355  * @retval *rp          release pointer (or NULL)
 356  * @return              0 always
 357  */
 358 RPM_GNUC_DEPRECATED
 359 int headerNVR(Header h,
 360                 const char ** np,
 361                 const char ** vp,
 362                 const char ** rp);
 363
 364 /** \ingroup header
 365  * Return name, epoch, version, release, arch strings from header.
 366  * @param h             header
 367  * @retval *np          name pointer (or NULL)
 368  * @retval *ep          epoch pointer (or NULL)
 369  * @retval *vp          version pointer (or NULL)
 370  * @retval *rp          release pointer (or NULL)
 371  * @retval *ap          arch pointer (or NULL)
 372  * @return              0 always
 373  */
 374 RPM_GNUC_DEPRECATED
 375 int headerNEVRA(Header h,
 376                 const char ** np,
 377                 uint32_t ** ep,
 378                 const char ** vp,
 379                 const char ** rp,
 380                 const char ** ap);
 381
 382 /** \ingroup header
 383  * Return (malloc'd) header name-version-release string.
 384  * @param h             header
 385  * @retval np           name tag value
 386  * @return              name-version-release string
 387  */
 388 RPM_GNUC_DEPRECATED
 389 char * headerGetNEVR(Header h, const char ** np );
 390
 391 /** \ingroup header
 392  * Return (malloc'd) header name-version-release.arch string.
 393  * @param h             header
 394  * @retval np           name tag value
 395  * @return              name-version-release string
 396  */
 397 RPM_GNUC_DEPRECATED
 398 char * headerGetNEVRA(Header h, const char ** np );
 399
 400 /* \ingroup header
 401  * Return (malloc'd) header (epoch:)version-release string.
 402  * @param h             header
 403  * @retval np           name tag value (or NULL)
 404  * @return             (epoch:)version-release string
 405  */
 406 RPM_GNUC_DEPRECATED
 407 char * headerGetEVR(Header h, const char **np);
 408
 409 /** \ingroup header
 410  * Return any non-array tag from header, converted to string
 411  * @param h             header
 412  * @param tag           tag to retrieve
 413  * @return              string pointer (malloced) or NULL on failure
 414  */
 415 char * headerGetAsString(Header h, rpmTagVal tag);
 416
 417 /** \ingroup header
 418  * Return a simple string tag from header
 419  * @param h             header
 420  * @param tag           tag to retrieve
 421  * @return              string pointer (to header memory) or NULL on failure
 422  */
 423 const char * headerGetString(Header h, rpmTagVal tag);
 424
 425 /* \ingroup header
 426  * Return a simple number tag (or extension) from header
 427  * @param h             header
 428  * @param tag           tag to retrieve
 429  * @return              numeric tag value or 0 on failure
 430  */
 431 uint64_t headerGetNumber(Header h, rpmTagVal tag);
 432
 433 /** \ingroup header
 434  * Return header color.
 435  * @param h             header
 436  * @return              header color
 437  */
 438 RPM_GNUC_DEPRECATED
 439 rpm_color_t headerGetColor(Header h);
 440
 441 /** \ingroup header
 442  * Check if header is a source or binary package header
 443  * @param h             header
 444  * @return              0 == binary, 1 == source
 445  */
 446 int headerIsSource(Header h);
 447
 448 /** \ingroup header
 449  * Return header instance, ie is the header from rpmdb.
 450  * @param h             header
 451  * @return              rpmdb record number or 0
 452  */
 453 unsigned int headerGetInstance(Header h);
 454
 455 typedef enum headerConvOps_e {
 456     HEADERCONV_EXPANDFILELIST   = 0,
 457     HEADERCONV_COMPRESSFILELIST = 1,
 458     HEADERCONV_RETROFIT_V3      = 2,
 459 } headerConvOps;
 460
 461 /** \ingroup header
 462  * Convert header to/from (legacy) data presentation
 463  * @param h             header
 464  * @param op            one of headerConvOps operations
 465  * @return              1 on success, 0 on failure
 466  */
 467 int headerConvert(Header h, int op);
 468
 469 #ifdef __cplusplus
 470 }
 471 #endif
 472
 473 #endif  /* H_HEADER */