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  * Include calculation for 8 bytes of (magic, 0)?
  26  */
  27 enum hMagic {
  28     HEADER_MAGIC_NO             = 0,
  29     HEADER_MAGIC_YES            = 1
  30 };
  31
  32 /** \ingroup header
  33  * Create new (empty) header instance.
  34  * @return              header
  35  */
  36 Header headerNew(void);
  37
  38 /** \ingroup header
  39  * Dereference a header instance.
  40  * @param h             header
  41  * @return              NULL always
  42  */
  43 Header headerFree( Header h);
  44
  45 /** \ingroup header
  46  * Reference a header instance.
  47  * @param h             header
  48  * @return              new header reference
  49  */
  50 Header headerLink(Header h);
  51
  52 /** \ingroup header
  53  * Dereference a header instance.
  54  * @param h             header
  55  * @return              new header reference
  56  */
  57 Header headerUnlink(Header h);
  58
  59 /** \ingroup header
  60  * Sort tags in header.
  61  * @param h             header
  62  */
  63 void headerSort(Header h);
  64
  65 /** \ingroup header
  66  * Restore tags in header to original ordering.
  67  * @param h             header
  68  */
  69 void headerUnsort(Header h);
  70
  71 /** \ingroup header
  72  * Return size of on-disk header representation in bytes.
  73  * @param h             header
  74  * @param magicp        include size of 8 bytes for (magic, 0)?
  75  * @return              size of on-disk header
  76  */
  77 unsigned int headerSizeof(Header h, enum hMagic magicp);
  78
  79 /** \ingroup header
  80  * Perform simple sanity and range checks on header tag(s).
  81  * @param il            no. of tags in header
  82  * @param dl            no. of bytes in header data.
  83  * @param pev           1st element in tag array, big-endian
  84  * @param iv            failing (or last) tag element, host-endian
  85  * @param negate        negative offset expected?
  86  * @return              -1 on success, otherwise failing tag element index
  87  */
  88 int headerVerifyInfo(int il, int dl, const void * pev, void * iv, int negate);
  89
  90 /** \ingroup header
  91  * Convert header to on-disk representation.
  92  * @param h             header (with pointers)
  93  * @return              on-disk header blob (i.e. with offsets)
  94  */
  95 void * headerUnload(Header h);
  96
  97 /** \ingroup header
  98  * Convert header to on-disk representation, and then reload.
  99  * This is used to insure that all header data is in one chunk.
 100  * @param h             header (with pointers)
 101  * @param tag           region tag
 102  * @return              on-disk header (with offsets)
 103  */
 104 Header headerReload(Header h, rpmTag tag);
 105
 106 /** \ingroup header
 107  * Duplicate a header.
 108  * @param h             header
 109  * @return              new header instance
 110  */
 111 Header headerCopy(Header h);
 112
 113 /** \ingroup header
 114  * Convert header to in-memory representation.
 115  * @param uh            on-disk header blob (i.e. with offsets)
 116  * @return              header
 117  */
 118 Header headerLoad(void * uh);
 119
 120 /** \ingroup header
 121  * Make a copy and convert header to in-memory representation.
 122  * @param uh            on-disk header blob (i.e. with offsets)
 123  * @return              header
 124  */
 125 Header headerCopyLoad(const void * uh);
 126
 127 /** \ingroup header
 128  * Read (and load) header from file handle.
 129  * @param fd            file handle
 130  * @param magicp        read (and verify) 8 bytes of (magic, 0)?
 131  * @return              header (or NULL on error)
 132  */
 133 Header headerRead(FD_t fd, enum hMagic magicp);
 134
 135 /** \ingroup header
 136  * Write (with unload) header to file handle.
 137  * @param fd            file handle
 138  * @param h             header
 139  * @param magicp        prefix write with 8 bytes of (magic, 0)?
 140  * @return              0 on success, 1 on error
 141  */
 142 int headerWrite(FD_t fd, Header h, enum hMagic magicp);
 143
 144 /** \ingroup header
 145  * Check if tag is in header.
 146  * @param h             header
 147  * @param tag           tag
 148  * @return              1 on success, 0 on failure
 149  */
 150 int headerIsEntry(Header h, rpmTag tag);
 151
 152 typedef enum headerGetFlags_e {
 153     HEADERGET_DEFAULT   = 0,
 154     HEADERGET_MINMEM    = (1 << 0), /* string pointers refer to header memory */
 155     HEADERGET_EXT       = (1 << 1), /* lookup extension types too */
 156     HEADERGET_RAW       = (1 << 2), /* return raw contents (no i18n lookups) */
 157 } headerGetFlags;
 158
 159 /** \ingroup header
 160  * Retrieve tag value.
 161  * @param h             header
 162  * @param tag           tag
 163  * @retval td           tag data container
 164  * @param flags         retrieval modifier flags
 165  * @return              1 on success, 0 on failure
 166  */
 167 int headerGet(Header h, rpmTag tag, rpmtd td, headerGetFlags flags);
 168
 169 /** \ingroup header
 170  * Free data allocated when retrieved from header.
 171  * @param h             header
 172  * @param data          pointer to tag value(s)
 173  * @param type          type of data (or -1 to force free)
 174  * @return              NULL always
 175  */
 176 void * headerFreeTag(Header h, rpm_data_t data, rpmTagType type);
 177
 178 /** \ingroup header
 179  * Retrieve tag value.
 180  * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
 181  * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
 182  * entry is present).
 183  *
 184  * @param h             header
 185  * @param tag           tag
 186  * @retval *type        tag value data type (or NULL)
 187  * @retval *p           pointer to tag value(s) (or NULL)
 188  * @retval *c           number of values (or NULL)
 189  * @return              1 on success, 0 on failure
 190  */
 191 int headerGetEntry(Header h, rpmTag tag,
 192                         rpmTagType * type,
 193                         rpm_data_t * p,
 194                         rpm_count_t * c);
 195
 196 /** \ingroup header
 197  * Retrieve tag value using header internal array.
 198  * Get an entry using as little extra RAM as possible to return the tag value.
 199  * This is only an issue for RPM_STRING_ARRAY_TYPE.
 200  *
 201  * @param h             header
 202  * @param tag           tag
 203  * @retval *type        tag value data type (or NULL)
 204  * @retval *p           pointer to tag value(s) (or NULL)
 205  * @retval *c           number of values (or NULL)
 206  * @return              1 on success, 0 on failure
 207  */
 208 int headerGetEntryMinMemory(Header h, rpmTag tag,
 209                         rpmTagType * type,
 210                         rpm_data_t * p,
 211                         rpm_count_t * c);
 212
 213 typedef enum headerPutFlags_e {
 214     HEADERPUT_DEFAULT   = 0,
 215     HEADERPUT_APPEND    = (1 << 0),
 216 } headerPutFlags;
 217
 218 /** \ingroup header
 219  * Add or append tag to header.
 220  *
 221  * @param h             header
 222  * @param td            tag data container
 223  * @param flags         flags to control operation
 224  * @return              1 on success, 0 on failure
 225  */
 226 int headerPut(Header h, rpmtd td, headerPutFlags flags);
 227
 228 /** \ingroup header
 229  * Add tag to header.
 230  * Duplicate tags are okay, but only defined for iteration (with the
 231  * exceptions noted below). While you are allowed to add i18n string
 232  * arrays through this function, you probably don't mean to. See
 233  * headerAddI18NString() instead.
 234  *
 235  * @param h             header
 236  * @param tag           tag
 237  * @param type          tag value data type
 238  * @param p             pointer to tag value(s)
 239  * @param c             number of values
 240  * @return              1 on success, 0 on failure
 241  */
 242 int headerAddEntry(Header h, rpmTag tag, rpmTagType type, rpm_constdata_t p, rpm_count_t c);
 243
 244 /** \ingroup header
 245  * Append element to tag array in header.
 246  * Appends item p to entry w/ tag and type as passed. Won't work on
 247  * RPM_STRING_TYPE. Any pointers into header memory returned from
 248  * headerGetEntryMinMemory() for this entry are invalid after this
 249  * call has been made!
 250  *
 251  * @param h             header
 252  * @param tag           tag
 253  * @param type          tag value data type
 254  * @param p             pointer to tag value(s)
 255  * @param c             number of values
 256  * @return              1 on success, 0 on failure
 257  */
 258 int headerAppendEntry(Header h, rpmTag tag, rpmTagType type,
 259                 rpm_constdata_t p, rpm_count_t c);
 260
 261 /** \ingroup header
 262  * Add or append element to tag array in header.
 263  * @param h             header
 264  * @param tag           tag
 265  * @param type          tag value data type
 266  * @param p             pointer to tag value(s)
 267  * @param c             number of values
 268  * @return              1 on success, 0 on failure
 269  */
 270 int headerAddOrAppendEntry(Header h, rpmTag tag, rpmTagType type,
 271                 rpm_constdata_t p, rpm_count_t c);
 272
 273 /** \ingroup header
 274  * Add locale specific tag to header.
 275  * A NULL lang is interpreted as the C locale. Here are the rules:
 276  * \verbatim
 277  *      - If the tag isn't in the header, it's added with the passed string
 278  *         as new value.
 279  *      - If the tag occurs multiple times in entry, which tag is affected
 280  *         by the operation is undefined.
 281  *      - If the tag is in the header w/ this language, the entry is
 282  *         *replaced* (like headerModifyEntry()).
 283  * \endverbatim
 284  * This function is intended to just "do the right thing". If you need
 285  * more fine grained control use headerAddEntry() and headerModifyEntry().
 286  *
 287  * @param h             header
 288  * @param tag           tag
 289  * @param string        tag value
 290  * @param lang          locale
 291  * @return              1 on success, 0 on failure
 292  */
 293 int headerAddI18NString(Header h, rpmTag tag, const char * string,
 294                 const char * lang);
 295
 296 /** \ingroup header
 297  * Modify tag in header.
 298  * If there are multiple entries with this tag, the first one gets replaced.
 299  * @param h             header
 300  * @param tag           tag
 301  * @param type          tag value data type
 302  * @param p             pointer to tag value(s)
 303  * @param c             number of values
 304  * @return              1 on success, 0 on failure
 305  */
 306 int headerModifyEntry(Header h, rpmTag tag, rpmTagType type,
 307                         rpm_constdata_t p, rpm_count_t c);
 308
 309 /** \ingroup header
 310  * Delete tag in header.
 311  * Removes all entries of type tag from the header, returns 1 if none were
 312  * found.
 313  *
 314  * @param h             header
 315  * @param tag           tag
 316  * @return              0 on success, 1 on failure (INCONSISTENT)
 317  */
 318 int headerRemoveEntry(Header h, rpmTag tag);
 319
 320 /** \ingroup header
 321  * Return formatted output string from header tags.
 322  * The returned string must be free()d.
 323  *
 324  * @param h             header
 325  * @param fmt           format to use
 326  * @retval errmsg       error message (if any)
 327  * @return              formatted output string (malloc'ed)
 328  */
 329 char * headerFormat(Header h, const char * fmt, errmsg_t * errmsg);
 330
 331 /** \ingroup header
 332  * Return formatted output string from header tags.
 333  * The returned string must be free()d.
 334  *
 335  * @param h             header
 336  * @param fmt           format to use
 337  * @param tbltags       array of tag name/value pairs (unused)
 338  * @param extensions    chained table of formatting extensions. (unused)
 339  * @retval errmsg       error message (if any)
 340  * @return              formatted output string (malloc'ed)
 341  */
 342 char * headerSprintf(Header h, const char * fmt,
 343                      void * tbltags, void * extensions,
 344                      errmsg_t * errmsg) RPM_GNUC_DEPRECATED;
 345
 346 /** \ingroup header
 347  * Duplicate tag values from one header into another.
 348  * @param headerFrom    source header
 349  * @param headerTo      destination header
 350  * @param tagstocopy    array of tags that are copied
 351  */
 352 void headerCopyTags(Header headerFrom, Header headerTo,
 353                     const rpmTag * tagstocopy);
 354
 355 /** \ingroup header
 356  * Destroy header tag iterator.
 357  * @param hi            header tag iterator
 358  * @return              NULL always
 359  */
 360 HeaderIterator headerFreeIterator(HeaderIterator hi);
 361
 362 /** \ingroup header
 363  * Create header tag iterator.
 364  * @param h             header
 365  * @return              header tag iterator
 366  */
 367 HeaderIterator headerInitIterator(Header h);
 368
 369 /** \ingroup header
 370  * Return next tag from header.
 371  * @param hi            header tag iterator
 372  * @retval td           tag data container
 373  * @return              1 on success, 0 on failure
 374  */
 375 int headerNext(HeaderIterator hi, rpmtd td);
 376
 377 /** \ingroup header
 378  * Return next tag from header.
 379  * @deprecated Use headerNext() instead.
 380  *
 381  * @param hi            header tag iterator
 382  * @retval *tag         tag
 383  * @retval *type        tag value data type
 384  * @retval *p           pointer to tag value(s)
 385  * @retval *c           number of values
 386  * @return              1 on success, 0 on failure
 387  */
 388 int headerNextIterator(HeaderIterator hi,
 389                 rpmTag * tag,
 390                 rpmTagType * type,
 391                 rpm_data_t * p,
 392                 rpm_count_t * c) RPM_GNUC_DEPRECATED;
 393
 394
 395
 396 /** \ingroup header
 397  * Free data allocated when retrieved from header.
 398  * @deprecated Use headerFreeTag() instead.
 399  * @todo Remove from API.
 400  *
 401  * @param data          address of data (or NULL)
 402  * @param type          type of data (or RPM_FORCEFREE_TYPE to force free)
 403  * @return              NULL always
 404  */
 405 void * headerFreeData(rpm_data_t data, rpmTagType type);
 406
 407 /** \ingroup header
 408  * Return name, version, release strings from header.
 409  * @param h             header
 410  * @retval *np          name pointer (or NULL)
 411  * @retval *vp          version pointer (or NULL)
 412  * @retval *rp          release pointer (or NULL)
 413  * @return              0 always
 414  */
 415 int headerNVR(Header h,
 416                 const char ** np,
 417                 const char ** vp,
 418                 const char ** rp);
 419
 420 /** \ingroup header
 421  * Return name, epoch, version, release, arch strings from header.
 422  * @param h             header
 423  * @retval *np          name pointer (or NULL)
 424  * @retval *ep          epoch pointer (or NULL)
 425  * @retval *vp          version pointer (or NULL)
 426  * @retval *rp          release pointer (or NULL)
 427  * @retval *ap          arch pointer (or NULL)
 428  * @return              0 always
 429  */
 430 int headerNEVRA(Header h,
 431                 const char ** np,
 432                 uint32_t ** ep,
 433                 const char ** vp,
 434                 const char ** rp,
 435                 const char ** ap);
 436
 437 /** \ingroup header
 438  * Return (malloc'd) header name-version-release string.
 439  * @param h             header
 440  * @retval np           name tag value
 441  * @return              name-version-release string
 442  */
 443 char * headerGetNEVR(Header h, const char ** np );
 444
 445 /** \ingroup header
 446  * Return (malloc'd) header name-version-release.arch string.
 447  * @param h             header
 448  * @retval np           name tag value
 449  * @return              name-version-release string
 450  */
 451 char * headerGetNEVRA(Header h, const char ** np );
 452
 453 /* \ingroup header
 454  * Return (malloc'd) header (epoch:)version-release string.
 455  * @param h             header
 456  * @retval np           name tag value (or NULL)
 457  * @return             (epoch:)version-release string
 458  */
 459 char * headerGetEVR(Header h, const char **np);
 460
 461 /** \ingroup header
 462  * Return header color.
 463  * @param h             header
 464  * @return              header color
 465  */
 466 rpm_color_t headerGetColor(Header h);
 467
 468 /** \ingroup header
 469  * Check if header is a source or binary package header
 470  * @param h             header
 471  * @return              0 == binary, 1 == source
 472  */
 473 int headerIsSource(Header h);
 474
 475 /* ==================================================================== */
 476 /** \name RPMTS */
 477 /**
 478  * Prototype for headerFreeData() vector.
 479  *
 480  * @param data          address of data (or NULL)
 481  * @param type          type of data (or  to force free)
 482  * @return              NULL always
 483  */
 484 typedef
 485     void * (*HFD_t) (rpm_data_t data, rpmTagType type);
 486
 487 /**
 488  * Prototype for headerGetEntry() vector.
 489  *
 490  * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
 491  * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
 492  * entry is present).
 493  *
 494  * @param h             header
 495  * @param tag           tag
 496  * @retval type         address of tag value data type (or NULL)
 497  * @retval p            address of pointer to tag value(s) (or NULL)
 498  * @retval c            address of number of values (or NULL)
 499  * @return              1 on success, 0 on failure
 500  */
 501 typedef int (*HGE_t) (Header h, rpmTag tag,
 502                         rpmTagType * type,
 503                         rpm_data_t * p,
 504                         rpm_count_t * c);
 505
 506 /**
 507  * Prototype for headerAddEntry() vector.
 508  *
 509  * Duplicate tags are okay, but only defined for iteration (with the
 510  * exceptions noted below). While you are allowed to add i18n string
 511  * arrays through this function, you probably don't mean to. See
 512  * headerAddI18NString() instead.
 513  *
 514  * @param h             header
 515  * @param tag           tag
 516  * @param type          tag value data type
 517  * @param p             pointer to tag value(s)
 518  * @param c             number of values
 519  * @return              1 on success, 0 on failure
 520  */
 521 typedef int (*HAE_t) (Header h, rpmTag tag, rpmTagType type,
 522                         rpm_constdata_t p, rpm_count_t c);
 523
 524 /**
 525  * Prototype for headerModifyEntry() vector.
 526  * If there are multiple entries with this tag, the first one gets replaced.
 527  *
 528  * @param h             header
 529  * @param tag           tag
 530  * @param type          tag value data type
 531  * @param p             pointer to tag value(s)
 532  * @param c             number of values
 533  * @return              1 on success, 0 on failure
 534  */
 535 typedef int (*HME_t) (Header h, rpmTag tag, rpmTagType type,
 536                         rpm_constdata_t p, rpm_count_t c);
 537
 538 /**
 539  * Prototype for headerRemoveEntry() vector.
 540  * Delete tag in header.
 541  * Removes all entries of type tag from the header, returns 1 if none were
 542  * found.
 543  *
 544  * @param h             header
 545  * @param tag           tag
 546  * @return              0 on success, 1 on failure (INCONSISTENT)
 547  */
 548 typedef int (*HRE_t) (Header h, rpmTag tag);
 549
 550 #ifdef __cplusplus
 551 }
 552 #endif
 553
 554 #endif  /* H_HEADER */