lib/libalpm/alpm.h

   1 /*
   2  * alpm.h
   3  *
   4  *  Copyright (c) 2006-2011 Pacman Development Team <pacman-dev@archlinux.org>
   5  *  Copyright (c) 2002-2006 by Judd Vinet <jvinet@zeroflux.org>
   6  *  Copyright (c) 2005 by Aurelien Foret <orelien@chez.com>
   7  *  Copyright (c) 2005 by Christian Hamar <krics@linuxforum.hu>
   8  *  Copyright (c) 2005, 2006 by Miklos Vajna <vmiklos@frugalware.org>
   9  *
  10  *  This program is free software; you can redistribute it and/or modify
  11  *  it under the terms of the GNU General Public License as published by
  12  *  the Free Software Foundation; either version 2 of the License, or
  13  *  (at your option) any later version.
  14  *
  15  *  This program is distributed in the hope that it will be useful,
  16  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  *  GNU General Public License for more details.
  19  *
  20  *  You should have received a copy of the GNU General Public License
  21  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  22  */
  23 #ifndef _ALPM_H
  24 #define _ALPM_H
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include <sys/types.h> /* for off_t */
  31 #include <time.h> /* for time_t */
  32 #include <stdarg.h> /* for va_list */
  33
  34 #include <alpm_list.h>
  35
  36 #define DEPRECATED __attribute__((deprecated))
  37
  38 /*
  39  * Arch Linux Package Management library
  40  */
  41
  42 /** @addtogroup alpm_api Public API
  43  * The libalpm Public API
  44  * @{
  45  */
  46
  47 /*
  48  * Enumerations
  49  * These ones are used in multiple contexts, so are forward-declared.
  50  */
  51
  52 /**
  53  * Install reasons
  54  * Why the package was installed.
  55  */
  56 typedef enum _pmpkgreason_t {
  57         /** Explicitly requested by the user. */
  58         PM_PKG_REASON_EXPLICIT = 0,
  59         /** Installed as a dependency for another package. */
  60         PM_PKG_REASON_DEPEND = 1
  61 } pmpkgreason_t;
  62
  63 /**
  64  * GPG signature verification options
  65  */
  66 typedef enum _pgp_verify_t {
  67         PM_PGP_VERIFY_UNKNOWN,
  68         PM_PGP_VERIFY_NEVER,
  69         PM_PGP_VERIFY_OPTIONAL,
  70         PM_PGP_VERIFY_ALWAYS
  71 } pgp_verify_t;
  72
  73 /*
  74  * Structures
  75  */
  76
  77 typedef struct __pmhandle_t pmhandle_t;
  78 typedef struct __pmdb_t pmdb_t;
  79 typedef struct __pmpkg_t pmpkg_t;
  80 typedef struct __pmdelta_t pmdelta_t;
  81 typedef struct __pmgrp_t pmgrp_t;
  82 typedef struct __pmtrans_t pmtrans_t;
  83 typedef struct __pmdepend_t pmdepend_t;
  84 typedef struct __pmdepmissing_t pmdepmissing_t;
  85 typedef struct __pmconflict_t pmconflict_t;
  86 typedef struct __pmfileconflict_t pmfileconflict_t;
  87
  88 /*
  89  * Library
  90  */
  91
  92 int alpm_initialize(void);
  93 int alpm_release(void);
  94 const char *alpm_version(void);
  95
  96 /*
  97  * Logging facilities
  98  */
  99
 100 /**
 101  * Logging Levels
 102  */
 103 typedef enum _pmloglevel_t {
 104         PM_LOG_ERROR    = 1,
 105         PM_LOG_WARNING  = (1 << 1),
 106         PM_LOG_DEBUG    = (1 << 2),
 107         PM_LOG_FUNCTION = (1 << 3)
 108 } pmloglevel_t;
 109
 110 typedef void (*alpm_cb_log)(pmloglevel_t, const char *, va_list);
 111 int alpm_logaction(const char *fmt, ...);
 112
 113 /*
 114  * Downloading
 115  */
 116
 117 /** Type of download progress callbacks.
 118  * @param filename the name of the file being downloaded
 119  * @param xfered the number of transferred bytes
 120  * @param total the total number of bytes to transfer
 121  */
 122 typedef void (*alpm_cb_download)(const char *filename,
 123                 off_t xfered, off_t total);
 124
 125 typedef void (*alpm_cb_totaldl)(off_t total);
 126
 127 /** A callback for downloading files
 128  * @param url the URL of the file to be downloaded
 129  * @param localpath the directory to which the file should be downloaded
 130  * @param force whether to force an update, even if the file is the same
 131  * @return 0 on success, 1 if the file exists and is identical, -1 on
 132  * error.
 133  */
 134 typedef int (*alpm_cb_fetch)(const char *url, const char *localpath,
 135                 int force);
 136
 137 /** Fetch a remote pkg.
 138  * @param url URL of the package to download
 139  * @return the downloaded filepath on success, NULL on error
 140  */
 141 char *alpm_fetch_pkgurl(const char *url);
 142
 143 /** @addtogroup alpm_api_options Options
 144  * Libalpm option getters and setters
 145  * @{
 146  */
 147
 148 /** Returns the callback used for logging. */
 149 alpm_cb_log alpm_option_get_logcb(void);
 150 /** Sets the callback used for logging. */
 151 int alpm_option_set_logcb(alpm_cb_log cb);
 152
 153 /** Returns the callback used to report download progress. */
 154 alpm_cb_download alpm_option_get_dlcb(void);
 155 /** Sets the callback used to report download progress. */
 156 int alpm_option_set_dlcb(alpm_cb_download cb);
 157
 158 /** Returns the downloading callback. */
 159 alpm_cb_fetch alpm_option_get_fetchcb(void);
 160 /** Sets the downloading callback. */
 161 int alpm_option_set_fetchcb(alpm_cb_fetch cb);
 162
 163 /** Returns the callback used to report total download size. */
 164 alpm_cb_totaldl alpm_option_get_totaldlcb(void);
 165 /** Sets the callback used to report total download size. */
 166 int alpm_option_set_totaldlcb(alpm_cb_totaldl cb);
 167
 168 /** Returns the root of the destination filesystem. */
 169 const char *alpm_option_get_root(void);
 170 /** Sets the root of the destination filesystem. */
 171 int alpm_option_set_root(const char *root);
 172
 173 /** Returns the path to the database directory. */
 174 const char *alpm_option_get_dbpath(void);
 175 /** Sets the path to the database directory. */
 176 int alpm_option_set_dbpath(const char *dbpath);
 177
 178 /** @name Accessors to the list of package cache directories.
 179  * @{
 180  */
 181 alpm_list_t *alpm_option_get_cachedirs(void);
 182 int alpm_option_set_cachedirs(alpm_list_t *cachedirs);
 183 int alpm_option_add_cachedir(const char *cachedir);
 184 int alpm_option_remove_cachedir(const char *cachedir);
 185 /** @} */
 186
 187 /** Returns the logfile name. */
 188 const char *alpm_option_get_logfile(void);
 189 /** Sets the logfile name. */
 190 int alpm_option_set_logfile(const char *logfile);
 191
 192 /** Get the name of the database lock file.
 193  *
 194  * This properly is read-only, and determined from
 195  * the database path.
 196  *
 197  * @sa alpm_option_set_dbpath(const char*)
 198  */
 199 const char *alpm_option_get_lockfile(void);
 200
 201 /** Returns the signature directory path. */
 202 const char *alpm_option_get_signaturedir(void);
 203 /** Sets the signature directory path. */
 204 int alpm_option_set_signaturedir(const char *signaturedir);
 205
 206 /** Returns whether to use syslog (0 is FALSE, TRUE otherwise). */
 207 int alpm_option_get_usesyslog(void);
 208 /** Sets whether to use syslog (0 is FALSE, TRUE otherwise). */
 209 int alpm_option_set_usesyslog(int usesyslog);
 210
 211 /** @name Accessors to the list of no-upgrade files.
 212  * These functions modify the list of files which should
 213  * not be updated by package installation.
 214  * @{
 215  */
 216 alpm_list_t *alpm_option_get_noupgrades(void);
 217 int alpm_option_add_noupgrade(const char *pkg);
 218 int alpm_option_set_noupgrades(alpm_list_t *noupgrade);
 219 int alpm_option_remove_noupgrade(const char *pkg);
 220 /** @} */
 221
 222 /** @name Accessors to the list of no-extract files.
 223  * These functions modify the list of filenames which should
 224  * be skipped packages which should
 225  * not be upgraded by a sysupgrade operation.
 226  * @{
 227  */
 228 alpm_list_t *alpm_option_get_noextracts(void);
 229 int alpm_option_add_noextract(const char *pkg);
 230 int alpm_option_set_noextracts(alpm_list_t *noextract);
 231 int alpm_option_remove_noextract(const char *pkg);
 232 /** @} */
 233
 234 /** @name Accessors to the list of ignored packages.
 235  * These functions modify the list of packages that
 236  * should be ignored by a sysupgrade.
 237  * @{
 238  */
 239 alpm_list_t *alpm_option_get_ignorepkgs(void);
 240 int alpm_option_add_ignorepkg(const char *pkg);
 241 int alpm_option_set_ignorepkgs(alpm_list_t *ignorepkgs);
 242 int alpm_option_remove_ignorepkg(const char *pkg);
 243 /** @} */
 244
 245 /** @name Accessors to the list of ignored groups.
 246  * These functions modify the list of groups whose packages
 247  * should be ignored by a sysupgrade.
 248  * @{
 249  */
 250 alpm_list_t *alpm_option_get_ignoregrps(void);
 251 int alpm_option_add_ignoregrp(const char *grp);
 252 int alpm_option_set_ignoregrps(alpm_list_t *ignoregrps);
 253 int alpm_option_remove_ignoregrp(const char *grp);
 254 /** @} */
 255
 256 /** Returns the targeted architecture. */
 257 const char *alpm_option_get_arch(void);
 258 /** Sets the targeted architecture. */
 259 int alpm_option_set_arch(const char *arch);
 260
 261 int alpm_option_get_usedelta(void);
 262 int alpm_option_set_usedelta(int usedelta);
 263
 264 int alpm_option_get_checkspace(void);
 265 int alpm_option_set_checkspace(int checkspace);
 266
 267 pgp_verify_t alpm_option_get_default_sigverify(void);
 268 int alpm_option_set_default_sigverify(pgp_verify_t level);
 269
 270 /** @} */
 271
 272 /** @addtogroup alpm_api_databases Database Functions
 273  * Functions to query and manipulate the database of libalpm.
 274  * @{
 275  */
 276
 277 /** Get the database of locally installed packages.
 278  * The returned pointer points to an internal structure
 279  * of libalpm which should only be manipulated through
 280  * libalpm functions.
 281  * @return a reference to the local database
 282  */
 283 pmdb_t *alpm_option_get_localdb(void);
 284
 285 /** Get the list of sync databases.
 286  * Returns a list of pmdb_t structures, one for each registered
 287  * sync database.
 288  * @return a reference to an internal list of pmdb_t structures
 289  */
 290 alpm_list_t *alpm_option_get_syncdbs(void);
 291
 292 /** Register a sync database of packages.
 293  * @param treename the name of the sync repository
 294  * @return a pmdb_t* on success (the value), NULL on error
 295  */
 296 pmdb_t *alpm_db_register_sync(const char *treename);
 297
 298 /** Unregister a package database.
 299  * @param db pointer to the package database to unregister
 300  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 301  */
 302 int alpm_db_unregister(pmdb_t *db);
 303
 304 /** Unregister all package databases.
 305  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 306  */
 307 int alpm_db_unregister_all(void);
 308
 309 /** Get the name of a package database.
 310  * @param db pointer to the package database
 311  * @return the name of the package database, NULL on error
 312  */
 313 const char *alpm_db_get_name(const pmdb_t *db);
 314
 315 /** Get a download URL for the package database.
 316  * @param db pointer to the package database
 317  * @return a fully-specified download URL, NULL on error
 318  */
 319 const char *alpm_db_get_url(const pmdb_t *db);
 320
 321 /** @name Accessors to the list of servers for a database.
 322  * @{
 323  */
 324 alpm_list_t *alpm_db_get_servers(const pmdb_t *db);
 325 int alpm_db_set_servers(pmdb_t *db, alpm_list_t *servers);
 326 int alpm_db_add_server(pmdb_t *db, const char *url);
 327 int alpm_db_remove_server(pmdb_t *db, const char *url);
 328 /** @} */
 329
 330 int alpm_db_update(int level, pmdb_t *db);
 331
 332 /** Get a package entry from a package database.
 333  * @param db pointer to the package database to get the package from
 334  * @param name of the package
 335  * @return the package entry on success, NULL on error
 336  */
 337 pmpkg_t *alpm_db_get_pkg(pmdb_t *db, const char *name);
 338
 339 /** Get the package cache of a package database.
 340  * @param db pointer to the package database to get the package from
 341  * @return the list of packages on success, NULL on error
 342  */
 343 alpm_list_t *alpm_db_get_pkgcache(pmdb_t *db);
 344
 345 /** Get a group entry from a package database.
 346  * @param db pointer to the package database to get the group from
 347  * @param name of the group
 348  * @return the groups entry on success, NULL on error
 349  */
 350 pmgrp_t *alpm_db_readgrp(pmdb_t *db, const char *name);
 351
 352 /** Get the group cache of a package database.
 353  * @param db pointer to the package database to get the group from
 354  * @return the list of groups on success, NULL on error
 355  */
 356 alpm_list_t *alpm_db_get_grpcache(pmdb_t *db);
 357
 358 /** Searches a database with regular expressions.
 359  * @param db pointer to the package database to search in
 360  * @param needles a list of regular expressions to search for
 361  * @return the list of packages matching all regular expressions on success, NULL on error
 362  */
 363 alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles);
 364
 365 /** Set install reason for a package in db.
 366  * @param db pointer to the package database
 367  * @param name the name of the package
 368  * @param reason the new install reason
 369  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 370  */
 371 int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason);
 372
 373 /** @} */
 374
 375 /** @addtogroup alpm_api_packages Package Functions
 376  * Functions to manipulate libalpm packages
 377  * @{
 378  */
 379
 380 /** Create a package from a file.
 381  * If full is false, the archive is read only until all necessary
 382  * metadata is found. If it is true, the entire archive is read, which
 383  * serves as a verification of integrity and the filelist can be created.
 384  * The allocated structure should be freed using alpm_pkg_free().
 385  * @param filename location of the package tarball
 386  * @param full whether to stop the load after metadata is read or continue
 387  * through the full archive
 388  * @param check_sig what level of package signature checking to perform on the
 389  * package; note that this must be a '.sig' file type verification
 390  * @param pkg address of the package pointer
 391  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 392  */
 393 int alpm_pkg_load(const char *filename, int full, pgp_verify_t check_sig,
 394                 pmpkg_t **pkg);
 395
 396 /** Free a package.
 397  * @param pkg package pointer to free
 398  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 399  */
 400 int alpm_pkg_free(pmpkg_t *pkg);
 401
 402 /** Check the integrity (with md5) of a package from the sync cache.
 403  * @param pkg package pointer
 404  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 405  */
 406 int alpm_pkg_checkmd5sum(pmpkg_t *pkg);
 407
 408 /** Compare two version strings and determine which one is 'newer'. */
 409 int alpm_pkg_vercmp(const char *a, const char *b);
 410
 411 /** Computes the list of packages requiring a given package.
 412  * The return value of this function is a newly allocated
 413  * list of package names (char*), it should be freed by the caller.
 414  * @param pkg a package
 415  * @return the list of packages requiring pkg
 416  */
 417 alpm_list_t *alpm_pkg_compute_requiredby(pmpkg_t *pkg);
 418
 419 /** @name Package Property Accessors
 420  * Any pointer returned by these functions points to internal structures
 421  * allocated by libalpm. They should not be freed nor modified in any
 422  * way.
 423  * @{
 424  */
 425
 426 /** Gets the name of the file from which the package was loaded.
 427  * @param pkg a pointer to package
 428  * @return a reference to an internal string
 429  */
 430 const char *alpm_pkg_get_filename(pmpkg_t *pkg);
 431
 432 /** Returns the package name.
 433  * @param pkg a pointer to package
 434  * @return a reference to an internal string
 435  */
 436 const char *alpm_pkg_get_name(pmpkg_t *pkg);
 437
 438 /** Returns the package version as a string.
 439  * This includes all available epoch, version, and pkgrel components. Use
 440  * alpm_pkg_vercmp() to compare version strings if necessary.
 441  * @param pkg a pointer to package
 442  * @return a reference to an internal string
 443  */
 444 const char *alpm_pkg_get_version(pmpkg_t *pkg);
 445
 446 /** Returns the package description.
 447  * @param pkg a pointer to package
 448  * @return a reference to an internal string
 449  */
 450 const char *alpm_pkg_get_desc(pmpkg_t *pkg);
 451
 452 /** Returns the package URL.
 453  * @param pkg a pointer to package
 454  * @return a reference to an internal string
 455  */
 456 const char *alpm_pkg_get_url(pmpkg_t *pkg);
 457
 458 /** Returns the build timestamp of the package.
 459  * @param pkg a pointer to package
 460  * @return the timestamp of the build time
 461  */
 462 time_t alpm_pkg_get_builddate(pmpkg_t *pkg);
 463
 464 /** Returns the install timestamp of the package.
 465  * @param pkg a pointer to package
 466  * @return the timestamp of the install time
 467  */
 468 time_t alpm_pkg_get_installdate(pmpkg_t *pkg);
 469
 470 /** Returns the packager's name.
 471  * @param pkg a pointer to package
 472  * @return a reference to an internal string
 473  */
 474 const char *alpm_pkg_get_packager(pmpkg_t *pkg);
 475
 476 /** Returns the package's MD5 checksum as a string.
 477  * The returned string is a sequence of lowercase hexadecimal digits.
 478  * @param pkg a pointer to package
 479  * @return a reference to an internal string
 480  */
 481 const char *alpm_pkg_get_md5sum(pmpkg_t *pkg);
 482
 483 /** Returns the architecture for which the package was built.
 484  * @param pkg a pointer to package
 485  * @return a reference to an internal string
 486  */
 487 const char *alpm_pkg_get_arch(pmpkg_t *pkg);
 488
 489 /** Returns the size of the package.
 490  * @param pkg a pointer to package
 491  * @return the size of the package in bytes.
 492  */
 493 off_t alpm_pkg_get_size(pmpkg_t *pkg);
 494
 495 /** Returns the installed size of the package.
 496  * @param pkg a pointer to package
 497  * @return the total size of files installed by the package.
 498  */
 499 off_t alpm_pkg_get_isize(pmpkg_t *pkg);
 500
 501 /** Returns the package installation reason.
 502  * @param pkg a pointer to package
 503  * @return an enum member giving the install reason.
 504  */
 505 pmpkgreason_t alpm_pkg_get_reason(pmpkg_t *pkg);
 506
 507 /** Returns the list of package licenses.
 508  * @param pkg a pointer to package
 509  * @return a pointer to an internal list of strings.
 510  */
 511 alpm_list_t *alpm_pkg_get_licenses(pmpkg_t *pkg);
 512
 513 /** Returns the list of package groups.
 514  * @param pkg a pointer to package
 515  * @return a pointer to an internal list of strings.
 516  */
 517 alpm_list_t *alpm_pkg_get_groups(pmpkg_t *pkg);
 518
 519 /** Returns the list of package dependencies as pmdepend_t.
 520  * @param pkg a pointer to package
 521  * @return a reference to an internal list of pmdepend_t structures.
 522  */
 523 alpm_list_t *alpm_pkg_get_depends(pmpkg_t *pkg);
 524
 525 /** Returns the list of package optional dependencies.
 526  * @param pkg a pointer to package
 527  * @return a reference to an internal list of strings.
 528  */
 529 alpm_list_t *alpm_pkg_get_optdepends(pmpkg_t *pkg);
 530
 531 /** Returns the list of package names conflicting with pkg.
 532  * @param pkg a pointer to package
 533  * @return a reference to an internal list of strings.
 534  */
 535 alpm_list_t *alpm_pkg_get_conflicts(pmpkg_t *pkg);
 536
 537 /** Returns the list of package names provided by pkg.
 538  * @param pkg a pointer to package
 539  * @return a reference to an internal list of strings.
 540  */
 541 alpm_list_t *alpm_pkg_get_provides(pmpkg_t *pkg);
 542
 543 /** Returns the list of available deltas for pkg.
 544  * @param pkg a pointer to package
 545  * @return a reference to an internal list of strings.
 546  */
 547 alpm_list_t *alpm_pkg_get_deltas(pmpkg_t *pkg);
 548
 549 /** Returns the list of packages to be replaced by pkg.
 550  * @param pkg a pointer to package
 551  * @return a reference to an internal list of strings.
 552  */
 553 alpm_list_t *alpm_pkg_get_replaces(pmpkg_t *pkg);
 554
 555 /** Returns the list of files installed by pkg.
 556  * The filenames are relative to the install root,
 557  * and do not include leading slashes.
 558  * @param pkg a pointer to package
 559  * @return a reference to an internal list of strings.
 560  */
 561 alpm_list_t *alpm_pkg_get_files(pmpkg_t *pkg);
 562
 563 /** Returns the list of files backed up when installing pkg.
 564  * The elements of the returned list have the form
 565  * "<filename>\t<md5sum>", where the given md5sum is that of
 566  * the file as provided by the package.
 567  * @param pkg a pointer to package
 568  * @return a reference to an internal list of strings.
 569  */
 570 alpm_list_t *alpm_pkg_get_backup(pmpkg_t *pkg);
 571
 572 /** Returns the database containing pkg.
 573  * Returns a pointer to the pmdb_t structure the package is
 574  * originating from, or NULL if the package was loaded from a file.
 575  * @param pkg a pointer to package
 576  * @return a pointer to the DB containing pkg, or NULL.
 577  */
 578 pmdb_t *alpm_pkg_get_db(pmpkg_t *pkg);
 579
 580 /* End of pmpkg_t accessors */
 581 /* @} */
 582
 583 /** Open a package changelog for reading.
 584  * Similar to fopen in functionality, except that the returned 'file
 585  * stream' could really be from an archive as well as from the database.
 586  * @param pkg the package to read the changelog of (either file or db)
 587  * @return a 'file stream' to the package changelog
 588  */
 589 void *alpm_pkg_changelog_open(pmpkg_t *pkg);
 590
 591 /** Read data from an open changelog 'file stream'.
 592  * Similar to fread in functionality, this function takes a buffer and
 593  * amount of data to read. If an error occurs pm_errno will be set.
 594  * @param ptr a buffer to fill with raw changelog data
 595  * @param size the size of the buffer
 596  * @param pkg the package that the changelog is being read from
 597  * @param fp a 'file stream' to the package changelog
 598  * @return the number of characters read, or 0 if there is no more data or an
 599  * error occurred.
 600  */
 601 size_t alpm_pkg_changelog_read(void *ptr, size_t size,
 602                 const pmpkg_t *pkg, const void *fp);
 603
 604 /*int alpm_pkg_changelog_feof(const pmpkg_t *pkg, void *fp);*/
 605
 606 int alpm_pkg_changelog_close(const pmpkg_t *pkg, void *fp);
 607
 608 /** Returns whether the package has an install scriptlet.
 609  * @return 0 if FALSE, TRUE otherwise
 610  */
 611 int alpm_pkg_has_scriptlet(pmpkg_t *pkg);
 612
 613 /** Returns the size of download.
 614  * Returns the size of the files that will be downloaded to install a
 615  * package.
 616  * @param newpkg the new package to upgrade to
 617  * @return the size of the download
 618  */
 619 off_t alpm_pkg_download_size(pmpkg_t *newpkg);
 620
 621 alpm_list_t *alpm_pkg_unused_deltas(pmpkg_t *pkg);
 622
 623 /* End of alpm_pkg */
 624 /** @} */
 625
 626 /*
 627  * Signatures
 628  */
 629
 630 int alpm_pkg_check_pgp_signature(pmpkg_t *pkg);
 631
 632 int alpm_db_check_pgp_signature(pmdb_t *db);
 633 int alpm_db_set_pgp_verify(pmdb_t *db, pgp_verify_t verify);
 634
 635 /*
 636  * Deltas
 637  */
 638
 639 const char *alpm_delta_get_from(pmdelta_t *delta);
 640 const char *alpm_delta_get_to(pmdelta_t *delta);
 641 const char *alpm_delta_get_filename(pmdelta_t *delta);
 642 const char *alpm_delta_get_md5sum(pmdelta_t *delta);
 643 off_t alpm_delta_get_size(pmdelta_t *delta);
 644
 645 /*
 646  * Groups
 647  */
 648 const char *alpm_grp_get_name(const pmgrp_t *grp);
 649 alpm_list_t *alpm_grp_get_pkgs(const pmgrp_t *grp);
 650 alpm_list_t *alpm_find_grp_pkgs(alpm_list_t *dbs, const char *name);
 651
 652 /*
 653  * Sync
 654  */
 655
 656 pmpkg_t *alpm_sync_newversion(pmpkg_t *pkg, alpm_list_t *dbs_sync);
 657
 658 /** @addtogroup alpm_api_trans Transaction Functions
 659  * Functions to manipulate libalpm transactions
 660  * @{
 661  */
 662
 663 /** Transaction flags */
 664 typedef enum _pmtransflag_t {
 665         /** Ignore dependency checks. */
 666         PM_TRANS_FLAG_NODEPS = 1,
 667         /** Ignore file conflicts and overwrite files. */
 668         PM_TRANS_FLAG_FORCE = (1 << 1),
 669         /** Delete files even if they are tagged as backup. */
 670         PM_TRANS_FLAG_NOSAVE = (1 << 2),
 671         /** Ignore version numbers when checking dependencies. */
 672         PM_TRANS_FLAG_NODEPVERSION = (1 << 3),
 673         /** Remove also any packages depending on a package being removed. */
 674         PM_TRANS_FLAG_CASCADE = (1 << 4),
 675         /** Remove packages and their unneeded deps (not explicitly installed). */
 676         PM_TRANS_FLAG_RECURSE = (1 << 5),
 677         /** Modify database but do not commit changes to the filesystem. */
 678         PM_TRANS_FLAG_DBONLY = (1 << 6),
 679         /* (1 << 7) flag can go here */
 680         /** Use PM_PKG_REASON_DEPEND when installing packages. */
 681         PM_TRANS_FLAG_ALLDEPS = (1 << 8),
 682         /** Only download packages and do not actually install. */
 683         PM_TRANS_FLAG_DOWNLOADONLY = (1 << 9),
 684         /** Do not execute install scriptlets after installing. */
 685         PM_TRANS_FLAG_NOSCRIPTLET = (1 << 10),
 686         /** Ignore dependency conflicts. */
 687         PM_TRANS_FLAG_NOCONFLICTS = (1 << 11),
 688         /* (1 << 12) flag can go here */
 689         /** Do not install a package if it is already installed and up to date. */
 690         PM_TRANS_FLAG_NEEDED = (1 << 13),
 691         /** Use PM_PKG_REASON_EXPLICIT when installing packages. */
 692         PM_TRANS_FLAG_ALLEXPLICIT = (1 << 14),
 693         /** Do not remove a package if it is needed by another one. */
 694         PM_TRANS_FLAG_UNNEEDED = (1 << 15),
 695         /** Remove also explicitly installed unneeded deps (use with PM_TRANS_FLAG_RECURSE). */
 696         PM_TRANS_FLAG_RECURSEALL = (1 << 16),
 697         /** Do not lock the database during the operation. */
 698         PM_TRANS_FLAG_NOLOCK = (1 << 17)
 699 } pmtransflag_t;
 700
 701 /** Transaction events.
 702  * NULL parameters are passed to in all events unless specified otherwise.
 703  */
 704 typedef enum _pmtransevt_t {
 705         /** Dependencies will be computed for a package. */
 706         PM_TRANS_EVT_CHECKDEPS_START = 1,
 707         /** Dependencies were computed for a package. */
 708         PM_TRANS_EVT_CHECKDEPS_DONE,
 709         /** File conflicts will be computed for a package. */
 710         PM_TRANS_EVT_FILECONFLICTS_START,
 711         /** File conflicts were computed for a package. */
 712         PM_TRANS_EVT_FILECONFLICTS_DONE,
 713         /** Dependencies will be resolved for target package. */
 714         PM_TRANS_EVT_RESOLVEDEPS_START,
 715         /** Dependencies were resolved for target package. */
 716         PM_TRANS_EVT_RESOLVEDEPS_DONE,
 717         /** Inter-conflicts will be checked for target package. */
 718         PM_TRANS_EVT_INTERCONFLICTS_START,
 719         /** Inter-conflicts were checked for target package. */
 720         PM_TRANS_EVT_INTERCONFLICTS_DONE,
 721         /** Package will be installed.
 722          * A pointer to the target package is passed to the callback.
 723          */
 724         PM_TRANS_EVT_ADD_START,
 725         /** Package was installed.
 726          * A pointer to the new package is passed to the callback.
 727          */
 728         PM_TRANS_EVT_ADD_DONE,
 729         /** Package will be removed.
 730          * A pointer to the target package is passed to the callback.
 731          */
 732         PM_TRANS_EVT_REMOVE_START,
 733         /** Package was removed.
 734          * A pointer to the removed package is passed to the callback.
 735          */
 736         PM_TRANS_EVT_REMOVE_DONE,
 737         /** Package will be upgraded.
 738          * A pointer to the upgraded package is passed to the callback.
 739          */
 740         PM_TRANS_EVT_UPGRADE_START,
 741         /** Package was upgraded.
 742          * A pointer to the new package, and a pointer to the old package is passed
 743          * to the callback, respectively.
 744          */
 745         PM_TRANS_EVT_UPGRADE_DONE,
 746         /** Target package's integrity will be checked. */
 747         PM_TRANS_EVT_INTEGRITY_START,
 748         /** Target package's integrity was checked. */
 749         PM_TRANS_EVT_INTEGRITY_DONE,
 750         /** Target deltas's integrity will be checked. */
 751         PM_TRANS_EVT_DELTA_INTEGRITY_START,
 752         /** Target delta's integrity was checked. */
 753         PM_TRANS_EVT_DELTA_INTEGRITY_DONE,
 754         /** Deltas will be applied to packages. */
 755         PM_TRANS_EVT_DELTA_PATCHES_START,
 756         /** Deltas were applied to packages. */
 757         PM_TRANS_EVT_DELTA_PATCHES_DONE,
 758         /** Delta patch will be applied to target package.
 759          * The filename of the package and the filename of the patch is passed to the
 760          * callback.
 761          */
 762         PM_TRANS_EVT_DELTA_PATCH_START,
 763         /** Delta patch was applied to target package. */
 764         PM_TRANS_EVT_DELTA_PATCH_DONE,
 765         /** Delta patch failed to apply to target package. */
 766         PM_TRANS_EVT_DELTA_PATCH_FAILED,
 767         /** Scriptlet has printed information.
 768          * A line of text is passed to the callback.
 769          */
 770         PM_TRANS_EVT_SCRIPTLET_INFO,
 771         /** Files will be downloaded from a repository.
 772          * The repository's tree name is passed to the callback.
 773          */
 774         PM_TRANS_EVT_RETRIEVE_START,
 775         /** Disk space usage will be computed for a package */
 776         PM_TRANS_EVT_DISKSPACE_START,
 777         /** Disk space usage was computed for a package */
 778         PM_TRANS_EVT_DISKSPACE_DONE,
 779 } pmtransevt_t;
 780
 781 /** Transaction Conversations (ie, questions) */
 782 typedef enum _pmtransconv_t {
 783         PM_TRANS_CONV_INSTALL_IGNOREPKG = 1,
 784         PM_TRANS_CONV_REPLACE_PKG = (1 << 1),
 785         PM_TRANS_CONV_CONFLICT_PKG = (1 << 2),
 786         PM_TRANS_CONV_CORRUPTED_PKG = (1 << 3),
 787         PM_TRANS_CONV_LOCAL_NEWER = (1 << 4),
 788         PM_TRANS_CONV_REMOVE_PKGS = (1 << 5),
 789         PM_TRANS_CONV_SELECT_PROVIDER = (1 << 6),
 790 } pmtransconv_t;
 791
 792 /** Transaction Progress */
 793 typedef enum _pmtransprog_t {
 794         PM_TRANS_PROGRESS_ADD_START,
 795         PM_TRANS_PROGRESS_UPGRADE_START,
 796         PM_TRANS_PROGRESS_REMOVE_START,
 797         PM_TRANS_PROGRESS_CONFLICTS_START,
 798         PM_TRANS_PROGRESS_DISKSPACE_START,
 799         PM_TRANS_PROGRESS_INTEGRITY_START,
 800 } pmtransprog_t;
 801
 802 /** Transaction Event callback */
 803 typedef void (*alpm_trans_cb_event)(pmtransevt_t, void *, void *);
 804
 805 /** Transaction Conversation callback */
 806 typedef void (*alpm_trans_cb_conv)(pmtransconv_t, void *, void *,
 807                                    void *, int *);
 808
 809 /** Transaction Progress callback */
 810 typedef void (*alpm_trans_cb_progress)(pmtransprog_t, const char *, int, size_t, size_t);
 811
 812 /** Returns the bitfield of flags for the current transaction.
 813  * @sa _pmtransflag_t
 814  */
 815 int alpm_trans_get_flags(void);
 816
 817 /** Returns a list of packages added by the transaction.
 818  * @return a list of pmpkg_t structures
 819  */
 820 alpm_list_t * alpm_trans_get_add(void);
 821
 822 /** Returns the list of packages removed by the transaction.
 823  * @return a list of pmpkg_t structures
 824  */
 825 alpm_list_t * alpm_trans_get_remove(void);
 826
 827 /** Initialize the transaction.
 828  * @param flags flags of the transaction (like nodeps, etc)
 829  * @param event event callback function pointer
 830  * @param conv question callback function pointer
 831  * @param progress progress callback function pointer
 832  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 833  */
 834 int alpm_trans_init(pmtransflag_t flags,
 835                     alpm_trans_cb_event cb_event, alpm_trans_cb_conv conv,
 836                     alpm_trans_cb_progress cb_progress);
 837
 838 /** Prepare a transaction.
 839  * @param data the address of an alpm_list where a list
 840  * of pmdepmissing_t objects is dumped (conflicting packages)
 841  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 842  */
 843 int alpm_trans_prepare(alpm_list_t **data);
 844
 845 /** Commit a transaction.
 846  * @param data the address of an alpm_list where detailed description
 847  * of an error can be dumped (ie. list of conflicting files)
 848  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 849  */
 850 int alpm_trans_commit(alpm_list_t **data);
 851
 852 /** Interrupt a transaction.
 853  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 854  */
 855 int alpm_trans_interrupt(void);
 856
 857 /** Release a transaction.
 858  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 859  */
 860 int alpm_trans_release(void);
 861 /** @} */
 862
 863 /** @name Common Transactions */
 864 /** @{ */
 865
 866 /** Search for packages to upgrade and add them to the transaction.
 867  * @param enable_downgrade allow downgrading of packages if the remote version is lower
 868  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 869  */
 870 int alpm_sync_sysupgrade(int enable_downgrade);
 871
 872 /** Add a package to the transaction.
 873  * If the package was loaded by alpm_pkg_load(), it will be freed upon
 874  * alpm_trans_release() invocation.
 875  * @param pkg the package to add
 876  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 877  */
 878 int alpm_add_pkg(pmpkg_t *pkg);
 879
 880 /** Add a package removal action to the transaction.
 881  * @param pkg the package to uninstall
 882  * @return 0 on success, -1 on error (pm_errno is set accordingly)
 883  */
 884 int alpm_remove_pkg(pmpkg_t *pkg);
 885
 886 /** @} */
 887
 888 /** @addtogroup alpm_api_depends Dependency Functions
 889  * Functions dealing with libalpm representation of dependency
 890  * information.
 891  * @{
 892  */
 893
 894 /** Types of version constraints in dependency specs. */
 895 typedef enum _pmdepmod_t {
 896   /** No version constraint */
 897         PM_DEP_MOD_ANY = 1,
 898   /** Test version equality (package=x.y.z) */
 899         PM_DEP_MOD_EQ,
 900   /** Test for at least a version (package>=x.y.z) */
 901         PM_DEP_MOD_GE,
 902   /** Test for at most a version (package<=x.y.z) */
 903         PM_DEP_MOD_LE,
 904   /** Test for greater than some version (package>x.y.z) */
 905         PM_DEP_MOD_GT,
 906   /** Test for less than some version (package<x.y.z) */
 907         PM_DEP_MOD_LT
 908 } pmdepmod_t;
 909
 910 alpm_list_t *alpm_checkdeps(alpm_list_t *pkglist, int reversedeps,
 911                 alpm_list_t *remove, alpm_list_t *upgrade);
 912 pmpkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring);
 913 pmpkg_t *alpm_find_dbs_satisfier(alpm_list_t *dbs, const char *depstring);
 914
 915 const char *alpm_miss_get_target(const pmdepmissing_t *miss);
 916 pmdepend_t *alpm_miss_get_dep(pmdepmissing_t *miss);
 917 const char *alpm_miss_get_causingpkg(const pmdepmissing_t *miss);
 918
 919 alpm_list_t *alpm_checkconflicts(alpm_list_t *pkglist);
 920
 921 const char *alpm_conflict_get_package1(pmconflict_t *conflict);
 922 const char *alpm_conflict_get_package2(pmconflict_t *conflict);
 923 const char *alpm_conflict_get_reason(pmconflict_t *conflict);
 924
 925 /** Returns the type of version constraint.
 926  * @param dep a dependency info structure
 927  * @return the type of version constraint (PM_DEP_MOD_ANY if no version
 928  * is specified).
 929  */
 930 pmdepmod_t alpm_dep_get_mod(const pmdepend_t *dep);
 931
 932 /** Returns the package name of a dependency constraint.
 933  * @param dep a dependency info structure
 934  * @return a pointer to an internal string.
 935  */
 936 const char *alpm_dep_get_name(const pmdepend_t *dep);
 937
 938 /** Returns the version specified by a dependency constraint.
 939  * The version information is returned as a string in the same format
 940  * as given by alpm_pkg_get_version().
 941  * @param dep a dependency info structure
 942  * @return a pointer to an internal string.
 943  */
 944 const char *alpm_dep_get_version(const pmdepend_t *dep);
 945
 946 /** Returns a newly allocated string representing the dependency information.
 947  * @param dep a dependency info structure
 948  * @return a formatted string, e.g. "glibc>=2.12"
 949  */
 950 char *alpm_dep_compute_string(const pmdepend_t *dep);
 951
 952 /** @} */
 953
 954 /** @addtogroup alpm_api_fileconflicts File Conflicts Functions
 955  * Functions to manipulate file conflict information.
 956  * @{
 957  */
 958
 959 typedef enum _pmfileconflicttype_t {
 960         PM_FILECONFLICT_TARGET = 1,
 961         PM_FILECONFLICT_FILESYSTEM
 962 } pmfileconflicttype_t;
 963
 964 const char *alpm_fileconflict_get_target(pmfileconflict_t *conflict);
 965 pmfileconflicttype_t alpm_fileconflict_get_type(pmfileconflict_t *conflict);
 966 const char *alpm_fileconflict_get_file(pmfileconflict_t *conflict);
 967 const char *alpm_fileconflict_get_ctarget(pmfileconflict_t *conflict);
 968
 969 /** @} */
 970
 971 /*
 972  * Helpers
 973  */
 974
 975 /* checksums */
 976 char *alpm_compute_md5sum(const char *name);
 977
 978 /** @addtogroup alpm_api_errors Error Codes
 979  * @{
 980  */
 981 enum _pmerrno_t {
 982         PM_ERR_MEMORY = 1,
 983         PM_ERR_SYSTEM,
 984         PM_ERR_BADPERMS,
 985         PM_ERR_NOT_A_FILE,
 986         PM_ERR_NOT_A_DIR,
 987         PM_ERR_WRONG_ARGS,
 988         PM_ERR_DISK_SPACE,
 989         /* Interface */
 990         PM_ERR_HANDLE_NULL,
 991         PM_ERR_HANDLE_NOT_NULL,
 992         PM_ERR_HANDLE_LOCK,
 993         /* Databases */
 994         PM_ERR_DB_OPEN,
 995         PM_ERR_DB_CREATE,
 996         PM_ERR_DB_NULL,
 997         PM_ERR_DB_NOT_NULL,
 998         PM_ERR_DB_NOT_FOUND,
 999         PM_ERR_DB_VERSION,
1000         PM_ERR_DB_WRITE,
1001         PM_ERR_DB_REMOVE,
1002         /* Servers */
1003         PM_ERR_SERVER_BAD_URL,
1004         PM_ERR_SERVER_NONE,
1005         /* Transactions */
1006         PM_ERR_TRANS_NOT_NULL,
1007         PM_ERR_TRANS_NULL,
1008         PM_ERR_TRANS_DUP_TARGET,
1009         PM_ERR_TRANS_NOT_INITIALIZED,
1010         PM_ERR_TRANS_NOT_PREPARED,
1011         PM_ERR_TRANS_ABORT,
1012         PM_ERR_TRANS_TYPE,
1013         PM_ERR_TRANS_NOT_LOCKED,
1014         /* Packages */
1015         PM_ERR_PKG_NOT_FOUND,
1016         PM_ERR_PKG_IGNORED,
1017         PM_ERR_PKG_INVALID,
1018         PM_ERR_PKG_OPEN,
1019         PM_ERR_PKG_CANT_REMOVE,
1020         PM_ERR_PKG_INVALID_NAME,
1021         PM_ERR_PKG_INVALID_ARCH,
1022         PM_ERR_PKG_REPO_NOT_FOUND,
1023         /* Signatures */
1024         PM_ERR_SIG_MISSINGDIR,
1025         PM_ERR_SIG_INVALID,
1026         PM_ERR_SIG_UNKNOWN,
1027         /* Deltas */
1028         PM_ERR_DLT_INVALID,
1029         PM_ERR_DLT_PATCHFAILED,
1030         /* Dependencies */
1031         PM_ERR_UNSATISFIED_DEPS,
1032         PM_ERR_CONFLICTING_DEPS,
1033         PM_ERR_FILE_CONFLICTS,
1034         /* Misc */
1035         PM_ERR_RETRIEVE,
1036         PM_ERR_WRITE,
1037         PM_ERR_INVALID_REGEX,
1038         /* External library errors */
1039         PM_ERR_LIBARCHIVE,
1040         PM_ERR_LIBCURL,
1041         PM_ERR_EXTERNAL_DOWNLOAD,
1042         PM_ERR_GPGME
1043 };
1044
1045 /** The number of the last error that occurred. */
1046 extern enum _pmerrno_t pm_errno;
1047
1048 /** Returns the string corresponding to an error number. */
1049 const char *alpm_strerror(int err);
1050
1051 /** Returns the string corresponding to pm_errno. */
1052 const char *alpm_strerrorlast(void);
1053
1054 /* End of alpm_api_errors */
1055 /** @} */
1056
1057 /* End of alpm_api */
1058 /** @} */
1059
1060 #ifdef __cplusplus
1061 }
1062 #endif
1063 #endif /* _ALPM_H */
1064
1065 /* vim: set ts=2 sw=2 noet: */