lib/rpmds.h

   1 #ifndef H_RPMDS
   2 #define H_RPMDS
   3
   4 /** \ingroup rpmdep rpmtrans
   5  * \file lib/rpmds.h
   6  * Structure(s) used for dependency tag sets.
   7  */
   8
   9 #include "rpmps.h"
  10
  11 /**
  12  */
  13 /*@-exportlocal@*/
  14 /*@unchecked@*/
  15 extern int _rpmds_debug;
  16 /*@=exportlocal@*/
  17
  18 /**
  19  */
  20 /*@-exportlocal@*/
  21 /*@unchecked@*/
  22 extern int _rpmds_nopromote;
  23 /*@=exportlocal@*/
  24
  25 #if defined(_RPMDS_INTERNAL)
  26 /**
  27  * A package dependency set.
  28  */
  29 struct rpmds_s {
  30 /*@observer@*/
  31     const char * Type;          /*!< Tag name. */
  32 /*@only@*/ /*@null@*/
  33     const char * DNEVR;         /*!< Formatted dependency string. */
  34 /*@refcounted@*/ /*@null@*/
  35     Header h;                   /*!< Header for dependency set (or NULL) */
  36 /*@only@*/
  37     const char ** N;            /*!< Name. */
  38 /*@only@*/ /*@null@*/
  39     const char ** EVR;          /*!< Epoch-Version-Release. */
  40 /*@only@*/ /*@null@*/
  41     int_32 * Flags;             /*!< Bit(s) identifying context/comparison. */
  42 /*@only@*/ /*@null@*/
  43     uint_32 * Color;            /*!< Bit(s) calculated from file color(s). */
  44 /*@only@*/ /*@null@*/
  45     int_32 * Refs;              /*!< No. of file refs. */
  46     rpmTag tagN;                /*!< Header tag. */
  47     rpmTagType Nt, EVRt, Ft;    /*!< Tag data types. */
  48     int_32 Count;               /*!< No. of elements */
  49     int i;                      /*!< Element index. */
  50     unsigned l;                 /*!< Low element (bsearch). */
  51     unsigned u;                 /*!< High element (bsearch). */
  52     int nopromote;              /*!< Don't promote Epoch: in rpmdsCompare()? */
  53 /*@refs@*/
  54     int nrefs;                  /*!< Reference count. */
  55 };
  56 #endif  /* _RPMDS_INTERNAL */
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62 /**
  63  * Unreference a dependency set instance.
  64  * @param ds            dependency set
  65  * @param msg
  66  * @return              NULL always
  67  */
  68 /*@unused@*/ /*@null@*/
  69 rpmds rpmdsUnlink (/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds,
  70                 /*@null@*/ const char * msg)
  71         /*@modifies ds @*/;
  72
  73 /** @todo Remove debugging entry from the ABI. */
  74 /*@-exportlocal@*/
  75 /*@null@*/
  76 rpmds XrpmdsUnlink (/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds,
  77                 /*@null@*/ const char * msg, const char * fn, unsigned ln)
  78         /*@modifies ds @*/;
  79 /*@=exportlocal@*/
  80 #define rpmdsUnlink(_ds, _msg)  XrpmdsUnlink(_ds, _msg, __FILE__, __LINE__)
  81
  82 /**
  83  * Reference a dependency set instance.
  84  * @param ds            dependency set
  85  * @param msg
  86  * @return              new dependency set reference
  87  */
  88 /*@unused@*/ /*@newref@*/
  89 rpmds rpmdsLink (/*@null@*/ rpmds ds, /*@null@*/ const char * msg)
  90         /*@modifies ds @*/;
  91
  92 /** @todo Remove debugging entry from the ABI. */
  93 /*@newref@*/
  94 rpmds XrpmdsLink (/*@null@*/ rpmds ds, /*@null@*/ const char * msg,
  95                 const char * fn, unsigned ln)
  96         /*@modifies ds @*/;
  97 #define rpmdsLink(_ds, _msg)    XrpmdsLink(_ds, _msg, __FILE__, __LINE__)
  98
  99 /**
 100  * Destroy a dependency set.
 101  * @param ds            dependency set
 102  * @return              NULL always
 103  */
 104 /*@null@*/
 105 rpmds rpmdsFree(/*@killref@*/ /*@only@*/ /*@null@*/ rpmds ds)
 106         /*@modifies ds@*/;
 107 /**
 108  * Create and load a dependency set.
 109  * @param h             header
 110  * @param tagN          type of dependency
 111  * @param scareMem      Use pointers to refcounted header memory?
 112  * @return              new dependency set
 113  */
 114 /*@null@*/
 115 rpmds rpmdsNew(Header h, rpmTag tagN, int scareMem)
 116         /*@modifies h @*/;
 117
 118 /**
 119  * Return new formatted dependency string.
 120  * @param dspfx         formatted dependency string prefix
 121  * @param ds            dependency set
 122  * @return              new formatted dependency (malloc'ed)
 123  */
 124 /*@only@*/
 125 char * rpmdsNewDNEVR(const char * dspfx, const rpmds ds)
 126         /*@*/;
 127
 128 /**
 129  * Create, load and initialize a dependency for this header.
 130  * @param h             header
 131  * @param tagN          type of dependency
 132  * @param Flags         comparison flags
 133  * @return              new dependency set
 134  */
 135 /*@null@*/
 136 rpmds rpmdsThis(Header h, rpmTag tagN, int_32 Flags)
 137         /*@*/;
 138
 139 /**
 140  * Create, load and initialize a dependency set of size 1.
 141  * @param tagN          type of dependency
 142  * @param N             name
 143  * @param EVR           epoch:version-release
 144  * @param Flags         comparison flags
 145  * @return              new dependency set
 146  */
 147 /*@null@*/
 148 rpmds rpmdsSingle(rpmTag tagN, const char * N, const char * EVR, int_32 Flags)
 149         /*@*/;
 150
 151 /**
 152  * Return dependency set count.
 153  * @param ds            dependency set
 154  * @return              current count
 155  */
 156 int rpmdsCount(/*@null@*/ const rpmds ds)
 157         /*@*/;
 158
 159 /**
 160  * Return dependency set index.
 161  * @param ds            dependency set
 162  * @return              current index
 163  */
 164 int rpmdsIx(/*@null@*/ const rpmds ds)
 165         /*@*/;
 166
 167 /**
 168  * Set dependency set index.
 169  * @param ds            dependency set
 170  * @param ix            new index
 171  * @return              current index
 172  */
 173 int rpmdsSetIx(/*@null@*/ rpmds ds, int ix)
 174         /*@modifies ds @*/;
 175
 176 /**
 177  * Return current formatted dependency string.
 178  * @param ds            dependency set
 179  * @return              current dependency DNEVR, NULL on invalid
 180  */
 181 /*@observer@*/ /*@null@*/
 182 extern const char * rpmdsDNEVR(/*@null@*/ const rpmds ds)
 183         /*@*/;
 184
 185 /**
 186  * Return current dependency name.
 187  * @param ds            dependency set
 188  * @return              current dependency name, NULL on invalid
 189  */
 190 /*@observer@*/ /*@null@*/
 191 extern const char * rpmdsN(/*@null@*/ const rpmds ds)
 192         /*@*/;
 193
 194 /**
 195  * Return current dependency epoch-version-release.
 196  * @param ds            dependency set
 197  * @return              current dependency EVR, NULL on invalid
 198  */
 199 /*@observer@*/ /*@null@*/
 200 extern const char * rpmdsEVR(/*@null@*/ const rpmds ds)
 201         /*@*/;
 202
 203 /**
 204  * Return current dependency flags.
 205  * @param ds            dependency set
 206  * @return              current dependency flags, 0 on invalid
 207  */
 208 int_32 rpmdsFlags(/*@null@*/ const rpmds ds)
 209         /*@*/;
 210
 211 /**
 212  * Return current dependency type.
 213  * @param ds            dependency set
 214  * @return              current dependency type, 0 on invalid
 215  */
 216 rpmTag rpmdsTagN(/*@null@*/ const rpmds ds)
 217         /*@*/;
 218
 219 /**
 220  * Return current "Don't promote Epoch:" flag.
 221  *
 222  * This flag controls for Epoch: promotion when a dependency set is
 223  * compared. If the flag is set (for already installed packages), then
 224  * an unspecified value will be treated as Epoch: 0. Otherwise (for added
 225  * packages), the Epoch: portion of the comparison is skipped if the value
 226  * is not specified, i.e. an unspecified Epoch: is assumed to be equal
 227  * in dependency comparisons.
 228  *
 229  * @param ds            dependency set
 230  * @return              current "Don't promote Epoch:" flag
 231  */
 232 int rpmdsNoPromote(/*@null@*/ const rpmds ds)
 233         /*@*/;
 234
 235 /**
 236  * Return current dependency color.
 237  * @param ds            dependency set
 238  * @return              current dependency color
 239  */
 240 uint_32 rpmdsColor(/*@null@*/ const rpmds ds)
 241         /*@*/;
 242
 243 /**
 244  * Return current dependency color.
 245  * @param ds            dependency set
 246  * @param color         new dependency color
 247  * @return              previous dependency color
 248  */
 249 uint_32 rpmdsSetColor(/*@null@*/ const rpmds ds, uint_32 color)
 250         /*@modifies ds @*/;
 251
 252 /**
 253  * Return current dependency file refs.
 254  * @param ds            dependency set
 255  * @return              current dependency file refs, -1 on global
 256  */
 257 int_32 rpmdsRefs(/*@null@*/ const rpmds ds)
 258         /*@*/;
 259
 260 /**
 261  * Return current dependency color.
 262  * @param ds            dependency set
 263  * @param refs          new dependency refs
 264  * @return              previous dependency refs
 265  */
 266 int_32 rpmdsSetRefs(/*@null@*/ const rpmds ds, int_32 refs)
 267         /*@modifies ds @*/;
 268
 269 /**
 270  * Set "Don't promote Epoch:" flag.
 271  * @param ds            dependency set
 272  * @param nopromote     Should an unspecified Epoch: be treated as Epoch: 0?
 273  * @return              previous "Don't promote Epoch:" flag
 274  */
 275 int rpmdsSetNoPromote(/*@null@*/ rpmds ds, int nopromote)
 276         /*@modifies ds @*/;
 277
 278 /**
 279  * Return current dependency color.
 280  * @param ds            dependency set
 281  * @return              current dependency color
 282  */
 283 uint_32 rpmdsColor(/*@null@*/ const rpmds ds)
 284         /*@*/;
 285
 286 /**
 287  * Return current dependency color.
 288  * @param ds            dependency set
 289  * @param color         new dependency color
 290  * @return              previous dependency color
 291  */
 292 uint_32 rpmdsSetColor(/*@null@*/ const rpmds ds, uint_32 color)
 293         /*@modifies ds @*/;
 294
 295 /**
 296  * Return current dependency file refs.
 297  * @param ds            dependency set
 298  * @return              current dependency file refs, -1 on global
 299  */
 300 int_32 rpmdsRefs(/*@null@*/ const rpmds ds)
 301         /*@*/;
 302
 303 /**
 304  * Return current dependency color.
 305  * @param ds            dependency set
 306  * @param refs          new dependency refs
 307  * @return              previous dependency refs
 308  */
 309 int_32 rpmdsSetRefs(/*@null@*/ const rpmds ds, int_32 refs)
 310         /*@modifies ds @*/;
 311
 312 /**
 313  * Notify of results of dependency match.
 314  * @param ds            dependency set
 315  * @param where         where dependency was resolved (or NULL)
 316  * @param rc            0 == YES, otherwise NO
 317  */
 318 /*@-globuse@*/ /* FIX: rpmMessage annotation is a lie */
 319 void rpmdsNotify(/*@null@*/ rpmds ds, /*@null@*/ const char * where, int rc)
 320         /*@globals fileSystem @*/
 321         /*@modifies fileSystem @*/;
 322 /*@=globuse@*/
 323
 324 /**
 325  * Return next dependency set iterator index.
 326  * @param ds            dependency set
 327  * @return              dependency set iterator index, -1 on termination
 328  */
 329 int rpmdsNext(/*@null@*/ rpmds ds)
 330         /*@modifies ds @*/;
 331
 332 /**
 333  * Initialize dependency set iterator.
 334  * @param ds            dependency set
 335  * @return              dependency set
 336  */
 337 /*@null@*/
 338 rpmds rpmdsInit(/*@null@*/ rpmds ds)
 339         /*@modifies ds @*/;
 340
 341 /**
 342  * Find a dependency set element using binary search.
 343  * @param ds            dependency set to search
 344  * @param ods           dependency set element to find.
 345  * @return              dependency index (or -1 if not found)
 346  */
 347 /*@null@*/
 348 int rpmdsFind(rpmds ds, /*@null@*/ rpmds ods)
 349         /*@modifies ds, ods @*/;
 350
 351 /**
 352  * Merge a dependency set maintaining (N,EVR,Flags) sorted order.
 353  * @retval *dsp         (merged) dependency set
 354  * @param ods           dependency set to merge
 355  * @return              (merged) dependency index
 356  */
 357 /*@null@*/
 358 int rpmdsMerge(/*@out@*/ rpmds * dsp, /*@null@*/ rpmds ods)
 359         /*@modifies *dsp, ods @*/;
 360
 361 /**
 362  * Compare two versioned dependency ranges, looking for overlap.
 363  * @param A             1st dependency
 364  * @param B             2nd dependency
 365  * @return              1 if dependencies overlap, 0 otherwise
 366  */
 367 int rpmdsCompare(const rpmds A, const rpmds B)
 368         /*@*/;
 369
 370 /**
 371  * Report a Requires: or Conflicts: dependency problem.
 372  * @param ps            transaction set problems
 373  * @param pkgNEVR       package name/epoch/version/release
 374  * @param ds            dependency set
 375  * @param suggestedKeys filename or python object address
 376  * @param adding        dependency problem is from added package set?
 377  */
 378 void rpmdsProblem(/*@null@*/ rpmps ps, const char * pkgNEVR, const rpmds ds,
 379                 /*@only@*/ /*@null@*/ const fnpyKey * suggestedKeys,
 380                 int adding)
 381         /*@modifies ps @*/;
 382
 383 /**
 384  * Compare package provides dependencies from header with a single dependency.
 385  * @param h             header
 386  * @param req           dependency set
 387  * @param nopromote     Don't promote Epoch: in comparison?
 388  * @return              1 if any dependency overlaps, 0 otherwise
 389  */
 390 int rpmdsAnyMatchesDep (const Header h, const rpmds req, int nopromote)
 391         /*@modifies h @*/;
 392
 393 /**
 394  * Compare package name-version-release from header with a single dependency.
 395  * @param h             header
 396  * @param req           dependency set
 397  * @param nopromote     Don't promote Epoch: in comparison?
 398  * @return              1 if dependency overlaps, 0 otherwise
 399  */
 400 int rpmdsNVRMatchesDep(const Header h, const rpmds req, int nopromote)
 401         /*@*/;
 402
 403 #ifdef __cplusplus
 404 }
 405 #endif
 406
 407 #endif  /* H_RPMDS */