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