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  * @param BT            build time
 234  * @return              dependency build time, 0 on invalid
 235  */
 236 time_t rpmdsSetBT(/*@null@*/ const rpmds ds, time_t BT)
 237         /*@modifies ds @*/;
 238
 239 /**
 240  * Return current "Don't promote Epoch:" flag.
 241  *
 242  * This flag controls for Epoch: promotion when a dependency set is
 243  * compared. If the flag is set (for already installed packages), then
 244  * an unspecified value will be treated as Epoch: 0. Otherwise (for added
 245  * packages), the Epoch: portion of the comparison is skipped if the value
 246  * is not specified, i.e. an unspecified Epoch: is assumed to be equal
 247  * in dependency comparisons.
 248  *
 249  * @param ds            dependency set
 250  * @return              current "Don't promote Epoch:" flag
 251  */
 252 int rpmdsNoPromote(/*@null@*/ const rpmds ds)
 253         /*@*/;
 254
 255 /**
 256  * Set "Don't promote Epoch:" flag.
 257  * @param ds            dependency set
 258  * @param nopromote     Should an unspecified Epoch: be treated as Epoch: 0?
 259  * @return              previous "Don't promote Epoch:" flag
 260  */
 261 int rpmdsSetNoPromote(/*@null@*/ rpmds ds, int nopromote)
 262         /*@modifies ds @*/;
 263
 264 /**
 265  * Return current dependency color.
 266  * @param ds            dependency set
 267  * @return              current dependency color
 268  */
 269 uint_32 rpmdsColor(/*@null@*/ const rpmds ds)
 270         /*@*/;
 271
 272 /**
 273  * Return current dependency color.
 274  * @param ds            dependency set
 275  * @param color         new dependency color
 276  * @return              previous dependency color
 277  */
 278 uint_32 rpmdsSetColor(/*@null@*/ const rpmds ds, uint_32 color)
 279         /*@modifies ds @*/;
 280
 281 /**
 282  * Return current dependency file refs.
 283  * @param ds            dependency set
 284  * @return              current dependency file refs, -1 on global
 285  */
 286 int_32 rpmdsRefs(/*@null@*/ const rpmds ds)
 287         /*@*/;
 288
 289 /**
 290  * Return current dependency color.
 291  * @param ds            dependency set
 292  * @param refs          new dependency refs
 293  * @return              previous dependency refs
 294  */
 295 int_32 rpmdsSetRefs(/*@null@*/ const rpmds ds, int_32 refs)
 296         /*@modifies ds @*/;
 297
 298 /**
 299  * Notify of results of dependency match.
 300  * @param ds            dependency set
 301  * @param where         where dependency was resolved (or NULL)
 302  * @param rc            0 == YES, otherwise NO
 303  */
 304 /*@-globuse@*/ /* FIX: rpmMessage annotation is a lie */
 305 void rpmdsNotify(/*@null@*/ rpmds ds, /*@null@*/ const char * where, int rc)
 306         /*@globals fileSystem @*/
 307         /*@modifies fileSystem @*/;
 308 /*@=globuse@*/
 309
 310 /**
 311  * Return next dependency set iterator index.
 312  * @param ds            dependency set
 313  * @return              dependency set iterator index, -1 on termination
 314  */
 315 int rpmdsNext(/*@null@*/ rpmds ds)
 316         /*@modifies ds @*/;
 317
 318 /**
 319  * Initialize dependency set iterator.
 320  * @param ds            dependency set
 321  * @return              dependency set
 322  */
 323 /*@null@*/
 324 rpmds rpmdsInit(/*@null@*/ rpmds ds)
 325         /*@modifies ds @*/;
 326
 327 /**
 328  * Find a dependency set element using binary search.
 329  * @param ds            dependency set to search
 330  * @param ods           dependency set element to find.
 331  * @return              dependency index (or -1 if not found)
 332  */
 333 /*@null@*/
 334 int rpmdsFind(rpmds ds, /*@null@*/ rpmds ods)
 335         /*@modifies ds, ods @*/;
 336
 337 /**
 338  * Merge a dependency set maintaining (N,EVR,Flags) sorted order.
 339  * @retval *dsp         (merged) dependency set
 340  * @param ods           dependency set to merge
 341  * @return              (merged) dependency index
 342  */
 343 /*@null@*/
 344 int rpmdsMerge(/*@out@*/ rpmds * dsp, /*@null@*/ rpmds ods)
 345         /*@modifies *dsp, ods @*/;
 346
 347 /**
 348  * Compare two versioned dependency ranges, looking for overlap.
 349  * @param A             1st dependency
 350  * @param B             2nd dependency
 351  * @return              1 if dependencies overlap, 0 otherwise
 352  */
 353 int rpmdsCompare(const rpmds A, const rpmds B)
 354         /*@*/;
 355
 356 /**
 357  * Report a Requires: or Conflicts: dependency problem.
 358  * @param ps            transaction set problems
 359  * @param pkgNEVR       package name/epoch/version/release
 360  * @param ds            dependency set
 361  * @param suggestedKeys filename or python object address
 362  * @param adding        dependency problem is from added package set?
 363  */
 364 void rpmdsProblem(/*@null@*/ rpmps ps, const char * pkgNEVR, const rpmds ds,
 365                 /*@only@*/ /*@null@*/ const fnpyKey * suggestedKeys,
 366                 int adding)
 367         /*@modifies ps @*/;
 368
 369 /**
 370  * Compare package provides dependencies from header with a single dependency.
 371  * @param h             header
 372  * @param req           dependency set
 373  * @param nopromote     Don't promote Epoch: in comparison?
 374  * @return              1 if any dependency overlaps, 0 otherwise
 375  */
 376 int rpmdsAnyMatchesDep (const Header h, const rpmds req, int nopromote)
 377         /*@globals rpmGlobalMacroContext, h_errno, fileSystem, internalState @*/
 378         /*@modifies h, rpmGlobalMacroContext, fileSystem, internalState @*/;
 379
 380 /**
 381  * Compare package name-version-release from header with a single dependency.
 382  * @param h             header
 383  * @param req           dependency set
 384  * @param nopromote     Don't promote Epoch: in comparison?
 385  * @return              1 if dependency overlaps, 0 otherwise
 386  */
 387 int rpmdsNVRMatchesDep(const Header h, const rpmds req, int nopromote)
 388         /*@*/;
 389
 390 #ifdef __cplusplus
 391 }
 392 #endif
 393
 394 #endif  /* H_RPMDS */