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