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 scareMem      Use pointers to refcounted header memory?
 114  * @return              new dependency set
 115  */
 116 /*@null@*/
 117 rpmds rpmdsNew(Header h, rpmTag tagN, int scareMem)
 118         /*@modifies h @*/;
 119
 120 /**
 121  * Return new formatted dependency string.
 122  * @param dspfx         formatted dependency string prefix
 123  * @param ds            dependency set
 124  * @return              new formatted dependency (malloc'ed)
 125  */
 126 /*@only@*/
 127 char * rpmdsNewDNEVR(const char * dspfx, const rpmds ds)
 128         /*@*/;
 129
 130 /**
 131  * Create, load and initialize a dependency for this header.
 132  * @param h             header
 133  * @param tagN          type of dependency
 134  * @param Flags         comparison flags
 135  * @return              new dependency set
 136  */
 137 /*@null@*/
 138 rpmds rpmdsThis(Header h, rpmTag tagN, int_32 Flags)
 139         /*@*/;
 140
 141 /**
 142  * Create, load and initialize a dependency set of size 1.
 143  * @param tagN          type of dependency
 144  * @param N             name
 145  * @param EVR           epoch:version-release
 146  * @param Flags         comparison flags
 147  * @return              new dependency set
 148  */
 149 /*@null@*/
 150 rpmds rpmdsSingle(rpmTag tagN, const char * N, const char * EVR, int_32 Flags)
 151         /*@*/;
 152
 153 /**
 154  * Return dependency set count.
 155  * @param ds            dependency set
 156  * @return              current count
 157  */
 158 int rpmdsCount(/*@null@*/ const rpmds ds)
 159         /*@*/;
 160
 161 /**
 162  * Return dependency set index.
 163  * @param ds            dependency set
 164  * @return              current index
 165  */
 166 int rpmdsIx(/*@null@*/ const rpmds ds)
 167         /*@*/;
 168
 169 /**
 170  * Set dependency set index.
 171  * @param ds            dependency set
 172  * @param ix            new index
 173  * @return              current index
 174  */
 175 int rpmdsSetIx(/*@null@*/ rpmds ds, int ix)
 176         /*@modifies ds @*/;
 177
 178 /**
 179  * Return current formatted dependency string.
 180  * @param ds            dependency set
 181  * @return              current dependency DNEVR, NULL on invalid
 182  */
 183 /*@observer@*/ /*@null@*/
 184 extern const char * rpmdsDNEVR(/*@null@*/ const rpmds ds)
 185         /*@*/;
 186
 187 /**
 188  * Return current dependency name.
 189  * @param ds            dependency set
 190  * @return              current dependency name, NULL on invalid
 191  */
 192 /*@observer@*/ /*@null@*/
 193 extern const char * rpmdsN(/*@null@*/ const rpmds ds)
 194         /*@*/;
 195
 196 /**
 197  * Return current dependency epoch-version-release.
 198  * @param ds            dependency set
 199  * @return              current dependency EVR, NULL on invalid
 200  */
 201 /*@observer@*/ /*@null@*/
 202 extern const char * rpmdsEVR(/*@null@*/ const rpmds ds)
 203         /*@*/;
 204
 205 /**
 206  * Return current dependency flags.
 207  * @param ds            dependency set
 208  * @return              current dependency flags, 0 on invalid
 209  */
 210 int_32 rpmdsFlags(/*@null@*/ const rpmds ds)
 211         /*@*/;
 212
 213 /**
 214  * Return current dependency type.
 215  * @param ds            dependency set
 216  * @return              current dependency type, 0 on invalid
 217  */
 218 rpmTag rpmdsTagN(/*@null@*/ const rpmds ds)
 219         /*@*/;
 220
 221 /**
 222  * Return dependency build time.
 223  * @param ds            dependency set
 224  * @return              dependency build time, 0 on invalid
 225  */
 226 time_t rpmdsBT(/*@null@*/ const rpmds ds)
 227         /*@*/;
 228
 229 /**
 230  * Set dependency build time.
 231  * @param ds            dependency set
 232  * @return              dependency build time, 0 on invalid
 233  */
 234 time_t rpmdsSetBT(/*@null@*/ const rpmds ds, time_t BT)
 235         /*@modifies ds @*/;
 236
 237 /**
 238  * Return current "Don't promote Epoch:" flag.
 239  *
 240  * This flag controls for Epoch: promotion when a dependency set is
 241  * compared. If the flag is set (for already installed packages), then
 242  * an unspecified value will be treated as Epoch: 0. Otherwise (for added
 243  * packages), the Epoch: portion of the comparison is skipped if the value
 244  * is not specified, i.e. an unspecified Epoch: is assumed to be equal
 245  * in dependency comparisons.
 246  *
 247  * @param ds            dependency set
 248  * @return              current "Don't promote Epoch:" flag
 249  */
 250 int rpmdsNoPromote(/*@null@*/ const rpmds ds)
 251         /*@*/;
 252
 253 /**
 254  * Set "Don't promote Epoch:" flag.
 255  * @param ds            dependency set
 256  * @param nopromote     Should an unspecified Epoch: be treated as Epoch: 0?
 257  * @return              previous "Don't promote Epoch:" flag
 258  */
 259 int rpmdsSetNoPromote(/*@null@*/ rpmds ds, int nopromote)
 260         /*@modifies ds @*/;
 261
 262 /**
 263  * Return current dependency color.
 264  * @param ds            dependency set
 265  * @return              current dependency color
 266  */
 267 uint_32 rpmdsColor(/*@null@*/ const rpmds ds)
 268         /*@*/;
 269
 270 /**
 271  * Return current dependency color.
 272  * @param ds            dependency set
 273  * @param color         new dependency color
 274  * @return              previous dependency color
 275  */
 276 uint_32 rpmdsSetColor(/*@null@*/ const rpmds ds, uint_32 color)
 277         /*@modifies ds @*/;
 278
 279 /**
 280  * Return current dependency file refs.
 281  * @param ds            dependency set
 282  * @return              current dependency file refs, -1 on global
 283  */
 284 int_32 rpmdsRefs(/*@null@*/ const rpmds ds)
 285         /*@*/;
 286
 287 /**
 288  * Return current dependency color.
 289  * @param ds            dependency set
 290  * @param refs          new dependency refs
 291  * @return              previous dependency refs
 292  */
 293 int_32 rpmdsSetRefs(/*@null@*/ const rpmds ds, int_32 refs)
 294         /*@modifies ds @*/;
 295
 296 /**
 297  * Notify of results of dependency match.
 298  * @param ds            dependency set
 299  * @param where         where dependency was resolved (or NULL)
 300  * @param rc            0 == YES, otherwise NO
 301  */
 302 /*@-globuse@*/ /* FIX: rpmMessage annotation is a lie */
 303 void rpmdsNotify(/*@null@*/ rpmds ds, /*@null@*/ const char * where, int rc)
 304         /*@globals fileSystem @*/
 305         /*@modifies fileSystem @*/;
 306 /*@=globuse@*/
 307
 308 /**
 309  * Return next dependency set iterator index.
 310  * @param ds            dependency set
 311  * @return              dependency set iterator index, -1 on termination
 312  */
 313 int rpmdsNext(/*@null@*/ rpmds ds)
 314         /*@modifies ds @*/;
 315
 316 /**
 317  * Initialize dependency set iterator.
 318  * @param ds            dependency set
 319  * @return              dependency set
 320  */
 321 /*@null@*/
 322 rpmds rpmdsInit(/*@null@*/ rpmds ds)
 323         /*@modifies ds @*/;
 324
 325 /**
 326  * Find a dependency set element using binary search.
 327  * @param ds            dependency set to search
 328  * @param ods           dependency set element to find.
 329  * @return              dependency index (or -1 if not found)
 330  */
 331 /*@null@*/
 332 int rpmdsFind(rpmds ds, /*@null@*/ rpmds ods)
 333         /*@modifies ds, ods @*/;
 334
 335 /**
 336  * Merge a dependency set maintaining (N,EVR,Flags) sorted order.
 337  * @retval *dsp         (merged) dependency set
 338  * @param ods           dependency set to merge
 339  * @return              (merged) dependency index
 340  */
 341 /*@null@*/
 342 int rpmdsMerge(/*@out@*/ rpmds * dsp, /*@null@*/ rpmds ods)
 343         /*@modifies *dsp, ods @*/;
 344
 345 /**
 346  * Compare two versioned dependency ranges, looking for overlap.
 347  * @param A             1st dependency
 348  * @param B             2nd dependency
 349  * @return              1 if dependencies overlap, 0 otherwise
 350  */
 351 int rpmdsCompare(const rpmds A, const rpmds B)
 352         /*@*/;
 353
 354 /**
 355  * Report a Requires: or Conflicts: dependency problem.
 356  * @param ps            transaction set problems
 357  * @param pkgNEVR       package name/epoch/version/release
 358  * @param ds            dependency set
 359  * @param suggestedKeys filename or python object address
 360  * @param adding        dependency problem is from added package set?
 361  */
 362 void rpmdsProblem(/*@null@*/ rpmps ps, const char * pkgNEVR, const rpmds ds,
 363                 /*@only@*/ /*@null@*/ const fnpyKey * suggestedKeys,
 364                 int adding)
 365         /*@modifies ps @*/;
 366
 367 /**
 368  * Compare package provides dependencies from header with a single dependency.
 369  * @param h             header
 370  * @param req           dependency set
 371  * @param nopromote     Don't promote Epoch: in comparison?
 372  * @return              1 if any dependency overlaps, 0 otherwise
 373  */
 374 int rpmdsAnyMatchesDep (const Header h, const rpmds req, int nopromote)
 375         /*@modifies h @*/;
 376
 377 /**
 378  * Compare package name-version-release from header with a single dependency.
 379  * @param h             header
 380  * @param req           dependency set
 381  * @param nopromote     Don't promote Epoch: in comparison?
 382  * @return              1 if dependency overlaps, 0 otherwise
 383  */
 384 int rpmdsNVRMatchesDep(const Header h, const rpmds req, int nopromote)
 385         /*@*/;
 386
 387 #ifdef __cplusplus
 388 }
 389 #endif
 390
 391 #endif  /* H_RPMDS */