rpmdb/hdrinline.h

   1 /*@-type@*/ /* FIX: cast to HV_t bogus */
   2 #ifndef H_HDRINLINE
   3 #define H_HDRINLINE
   4
   5 /** \ingroup header
   6  * \file lib/hdrinline.h
   7  */
   8
   9 #ifdef __cplusplus
  10 extern "C" {
  11 #endif
  12 /*@+voidabstract -nullpass -mustmod -compdef -shadow -predboolothers @*/
  13
  14 /** \ingroup header
  15  * Header methods for rpm headers.
  16  */
  17 /*@observer@*/ /*@unchecked@*/
  18 extern struct HV_s * hdrVec;
  19
  20 /** \ingroup header
  21  */
  22 /*@unused@*/ static inline HV_t h2hv(Header h)
  23         /*@*/
  24 {
  25     /*@-abstract -castexpose -refcounttrans@*/
  26     return ((HV_t)h);
  27     /*@=abstract =castexpose =refcounttrans@*/
  28 }
  29
  30 /** \ingroup header
  31  * Create new (empty) header instance.
  32  * @return              header
  33  */
  34 /*@unused@*/ static inline
  35 Header headerNew(void)
  36         /*@*/
  37 {
  38     return hdrVec->hdrnew();
  39 }
  40
  41 /** \ingroup header
  42  * Dereference a header instance.
  43  * @todo Remove debugging entry from the ABI.
  44  * @param h             header
  45  * @param msg
  46  * @param fn
  47  * @param ln
  48  * @return              NULL always
  49  */
  50 /*@unused@*/ static inline
  51 /*@null@*/ Header XheaderFree( /*@killref@*/ /*@null@*/ Header h,
  52                 /*@null@*/ const char * msg, const char * fn, unsigned ln)
  53         /*@modifies h @*/
  54 {
  55     /*@-abstract@*/
  56     if (h == NULL) return NULL;
  57     /*@=abstract@*/
  58     return (h2hv(h)->Xhdrfree) (h, msg, fn, ln);
  59 }
  60
  61 /** \ingroup header
  62  * Reference a header instance.
  63  * @todo Remove debugging entry from the ABI.
  64  * @param h             header
  65  * @param msg
  66  * @param fn
  67  * @param ln
  68  * @return              new header reference
  69  */
  70 /*@unused@*/ static inline
  71 Header XheaderLink(Header h, /*@null@*/ const char * msg,
  72                 const char * fn, unsigned ln)
  73         /*@modifies h @*/
  74 {
  75     return (h2hv(h)->Xhdrlink) (h, msg, fn, ln);
  76 }
  77
  78 /** \ingroup header
  79  * Dereference a header instance.
  80  * @todo Remove debugging entry from the ABI.
  81  * @param h             header
  82  * @param msg
  83  * @param fn
  84  * @param ln
  85  * @return              new header reference
  86  */
  87 /*@unused@*/ static inline
  88 Header XheaderUnlink(/*@killref@*/ /*@null@*/ Header h,
  89                 /*@null@*/ const char * msg, const char * fn, unsigned ln)
  90         /*@modifies h @*/
  91 {
  92     /*@-abstract@*/
  93     if (h == NULL) return NULL;
  94     /*@=abstract@*/
  95     return (h2hv(h)->Xhdrunlink) (h, msg, fn, ln);
  96 }
  97
  98 /*@-exportlocal@*/
  99 /** \ingroup header
 100  * Sort tags in header.
 101  * @param h             header
 102  */
 103 /*@unused@*/ static inline
 104 void headerSort(Header h)
 105         /*@modifies h @*/
 106 {
 107 /*@-noeffectuncon@*/ /* FIX: add rc */
 108     (h2hv(h)->hdrsort) (h);
 109 /*@=noeffectuncon@*/
 110     return;
 111 }
 112
 113 /** \ingroup header
 114  * Restore tags in header to original ordering.
 115  * @param h             header
 116  */
 117 /*@unused@*/ static inline
 118 void headerUnsort(Header h)
 119         /*@modifies h @*/
 120 {
 121 /*@-noeffectuncon@*/ /* FIX: add rc */
 122     (h2hv(h)->hdrunsort) (h);
 123 /*@=noeffectuncon@*/
 124     return;
 125 }
 126 /*@=exportlocal@*/
 127
 128 /** \ingroup header
 129  * Return size of on-disk header representation in bytes.
 130  * @param h             header
 131  * @param magicp        include size of 8 bytes for (magic, 0)?
 132  * @return              size of on-disk header
 133  */
 134 /*@unused@*/ static inline
 135 unsigned int headerSizeof(/*@null@*/ Header h, enum hMagic magicp)
 136         /*@modifies h @*/
 137 {
 138     /*@-abstract@*/
 139     if (h == NULL) return 0;
 140     /*@=abstract@*/
 141     return (h2hv(h)->hdrsizeof) (h, magicp);
 142 }
 143
 144 /** \ingroup header
 145  * Convert header to on-disk representation.
 146  * @param h             header (with pointers)
 147  * @return              on-disk header blob (i.e. with offsets)
 148  */
 149 /*@unused@*/ static inline
 150 /*@only@*/ /*@null@*/ void * headerUnload(Header h)
 151         /*@modifies h @*/
 152 {
 153     return (h2hv(h)->hdrunload) (h);
 154 }
 155
 156 /** \ingroup header
 157  * Convert header to on-disk representation, and then reload.
 158  * This is used to insure that all header data is in one chunk.
 159  * @param h             header (with pointers)
 160  * @param tag           region tag
 161  * @return              on-disk header (with offsets)
 162  */
 163 /*@unused@*/ static inline
 164 /*@null@*/ Header headerReload(/*@only@*/ Header h, int tag)
 165         /*@modifies h @*/
 166 {
 167     /*@-onlytrans@*/
 168     return (h2hv(h)->hdrreload) (h, tag);
 169     /*@=onlytrans@*/
 170 }
 171
 172 /** \ingroup header
 173  * Duplicate a header.
 174  * @param h             header
 175  * @return              new header instance
 176  */
 177 /*@unused@*/ static inline
 178 /*@null@*/ Header headerCopy(Header h)
 179         /*@modifies h @*/
 180 {
 181     return (h2hv(h)->hdrcopy) (h);
 182 }
 183
 184 /** \ingroup header
 185  * Convert header to in-memory representation.
 186  * @param uh            on-disk header blob (i.e. with offsets)
 187  * @return              header
 188  */
 189 /*@unused@*/ static inline
 190 /*@null@*/ Header headerLoad(/*@kept@*/ void * uh)
 191         /*@modifies uh @*/
 192 {
 193     return hdrVec->hdrload(uh);
 194 }
 195
 196 /** \ingroup header
 197  * Make a copy and convert header to in-memory representation.
 198  * @param uh            on-disk header blob (i.e. with offsets)
 199  * @return              header
 200  */
 201 /*@unused@*/ static inline
 202 /*@null@*/ Header headerCopyLoad(const void * uh)
 203         /*@*/
 204 {
 205     return hdrVec->hdrcopyload(uh);
 206 }
 207
 208 /** \ingroup header
 209  * Read (and load) header from file handle.
 210  * @param fd            file handle
 211  * @param magicp        read (and verify) 8 bytes of (magic, 0)?
 212  * @return              header (or NULL on error)
 213  */
 214 /*@unused@*/ static inline
 215 /*@null@*/ Header headerRead(FD_t fd, enum hMagic magicp)
 216         /*@modifies fd @*/
 217 {
 218     return hdrVec->hdrread(fd, magicp);
 219 }
 220
 221 /** \ingroup header
 222  * Write (with unload) header to file handle.
 223  * @param fd            file handle
 224  * @param h             header
 225  * @param magicp        prefix write with 8 bytes of (magic, 0)?
 226  * @return              0 on success, 1 on error
 227  */
 228 /*@unused@*/ static inline
 229 int headerWrite(FD_t fd, /*@null@*/ Header h, enum hMagic magicp)
 230         /*@modifies fd, h @*/
 231 {
 232     /*@-abstract@*/
 233     if (h == NULL) return 0;
 234     /*@=abstract@*/
 235     return (h2hv(h)->hdrwrite) (fd, h, magicp);
 236 }
 237
 238 /** \ingroup header
 239  * Check if tag is in header.
 240  * @param h             header
 241  * @param tag           tag
 242  * @return              1 on success, 0 on failure
 243  */
 244 /*@unused@*/ static inline
 245 int headerIsEntry(/*@null@*/ Header h, int_32 tag)
 246         /*@modifies h @*/
 247 {
 248     /*@-abstract@*/
 249     if (h == NULL) return 0;
 250     /*@=abstract@*/
 251     return (h2hv(h)->hdrisentry) (h, tag);
 252 }
 253
 254 /** \ingroup header
 255  * Free data allocated when retrieved from header.
 256  * @param h             header
 257  * @param data          address of data (or NULL)
 258  * @param type          type of data (or -1 to force free)
 259  * @return              NULL always
 260  */
 261 /*@unused@*/ static inline
 262 /*@null@*/ void * headerFreeTag(Header h,
 263                 /*@only@*/ /*@null@*/ const void * data, rpmTagType type)
 264         /*@modifies data @*/
 265 {
 266     return (h2hv(h)->hdrfreetag) (h, data, type);
 267 }
 268
 269 /** \ingroup header
 270  * Retrieve tag value.
 271  * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
 272  * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
 273  * entry is present).
 274  *
 275  * @param h             header
 276  * @param tag           tag
 277  * @retval type         address of tag value data type (or NULL)
 278  * @retval p            address of pointer to tag value(s) (or NULL)
 279  * @retval c            address of number of values (or NULL)
 280  * @return              1 on success, 0 on failure
 281  */
 282 /*@unused@*/ static inline
 283 int headerGetEntry(Header h, int_32 tag,
 284                         /*@null@*/ /*@out@*/ hTYP_t type,
 285                         /*@null@*/ /*@out@*/ void ** p,
 286                         /*@null@*/ /*@out@*/ hCNT_t c)
 287         /*@modifies *type, *p, *c @*/
 288 {
 289     return (h2hv(h)->hdrget) (h, tag, type, p, c);
 290 }
 291
 292 /** \ingroup header
 293  * Retrieve tag value using header internal array.
 294  * Get an entry using as little extra RAM as possible to return the tag value.
 295  * This is only an issue for RPM_STRING_ARRAY_TYPE.
 296  *
 297  * @param h             header
 298  * @param tag           tag
 299  * @retval type         address of tag value data type (or NULL)
 300  * @retval p            address of pointer to tag value(s) (or NULL)
 301  * @retval c            address of number of values (or NULL)
 302  * @return              1 on success, 0 on failure
 303  */
 304 /*@unused@*/ static inline
 305 int headerGetEntryMinMemory(Header h, int_32 tag,
 306                         /*@null@*/ /*@out@*/ hTYP_t type,
 307                         /*@null@*/ /*@out@*/ hPTR_t * p,
 308                         /*@null@*/ /*@out@*/ hCNT_t c)
 309         /*@modifies *type, *p, *c @*/
 310 {
 311     return (h2hv(h)->hdrgetmin) (h, tag, type, p, c);
 312 }
 313
 314 /** \ingroup header
 315  * Add tag to header.
 316  * Duplicate tags are okay, but only defined for iteration (with the
 317  * exceptions noted below). While you are allowed to add i18n string
 318  * arrays through this function, you probably don't mean to. See
 319  * headerAddI18NString() instead.
 320  *
 321  * @param h             header
 322  * @param tag           tag
 323  * @param type          tag value data type
 324  * @param p             pointer to tag value(s)
 325  * @param c             number of values
 326  * @return              1 on success, 0 on failure
 327  */
 328 /*@mayexit@*/
 329 /*@unused@*/ static inline
 330 int headerAddEntry(Header h, int_32 tag, int_32 type, const void * p, int_32 c)
 331         /*@modifies h @*/
 332 {
 333     return (h2hv(h)->hdradd) (h, tag, type, p, c);
 334 }
 335
 336 /** \ingroup header
 337  * Append element to tag array in header.
 338  * Appends item p to entry w/ tag and type as passed. Won't work on
 339  * RPM_STRING_TYPE. Any pointers into header memory returned from
 340  * headerGetEntryMinMemory() for this entry are invalid after this
 341  * call has been made!
 342  *
 343  * @param h             header
 344  * @param tag           tag
 345  * @param type          tag value data type
 346  * @param p             pointer to tag value(s)
 347  * @param c             number of values
 348  * @return              1 on success, 0 on failure
 349  */
 350 /*@unused@*/ static inline
 351 int headerAppendEntry(Header h, int_32 tag, int_32 type,
 352                 const void * p, int_32 c)
 353         /*@modifies h @*/
 354 {
 355     return (h2hv(h)->hdrappend) (h, tag, type, p, c);
 356 }
 357
 358 /** \ingroup header
 359  * Add or append element to tag array in header.
 360  * @todo Arg "p" should have const.
 361  * @param h             header
 362  * @param tag           tag
 363  * @param type          tag value data type
 364  * @param p             pointer to tag value(s)
 365  * @param c             number of values
 366  * @return              1 on success, 0 on failure
 367  */
 368 /*@unused@*/ static inline
 369 int headerAddOrAppendEntry(Header h, int_32 tag, int_32 type,
 370                 const void * p, int_32 c)
 371         /*@modifies h @*/
 372 {
 373     return (h2hv(h)->hdraddorappend) (h, tag, type, p, c);
 374 }
 375
 376 /** \ingroup header
 377  * Add locale specific tag to header.
 378  * A NULL lang is interpreted as the C locale. Here are the rules:
 379  * \verbatim
 380  *      - If the tag isn't in the header, it's added with the passed string
 381  *         as new value.
 382  *      - If the tag occurs multiple times in entry, which tag is affected
 383  *         by the operation is undefined.
 384  *      - If the tag is in the header w/ this language, the entry is
 385  *         *replaced* (like headerModifyEntry()).
 386  * \endverbatim
 387  * This function is intended to just "do the right thing". If you need
 388  * more fine grained control use headerAddEntry() and headerModifyEntry().
 389  *
 390  * @param h             header
 391  * @param tag           tag
 392  * @param string        tag value
 393  * @param lang          locale
 394  * @return              1 on success, 0 on failure
 395  */
 396 /*@unused@*/ static inline
 397 int headerAddI18NString(Header h, int_32 tag, const char * string,
 398                 const char * lang)
 399         /*@modifies h @*/
 400 {
 401     return (h2hv(h)->hdraddi18n) (h, tag, string, lang);
 402 }
 403
 404 /** \ingroup header
 405  * Modify tag in header.
 406  * If there are multiple entries with this tag, the first one gets replaced.
 407  * @param h             header
 408  * @param tag           tag
 409  * @param type          tag value data type
 410  * @param p             pointer to tag value(s)
 411  * @param c             number of values
 412  * @return              1 on success, 0 on failure
 413  */
 414 /*@unused@*/ static inline
 415 int headerModifyEntry(Header h, int_32 tag, int_32 type,
 416                         const void * p, int_32 c)
 417         /*@modifies h @*/
 418 {
 419     return (h2hv(h)->hdrmodify) (h, tag, type, p, c);
 420 }
 421
 422 /** \ingroup header
 423  * Delete tag in header.
 424  * Removes all entries of type tag from the header, returns 1 if none were
 425  * found.
 426  *
 427  * @param h             header
 428  * @param tag           tag
 429  * @return              0 on success, 1 on failure (INCONSISTENT)
 430  */
 431 /*@unused@*/ static inline
 432 int headerRemoveEntry(Header h, int_32 tag)
 433         /*@modifies h @*/
 434 {
 435     return (h2hv(h)->hdrremove) (h, tag);
 436 }
 437
 438 /** \ingroup header
 439  * Return formatted output string from header tags.
 440  * The returned string must be free()d.
 441  *
 442  * @param h             header
 443  * @param fmt           format to use
 444  * @param tbltags       array of tag name/value pairs
 445  * @param extensions    chained table of formatting extensions.
 446  * @retval errmsg       error message (if any)
 447  * @return              formatted output string (malloc'ed)
 448  */
 449 /*@unused@*/ static inline
 450 /*@only@*/ char * headerSprintf(Header h, const char * fmt,
 451                      const struct headerTagTableEntry_s * tbltags,
 452                      const struct headerSprintfExtension_s * extensions,
 453                      /*@null@*/ /*@out@*/ errmsg_t * errmsg)
 454         /*@modifies *errmsg @*/
 455 {
 456     return (h2hv(h)->hdrsprintf) (h, fmt, tbltags, extensions, errmsg);
 457 }
 458
 459 /** \ingroup header
 460  * Duplicate tag values from one header into another.
 461  * @param headerFrom    source header
 462  * @param headerTo      destination header
 463  * @param tagstocopy    array of tags that are copied
 464  */
 465 /*@unused@*/ static inline
 466 void headerCopyTags(Header headerFrom, Header headerTo, hTAG_t tagstocopy)
 467         /*@modifies headerFrom, headerTo @*/
 468 {
 469 /*@-noeffectuncon@*/ /* FIX: add rc */
 470     hdrVec->hdrcopytags(headerFrom, headerTo, tagstocopy);
 471 /*@=noeffectuncon@*/
 472     return;
 473 }
 474
 475 /** \ingroup header
 476  * Destroy header tag iterator.
 477  * @param hi            header tag iterator
 478  * @return              NULL always
 479  */
 480 /*@unused@*/ static inline
 481 HeaderIterator headerFreeIterator(/*@only@*/ HeaderIterator hi)
 482         /*@modifies hi @*/
 483 {
 484     return hdrVec->hdrfreeiter(hi);
 485 }
 486
 487 /** \ingroup header
 488  * Create header tag iterator.
 489  * @param h             header
 490  * @return              header tag iterator
 491  */
 492 /*@unused@*/ static inline
 493 HeaderIterator headerInitIterator(Header h)
 494         /*@modifies h */
 495 {
 496     return hdrVec->hdrinititer(h);
 497 }
 498
 499 /** \ingroup header
 500  * Return next tag from header.
 501  * @param hi            header tag iterator
 502  * @retval tag          address of tag
 503  * @retval type         address of tag value data type
 504  * @retval p            address of pointer to tag value(s)
 505  * @retval c            address of number of values
 506  * @return              1 on success, 0 on failure
 507  */
 508 /*@unused@*/ static inline
 509 int headerNextIterator(HeaderIterator hi,
 510                 /*@null@*/ /*@out@*/ hTAG_t tag,
 511                 /*@null@*/ /*@out@*/ hTYP_t type,
 512                 /*@null@*/ /*@out@*/ hPTR_t * p,
 513                 /*@null@*/ /*@out@*/ hCNT_t c)
 514         /*@modifies hi, *tag, *type, *p, *c @*/
 515 {
 516     return hdrVec->hdrnextiter(hi, tag, type, p, c);
 517 }
 518
 519 /*@=voidabstract =nullpass =mustmod =compdef =shadow =predboolothers @*/
 520
 521 #ifdef __cplusplus
 522 }
 523 #endif
 524
 525 #endif  /* H_HDRINLINE */
 526 /*@=type@*/