lib/rpmts.h

   1 #ifndef H_RPMTS
   2 #define H_RPMTS
   3
   4 /** \ingroup rpmts
   5  * \file lib/rpmts.h
   6  * Structures and prototypes used for an "rpmts" transaction set.
   7  */
   8
   9 #include <sys/types.h>
  10
  11 #include <rpm/rpmtypes.h>
  12 #include <rpm/rpmte.h>
  13 #include <rpm/rpmps.h>
  14 #include <rpm/rpmsw.h>
  15 #include <rpm/rpmpgp.h>
  16 #include <rpm/rpmfi.h>
  17 #include <rpm/rpmcallback.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 extern int _rpmts_stats;
  24
  25 /** \ingroup rpmts
  26  * Bit(s) to control rpmtsRun() operation.
  27  */
  28 enum rpmtransFlags_e {
  29     RPMTRANS_FLAG_NONE          = 0,
  30     RPMTRANS_FLAG_TEST          = (1 <<  0),    /*!< from --test */
  31     RPMTRANS_FLAG_BUILD_PROBS   = (1 <<  1),    /*!< don't process payload */
  32     RPMTRANS_FLAG_NOSCRIPTS     = (1 <<  2),    /*!< from --noscripts */
  33     RPMTRANS_FLAG_JUSTDB        = (1 <<  3),    /*!< from --justdb */
  34     RPMTRANS_FLAG_NOTRIGGERS    = (1 <<  4),    /*!< from --notriggers */
  35     RPMTRANS_FLAG_NODOCS        = (1 <<  5),    /*!< from --excludedocs */
  36     RPMTRANS_FLAG_ALLFILES      = (1 <<  6),    /*!< from --allfiles */
  37     /* bit 7 unused */
  38     RPMTRANS_FLAG_NOCONTEXTS    = (1 <<  8),    /*!< from --nocontexts */
  39     /* bits 9-15 unused */
  40     RPMTRANS_FLAG_NOTRIGGERPREIN= (1 << 16),    /*!< from --notriggerprein */
  41     RPMTRANS_FLAG_NOPRE         = (1 << 17),    /*!< from --nopre */
  42     RPMTRANS_FLAG_NOPOST        = (1 << 18),    /*!< from --nopost */
  43     RPMTRANS_FLAG_NOTRIGGERIN   = (1 << 19),    /*!< from --notriggerin */
  44     RPMTRANS_FLAG_NOTRIGGERUN   = (1 << 20),    /*!< from --notriggerun */
  45     RPMTRANS_FLAG_NOPREUN       = (1 << 21),    /*!< from --nopreun */
  46     RPMTRANS_FLAG_NOPOSTUN      = (1 << 22),    /*!< from --nopostun */
  47     RPMTRANS_FLAG_NOTRIGGERPOSTUN = (1 << 23),  /*!< from --notriggerpostun */
  48     /* bits 24-25 unused */
  49     RPMTRANS_FLAG_NOCOLLECTIONS = (1 << 26),    /*!< from --nocollections */
  50     RPMTRANS_FLAG_NOMD5         = (1 << 27),    /*!< from --nomd5 */
  51     RPMTRANS_FLAG_NOFILEDIGEST  = (1 << 27),    /*!< from --nofiledigest (alias to --nomd5) */
  52     /* bits 28-29 unused */
  53     RPMTRANS_FLAG_NOCONFIGS     = (1 << 30),    /*!< from --noconfigs */
  54     RPMTRANS_FLAG_DEPLOOPS      = (1 << 31)     /*!< from --deploops */
  55 };
  56
  57 typedef rpmFlags rpmtransFlags;
  58
  59 #define _noTransScripts         \
  60   ( RPMTRANS_FLAG_NOPRE |       \
  61     RPMTRANS_FLAG_NOPOST |      \
  62     RPMTRANS_FLAG_NOPREUN |     \
  63     RPMTRANS_FLAG_NOPOSTUN      \
  64   )
  65
  66 #define _noTransTriggers        \
  67   ( RPMTRANS_FLAG_NOTRIGGERPREIN | \
  68     RPMTRANS_FLAG_NOTRIGGERIN | \
  69     RPMTRANS_FLAG_NOTRIGGERUN | \
  70     RPMTRANS_FLAG_NOTRIGGERPOSTUN \
  71   )
  72
  73 /* Avoid unnecessary breakage for stuff referring to these unused flags */
  74 #define RPMTRANS_FLAG_NOPAYLOAD 0
  75 #define RPMTRANS_FLAG_APPLYONLY 0
  76 #define RPMTRANS_FLAG_KEEPOBSOLETE 0
  77 #define RPMTRANS_FLAG_DIRSTASH 0
  78 #define RPMTRANS_FLAG_REPACKAGE 0
  79 #define RPMTRANS_FLAG_PKGCOMMIT 0
  80 #define RPMTRANS_FLAG_PKGUNDO 0
  81 #define RPMTRANS_FLAG_COMMIT 0
  82 #define RPMTRANS_FLAG_UNDO 0
  83 #define RPMTRANS_FLAG_REVERSE 0
  84 #define RPMTRANS_FLAG_NOSUGGEST 0
  85 #define RPMTRANS_FLAG_ADDINDEPS 0
  86
  87 /** \ingroup rpmts
  88  * Bit(s) to control digest and signature verification.
  89  */
  90 enum rpmVSFlags_e {
  91     RPMVSF_DEFAULT      = 0,
  92     RPMVSF_NOHDRCHK     = (1 <<  0),
  93     RPMVSF_NEEDPAYLOAD  = (1 <<  1),
  94     /* bit(s) 2-7 unused */
  95     RPMVSF_NOSHA1HEADER = (1 <<  8),
  96     RPMVSF_NOMD5HEADER  = (1 <<  9),    /* unimplemented */
  97     RPMVSF_NODSAHEADER  = (1 << 10),
  98     RPMVSF_NORSAHEADER  = (1 << 11),    /* unimplemented */
  99     /* bit(s) 12-15 unused */
 100     RPMVSF_NOSHA1       = (1 << 16),    /* unimplemented */
 101     RPMVSF_NOMD5        = (1 << 17),
 102     RPMVSF_NODSA        = (1 << 18),
 103     RPMVSF_NORSA        = (1 << 19)
 104     /* bit(s) 16-31 unused */
 105 };
 106
 107 typedef rpmFlags rpmVSFlags;
 108
 109 #define _RPMVSF_NODIGESTS       \
 110   ( RPMVSF_NOSHA1HEADER |       \
 111     RPMVSF_NOMD5HEADER |        \
 112     RPMVSF_NOSHA1 |             \
 113     RPMVSF_NOMD5 )
 114
 115 #define _RPMVSF_NOSIGNATURES    \
 116   ( RPMVSF_NODSAHEADER |        \
 117     RPMVSF_NORSAHEADER |        \
 118     RPMVSF_NODSA |              \
 119     RPMVSF_NORSA )
 120
 121 #define _RPMVSF_NOHEADER        \
 122   ( RPMVSF_NOSHA1HEADER |       \
 123     RPMVSF_NOMD5HEADER |        \
 124     RPMVSF_NODSAHEADER |        \
 125     RPMVSF_NORSAHEADER )
 126
 127 #define _RPMVSF_NOPAYLOAD       \
 128   ( RPMVSF_NOSHA1 |             \
 129     RPMVSF_NOMD5 |              \
 130     RPMVSF_NODSA |              \
 131     RPMVSF_NORSA )
 132
 133 /** \ingroup rpmts
 134  * Indices for timestamps.
 135  */
 136 typedef enum rpmtsOpX_e {
 137     RPMTS_OP_TOTAL              =  0,
 138     RPMTS_OP_CHECK              =  1,
 139     RPMTS_OP_ORDER              =  2,
 140     RPMTS_OP_FINGERPRINT        =  3,
 141     RPMTS_OP_INSTALL            =  5,
 142     RPMTS_OP_ERASE              =  6,
 143     RPMTS_OP_SCRIPTLETS         =  7,
 144     RPMTS_OP_COMPRESS           =  8,
 145     RPMTS_OP_UNCOMPRESS         =  9,
 146     RPMTS_OP_DIGEST             = 10,
 147     RPMTS_OP_SIGNATURE          = 11,
 148     RPMTS_OP_DBADD              = 12,
 149     RPMTS_OP_DBREMOVE           = 13,
 150     RPMTS_OP_DBGET              = 14,
 151     RPMTS_OP_DBPUT              = 15,
 152     RPMTS_OP_DBDEL              = 16,
 153     RPMTS_OP_MAX                = 17
 154 } rpmtsOpX;
 155
 156 /** \ingroup rpmts
 157  * Perform dependency resolution on the transaction set.
 158  *
 159  * Any problems found by rpmtsCheck() can be examined by retrieving the
 160  * problem set with rpmtsProblems(), success here only means that
 161  * the resolution was successfully attempted for all packages in the set.
 162  *
 163  * @param ts            transaction set
 164  * @return              0 on success
 165  */
 166 int rpmtsCheck(rpmts ts);
 167
 168 /** \ingroup rpmts
 169  * Determine package order in a transaction set according to dependencies.
 170  *
 171  * Order packages, returning error if circular dependencies cannot be
 172  * eliminated by removing Requires's from the loop(s). Only dependencies from
 173  * added or removed packages are used to determine ordering using a
 174  * topological sort (Knuth vol. 1, p. 262). Use rpmtsCheck() to verify
 175  * that all dependencies can be resolved.
 176  *
 177  * The final order ends up as installed packages followed by removed packages,
 178  * with packages removed for upgrades immediately following the new package
 179  * to be installed.
 180  *
 181  * @param ts            transaction set
 182  * @return              no. of (added) packages that could not be ordered
 183  */
 184 int rpmtsOrder(rpmts ts);
 185
 186 /** \ingroup rpmts
 187  * Process all package elements in a transaction set.  Before calling
 188  * rpmtsRun be sure to have:
 189  *
 190  *    - setup the rpm root dir via rpmtsSetRoot().
 191  *    - setup the rpm notify callback via rpmtsSetNotifyCallback().
 192  *    - setup the rpm transaction flags via rpmtsSetFlags().
 193  *
 194  * Additionally, though not required you may want to:
 195  *
 196  *    - setup the rpm verify signature flags via rpmtsSetVSFlags().
 197  *
 198  * @param ts            transaction set
 199  * @param okProbs       unused
 200  * @param ignoreSet     bits to filter problem types
 201  * @return              0 on success, -1 on error, >0 with newProbs set
 202  */
 203 int rpmtsRun(rpmts ts, rpmps okProbs, rpmprobFilterFlags ignoreSet);
 204
 205 /** \ingroup rpmts
 206  * Reference a transaction set instance.
 207  * @param ts            transaction set
 208  * @return              new transaction set reference
 209  */
 210 rpmts rpmtsLink (rpmts ts);
 211
 212 /** \ingroup rpmts
 213  * Close the database used by the transaction.
 214  * @param ts            transaction set
 215  * @return              0 on success
 216  */
 217 int rpmtsCloseDB(rpmts ts);
 218
 219 /** \ingroup rpmts
 220  * Open the database used by the transaction.
 221  * @param ts            transaction set
 222  * @param dbmode        O_RDONLY or O_RDWR
 223  * @return              0 on success
 224  */
 225 int rpmtsOpenDB(rpmts ts, int dbmode);
 226
 227 /** \ingroup rpmts
 228  * Initialize the database used by the transaction.
 229  * @deprecated An explicit rpmdbInit() is almost never needed.
 230  * @param ts            transaction set
 231  * @param dbmode        O_RDONLY or O_RDWR
 232  * @return              0 on success
 233  */
 234 int rpmtsInitDB(rpmts ts, int dbmode);
 235
 236 /** \ingroup rpmts
 237  * Return the transaction database mode
 238  * @param ts            transaction set
 239  * @return              O_RDONLY, O_RDWR or -1 (lazy opens disabled)
 240  */
 241 int rpmtsGetDBMode(rpmts ts);
 242
 243 /** \ingroup rpmts
 244  * Set the transaction database mode. Only permitted when when backing
 245  * database hasn't been opened yet (ie rpmtsGetRdb(ts) == NULL)
 246  * @param ts            transaction set
 247  * @param dbmode        O_RDONLY, O_RDWR or -1 (disable lazy opens)
 248  * @return              0 on success, 1 on error
 249  */
 250 int rpmtsSetDBMode(rpmts ts, int dbmode);
 251
 252 /** \ingroup rpmts
 253  * Rebuild the database used by the transaction.
 254  * @param ts            transaction set
 255  * @return              0 on success
 256  */
 257 int rpmtsRebuildDB(rpmts ts);
 258
 259 /** \ingroup rpmts
 260  * Verify the database used by the transaction.
 261  * @param ts            transaction set
 262  * @return              0 on success
 263  */
 264 int rpmtsVerifyDB(rpmts ts);
 265
 266 /** \ingroup rpmts
 267  * Return transaction database iterator.
 268  * @param ts            transaction set
 269  * @param rpmtag        database index tag
 270  * @param keyp          key data (NULL for sequential access)
 271  * @param keylen        key data length (0 will use strlen(keyp))
 272  * @return              NULL on failure
 273  */
 274 rpmdbMatchIterator rpmtsInitIterator(const rpmts ts, rpmDbiTagVal rpmtag,
 275                         const void * keyp, size_t keylen);
 276
 277 /** \ingroup rpmts
 278  * Import public key packet(s).
 279  * @todo Implicit --update policy for gpg-pubkey headers.
 280  * @param ts            transaction set
 281  * @param pkt           pgp pubkey packet(s)
 282  * @param pktlen        pgp pubkey length
 283  * @return              RPMRC_OK/RPMRC_FAIL
 284  */
 285 rpmRC rpmtsImportPubkey(rpmts ts, const unsigned char * pkt, size_t pktlen);
 286
 287 /** \ingroup rpmts
 288  * Retrieve handle for keyring used for this transaction set
 289  * @param ts            transaction set
 290  * @param autoload      load default keyring if keyring is not set
 291  * @return              keyring handle (or NULL)
 292  */
 293 rpmKeyring rpmtsGetKeyring(rpmts ts, int autoload);
 294
 295 /** \ingroup rpmts
 296  * Set keyring to use for this transaction set.
 297  * Keyring can be only changed while the underlying rpm database is not
 298  * yet open.
 299  * @param ts            transaction set
 300  * @param keyring       keyring handle (NULL to free current keyring)
 301  * @return              0 on success, -1 on error
 302  */
 303 int rpmtsSetKeyring(rpmts ts, rpmKeyring keyring);
 304
 305 /** \ingroup rpmts
 306  * Set dependency solver callback.
 307  * @param ts            transaction set
 308  * @param (*solve)      dependency solver callback
 309  * @param solveData     dependency solver callback data (opaque)
 310  * @return              0 on success
 311  */
 312 int rpmtsSetSolveCallback(rpmts ts,
 313                 int (*solve) (rpmts ts, rpmds ds, const void * data),
 314                 const void * solveData);
 315
 316 /** \ingroup rpmts
 317  * Return current transaction set problems.
 318  * @param ts            transaction set
 319  * @return              current problem set (or NULL if no problems)
 320  */
 321 rpmps rpmtsProblems(rpmts ts);
 322
 323 /** \ingroup rpmts
 324  * Clean current transaction problem set.
 325  * @param ts            transaction set
 326  */
 327 void rpmtsCleanProblems(rpmts ts);
 328
 329 /** \ingroup rpmts
 330  * Free memory needed only for dependency checks and ordering.
 331  * @param ts            transaction set
 332  */
 333 void rpmtsClean(rpmts ts);
 334
 335 /** \ingroup rpmts
 336  * Re-create an empty transaction set.
 337  * @param ts            transaction set
 338  */
 339 void rpmtsEmpty(rpmts ts);
 340
 341 /** \ingroup rpmts
 342  * Destroy transaction set, closing the database as well.
 343  * @param ts            transaction set
 344  * @return              NULL always
 345  */
 346 rpmts rpmtsFree(rpmts ts);
 347
 348 /** \ingroup rpmts
 349  * Get verify signatures flag(s).
 350  * @param ts            transaction set
 351  * @return              verify signatures flags
 352  */
 353 rpmVSFlags rpmtsVSFlags(rpmts ts);
 354
 355 /** \ingroup rpmts
 356  * Set verify signatures flag(s).
 357  * @param ts            transaction set
 358  * @param vsflags       new verify signatures flags
 359  * @return              previous value
 360  */
 361 rpmVSFlags rpmtsSetVSFlags(rpmts ts, rpmVSFlags vsflags);
 362
 363 /** \ingroup rpmts
 364  * Get transaction rootDir, i.e. path to chroot(2).
 365  * @param ts            transaction set
 366  * @return              transaction rootDir
 367  */
 368 const char * rpmtsRootDir(rpmts ts);
 369
 370 /** \ingroup rpmts
 371  * Set transaction rootDir, i.e. path to chroot(2).
 372  * @param ts            transaction set
 373  * @param rootDir       new transaction rootDir (or NULL)
 374  * @return              0 on success, -1 on error (invalid rootDir)
 375  */
 376 int rpmtsSetRootDir(rpmts ts, const char * rootDir);
 377
 378 /** \ingroup rpmts
 379  * Get transaction script file handle, i.e. stdout/stderr on scriptlet execution
 380  * @param ts            transaction set
 381  * @return              transaction script file handle
 382  */
 383 FD_t rpmtsScriptFd(rpmts ts);
 384
 385 /** \ingroup rpmts
 386  * Set transaction script file handle, i.e. stdout/stderr on scriptlet execution
 387  * @param ts            transaction set
 388  * @param scriptFd      new script file handle (or NULL)
 389  */
 390 void rpmtsSetScriptFd(rpmts ts, FD_t scriptFd);
 391
 392 /** \ingroup rpmts
 393  * Get transaction id, i.e. transaction time stamp.
 394  * @param ts            transaction set
 395  * @return              transaction id
 396  */
 397 rpm_tid_t rpmtsGetTid(rpmts ts);
 398
 399 /** \ingroup rpmts
 400  * Set transaction id, i.e. transaction time stamp.
 401  * @param ts            transaction set
 402  * @param tid           new transaction id
 403  * @return              previous transaction id
 404  */
 405 rpm_tid_t rpmtsSetTid(rpmts ts, rpm_tid_t tid);
 406
 407 /** \ingroup rpmts
 408  * Get transaction set database handle.
 409  * @param ts            transaction set
 410  * @return              transaction database handle
 411  */
 412 rpmdb rpmtsGetRdb(rpmts ts);
 413
 414 /** \ingroup rpmts
 415  * Perform transaction progress notify callback.
 416  * @param ts            transaction set
 417  * @param te            current transaction element
 418  * @param what          type of call back
 419  * @param amount        current value
 420  * @param total         final value
 421  * @return              callback dependent pointer
 422  */
 423 void * rpmtsNotify(rpmts ts, rpmte te,
 424                 rpmCallbackType what, rpm_loff_t amount, rpm_loff_t total);
 425
 426 int rpmtsSuspendResumeDBLock(rpmts ts, int mode);
 427
 428 /** \ingroup rpmts
 429  * Return number of (ordered) transaction set elements.
 430  * @param ts            transaction set
 431  * @return              no. of transaction set elements
 432  */
 433 int rpmtsNElements(rpmts ts);
 434
 435 /** \ingroup rpmts
 436  * Return (ordered) transaction set element.
 437  * @param ts            transaction set
 438  * @param ix            transaction element index
 439  * @return              transaction element (or NULL)
 440  */
 441 rpmte rpmtsElement(rpmts ts, int ix);
 442
 443 /** \ingroup rpmts
 444  * Get problem ignore bit mask, i.e. bits to filter encountered problems.
 445  * @param ts            transaction set
 446  * @return              ignore bit mask
 447  */
 448 rpmprobFilterFlags rpmtsFilterFlags(rpmts ts);
 449
 450 /** \ingroup rpmts
 451  * Get transaction flags, i.e. bits that control rpmtsRun().
 452  * @param ts            transaction set
 453  * @return              transaction flags
 454  */
 455 rpmtransFlags rpmtsFlags(rpmts ts);
 456
 457 /** \ingroup rpmts
 458  * Set transaction flags, i.e. bits that control rpmtsRun().
 459  * @param ts            transaction set
 460  * @param transFlags    new transaction flags
 461  * @return              previous transaction flags
 462  */
 463 rpmtransFlags rpmtsSetFlags(rpmts ts, rpmtransFlags transFlags);
 464
 465 /** \ingroup rpmts
 466  * Retrieve color bits of transaction set.
 467  * @param ts            transaction set
 468  * @return              color bits
 469  */
 470 rpm_color_t rpmtsColor(rpmts ts);
 471
 472 /** \ingroup rpmts
 473  * Retrieve prefered file color
 474  * @param ts            transaction set
 475  * @return              color bits
 476  */
 477 rpm_color_t rpmtsPrefColor(rpmts ts);
 478
 479 /** \ingroup rpmts
 480  * Set color bits of transaction set.
 481  * @param ts            transaction set
 482  * @param color         new color bits
 483  * @return              previous color bits
 484  */
 485 rpm_color_t rpmtsSetColor(rpmts ts, rpm_color_t color);
 486
 487 /** \ingroup rpmts
 488  * Set prefered file color
 489  * @param ts            transaction set
 490  * @param color         new color bits
 491  * @return              previous color bits
 492  */
 493 rpm_color_t rpmtsSetPrefColor(rpmts ts, rpm_color_t color);
 494
 495 /** \ingroup rpmts
 496  * Retrieve operation timestamp from a transaction set.
 497  * @param ts            transaction set
 498  * @param opx           operation timestamp index
 499  * @return              pointer to operation timestamp.
 500  */
 501 rpmop rpmtsOp(rpmts ts, rpmtsOpX opx);
 502
 503 /** \ingroup rpmts
 504  * Get the plugins associated with a transaction set
 505  * @param ts            transaction set
 506  * @return              plugins
 507  */
 508 rpmPlugins rpmtsPlugins(rpmts ts);
 509
 510 /** \ingroup rpmts
 511  * Set transaction notify callback function and argument.
 512  *
 513  * @warning This call must be made before rpmtsRun() for
 514  *      install/upgrade/freshen to function correctly.
 515  *
 516  * @param ts            transaction set
 517  * @param notify        progress callback
 518  * @param notifyData    progress callback private data
 519  * @return              0 on success
 520  */
 521 int rpmtsSetNotifyCallback(rpmts ts,
 522                 rpmCallbackFunction notify,
 523                 rpmCallbackData notifyData);
 524
 525 /** \ingroup rpmts
 526  * Create an empty transaction set.
 527  * @return              new transaction set
 528  */
 529 rpmts rpmtsCreate(void);
 530
 531 /** \ingroup rpmts
 532  * Add package to be installed to transaction set.
 533  *
 534  * The transaction set is checked for duplicate package names.
 535  * If found, the package with the "newest" EVR will be replaced.
 536  *
 537  * @param ts            transaction set
 538  * @param h             header
 539  * @param key           package retrieval key (e.g. file name)
 540  * @param upgrade       is package being upgraded?
 541  * @param relocs        package file relocations
 542  * @return              0 on success, 1 on I/O error, 2 needs capabilities
 543  */
 544 int rpmtsAddInstallElement(rpmts ts, Header h,
 545                 const fnpyKey key, int upgrade,
 546                 rpmRelocation * relocs);
 547
 548 /** \ingroup rpmts
 549  * Add package to be erased to transaction set.
 550  * @param ts            transaction set
 551  * @param h             header
 552  * @param dboffset      ununsed
 553  * @return              0 on success, 1 on error (not installed)
 554  */
 555 int rpmtsAddEraseElement(rpmts ts, Header h, int dboffset);
 556
 557 /** \ingroup rpmte
 558  * Destroy transaction element iterator.
 559  * @param tsi           transaction element iterator
 560  * @return              NULL always
 561  */
 562 rpmtsi rpmtsiFree(rpmtsi tsi);
 563
 564 /** \ingroup rpmte
 565  * Create transaction element iterator.
 566  * @param ts            transaction set
 567  * @return              transaction element iterator
 568  */
 569 rpmtsi rpmtsiInit(rpmts ts);
 570
 571 /** \ingroup rpmte
 572  * Return next transaction element of type.
 573  * @param tsi           transaction element iterator
 574  * @param types         transaction element type selector (0 for any)
 575  * @return              next transaction element of type, NULL on termination
 576  */
 577 rpmte rpmtsiNext(rpmtsi tsi, rpmElementTypes types);
 578
 579 #ifdef __cplusplus
 580 }
 581 #endif
 582
 583
 584 #endif  /* H_RPMTS */