/* * alpm.h * * Copyright (c) 2006-2020 Pacman Development Team * Copyright (c) 2002-2006 by Judd Vinet * Copyright (c) 2005 by Aurelien Foret * Copyright (c) 2005 by Christian Hamar * Copyright (c) 2005, 2006 by Miklos Vajna * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ /** * @file alpm.h * @author Pacman Development Team * @brief Arch Linux Package Manager Library */ /** @mainpage alpm * * libalpm is a package management library, primarily used by pacman. */ #ifndef ALPM_H #define ALPM_H #ifdef __cplusplus extern "C" { #endif #include /* int64_t */ #include /* off_t */ #include /* va_list */ /* libarchive */ #include #include #include /* * Opaque Structures */ /** The libalpm context handle. * * This struct represents an instance of libalpm. */ typedef struct __alpm_handle_t alpm_handle_t; /** A database. * * A database is a container that stores metadata about packages. * * A database can be located on the local filesystem or on a remote server. * * To use a database, it must first be registered via \link alpm_register_syncdb \endlink. * If the database is already preasant in dbpath then it will be usable. Otherwise, * the database needs to be downloaded using \link alpm_db_update \endlink. Even if the * source of the database is the local filesystem. * * After this, the database can be used to query packages and groups. Any packages or groups * from the database will continue to be owned by the database and do not need to be freed by * the user. They will be freed when the database is unregistered. * * Databases are automatically unregistered when the \link alpm_handle_t \endlink is released. */ typedef struct __alpm_db_t alpm_db_t; /** A package. * * A package can be loaded from disk via \link alpm_pkg_load \endlink or retrieved from a database. * Packages from databases are automatically freed when the database is unregistered. Packages loaded * from a file must be freed manually. * * Packages can then be queried for metadata or added to a \link alpm_trans_t transaction \endlink * to be added or removed from the system. */ typedef struct __alpm_pkg_t alpm_pkg_t; /** Transaction structure used internally by libalpm */ typedef struct __alpm_trans_t alpm_trans_t; /** @addtogroup alpm_api ALPM * @brief The libalpm Public API * @{ */ /** @addtogroup alpm_files Files * @brief Functions for package files * @{ */ /** File in a package */ typedef struct _alpm_file_t { /** Name of the file */ char *name; /** Size of the file */ off_t size; /** The file's permissions */ mode_t mode; } alpm_file_t; /** Package filelist container */ typedef struct _alpm_filelist_t { /** Amount of files in the array */ size_t count; /** An array of files */ alpm_file_t *files; } alpm_filelist_t; /** Local package or package file backup entry */ typedef struct _alpm_backup_t { /** Name of the file (without .pacsave extension) */ char *name; /** Hash of the filename (used internally) */ char *hash; } alpm_backup_t; /** Determines whether a package filelist contains a given path. * The provided path should be relative to the install root with no leading * slashes, e.g. "etc/localtime". When searching for directories, the path must * have a trailing slash. * @param filelist a pointer to a package filelist * @param path the path to search for in the package * @return a pointer to the matching file or NULL if not found */ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); /* End of alpm_files */ /** @} */ /** @addtogroup alpm_groups Groups * @brief Functions for package groups * @{ */ /** Package group */ typedef struct _alpm_group_t { /** group name */ char *name; /** list of alpm_pkg_t packages */ alpm_list_t *packages; } alpm_group_t; /** Find group members across a list of databases. * If a member exists in several databases, only the first database is used. * IgnorePkg is also handled. * @param dbs the list of alpm_db_t * * @param name the name of the group * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free) */ alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); /* End of alpm_groups */ /** @} */ /** @addtogroup alpm_errors Error Codes * Error codes returned by libalpm. * @{ */ /** libalpm's error type */ typedef enum _alpm_errno_t { /** No error */ ALPM_ERR_OK = 0, /** Failed to allocate memory */ ALPM_ERR_MEMORY, /** A system error occurred */ ALPM_ERR_SYSTEM, /** Permmision denied */ ALPM_ERR_BADPERMS, /** Should be a file */ ALPM_ERR_NOT_A_FILE, /** Should be a directory */ ALPM_ERR_NOT_A_DIR, /** Function was called with invalid arguments */ ALPM_ERR_WRONG_ARGS, /** Insufficient disk space */ ALPM_ERR_DISK_SPACE, /* Interface */ /** Handle should be null */ ALPM_ERR_HANDLE_NULL, /** Handle should not be null */ ALPM_ERR_HANDLE_NOT_NULL, /** Failed to acquire lock */ ALPM_ERR_HANDLE_LOCK, /* Databases */ /** Failed to open database */ ALPM_ERR_DB_OPEN, /** Failed to create database */ ALPM_ERR_DB_CREATE, /** Database should not be null */ ALPM_ERR_DB_NULL, /** Database should be null */ ALPM_ERR_DB_NOT_NULL, /** The database could not be found */ ALPM_ERR_DB_NOT_FOUND, /** Database is invalid */ ALPM_ERR_DB_INVALID, /** Database has an invalid signature */ ALPM_ERR_DB_INVALID_SIG, /** The localdb is in a newer/older format than libalpm expects */ ALPM_ERR_DB_VERSION, /** Failed to write to the database */ ALPM_ERR_DB_WRITE, /** Failed to remove entry from database */ ALPM_ERR_DB_REMOVE, /* Servers */ /** Server URL is in an invalid format */ ALPM_ERR_SERVER_BAD_URL, /** The database has no configured servers */ ALPM_ERR_SERVER_NONE, /* Transactions */ /** A transaction is already initialized */ ALPM_ERR_TRANS_NOT_NULL, /** A transaction has not been initialized */ ALPM_ERR_TRANS_NULL, /** Duplicate target in transaction */ ALPM_ERR_TRANS_DUP_TARGET, /** A transaction has not been initialized */ ALPM_ERR_TRANS_NOT_INITIALIZED, /** Transaction has not been prepared */ ALPM_ERR_TRANS_NOT_PREPARED, /** Transaction was aborted */ ALPM_ERR_TRANS_ABORT, /** Failed to interrupt transaction */ ALPM_ERR_TRANS_TYPE, /** Tried to commit transaction without locking the database */ ALPM_ERR_TRANS_NOT_LOCKED, /** A hook failed to run */ ALPM_ERR_TRANS_HOOK_FAILED, /* Packages */ /** Package not found */ ALPM_ERR_PKG_NOT_FOUND, /** Package is in ignorepkg */ ALPM_ERR_PKG_IGNORED, /** Package is invalid */ ALPM_ERR_PKG_INVALID, /** Package has an invalid checksum */ ALPM_ERR_PKG_INVALID_CHECKSUM, /** Package has an invalid signature */ ALPM_ERR_PKG_INVALID_SIG, /** Package does not have a signature */ ALPM_ERR_PKG_MISSING_SIG, /** Cannot open the package file */ ALPM_ERR_PKG_OPEN, /** Failed to remove package files */ ALPM_ERR_PKG_CANT_REMOVE, /** Package has an invalid name */ ALPM_ERR_PKG_INVALID_NAME, /** Package has an invalid architecture */ ALPM_ERR_PKG_INVALID_ARCH, /** Unused */ ALPM_ERR_PKG_REPO_NOT_FOUND, /* Signatures */ /** Signatures are missing */ ALPM_ERR_SIG_MISSING, /** Signatures are invalid */ ALPM_ERR_SIG_INVALID, /* Dependencies */ /** Dependencies could not be satisfied */ ALPM_ERR_UNSATISFIED_DEPS, /** Conflicting dependencies */ ALPM_ERR_CONFLICTING_DEPS, /** Files conflict */ ALPM_ERR_FILE_CONFLICTS, /* Misc */ /** Download failed */ ALPM_ERR_RETRIEVE, /** Invalid Regex */ ALPM_ERR_INVALID_REGEX, /* External library errors */ /** Error in libarchive */ ALPM_ERR_LIBARCHIVE, /** Error in libcurl */ ALPM_ERR_LIBCURL, /** Error in external download program */ ALPM_ERR_EXTERNAL_DOWNLOAD, /** Error in gpgme */ ALPM_ERR_GPGME, /** Missing compile-time features */ ALPM_ERR_MISSING_CAPABILITY_SIGNATURES } alpm_errno_t; /** Returns the current error code from the handle. * @param handle the context handle * @return the current error code of the handle */ alpm_errno_t alpm_errno(alpm_handle_t *handle); /** Returns the string corresponding to an error number. * @param err the error code to get the string for * @return the string relating to the given error code */ const char *alpm_strerror(alpm_errno_t err); /* End of alpm_errors */ /** @} */ /** \addtogroup alpm_handle Handle * @brief Functions to initialize and release libalpm * @{ */ /** Initializes the library. * Creates handle, connects to database and creates lockfile. * This must be called before any other functions are called. * @param root the root path for all filesystem operations * @param dbpath the absolute path to the libalpm database * @param err an optional variable to hold any error return codes * @return a context handle on success, NULL on error, err will be set if provided */ alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, alpm_errno_t *err); /** Release the library. * Disconnects from the database, removes handle and lockfile * This should be the last alpm call you make. * After this returns, handle should be considered invalid and cannot be reused * in any way. * @param handle the context handle * @return 0 on success, -1 on error */ int alpm_release(alpm_handle_t *handle); /* End of alpm_handle */ /** @} */ typedef int64_t alpm_time_t; /** @addtogroup alpm_sig Signature checking * @brief Functions to check signatures * @{ */ /** PGP signature verification options */ typedef enum _alpm_siglevel_t { /** Packages require a signature */ ALPM_SIG_PACKAGE = (1 << 0), /** Packages do not require a signature, * but check packages that do have signatures */ ALPM_SIG_PACKAGE_OPTIONAL = (1 << 1), /* Allow packages with signatures that are marginal trust */ ALPM_SIG_PACKAGE_MARGINAL_OK = (1 << 2), /** Allow packages with signatues that are unknown trust */ ALPM_SIG_PACKAGE_UNKNOWN_OK = (1 << 3), /** Databases require a signature */ ALPM_SIG_DATABASE = (1 << 10), /** Databases do not require a signature, * but check databases that do have signatures */ ALPM_SIG_DATABASE_OPTIONAL = (1 << 11), /** Allow databases with signatures that are marginal trust */ ALPM_SIG_DATABASE_MARGINAL_OK = (1 << 12), /** Allow databases with signatues that are unknown trust */ ALPM_SIG_DATABASE_UNKNOWN_OK = (1 << 13), /** The Default siglevel */ ALPM_SIG_USE_DEFAULT = (1 << 30) } alpm_siglevel_t; /** PGP signature verification status return codes */ typedef enum _alpm_sigstatus_t { /** Signature is valid */ ALPM_SIGSTATUS_VALID, /** The key has expired */ ALPM_SIGSTATUS_KEY_EXPIRED, /** The signature has expired */ ALPM_SIGSTATUS_SIG_EXPIRED, /** The key is not in the keyring */ ALPM_SIGSTATUS_KEY_UNKNOWN, /** The key has been disabled */ ALPM_SIGSTATUS_KEY_DISABLED, /** The signature is invalid */ ALPM_SIGSTATUS_INVALID } alpm_sigstatus_t; /** The trust level of a PGP key */ typedef enum _alpm_sigvalidity_t { /** The signature is fully trusted */ ALPM_SIGVALIDITY_FULL, /** The signature is marginally trusted */ ALPM_SIGVALIDITY_MARGINAL, /** The signature is never trusted */ ALPM_SIGVALIDITY_NEVER, /** The signature has unknown trust */ ALPM_SIGVALIDITY_UNKNOWN } alpm_sigvalidity_t; /** A PGP key */ typedef struct _alpm_pgpkey_t { /** The actual key data */ void *data; /** The key's fingerprint */ char *fingerprint; /** UID of the key */ char *uid; /** Name of the key's owner */ char *name; /** Email of the key's owner */ char *email; /** When the key was created */ alpm_time_t created; /** When the key expires */ alpm_time_t expires; /** The length of the key */ unsigned int length; /** has the key been revoked */ unsigned int revoked; /** A character representing the encryption algorithm used by the public key * * ? = unknown * R = RSA * D = DSA * E = EDDSA */ char pubkey_algo; } alpm_pgpkey_t; /** * Signature result. Contains the key, status, and validity of a given * signature. */ typedef struct _alpm_sigresult_t { /** The key of the signature */ alpm_pgpkey_t key; /** The status of the signature */ alpm_sigstatus_t status; /** The validity of the signature */ alpm_sigvalidity_t validity; } alpm_sigresult_t; /** * Signature list. Contains the number of signatures found and a pointer to an * array of results. The array is of size count. */ typedef struct _alpm_siglist_t { /** The amount of results in the array */ size_t count; /** An array of sigresults */ alpm_sigresult_t *results; } alpm_siglist_t; /** * Check the PGP signature for the given package file. * @param pkg the package to check * @param siglist a pointer to storage for signature results * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); /** * Check the PGP signature for the given database. * @param db the database to check * @param siglist a pointer to storage for signature results * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); /** * Clean up and free a signature result list. * Note that this does not free the siglist object itself in case that * was allocated on the stack; this is the responsibility of the caller. * @param siglist a pointer to storage for signature results * @return 0 on success, -1 on error */ int alpm_siglist_cleanup(alpm_siglist_t *siglist); /** * Decode a loaded signature in base64 form. * @param base64_data the signature to attempt to decode * @param data the decoded data; must be freed by the caller * @param data_len the length of the returned data * @return 0 on success, -1 on failure to properly decode */ int alpm_decode_signature(const char *base64_data, unsigned char **data, size_t *data_len); /** * Extract the Issuer Key ID from a signature * @param handle the context handle * @param identifier the identifier of the key. * This may be the name of the package or the path to the package. * @param sig PGP signature * @param len length of signature * @param keys a pointer to storage for key IDs * @return 0 on success, -1 on error */ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, const unsigned char *sig, const size_t len, alpm_list_t **keys); /* End of alpm_sig */ /** @} */ /** @addtogroup alpm_depends Dependency * @brief Functions dealing with libalpm's dependency and conflict * information. * @{ */ /** Types of version constraints in dependency specs. */ typedef enum _alpm_depmod_t { /** No version constraint */ ALPM_DEP_MOD_ANY = 1, /** Test version equality (package=x.y.z) */ ALPM_DEP_MOD_EQ, /** Test for at least a version (package>=x.y.z) */ ALPM_DEP_MOD_GE, /** Test for at most a version (package<=x.y.z) */ ALPM_DEP_MOD_LE, /** Test for greater than some version (package>x.y.z) */ ALPM_DEP_MOD_GT, /** Test for less than some version (package=2.12" */ char *alpm_dep_compute_string(const alpm_depend_t *dep); /** Return a newly allocated dependency information parsed from a string *\link alpm_dep_free should be used to free the dependency \endlink * @param depstring a formatted string, e.g. "glibc=2.12" * @return a dependency info structure */ alpm_depend_t *alpm_dep_from_string(const char *depstring); /** Free a dependency info structure * @param dep struct to free */ void alpm_dep_free(alpm_depend_t *dep); /** Free a fileconflict and its members. * @param conflict the fileconflict to free */ void alpm_fileconflict_free(alpm_fileconflict_t *conflict); /** Free a depmissing and its members * @param miss the depmissing to free * */ void alpm_depmissing_free(alpm_depmissing_t *miss); /** * Free a conflict and its members. * @param conflict the conflict to free */ void alpm_conflict_free(alpm_conflict_t *conflict); /* End of alpm_depends */ /** @} */ /** \addtogroup alpm_cb Callbacks * @brief Functions and structures for libalpm's callbacks * @{ */ /** * Type of events. */ typedef enum _alpm_event_type_t { /** Dependencies will be computed for a package. */ ALPM_EVENT_CHECKDEPS_START = 1, /** Dependencies were computed for a package. */ ALPM_EVENT_CHECKDEPS_DONE, /** File conflicts will be computed for a package. */ ALPM_EVENT_FILECONFLICTS_START, /** File conflicts were computed for a package. */ ALPM_EVENT_FILECONFLICTS_DONE, /** Dependencies will be resolved for target package. */ ALPM_EVENT_RESOLVEDEPS_START, /** Dependencies were resolved for target package. */ ALPM_EVENT_RESOLVEDEPS_DONE, /** Inter-conflicts will be checked for target package. */ ALPM_EVENT_INTERCONFLICTS_START, /** Inter-conflicts were checked for target package. */ ALPM_EVENT_INTERCONFLICTS_DONE, /** Processing the package transaction is starting. */ ALPM_EVENT_TRANSACTION_START, /** Processing the package transaction is finished. */ ALPM_EVENT_TRANSACTION_DONE, /** Package will be installed/upgraded/downgraded/re-installed/removed; See * alpm_event_package_operation_t for arguments. */ ALPM_EVENT_PACKAGE_OPERATION_START, /** Package was installed/upgraded/downgraded/re-installed/removed; See * alpm_event_package_operation_t for arguments. */ ALPM_EVENT_PACKAGE_OPERATION_DONE, /** Target package's integrity will be checked. */ ALPM_EVENT_INTEGRITY_START, /** Target package's integrity was checked. */ ALPM_EVENT_INTEGRITY_DONE, /** Target package will be loaded. */ ALPM_EVENT_LOAD_START, /** Target package is finished loading. */ ALPM_EVENT_LOAD_DONE, /** Scriptlet has printed information; See alpm_event_scriptlet_info_t for * arguments. */ ALPM_EVENT_SCRIPTLET_INFO, /** Database files will be downloaded from a repository. */ ALPM_EVENT_DB_RETRIEVE_START, /** Database files were downloaded from a repository. */ ALPM_EVENT_DB_RETRIEVE_DONE, /** Not all database files were successfully downloaded from a repository. */ ALPM_EVENT_DB_RETRIEVE_FAILED, /** Package files will be downloaded from a repository. */ ALPM_EVENT_PKG_RETRIEVE_START, /** Package files were downloaded from a repository. */ ALPM_EVENT_PKG_RETRIEVE_DONE, /** Not all package files were successfully downloaded from a repository. */ ALPM_EVENT_PKG_RETRIEVE_FAILED, /** Disk space usage will be computed for a package. */ ALPM_EVENT_DISKSPACE_START, /** Disk space usage was computed for a package. */ ALPM_EVENT_DISKSPACE_DONE, /** An optdepend for another package is being removed; See * alpm_event_optdep_removal_t for arguments. */ ALPM_EVENT_OPTDEP_REMOVAL, /** A configured repository database is missing; See * alpm_event_database_missing_t for arguments. */ ALPM_EVENT_DATABASE_MISSING, /** Checking keys used to create signatures are in keyring. */ ALPM_EVENT_KEYRING_START, /** Keyring checking is finished. */ ALPM_EVENT_KEYRING_DONE, /** Downloading missing keys into keyring. */ ALPM_EVENT_KEY_DOWNLOAD_START, /** Key downloading is finished. */ ALPM_EVENT_KEY_DOWNLOAD_DONE, /** A .pacnew file was created; See alpm_event_pacnew_created_t for arguments. */ ALPM_EVENT_PACNEW_CREATED, /** A .pacsave file was created; See alpm_event_pacsave_created_t for * arguments. */ ALPM_EVENT_PACSAVE_CREATED, /** Processing hooks will be started. */ ALPM_EVENT_HOOK_START, /** Processing hooks is finished. */ ALPM_EVENT_HOOK_DONE, /** A hook is starting */ ALPM_EVENT_HOOK_RUN_START, /** A hook has finished running. */ ALPM_EVENT_HOOK_RUN_DONE } alpm_event_type_t; /** An event that may reprisent any event. */ typedef struct _alpm_event_any_t { /** Type of event */ alpm_event_type_t type; } alpm_event_any_t; /** An enum over the kind of package operations. */ typedef enum _alpm_package_operation_t { /** Package (to be) installed. (No oldpkg) */ ALPM_PACKAGE_INSTALL = 1, /** Package (to be) upgraded */ ALPM_PACKAGE_UPGRADE, /** Package (to be) re-installed */ ALPM_PACKAGE_REINSTALL, /** Package (to be) downgraded */ ALPM_PACKAGE_DOWNGRADE, /** Package (to be) removed (No newpkg) */ ALPM_PACKAGE_REMOVE } alpm_package_operation_t; /** A package operation event occurred. */ typedef struct _alpm_event_package_operation_t { /** Type of event */ alpm_event_type_t type; /** Type of operation */ alpm_package_operation_t operation; /** Old package */ alpm_pkg_t *oldpkg; /** New package */ alpm_pkg_t *newpkg; } alpm_event_package_operation_t; /** An optional dependency was removed. */ typedef struct _alpm_event_optdep_removal_t { /** Type of event */ alpm_event_type_t type; /** Package with the optdep */ alpm_pkg_t *pkg; /** Optdep being removed */ alpm_depend_t *optdep; } alpm_event_optdep_removal_t; /** A scriptlet was ran. */ typedef struct _alpm_event_scriptlet_info_t { /** Type of event */ alpm_event_type_t type; /** Line of scriptlet output */ const char *line; } alpm_event_scriptlet_info_t; /** A database is missing. * * The database is registered but has not been downloaded */ typedef struct _alpm_event_database_missing_t { /** Type of event */ alpm_event_type_t type; /** Name of the database */ const char *dbname; } alpm_event_database_missing_t; /** A package was downloaded. */ typedef struct _alpm_event_pkgdownload_t { /** Type of event */ alpm_event_type_t type; /** Name of the file */ const char *file; } alpm_event_pkgdownload_t; /** A pacnew file was created. */ typedef struct _alpm_event_pacnew_created_t { /** Type of event */ alpm_event_type_t type; /** Whether the creation was result of a NoUpgrade or not */ int from_noupgrade; /** Old package */ alpm_pkg_t *oldpkg; /** New Package */ alpm_pkg_t *newpkg; /** Filename of the file without the .pacnew suffix */ const char *file; } alpm_event_pacnew_created_t; /** A pacsave file was created. */ typedef struct _alpm_event_pacsave_created_t { /** Type of event */ alpm_event_type_t type; /** Old package */ alpm_pkg_t *oldpkg; /** Filename of the file without the .pacsave suffix */ const char *file; } alpm_event_pacsave_created_t; /** Kind of hook. */ typedef enum _alpm_hook_when_t { /* Pre transaction hook */ ALPM_HOOK_PRE_TRANSACTION = 1, /* Post transaction hook */ ALPM_HOOK_POST_TRANSACTION } alpm_hook_when_t; /** pre/post transaction hooks are to be ran. */ typedef struct _alpm_event_hook_t { /** Type of event*/ alpm_event_type_t type; /** Type of hook */ alpm_hook_when_t when; } alpm_event_hook_t; /** A pre/post transaction hook was ran. */ typedef struct _alpm_event_hook_run_t { /** Type of event */ alpm_event_type_t type; /** Name of hook */ const char *name; /** Description of hook to be outputted */ const char *desc; /** position of hook being run */ size_t position; /** total hooks being run */ size_t total; } alpm_event_hook_run_t; /** Events. * This is a union passed to the callback that allows the frontend to know * which type of event was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access event-specific data. */ typedef union _alpm_event_t { /** Type of event it's always safe to access this. */ alpm_event_type_t type; /** The any event type. It's always safe to access this. */ alpm_event_any_t any; /** Package operation */ alpm_event_package_operation_t package_operation; /** An optdept was remove */ alpm_event_optdep_removal_t optdep_removal; /** A scriptlet was ran */ alpm_event_scriptlet_info_t scriptlet_info; /** A database is missing */ alpm_event_database_missing_t database_missing; /** A package was downloaded */ alpm_event_pkgdownload_t pkgdownload; /** A pacnew file was created */ alpm_event_pacnew_created_t pacnew_created; /** A pacsave file was created */ alpm_event_pacsave_created_t pacsave_created; /** Pre/post transaction hooks are being ran */ alpm_event_hook_t hook; /** A hook was ran */ alpm_event_hook_run_t hook_run; } alpm_event_t; /** Event callback. * * Called when an event occurs * @param event the event that occurred */ typedef void (*alpm_cb_event)(alpm_event_t *); /** * Type of question. * Unlike the events or progress enumerations, this enum has bitmask values * so a frontend can use a bitmask map to supply preselected answers to the * different types of questions. */ typedef enum _alpm_question_type_t { /** Should target in ignorepkg be installed anyway? */ ALPM_QUESTION_INSTALL_IGNOREPKG = (1 << 0), /** Should a package be replaced? */ ALPM_QUESTION_REPLACE_PKG = (1 << 1), /** Should a conflicting package be removed? */ ALPM_QUESTION_CONFLICT_PKG = (1 << 2), /** Should a corrupted package be deleted? */ ALPM_QUESTION_CORRUPTED_PKG = (1 << 3), /** Should unresolvable targets be removed from the transaction? */ ALPM_QUESTION_REMOVE_PKGS = (1 << 4), /** Provider selection */ ALPM_QUESTION_SELECT_PROVIDER = (1 << 5), /** Should a key be imported? */ ALPM_QUESTION_IMPORT_KEY = (1 << 6) } alpm_question_type_t; /** A question that can represent any other question. */ typedef struct _alpm_question_any_t { /** Type of question */ alpm_question_type_t type; /** Answer */ int answer; } alpm_question_any_t; /** Should target in ignorepkg be installed anyway? */ typedef struct _alpm_question_install_ignorepkg_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to install pkg anyway */ int install; /** The ignored package that we are deciding whether to install */ alpm_pkg_t *pkg; } alpm_question_install_ignorepkg_t; /** Should a package be replaced? */ typedef struct _alpm_question_replace_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to replace oldpkg with newpkg */ int replace; /** Package to be replaced */ alpm_pkg_t *oldpkg; /** Package to replace with.*/ alpm_pkg_t *newpkg; /** DB of newpkg */ alpm_db_t *newdb; } alpm_question_replace_t; /** Should a conflicting package be removed? */ typedef struct _alpm_question_conflict_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to remove conflict->package2 */ int remove; /** Conflict info */ alpm_conflict_t *conflict; } alpm_question_conflict_t; /** Should a corrupted package be deleted? */ typedef struct _alpm_question_corrupted_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to remove filepath */ int remove; /** File to remove */ const char *filepath; /** Error code indicating the reason for package invalidity */ alpm_errno_t reason; } alpm_question_corrupted_t; /** Should unresolvable targets be removed from the transaction? */ typedef struct _alpm_question_remove_pkgs_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to skip packages */ int skip; /** List of alpm_pkg_t* with unresolved dependencies */ alpm_list_t *packages; } alpm_question_remove_pkgs_t; /** Provider selection */ typedef struct _alpm_question_select_provider_t { /** Type of question */ alpm_question_type_t type; /** Answer: which provider to use (index from providers) */ int use_index; /** List of alpm_pkg_t* as possible providers */ alpm_list_t *providers; /** What providers provide for */ alpm_depend_t *depend; } alpm_question_select_provider_t; /** Should a key be imported? */ typedef struct _alpm_question_import_key_t { /** Type of question */ alpm_question_type_t type; /** Answer: whether or not to import key */ int import; /** The key to import */ alpm_pgpkey_t *key; } alpm_question_import_key_t; /** * Questions. * This is an union passed to the callback that allows the frontend to know * which type of question was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access question-specific data. */ typedef union _alpm_question_t { /** The type of question. It's always safe to access this. */ alpm_question_type_t type; /** A question that can represent any question. * It's always safe to access this. */ alpm_question_any_t any; /** Should target in ignorepkg be installed anyway? */ alpm_question_install_ignorepkg_t install_ignorepkg; /** Should a package be replaced? */ alpm_question_replace_t replace; /** Should a conflicting package be removed? */ alpm_question_conflict_t conflict; /** Should a corrupted package be deleted? */ alpm_question_corrupted_t corrupted; /** Should unresolvable targets be removed from the transaction? */ alpm_question_remove_pkgs_t remove_pkgs; /** Provider selection */ alpm_question_select_provider_t select_provider; /** Should a key be imported? */ alpm_question_import_key_t import_key; } alpm_question_t; /** Question callback. * * This callback allows user to give input and decide what to do during certain events * @param question the question being asked. */ typedef void (*alpm_cb_question)(alpm_question_t *); /** An enum over different kinds of progress alerts. */ typedef enum _alpm_progress_t { /** Package install */ ALPM_PROGRESS_ADD_START, /** Package upgrade */ ALPM_PROGRESS_UPGRADE_START, /** Package downgrade */ ALPM_PROGRESS_DOWNGRADE_START, /** Package reinstall */ ALPM_PROGRESS_REINSTALL_START, /** Package removal */ ALPM_PROGRESS_REMOVE_START, /** Conflict checking */ ALPM_PROGRESS_CONFLICTS_START, /** Diskspace checking */ ALPM_PROGRESS_DISKSPACE_START, /** Package Integrity checking */ ALPM_PROGRESS_INTEGRITY_START, /** Loading packages from disk */ ALPM_PROGRESS_LOAD_START, /** Checking signatures of packages */ ALPM_PROGRESS_KEYRING_START } alpm_progress_t; /** Progress callback * * Alert the front end about the progress of certain events. * Allows the implementation of loading bars for events that * make take a while to complete. * @param progress the kind of event that is progressing * @param pkg for package operations, the name of the package being operated on * @param percent the percent completion of the action * @param howmany the total amount of items in the action * @param current the current amount of items completed */ /** Progress callback */ typedef void (*alpm_cb_progress)(alpm_progress_t progress, const char *pkg, int percent, size_t howmany, size_t current); /* * Downloading */ /** File download events. * These events are reported by ALPM via download callback. */ typedef enum _alpm_download_event_type_t { /** A download was started */ ALPM_DOWNLOAD_INIT, /** A download made progress */ ALPM_DOWNLOAD_PROGRESS, /** A download completed */ ALPM_DOWNLOAD_COMPLETED } alpm_download_event_type_t; /** Context struct for when a download starts. */ typedef struct _alpm_download_event_init_t { /** whether this file is optional and thus the errors could be ignored */ int optional; } alpm_download_event_init_t; /** Context struct for when a download progresses. */ typedef struct _alpm_download_event_progress_t { /** Amount of data downloaded */ off_t downloaded; /** Total amount need to be downloaded */ off_t total; } alpm_download_event_progress_t; /** Context struct for when a download completes. */ typedef struct _alpm_download_event_completed_t { /** Total bytes in file */ off_t total; /** download result code: * 0 - download completed successfully * 1 - the file is up-to-date * -1 - error */ int result; } alpm_download_event_completed_t; /** Type of download progress callbacks. * @param filename the name of the file being downloaded * @param event the event type * @param data the event data of type alpm_download_event_*_t */ typedef void (*alpm_cb_download)(const char *filename, alpm_download_event_type_t event, void *data); /** Total Download callback. * @param total amount that will be downloaded during \link alpm_trans_commit \endlink. */ typedef void (*alpm_cb_totaldl)(off_t total); /** A callback for downloading files * @param url the URL of the file to be downloaded * @param localpath the directory to which the file should be downloaded * @param force whether to force an update, even if the file is the same * @return 0 on success, 1 if the file exists and is identical, -1 on * error. */ typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, int force); /* End of alpm_cb */ /** @} */ /** @addtogroup alpm_databases Database * @brief Functions to query and manipulate the database of libalpm. * @{ */ /** Get the database of locally installed packages. * The returned pointer points to an internal structure * of libalpm which should only be manipulated through * libalpm functions. * @return a reference to the local database */ alpm_db_t *alpm_get_localdb(alpm_handle_t *handle); /** Get the list of sync databases. * Returns a list of alpm_db_t structures, one for each registered * sync database. * * @param handle the context handle * @return a reference to an internal list of alpm_db_t structures */ alpm_list_t *alpm_get_syncdbs(alpm_handle_t *handle); /** Register a sync database of packages. * Databases can not be registered when there is an active transaction. * * @param handle the context handle * @param treename the name of the sync repository * @param level what level of signature checking to perform on the * database; note that this must be a '.sig' file type verification * @return an alpm_db_t* on success (the value), NULL on error */ alpm_db_t *alpm_register_syncdb(alpm_handle_t *handle, const char *treename, int level); /** Unregister all package databases. * Databases can not be unregistered while there is an active transaction. * * @param handle the context handle * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_unregister_all_syncdbs(alpm_handle_t *handle); /** Unregister a package database. * Databases can not be unregistered when there is an active transaction. * * @param db pointer to the package database to unregister * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_db_unregister(alpm_db_t *db); /** Get the name of a package database. * @param db pointer to the package database * @return the name of the package database, NULL on error */ const char *alpm_db_get_name(const alpm_db_t *db); /** Get the signature verification level for a database. * Will return the default verification level if this database is set up * with ALPM_SIG_USE_DEFAULT. * @param db pointer to the package database * @return the signature verification level */ int alpm_db_get_siglevel(alpm_db_t *db); /** Check the validity of a database. * This is most useful for sync databases and verifying signature status. * If invalid, the handle error code will be set accordingly. * @param db pointer to the package database * @return 0 if valid, -1 if invalid (pm_errno is set accordingly) */ int alpm_db_get_valid(alpm_db_t *db); /** @name Server accessors * @{ */ /** Get the list of servers assigned to this db. * @param db pointer to the database to get the servers from * @return a char* list of servers */ alpm_list_t *alpm_db_get_servers(const alpm_db_t *db); /** Sets the list of servers for the database to use. * @param db the database to set the servers * @param servers a char* list of servers. Note: the database will * take ownership of the list and it should no longer be * freed by the caller */ int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers); /** Add a download server to a database. * @param db database pointer * @param url url of the server * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_db_add_server(alpm_db_t *db, const char *url); /** Remove a download server from a database. * @param db database pointer * @param url url of the server * @return 0 on success, 1 on server not present, * -1 on error (pm_errno is set accordingly) */ int alpm_db_remove_server(alpm_db_t *db, const char *url); /* End of server accessors */ /** @} */ /** Update package databases. * * An update of the package databases in the list \a dbs will be attempted. * Unless \a force is true, the update will only be performed if the remote * databases were modified since the last update. * * This operation requires a database lock, and will return an applicable error * if the lock could not be obtained. * * Example: * @code * alpm_list_t *dbs = alpm_get_syncdbs(config->handle); * ret = alpm_db_update(config->handle, dbs, force); * if(ret < 0) { * pm_printf(ALPM_LOG_ERROR, _("failed to synchronize all databases (%s)\n"), * alpm_strerror(alpm_errno(config->handle))); * } * @endcode * * @note After a successful update, the \link alpm_db_get_pkgcache() * package cache \endlink will be invalidated * @param handle the context handle * @param dbs list of package databases to update * @param force if true, then forces the update, otherwise update only in case * the databases aren't up to date * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_db_update(alpm_handle_t *handle, alpm_list_t *dbs, int force); /** Get a package entry from a package database. * Looking up a package is O(1) and will be significantly faster than * iterating over the pkgcahe. * @param db pointer to the package database to get the package from * @param name of the package * @return the package entry on success, NULL on error */ alpm_pkg_t *alpm_db_get_pkg(alpm_db_t *db, const char *name); /** Get the package cache of a package database. * This is a list of all packages the db contains. * @param db pointer to the package database to get the package from * @return the list of packages on success, NULL on error */ alpm_list_t *alpm_db_get_pkgcache(alpm_db_t *db); /** Get a group entry from a package database. * Looking up a group is O(1) and will be significantly faster than * iterating over the groupcahe. * @param db pointer to the package database to get the group from * @param name of the group * @return the groups entry on success, NULL on error */ alpm_group_t *alpm_db_get_group(alpm_db_t *db, const char *name); /** Get the group cache of a package database. * @param db pointer to the package database to get the group from * @return the list of groups on success, NULL on error */ alpm_list_t *alpm_db_get_groupcache(alpm_db_t *db); /** Searches a database with regular expressions. * @param db pointer to the package database to search in * @param needles a list of regular expressions to search for * @param ret pointer to list for storing packages matching all * regular expressions - must point to an empty (NULL) alpm_list_t *. * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_db_search(alpm_db_t *db, const alpm_list_t *needles, alpm_list_t **ret); /** The usage level of a database. */ typedef enum _alpm_db_usage_t { /** Enable refreshes for this database */ ALPM_DB_USAGE_SYNC = 1, /** Enable search for this database */ ALPM_DB_USAGE_SEARCH = (1 << 1), /** Enable installing packages from this database */ ALPM_DB_USAGE_INSTALL = (1 << 2), /** Enable sysupgrades with this database */ ALPM_DB_USAGE_UPGRADE = (1 << 3), /** Enable all usage levels */ ALPM_DB_USAGE_ALL = (1 << 4) - 1, } alpm_db_usage_t; /** @name Usage accessors * @{ */ /** Sets the usage of a database. * @param db pointer to the package database to set the status for * @param usage a bitmask of alpm_db_usage_t values * @return 0 on success, or -1 on error */ int alpm_db_set_usage(alpm_db_t *db, int usage); /** Gets the usage of a database. * @param db pointer to the package database to get the status of * @param usage pointer to an alpm_db_usage_t to store db's status * @return 0 on success, or -1 on error */ int alpm_db_get_usage(alpm_db_t *db, int *usage); /* End of usage accessors */ /** @} */ /* End of alpm_databases */ /** @} */ /** \addtogroup alpm_log Logging Functions * @brief Functions to log using libalpm * @{ */ /** Logging Levels */ typedef enum _alpm_loglevel_t { /** Error */ ALPM_LOG_ERROR = 1, /** Warning */ ALPM_LOG_WARNING = (1 << 1), /** Debug */ ALPM_LOG_DEBUG = (1 << 2), /** Function */ ALPM_LOG_FUNCTION = (1 << 3) } alpm_loglevel_t; /** The callback type for logging. * * libalpm will call this function whenever something is to be logged. * many libalpm will produce log output. Additionally any calls to \link alpm_logaction * \endlink will also call this callback. * @param level the currently set loglevel * @param fmt the printf like format string * @param args printf like arguments */ typedef void (*alpm_cb_log)(alpm_loglevel_t level, const char *fmt, va_list args); /** A printf-like function for logging. * @param handle the context handle * @param prefix caller-specific prefix for the log * @param fmt output format * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_logaction(alpm_handle_t *handle, const char *prefix, const char *fmt, ...) __attribute__((format(printf, 3, 4))); /* End of alpm_log */ /** @} */ /** @addtogroup alpm_api_options Options * Libalpm option getters and setters * @{ */ /** Returns the callback used for logging. */ alpm_cb_log alpm_option_get_logcb(alpm_handle_t *handle); /** Sets the callback used for logging. */ int alpm_option_set_logcb(alpm_handle_t *handle, alpm_cb_log cb); /** Returns the callback used to report download progress. */ alpm_cb_download alpm_option_get_dlcb(alpm_handle_t *handle); /** Sets the callback used to report download progress. */ int alpm_option_set_dlcb(alpm_handle_t *handle, alpm_cb_download cb); /** Returns the downloading callback. */ alpm_cb_fetch alpm_option_get_fetchcb(alpm_handle_t *handle); /** Sets the downloading callback. */ int alpm_option_set_fetchcb(alpm_handle_t *handle, alpm_cb_fetch cb); /** Returns the callback used to report total download size. */ alpm_cb_totaldl alpm_option_get_totaldlcb(alpm_handle_t *handle); /** Sets the callback used to report total download size. */ int alpm_option_set_totaldlcb(alpm_handle_t *handle, alpm_cb_totaldl cb); /** Returns the callback used for events. */ alpm_cb_event alpm_option_get_eventcb(alpm_handle_t *handle); /** Sets the callback used for events. */ int alpm_option_set_eventcb(alpm_handle_t *handle, alpm_cb_event cb); /** Returns the callback used for questions. */ alpm_cb_question alpm_option_get_questioncb(alpm_handle_t *handle); /** Sets the callback used for questions. */ int alpm_option_set_questioncb(alpm_handle_t *handle, alpm_cb_question cb); /** Returns the callback used for operation progress. */ alpm_cb_progress alpm_option_get_progresscb(alpm_handle_t *handle); /** Sets the callback used for operation progress. */ int alpm_option_set_progresscb(alpm_handle_t *handle, alpm_cb_progress cb); /** Returns the root of the destination filesystem. Read-only. */ const char *alpm_option_get_root(alpm_handle_t *handle); /** Returns the path to the database directory. Read-only. */ const char *alpm_option_get_dbpath(alpm_handle_t *handle); /** Get the name of the database lock file. Read-only. */ const char *alpm_option_get_lockfile(alpm_handle_t *handle); /** @name Accessors to the list of package cache directories. * @{ */ alpm_list_t *alpm_option_get_cachedirs(alpm_handle_t *handle); int alpm_option_set_cachedirs(alpm_handle_t *handle, alpm_list_t *cachedirs); int alpm_option_add_cachedir(alpm_handle_t *handle, const char *cachedir); int alpm_option_remove_cachedir(alpm_handle_t *handle, const char *cachedir); /** @} */ /** @name Accessors to the list of package hook directories. * @{ */ alpm_list_t *alpm_option_get_hookdirs(alpm_handle_t *handle); int alpm_option_set_hookdirs(alpm_handle_t *handle, alpm_list_t *hookdirs); int alpm_option_add_hookdir(alpm_handle_t *handle, const char *hookdir); int alpm_option_remove_hookdir(alpm_handle_t *handle, const char *hookdir); /** @} */ alpm_list_t *alpm_option_get_overwrite_files(alpm_handle_t *handle); int alpm_option_set_overwrite_files(alpm_handle_t *handle, alpm_list_t *globs); int alpm_option_add_overwrite_file(alpm_handle_t *handle, const char *glob); int alpm_option_remove_overwrite_file(alpm_handle_t *handle, const char *glob); /** Returns the logfile name. */ const char *alpm_option_get_logfile(alpm_handle_t *handle); /** Sets the logfile name. */ int alpm_option_set_logfile(alpm_handle_t *handle, const char *logfile); /** Returns the path to libalpm's GnuPG home directory. */ const char *alpm_option_get_gpgdir(alpm_handle_t *handle); /** Sets the path to libalpm's GnuPG home directory. */ int alpm_option_set_gpgdir(alpm_handle_t *handle, const char *gpgdir); /** Returns whether to use syslog (0 is FALSE, TRUE otherwise). */ int alpm_option_get_usesyslog(alpm_handle_t *handle); /** Sets whether to use syslog (0 is FALSE, TRUE otherwise). */ int alpm_option_set_usesyslog(alpm_handle_t *handle, int usesyslog); /** @name Accessors to the list of no-upgrade files. * These functions modify the list of files which should * not be updated by package installation. * @{ */ alpm_list_t *alpm_option_get_noupgrades(alpm_handle_t *handle); int alpm_option_add_noupgrade(alpm_handle_t *handle, const char *path); int alpm_option_set_noupgrades(alpm_handle_t *handle, alpm_list_t *noupgrade); int alpm_option_remove_noupgrade(alpm_handle_t *handle, const char *path); int alpm_option_match_noupgrade(alpm_handle_t *handle, const char *path); /** @} */ /** @name Accessors to the list of no-extract files. * These functions modify the list of filenames which should * be skipped packages which should * not be upgraded by a sysupgrade operation. * @{ */ alpm_list_t *alpm_option_get_noextracts(alpm_handle_t *handle); int alpm_option_add_noextract(alpm_handle_t *handle, const char *path); int alpm_option_set_noextracts(alpm_handle_t *handle, alpm_list_t *noextract); int alpm_option_remove_noextract(alpm_handle_t *handle, const char *path); int alpm_option_match_noextract(alpm_handle_t *handle, const char *path); /** @} */ /** @name Accessors to the list of ignored packages. * These functions modify the list of packages that * should be ignored by a sysupgrade. * @{ */ alpm_list_t *alpm_option_get_ignorepkgs(alpm_handle_t *handle); int alpm_option_add_ignorepkg(alpm_handle_t *handle, const char *pkg); int alpm_option_set_ignorepkgs(alpm_handle_t *handle, alpm_list_t *ignorepkgs); int alpm_option_remove_ignorepkg(alpm_handle_t *handle, const char *pkg); /** @} */ /** @name Accessors to the list of ignored groups. * These functions modify the list of groups whose packages * should be ignored by a sysupgrade. * @{ */ alpm_list_t *alpm_option_get_ignoregroups(alpm_handle_t *handle); int alpm_option_add_ignoregroup(alpm_handle_t *handle, const char *grp); int alpm_option_set_ignoregroups(alpm_handle_t *handle, alpm_list_t *ignoregrps); int alpm_option_remove_ignoregroup(alpm_handle_t *handle, const char *grp); /** @} */ /** @name Accessors to the list of ignored dependencies. * These functions modify the list of dependencies that * should be ignored by a sysupgrade. * @{ */ alpm_list_t *alpm_option_get_assumeinstalled(alpm_handle_t *handle); int alpm_option_add_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep); int alpm_option_set_assumeinstalled(alpm_handle_t *handle, alpm_list_t *deps); int alpm_option_remove_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep); /** @} */ /** Returns the targeted architecture. */ const char *alpm_option_get_arch(alpm_handle_t *handle); /** Sets the targeted architecture. */ int alpm_option_set_arch(alpm_handle_t *handle, const char *arch); int alpm_option_get_checkspace(alpm_handle_t *handle); int alpm_option_set_checkspace(alpm_handle_t *handle, int checkspace); const char *alpm_option_get_dbext(alpm_handle_t *handle); int alpm_option_set_dbext(alpm_handle_t *handle, const char *dbext); int alpm_option_get_default_siglevel(alpm_handle_t *handle); int alpm_option_set_default_siglevel(alpm_handle_t *handle, int level); int alpm_option_get_local_file_siglevel(alpm_handle_t *handle); int alpm_option_set_local_file_siglevel(alpm_handle_t *handle, int level); int alpm_option_get_remote_file_siglevel(alpm_handle_t *handle); int alpm_option_set_remote_file_siglevel(alpm_handle_t *handle, int level); int alpm_option_set_disable_dl_timeout(alpm_handle_t *handle, unsigned short disable_dl_timeout); int alpm_option_get_parallel_downloads(alpm_handle_t *handle); /** Sets number of parallel streams to download database and package files. * If the function is not called then the default value of '1' stream * (i.e. sequential download) is used. * @param handle the context handle * @param num_streams number of parallel download streams * @return 0 on success, -1 on error */ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_streams); /** @} */ /** @addtogroup alpm_packages Package Functions * Functions to manipulate libalpm packages * @{ */ /** Package install reasons. */ typedef enum _alpm_pkgreason_t { /** Explicitly requested by the user. */ ALPM_PKG_REASON_EXPLICIT = 0, /** Installed as a dependency for another package. */ ALPM_PKG_REASON_DEPEND = 1 } alpm_pkgreason_t; /** Location a package object was loaded from. */ typedef enum _alpm_pkgfrom_t { /** Loaded from a file via \link alpm_pkg_load \endlink */ ALPM_PKG_FROM_FILE = 1, /** From the local database */ ALPM_PKG_FROM_LOCALDB, /** From a sync database */ ALPM_PKG_FROM_SYNCDB } alpm_pkgfrom_t; /** Method used to validate a package. */ typedef enum _alpm_pkgvalidation_t { /** The package's validation type is unknown */ ALPM_PKG_VALIDATION_UNKNOWN = 0, /** The package does not have any validation */ ALPM_PKG_VALIDATION_NONE = (1 << 0), /** The package is validated with md5 */ ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), /** The package is validated with sha256 */ ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), /** The package is validated with a PGP signature */ ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) } alpm_pkgvalidation_t; /** Create a package from a file. * If full is false, the archive is read only until all necessary * metadata is found. If it is true, the entire archive is read, which * serves as a verification of integrity and the filelist can be created. * The allocated structure should be freed using alpm_pkg_free(). * @param handle the context handle * @param filename location of the package tarball * @param full whether to stop the load after metadata is read or continue * through the full archive * @param level what level of package signature checking to perform on the * package; note that this must be a '.sig' file type verification * @param pkg address of the package pointer * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_pkg_load(alpm_handle_t *handle, const char *filename, int full, int level, alpm_pkg_t **pkg); /** Fetch a list of remote packages. * @param handle the context handle * @param urls list of package URLs to download * @param fetched list of filepaths to the fetched packages, each item * corresponds to one in `urls` list. This is an output parameter, * the caller should provide a pointer to an empty list * (*fetched === NULL) and the callee fills the list with data. * @return 0 on success or -1 on failure */ int alpm_fetch_pkgurl(alpm_handle_t *handle, const alpm_list_t *urls, alpm_list_t **fetched); /** Find a package in a list by name. * @param haystack a list of alpm_pkg_t * @param needle the package name * @return a pointer to the package if found or NULL */ alpm_pkg_t *alpm_pkg_find(alpm_list_t *haystack, const char *needle); /** Free a package. * Only packages loaded with \link alpm_pkg_load \endlink can be freed. * Packages from databases will be freed by libalpm when they are unregistered. * @param pkg package pointer to free * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_pkg_free(alpm_pkg_t *pkg); /** Check the integrity (with md5) of a package from the sync cache. * @param pkg package pointer * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_pkg_checkmd5sum(alpm_pkg_t *pkg); /** Compare two version strings and determine which one is 'newer'. * Returns a value comparable to the way strcmp works. Returns 1 * if a is newer than b, 0 if a and b are the same version, or -1 * if b is newer than a. * * Different epoch values for version strings will override any further * comparison. If no epoch is provided, 0 is assumed. * * Keep in mind that the pkgrel is only compared if it is available * on both versions handed to this function. For example, comparing * 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield * -1 as expected. This is mainly for supporting versioned dependencies * that do not include the pkgrel. */ int alpm_pkg_vercmp(const char *a, const char *b); /** Computes the list of packages requiring a given package. * The return value of this function is a newly allocated * list of package names (char*), it should be freed by the caller. * @param pkg a package * @return the list of packages requiring pkg */ alpm_list_t *alpm_pkg_compute_requiredby(alpm_pkg_t *pkg); /** Computes the list of packages optionally requiring a given package. * The return value of this function is a newly allocated * list of package names (char*), it should be freed by the caller. * @param pkg a package * @return the list of packages optionally requiring pkg */ alpm_list_t *alpm_pkg_compute_optionalfor(alpm_pkg_t *pkg); /** Test if a package should be ignored. * Checks if the package is ignored via IgnorePkg, or if the package is * in a group ignored via IgnoreGroup. * @param handle the context handle * @param pkg the package to test * @return 1 if the package should be ignored, 0 otherwise */ int alpm_pkg_should_ignore(alpm_handle_t *handle, alpm_pkg_t *pkg); /** @name Package Property Accessors * Any pointer returned by these functions points to internal structures * allocated by libalpm. They should not be freed nor modified in any * way. * * For loaded packages, they will be freed when \link alpm_pkg_free \endlink is called. * For database packages, they will be freed when the database is unregistered. * @{ */ /** Gets the name of the file from which the package was loaded. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_filename(alpm_pkg_t *pkg); /** Returns the package base name. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_base(alpm_pkg_t *pkg); /** Returns the package name. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_name(alpm_pkg_t *pkg); /** Returns the package version as a string. * This includes all available epoch, version, and pkgrel components. Use * alpm_pkg_vercmp() to compare version strings if necessary. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_version(alpm_pkg_t *pkg); /** Returns the origin of the package. * @return an alpm_pkgfrom_t constant, -1 on error */ alpm_pkgfrom_t alpm_pkg_get_origin(alpm_pkg_t *pkg); /** Returns the package description. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_desc(alpm_pkg_t *pkg); /** Returns the package URL. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_url(alpm_pkg_t *pkg); /** Returns the build timestamp of the package. * @param pkg a pointer to package * @return the timestamp of the build time */ alpm_time_t alpm_pkg_get_builddate(alpm_pkg_t *pkg); /** Returns the install timestamp of the package. * @param pkg a pointer to package * @return the timestamp of the install time */ alpm_time_t alpm_pkg_get_installdate(alpm_pkg_t *pkg); /** Returns the packager's name. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_packager(alpm_pkg_t *pkg); /** Returns the package's MD5 checksum as a string. * The returned string is a sequence of 32 lowercase hexadecimal digits. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_md5sum(alpm_pkg_t *pkg); /** Returns the package's SHA256 checksum as a string. * The returned string is a sequence of 64 lowercase hexadecimal digits. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_sha256sum(alpm_pkg_t *pkg); /** Returns the architecture for which the package was built. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_arch(alpm_pkg_t *pkg); /** Returns the size of the package. This is only available for sync database * packages and package files, not those loaded from the local database. * @param pkg a pointer to package * @return the size of the package in bytes. */ off_t alpm_pkg_get_size(alpm_pkg_t *pkg); /** Returns the installed size of the package. * @param pkg a pointer to package * @return the total size of files installed by the package. */ off_t alpm_pkg_get_isize(alpm_pkg_t *pkg); /** Returns the package installation reason. * @param pkg a pointer to package * @return an enum member giving the install reason. */ alpm_pkgreason_t alpm_pkg_get_reason(alpm_pkg_t *pkg); /** Returns the list of package licenses. * @param pkg a pointer to package * @return a pointer to an internal list of strings. */ alpm_list_t *alpm_pkg_get_licenses(alpm_pkg_t *pkg); /** Returns the list of package groups. * @param pkg a pointer to package * @return a pointer to an internal list of strings. */ alpm_list_t *alpm_pkg_get_groups(alpm_pkg_t *pkg); /** Returns the list of package dependencies as alpm_depend_t. * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_depends(alpm_pkg_t *pkg); /** Returns the list of package optional dependencies. * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_optdepends(alpm_pkg_t *pkg); /** Returns a list of package check dependencies * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_checkdepends(alpm_pkg_t *pkg); /** Returns a list of package make dependencies * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_makedepends(alpm_pkg_t *pkg); /** Returns the list of packages conflicting with pkg. * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_conflicts(alpm_pkg_t *pkg); /** Returns the list of packages provided by pkg. * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_provides(alpm_pkg_t *pkg); /** Returns the list of packages to be replaced by pkg. * @param pkg a pointer to package * @return a reference to an internal list of alpm_depend_t structures. */ alpm_list_t *alpm_pkg_get_replaces(alpm_pkg_t *pkg); /** Returns the list of files installed by pkg. * The filenames are relative to the install root, * and do not include leading slashes. * @param pkg a pointer to package * @return a pointer to a filelist object containing a count and an array of * package file objects */ alpm_filelist_t *alpm_pkg_get_files(alpm_pkg_t *pkg); /** Returns the list of files backed up when installing pkg. * @param pkg a pointer to package * @return a reference to a list of alpm_backup_t objects */ alpm_list_t *alpm_pkg_get_backup(alpm_pkg_t *pkg); /** Returns the database containing pkg. * Returns a pointer to the alpm_db_t structure the package is * originating from, or NULL if the package was loaded from a file. * @param pkg a pointer to package * @return a pointer to the DB containing pkg, or NULL. */ alpm_db_t *alpm_pkg_get_db(alpm_pkg_t *pkg); /** Returns the base64 encoded package signature. * @param pkg a pointer to package * @return a reference to an internal string */ const char *alpm_pkg_get_base64_sig(alpm_pkg_t *pkg); /** Extracts package signature either from embedded package signature * or if it is absent then reads data from detached signature file. * @param pkg a pointer to package. * @param sig output parameter for signature data. Callee function allocates * a buffer needed for the signature data. Caller is responsible for * freeing this buffer. * @param sig_len output parameter for the signature data length. * @return 0 on success, negative number on error. */ int alpm_pkg_get_sig(alpm_pkg_t *pkg, unsigned char **sig, size_t *sig_len); /** Returns the method used to validate a package during install. * @param pkg a pointer to package * @return an enum member giving the validation method */ int alpm_pkg_get_validation(alpm_pkg_t *pkg); /** Returns whether the package has an install scriptlet. * @return 0 if FALSE, TRUE otherwise */ int alpm_pkg_has_scriptlet(alpm_pkg_t *pkg); /** Returns the size of the files that will be downloaded to install a * package. * @param newpkg the new package to upgrade to * @return the size of the download */ off_t alpm_pkg_download_size(alpm_pkg_t *newpkg); /** Set install reason for a package in the local database. * The provided package object must be from the local database or this method * will fail. The write to the local database is performed immediately. * @param pkg the package to update * @param reason the new install reason * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); /* End of alpm_pkg_t accessors */ /** @} */ /** @name Changelog functions * Functions for reading the changelog * @{ */ /** Open a package changelog for reading. * Similar to fopen in functionality, except that the returned 'file * stream' could really be from an archive as well as from the database. * @param pkg the package to read the changelog of (either file or db) * @return a 'file stream' to the package changelog */ void *alpm_pkg_changelog_open(alpm_pkg_t *pkg); /** Read data from an open changelog 'file stream'. * Similar to fread in functionality, this function takes a buffer and * amount of data to read. If an error occurs pm_errno will be set. * @param ptr a buffer to fill with raw changelog data * @param size the size of the buffer * @param pkg the package that the changelog is being read from * @param fp a 'file stream' to the package changelog * @return the number of characters read, or 0 if there is no more data or an * error occurred. */ size_t alpm_pkg_changelog_read(void *ptr, size_t size, const alpm_pkg_t *pkg, void *fp); /** Close a package changelog for reading. * @param pkg the package to close the changelog of (either file or db) * @param fp the 'file stream' to the package changelog to close * @return 0 on success, -1 on error */ int alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp); /* End of changelog accessors */ /** @} */ /** @name Mtree functions * Functions for reading the mtree * @{ */ /** Open a package mtree file for reading. * @param pkg the local package to read the mtree of * @return an archive structure for the package mtree file */ struct archive *alpm_pkg_mtree_open(alpm_pkg_t *pkg); /** Read next entry from a package mtree file. * @param pkg the package that the mtree file is being read from * @param archive the archive structure reading from the mtree file * @param entry an archive_entry to store the entry header information * @return 0 on success, 1 if end of archive is reached, -1 otherwise. */ int alpm_pkg_mtree_next(const alpm_pkg_t *pkg, struct archive *archive, struct archive_entry **entry); /** Close a package mtree file. * @param pkg the local package to close the mtree of * @param archive the archive to close */ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); /* End of mtree accessors */ /** @} */ /* End of alpm_packages */ /** @} */ /* * Sync */ /** Check for new version of pkg in sync repos * (only the first occurrence is considered in sync) */ alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync); /** @addtogroup alpm_api_trans Transaction Functions * Functions to manipulate libalpm transactions * @{ */ /** Transaction flags */ typedef enum _alpm_transflag_t { /** Ignore dependency checks. */ ALPM_TRANS_FLAG_NODEPS = 1, /* (1 << 1) flag can go here */ /** Delete files even if they are tagged as backup. */ ALPM_TRANS_FLAG_NOSAVE = (1 << 2), /** Ignore version numbers when checking dependencies. */ ALPM_TRANS_FLAG_NODEPVERSION = (1 << 3), /** Remove also any packages depending on a package being removed. */ ALPM_TRANS_FLAG_CASCADE = (1 << 4), /** Remove packages and their unneeded deps (not explicitly installed). */ ALPM_TRANS_FLAG_RECURSE = (1 << 5), /** Modify database but do not commit changes to the filesystem. */ ALPM_TRANS_FLAG_DBONLY = (1 << 6), /* (1 << 7) flag can go here */ /** Use ALPM_PKG_REASON_DEPEND when installing packages. */ ALPM_TRANS_FLAG_ALLDEPS = (1 << 8), /** Only download packages and do not actually install. */ ALPM_TRANS_FLAG_DOWNLOADONLY = (1 << 9), /** Do not execute install scriptlets after installing. */ ALPM_TRANS_FLAG_NOSCRIPTLET = (1 << 10), /** Ignore dependency conflicts. */ ALPM_TRANS_FLAG_NOCONFLICTS = (1 << 11), /* (1 << 12) flag can go here */ /** Do not install a package if it is already installed and up to date. */ ALPM_TRANS_FLAG_NEEDED = (1 << 13), /** Use ALPM_PKG_REASON_EXPLICIT when installing packages. */ ALPM_TRANS_FLAG_ALLEXPLICIT = (1 << 14), /** Do not remove a package if it is needed by another one. */ ALPM_TRANS_FLAG_UNNEEDED = (1 << 15), /** Remove also explicitly installed unneeded deps (use with ALPM_TRANS_FLAG_RECURSE). */ ALPM_TRANS_FLAG_RECURSEALL = (1 << 16), /** Do not lock the database during the operation. */ ALPM_TRANS_FLAG_NOLOCK = (1 << 17) } alpm_transflag_t; /** Returns the bitfield of flags for the current transaction. * @param handle the context handle * @return the bitfield of transaction flags */ int alpm_trans_get_flags(alpm_handle_t *handle); /** Returns a list of packages added by the transaction. * @param handle the context handle * @return a list of alpm_pkg_t structures */ alpm_list_t *alpm_trans_get_add(alpm_handle_t *handle); /** Returns the list of packages removed by the transaction. * @param handle the context handle * @return a list of alpm_pkg_t structures */ alpm_list_t *alpm_trans_get_remove(alpm_handle_t *handle); /** Initialize the transaction. * @param handle the context handle * @param flags flags of the transaction (like nodeps, etc; see alpm_transflag_t) * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_init(alpm_handle_t *handle, int flags); /** Prepare a transaction. * @param handle the context handle * @param data the address of an alpm_list where a list * of alpm_depmissing_t objects is dumped (conflicting packages) * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_prepare(alpm_handle_t *handle, alpm_list_t **data); /** Commit a transaction. * @param handle the context handle * @param data the address of an alpm_list where detailed description * of an error can be dumped (i.e. list of conflicting files) * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_commit(alpm_handle_t *handle, alpm_list_t **data); /** Interrupt a transaction. * @param handle the context handle * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_interrupt(alpm_handle_t *handle); /** Release a transaction. * @param handle the context handle * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_trans_release(alpm_handle_t *handle); /** @} */ /** @name Common Transactions */ /** @{ */ /** Search for packages to upgrade and add them to the transaction. * @param handle the context handle * @param enable_downgrade allow downgrading of packages if the remote version is lower * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade); /** Add a package to the transaction. * If the package was loaded by alpm_pkg_load(), it will be freed upon * alpm_trans_release() invocation. * @param handle the context handle * @param pkg the package to add * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); /** Add a package removal action to the transaction. * @param handle the context handle * @param pkg the package to uninstall * @return 0 on success, -1 on error (pm_errno is set accordingly) */ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); /** @} */ /** @} */ /* * Helpers */ /* checksums */ /** \addtogroup alpm_misc Miscellaneous Functions * @brief Various libalpm functions * @{ */ /** Get the md5 sum of file. * @param filename name of the file * @return the checksum on success, NULL on error */ char *alpm_compute_md5sum(const char *filename); /** Get the sha256 sum of file. * @param filename name of the file * @return the checksum on success, NULL on error */ char *alpm_compute_sha256sum(const char *filename); /** @} */ /** Remove the database lock file * @param handle the context handle * @return 0 on success, -1 on error * * @note Safe to call from inside signal handlers. */ int alpm_unlock(alpm_handle_t *handle); enum alpm_caps { ALPM_CAPABILITY_NLS = (1 << 0), ALPM_CAPABILITY_DOWNLOADER = (1 << 1), ALPM_CAPABILITY_SIGNATURES = (1 << 2) }; /** Get the version of library. * @return the library version, e.g. "6.0.4" * */ const char *alpm_version(void); /** Get the capabilities of the library. * @return a bitmask of the capabilities * */ int alpm_capabilities(void); /* End of alpm_api */ /** @} */ #ifdef __cplusplus } #endif #endif /* ALPM_H */