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