fix: restore upgrade functionality with colors.
[platform/upstream/rpm.git] / lib / rpmte.h
1 #ifndef H_RPMTE
2 #define H_RPMTE
3
4 /** \ingroup rpmts rpmte
5  * \file lib/rpmte.h
6  * Structures used for an "rpmte" transaction element.
7  */
8
9 /**
10  */
11 /*@-exportlocal@*/
12 /*@unchecked@*/
13 extern int _rpmte_debug;
14 /*@=exportlocal@*/
15
16 /**
17  * Transaction element ordering chain linkage.
18  */
19 typedef /*@abstract@*/ struct tsortInfo_s *             tsortInfo;
20
21 /**
22  * Transaction element iterator.
23  */
24 typedef /*@abstract@*/ struct rpmtsi_s *                rpmtsi;
25
26 /** \ingroup rpmte
27  * Transaction element type.
28  */
29 typedef enum rpmElementType_e {
30     TR_ADDED            = (1 << 0),     /*!< Package will be installed. */
31     TR_REMOVED          = (1 << 1)      /*!< Package will be removed. */
32 } rpmElementType;
33
34 #if     defined(_RPMTE_INTERNAL)
35 /** \ingroup rpmte
36  * Dependncy ordering information.
37  */
38 /*@-fielduse@*/ /* LCL: confused by union? */
39 struct tsortInfo_s {
40     union {
41         int     count;
42         /*@exposed@*/ /*@dependent@*/ /*@null@*/
43         rpmte   suc;
44     } tsi_u;
45 #define tsi_count       tsi_u.count
46 #define tsi_suc         tsi_u.suc
47 /*@owned@*/ /*@null@*/
48     struct tsortInfo_s * tsi_next;
49 /*@exposed@*/ /*@dependent@*/ /*@null@*/
50     rpmte tsi_chain;
51     int         tsi_reqx;
52     int         tsi_qcnt;
53 };
54 /*@=fielduse@*/
55
56 /** \ingroup rpmte
57  * A single package instance to be installed/removed atomically.
58  */
59 struct rpmte_s {
60     rpmElementType type;        /*!< Package disposition (installed/removed). */
61
62 /*@refcounted@*/ /*@null@*/
63     Header h;                   /*!< Package header. */
64 /*@only@*/
65     const char * NEVR;          /*!< Package name-version-release. */
66 /*@owned@*/
67     const char * name;          /*!< Name: */
68 /*@only@*/ /*@null@*/
69     char * epoch;
70 /*@dependent@*/ /*@null@*/
71     char * version;             /*!< Version: */
72 /*@dependent@*/ /*@null@*/
73     char * release;             /*!< Release: */
74 /*@only@*/ /*@null@*/
75     const char * arch;          /*!< Architecture hint. */
76 /*@only@*/ /*@null@*/
77     const char * os;            /*!< Operating system hint. */
78
79     rpmte parent;               /*!< Parent transaction element. */
80     int degree;                 /*!< No. of immediate children. */
81     int depth;                  /*!< Max. depth in dependency tree. */
82     int npreds;                 /*!< No. of predecessors. */
83     int tree;                   /*!< Tree index. */
84 /*@owned@*/
85     tsortInfo tsi;              /*!< Dependency ordering chains. */
86
87 /*@refcounted@*/ /*@null@*/
88     rpmds this;                 /*!< This package's provided NEVR. */
89 /*@refcounted@*/ /*@null@*/
90     rpmds provides;             /*!< Provides: dependencies. */
91 /*@refcounted@*/ /*@null@*/
92     rpmds requires;             /*!< Requires: dependencies. */
93 /*@refcounted@*/ /*@null@*/
94     rpmds conflicts;            /*!< Conflicts: dependencies. */
95 /*@refcounted@*/ /*@null@*/
96     rpmds obsoletes;            /*!< Obsoletes: dependencies. */
97 /*@refcounted@*/ /*@null@*/
98     rpmfi fi;                   /*!< File information. */
99
100     uint_32 color;              /*!< Color bit(s) from package dependencies */
101
102 /*@exposed@*/ /*@dependent@*/ /*@null@*/
103     fnpyKey key;                /*!< (TR_ADDED) Retrieval key. */
104 /*@owned@*/ /*@null@*/
105     rpmRelocation * relocs;     /*!< (TR_ADDED) Payload file relocations. */
106 /*@refcounted@*/ /*@null@*/     
107     FD_t fd;                    /*!< (TR_ADDED) Payload file descriptor. */
108
109 /*@-fielduse@*/ /* LCL: confused by union? */
110     union { 
111 /*@exposed@*/ /*@dependent@*/ /*@null@*/
112         alKey addedKey;
113         struct {
114 /*@exposed@*/ /*@dependent@*/ /*@null@*/
115             alKey dependsOnKey;
116             int dboffset;
117         } removed;
118     } u;
119 /*@=fielduse@*/
120
121 };
122
123 /**
124  * Iterator across transaction elements, forward on install, backward on erase.
125  */
126 struct rpmtsi_s {
127 /*@refcounted@*/
128     rpmts ts;           /*!< transaction set. */
129     int reverse;        /*!< reversed traversal? */
130     int ocsave;         /*!< last returned iterator index. */
131     int oc;             /*!< iterator index. */
132 };
133
134 #endif  /* _RPMTE_INTERNAL */
135
136 #ifdef __cplusplus
137 extern "C" {
138 #endif
139
140 /**
141  * Destroy a transaction element.
142  * @param te            transaction element
143  * @return              NULL always
144  */
145 /*@null@*/
146 rpmte rpmteFree(/*@only@*/ /*@null@*/ rpmte te)
147         /*@globals fileSystem @*/
148         /*@modifies te, fileSystem @*/;
149
150 /**
151  * Create a transaction element.
152  * @param ts            transaction set
153  * @param h             header
154  * @param type          TR_ADDED/TR_REMOVED
155  * @param key           (TR_ADDED) package retrieval key (e.g. file name)
156  * @param relocs        (TR_ADDED) package file relocations
157  * @param dboffset      (TR_REMOVED) rpmdb instance
158  * @param pkgKey        associated added package (if any)
159  * @return              new transaction element
160  */
161 /*@only@*/ /*@null@*/
162 rpmte rpmteNew(const rpmts ts, Header h, rpmElementType type,
163                 /*@exposed@*/ /*@dependent@*/ /*@null@*/ fnpyKey key,
164                 /*@null@*/ rpmRelocation * relocs,
165                 int dboffset,
166                 /*@exposed@*/ /*@dependent@*/ /*@null@*/ alKey pkgKey)
167         /*@globals fileSystem @*/
168         /*@modifies ts, h, fileSystem @*/;
169
170 /**
171  * Retrieve type of transaction element.
172  * @param te            transaction element
173  * @return              type
174  */
175 rpmElementType rpmteType(rpmte te)
176         /*@*/;
177
178 /**
179  * Retrieve name string of transaction element.
180  * @param te            transaction element
181  * @return              name string
182  */
183 /*@observer@*/
184 extern const char * rpmteN(rpmte te)
185         /*@*/;
186
187 /**
188  * Retrieve epoch string of transaction element.
189  * @param te            transaction element
190  * @return              epoch string
191  */
192 /*@observer@*/ /*@null@*/
193 extern const char * rpmteE(rpmte te)
194         /*@*/;
195
196 /**
197  * Retrieve version string of transaction element.
198  * @param te            transaction element
199  * @return              version string
200  */
201 /*@observer@*/ /*@null@*/
202 extern const char * rpmteV(rpmte te)
203         /*@*/;
204
205 /**
206  * Retrieve release string of transaction element.
207  * @param te            transaction element
208  * @return              release string
209  */
210 /*@observer@*/ /*@null@*/
211 extern const char * rpmteR(rpmte te)
212         /*@*/;
213
214 /**
215  * Retrieve arch string of transaction element.
216  * @param te            transaction element
217  * @return              arch string
218  */
219 /*@observer@*/ /*@null@*/
220 extern const char * rpmteA(rpmte te)
221         /*@*/;
222
223 /**
224  * Retrieve os string of transaction element.
225  * @param te            transaction element
226  * @return              os string
227  */
228 /*@observer@*/ /*@null@*/
229 extern const char * rpmteO(rpmte te)
230         /*@*/;
231
232 /**
233  * Retrieve color bits of transaction element.
234  * @param te            transaction element
235  * @return              color bits
236  */
237 uint_32 rpmteColor(rpmte te)
238         /*@*/;
239
240 /**
241  * Set color bits of transaction element.
242  * @param te            transaction element
243  * @param color         new color bits
244  * @return              previous color bits
245  */
246 uint_32 rpmteSetColor(rpmte te, uint_32 color)
247         /*@modifies te @*/;
248
249 /**
250  * Retrieve tsort tree depth of transaction element.
251  * @param te            transaction element
252  * @return              depth
253  */
254 int rpmteDepth(rpmte te)
255         /*@*/;
256
257 /**
258  * Set tsort tree depth of transaction element.
259  * @param te            transaction element
260  * @param ndepth        new depth
261  * @return              previous depth
262  */
263 int rpmteSetDepth(rpmte te, int ndepth)
264         /*@modifies te @*/;
265
266 /**
267  * Retrieve tsort no. of predecessors of transaction element.
268  * @param te            transaction element
269  * @return              no. of predecessors
270  */
271 int rpmteNpreds(rpmte te)
272         /*@*/;
273
274 /**
275  * Set tsort no. of predecessors of transaction element.
276  * @param te            transaction element
277  * @param npreds        new no. of predecessors
278  * @return              previous no. of predecessors
279  */
280 int rpmteSetNpreds(rpmte te, int npreds)
281         /*@modifies te @*/;
282
283 /**
284  * Retrieve tree index of transaction element.
285  * @param te            transaction element
286  * @return              tree index
287  */
288 int rpmteTree(rpmte te)
289         /*@*/;
290
291 /**
292  * Set tree index of transaction element.
293  * @param te            transaction element
294  * @param ntree         new tree index
295  * @return              previous tree index
296  */
297 int rpmteSetTree(rpmte te, int ntree)
298         /*@modifies te @*/;
299
300 /**
301  * Retrieve parent transaction element.
302  * @param te            transaction element
303  * @return              parent transaction element
304  */
305 /*@observer@*/ /*@unused@*/
306 rpmte rpmteParent(rpmte te)
307         /*@*/;
308
309 /**
310  * Set parent transaction element.
311  * @param te            transaction element
312  * @param pte           new parent transaction element
313  * @return              previous parent transaction element
314  */
315 rpmte rpmteSetParent(rpmte te, rpmte pte)
316         /*@modifies te @*/;
317
318 /**
319  * Retrieve number of children of transaction element.
320  * @param te            transaction element
321  * @return              tree index
322  */
323 int rpmteDegree(rpmte te)
324         /*@*/;
325
326 /**
327  * Set number of children of transaction element.
328  * @param te            transaction element
329  * @param ndegree       new number of children
330  * @return              previous number of children
331  */
332 int rpmteSetDegree(rpmte te, int ndegree)
333         /*@modifies te @*/;
334
335 /**
336  * Retrieve tsort info for transaction element.
337  * @param te            transaction element
338  * @return              tsort info
339  */
340 tsortInfo rpmteTSI(rpmte te)
341         /*@*/;
342
343 /**
344  * Destroy tsort info of transaction element.
345  * @param te            transaction element
346  */
347 void rpmteFreeTSI(rpmte te)
348         /*@modifies te @*/;
349
350 /**
351  * Initialize tsort info of transaction element.
352  * @param te            transaction element
353  */
354 void rpmteNewTSI(rpmte te)
355         /*@modifies te @*/;
356
357 /**
358  * Destroy dependency set info of transaction element.
359  * @param te            transaction element
360  */
361 /*@unused@*/
362 void rpmteCleanDS(rpmte te)
363         /*@modifies te @*/;
364
365 /**
366  * Retrieve pkgKey of TR_ADDED transaction element.
367  * @param te            transaction element
368  * @return              pkgKey
369  */
370 /*@exposed@*/ /*@dependent@*/ /*@null@*/
371 alKey rpmteAddedKey(rpmte te)
372         /*@*/;
373
374 /**
375  * Set pkgKey of TR_ADDED transaction element.
376  * @param te            transaction element
377  * @param npkgKey       new pkgKey
378  * @return              previous pkgKey
379  */
380 /*@exposed@*/ /*@dependent@*/ /*@null@*/
381 alKey rpmteSetAddedKey(rpmte te,
382                 /*@exposed@*/ /*@dependent@*/ /*@null@*/ alKey npkgKey)
383         /*@modifies te @*/;
384
385 /**
386  * Retrieve dependent pkgKey of TR_REMOVED transaction element.
387  * @param te            transaction element
388  * @return              dependent pkgKey
389  */
390 /*@exposed@*/ /*@dependent@*/ /*@null@*/
391 alKey rpmteDependsOnKey(rpmte te)
392         /*@*/;
393
394 /**
395  * Retrieve rpmdb instance of TR_REMOVED transaction element.
396  * @param te            transaction element
397  * @return              rpmdb instance
398  */
399 int rpmteDBOffset(rpmte te)
400         /*@*/;
401
402 /**
403  * Retrieve name-version-release string from transaction element.
404  * @param te            transaction element
405  * @return              name-version-release string
406  */
407 /*@observer@*/
408 extern const char * rpmteNEVR(rpmte te)
409         /*@*/;
410
411 /**
412  * Retrieve file handle from transaction element.
413  * @param te            transaction element
414  * @return              file handle
415  */
416 FD_t rpmteFd(rpmte te)
417         /*@*/;
418
419 /**
420  * Retrieve key from transaction element.
421  * @param te            transaction element
422  * @return              key
423  */
424 /*@exposed@*/
425 fnpyKey rpmteKey(rpmte te)
426         /*@*/;
427
428 /**
429  * Retrieve dependency tag set from transaction element.
430  * @param te            transaction element
431  * @param tag           dependency tag
432  * @return              dependency tag set
433  */
434 rpmds rpmteDS(rpmte te, rpmTag tag)
435         /*@*/;
436
437 /**
438  * Retrieve file info tag set from transaction element.
439  * @param te            transaction element
440  * @param tag           file info tag (RPMTAG_BASENAMES)
441  * @return              file info tag set
442  */
443 rpmfi rpmteFI(rpmte te, rpmTag tag)
444         /*@*/;
445
446 /**
447  * Calculate transaction element dependency colors/refs from file info.
448  * @param te            transaction element
449  * @param tag           dependency tag (RPMTAG_PROVIDENAME, RPMTAG_REQUIRENAME)
450  */
451 /*@-exportlocal@*/
452 void rpmteColorDS(rpmte te, rpmTag tag)
453         /*@modifies te @*/;
454 /*@=exportlocal@*/
455
456 /**
457  * Return transaction element index.
458  * @param tsi           transaction element iterator
459  * @return              transaction element index
460  */
461 int rpmtsiOc(rpmtsi tsi)
462         /*@*/;
463
464 /**
465  * Destroy transaction element iterator.
466  * @param tsi           transaction element iterator
467  * @return              NULL always
468  */
469 /*@unused@*/ /*@null@*/
470 rpmtsi rpmtsiFree(/*@only@*//*@null@*/ rpmtsi tsi)
471         /*@globals fileSystem @*/
472         /*@modifies fileSystem @*/;
473
474 /**
475  * Destroy transaction element iterator.
476  * @param tsi           transaction element iterator
477  * @param fn
478  * @param ln
479  * @return              NULL always
480  */
481 /*@null@*/
482 rpmtsi XrpmtsiFree(/*@only@*//*@null@*/ rpmtsi tsi,
483                 const char * fn, unsigned int ln)
484         /*@globals fileSystem @*/
485         /*@modifies fileSystem @*/;
486 #define rpmtsiFree(_tsi)        XrpmtsiFree(_tsi, __FILE__, __LINE__)
487
488 /**
489  * Create transaction element iterator.
490  * @param ts            transaction set
491  * @return              transaction element iterator
492  */
493 /*@unused@*/ /*@only@*/
494 rpmtsi rpmtsiInit(rpmts ts)
495         /*@modifies ts @*/;
496
497 /**
498  * Create transaction element iterator.
499  * @param ts            transaction set
500  * @param fn
501  * @param ln
502  * @return              transaction element iterator
503  */
504 /*@unused@*/ /*@only@*/
505 rpmtsi XrpmtsiInit(rpmts ts,
506                 const char * fn, unsigned int ln)
507         /*@modifies ts @*/;
508 #define rpmtsiInit(_ts)         XrpmtsiInit(_ts, __FILE__, __LINE__)
509
510 /**
511  * Return next transaction element of type.
512  * @param tsi           transaction element iterator
513  * @param type          transaction element type selector (0 for any)
514  * @return              next transaction element of type, NULL on termination
515  */
516 /*@dependent@*/ /*@null@*/
517 rpmte rpmtsiNext(rpmtsi tsi, rpmElementType type)
518         /*@modifies tsi @*/;
519
520 #ifdef __cplusplus
521 }
522 #endif
523
524 #endif  /* H_RPMTE */