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