Write docs for every public alpm member and expand on the existing documentation for other members. --- The entire .h file has basically been restructed. The best way to see the end result is either to read the generated man pages or enabled html and view the generated html. Also note alpm_list is still not documented. --- lib/libalpm/alpm.h | 1546 ++++++++++++++++++++++++++++++--------- lib/libalpm/alpm_list.h | 14 +- lib/libalpm/version.c | 2 +- 3 files changed, 1200 insertions(+), 362 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 4a2d2fc1..51e9e5b4 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -20,6 +20,16 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. */ + +/** + * @file alpm.h + * @author Pacman Development Team + * @date 26 Jan 2020 + * @brief Arch Linux Package Manager Library + * + * bork + */ + #ifndef ALPM_H #define ALPM_H @@ -38,267 +48,313 @@ extern "C" { #include <alpm_list.h> /* - * Arch Linux Package Management library + * Opaque Structures */ -/* - * 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 the 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_errors Error Codes +/** @addtogroup alpm_api ALPM + * @brief The libalpm Public API + * @{ + */ + +/** @addtogroup alpm_errors Error Codes + * @brief The error codes used 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, + /** Fauked to write to the database */ ALPM_ERR_DB_WRITE, + /** Fauked 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, + /** Transaction tried to commit 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 architecute */ ALPM_ERR_PKG_INVALID_ARCH, + /** Unused */ ALPM_ERR_PKG_REPO_NOT_FOUND, /* Signatures */ + /** Signatues 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 */ + /** Missing compile-time features */ ALPM_ERR_MISSING_CAPABILITY_SIGNATURES } alpm_errno_t; -/** Returns the current error code from the handle. */ +/** 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. */ +/** 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_api_errors */ /** @} */ -/** @addtogroup alpm_api Public API - * The libalpm Public API +/** \addtogroup alpm_handle Handle + * @brief Functions to initialize and release libalpm * @{ */ -typedef int64_t alpm_time_t; - -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. +/** 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); -/** 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; +/** Release the library. + * Disconnects from the database, releases transaction, 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); -/** Location a package object was loaded from. */ -typedef enum _alpm_pkgfrom_t { - ALPM_PKG_FROM_FILE = 1, - ALPM_PKG_FROM_LOCALDB, - ALPM_PKG_FROM_SYNCDB -} alpm_pkgfrom_t; +/** @} */ -/** Method used to validate a package. */ -typedef enum _alpm_pkgvalidation_t { - ALPM_PKG_VALIDATION_UNKNOWN = 0, - ALPM_PKG_VALIDATION_NONE = (1 << 0), - ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), - ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), - ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) -} alpm_pkgvalidation_t; -/** 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<x.y.z) */ - ALPM_DEP_MOD_LT -} alpm_depmod_t; +/** The time type used by libalpm. Represents a unix time stamp */ +typedef int64_t alpm_time_t; -/** - * File conflict type. - * Whether the conflict results from a file existing on the filesystem, or with - * another target in the transaction. +/** @addtogroup alpm_sig Signature checking + * @brief Functions to check signatures + * @{ */ -typedef enum _alpm_fileconflicttype_t { - ALPM_FILECONFLICT_TARGET = 1, - ALPM_FILECONFLICT_FILESYSTEM -} alpm_fileconflicttype_t; -/** 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 a signature */ 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 a signature */ 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; /** PGP signature verification status return codes */ 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; -/* - * Structures - */ - -/** Dependency */ -typedef struct _alpm_depend_t { - char *name; - char *version; - char *desc; - unsigned long name_hash; - alpm_depmod_t mod; -} alpm_depend_t; - -/** Missing dependency */ -typedef struct _alpm_depmissing_t { - char *target; - alpm_depend_t *depend; - /* this is used only in the case of a remove dependency error */ - char *causingpkg; -} alpm_depmissing_t; - -/** Conflict */ -typedef struct _alpm_conflict_t { - unsigned long package1_hash; - unsigned long package2_hash; - char *package1; - char *package2; - alpm_depend_t *reason; -} alpm_conflict_t; - -/** File conflict */ -typedef struct _alpm_fileconflict_t { - char *target; - alpm_fileconflicttype_t type; - char *file; - char *ctarget; -} alpm_fileconflict_t; - -/** Package group */ -typedef struct _alpm_group_t { - /** group name */ - char *name; - /** list of alpm_pkg_t packages */ - alpm_list_t *packages; -} alpm_group_t; - -/** File in a package */ -typedef struct _alpm_file_t { - char *name; - off_t size; - mode_t mode; -} alpm_file_t; - -/** Package filelist container */ -typedef struct _alpm_filelist_t { - size_t count; - alpm_file_t *files; -} alpm_filelist_t; - -/** Local package or package file backup entry */ -typedef struct _alpm_backup_t { - char *name; - char *hash; -} alpm_backup_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 expired */ alpm_time_t expires; + /** The length of they 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; @@ -307,8 +363,11 @@ typedef struct _alpm_pgpkey_t { * 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; @@ -317,50 +376,127 @@ typedef struct _alpm_sigresult_t { * 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; +/** @} */ -/* - * Hooks +/** @addtogroup alpm_depends Dependency + * @brief Functions dealing with libalpm representation of dependency + * information. + * @{ */ -typedef enum _alpm_hook_when_t { - ALPM_HOOK_PRE_TRANSACTION = 1, - ALPM_HOOK_POST_TRANSACTION -} alpm_hook_when_t; +/** 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<x.y.z) */ + ALPM_DEP_MOD_LT +} alpm_depmod_t; -/* - * Logging facilities +/** + * File conflict type. + * Whether the conflict results from a file existing on the filesystem, or with + * another target in the transaction. */ +typedef enum _alpm_fileconflicttype_t { + /** The conflict results with a another target in the transaction */ + ALPM_FILECONFLICT_TARGET = 1, + /** The conflict results from a file existing on the filesystem */ + ALPM_FILECONFLICT_FILESYSTEM +} alpm_fileconflicttype_t; -/** \addtogroup alpm_log Logging Functions - * @brief Functions to log using libalpm - * @{ - */ +/** The basic dependency type + * + * This type is used throughout libalpm, not just for dependencies, + * but also conflicts and providers. */ +typedef struct _alpm_depend_t { + /** Name of the provider to satisfy this dependnecy */ + char *name; + /** Version of the provider to match against (optional) */ + char *version; + /** An optional description to describe why this dependency is needed */ + char *desc; + /** A hash of the name, used to speed up dependnecy checks */ + unsigned long name_hash; + /** How the version should match against the provider */ + alpm_depmod_t mod; +} alpm_depend_t; -/** Logging Levels */ -typedef enum _alpm_loglevel_t { - ALPM_LOG_ERROR = 1, - ALPM_LOG_WARNING = (1 << 1), - ALPM_LOG_DEBUG = (1 << 2), - ALPM_LOG_FUNCTION = (1 << 3) -} alpm_loglevel_t; +/** Missing dependency */ +typedef struct _alpm_depmissing_t { + /** Name of the package that has the dependnecy */ + char *target; + /** The dependency that was wanted */ + alpm_depend_t *depend; + /** If the depmissing was caused by a conflict, the name of the package + * that would be installed, causing the satisfying package to be removed */ + char *causingpkg; +} alpm_depmissing_t; -typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); +/** A conflict that has occurred between two packages */ +typedef struct _alpm_conflict_t { + /** Hash of the first package name + * (used internally to speed up conflict checks) */ + unsigned long package1_hash; + /** Hash of the second package name + * (used internally to speed up conflict checks) */ + unsigned long package2_hash; + /** Name of the first package */ + char *package1; + /** Name of the second package */ + char *package2; + /** The conflict */ + alpm_depend_t *reason; +} alpm_conflict_t; -/** 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))); +/** File conflict + * + * A conflict that has happened due to a two packages containing the same file, + * or a package contains a file that is already on the filesystem and not owned + * by that package */ +typedef struct _alpm_fileconflict_t { + /** The name of the package that caused the conflict */ + char *target; + /** The type of conflict */ + alpm_fileconflicttype_t type; + /** The name of the file that the package conflicts with */ + char *file; + /** The name of the package that also owns the file if there is one*/ + char *ctarget; +} alpm_fileconflict_t; /** @} */ +/** \addtogroup alpm_cb Callbacks + * @brief Functions and structures for libalpm's callbacks + * @{ + */ + +/* + * Hooks + */ + +/** When a hook should be ran */ +typedef enum _alpm_hook_when_t { + /** Before the transaction is committed */ + ALPM_HOOK_PRE_TRANSACTION = 1, + /** After the transaction is committed */ + ALPM_HOOK_POST_TRANSACTION +} alpm_hook_when_t; + /** * Type of events. */ @@ -450,11 +586,13 @@ typedef enum _alpm_event_type_t { 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, @@ -468,6 +606,7 @@ typedef enum _alpm_package_operation_t { 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; @@ -479,6 +618,7 @@ typedef struct _alpm_event_package_operation_t { 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; @@ -488,6 +628,7 @@ typedef struct _alpm_event_optdep_removal_t { 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; @@ -495,6 +636,10 @@ typedef struct _alpm_event_scriptlet_info_t { 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; @@ -502,6 +647,7 @@ typedef struct _alpm_event_database_missing_t { 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; @@ -509,6 +655,7 @@ typedef struct _alpm_event_pkgdownload_t { 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; @@ -522,6 +669,7 @@ typedef struct _alpm_event_pacnew_created_t { const char *file; } alpm_event_pacnew_created_t; +/** A pacsace file was created */ typedef struct _alpm_event_pacsave_created_t { /** Type of event. */ alpm_event_type_t type; @@ -531,6 +679,7 @@ typedef struct _alpm_event_pacsave_created_t { const char *file; } alpm_event_pacsave_created_t; +/** pre/post transaction hooks are to be ran */ typedef struct _alpm_event_hook_t { /** Type of event.*/ alpm_event_type_t type; @@ -538,6 +687,7 @@ typedef struct _alpm_event_hook_t { alpm_hook_when_t when; } alpm_event_hook_t; +/** A hook was ran */ typedef struct _alpm_event_hook_run_t { /** Type of event.*/ alpm_event_type_t type; @@ -557,21 +707,35 @@ typedef struct _alpm_event_hook_run_t { * 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. */ -typedef void (*alpm_cb_event)(alpm_event_t *); +/** Event callback. + * + * Called when an event occurs + * @param event the event that occurred */ +typedef void (*alpm_cb_event)(alpm_event_t *event); /** * Type of questions. @@ -580,15 +744,23 @@ typedef void (*alpm_cb_event)(alpm_event_t *); * 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; @@ -596,28 +768,31 @@ typedef struct _alpm_question_any_t { 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; - /* Package in IgnorePkg/IgnoreGroup. */ + /** Package in IgnorePkg/IgnoreGroup. */ 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. */ + /** Package to be replaced. */ alpm_pkg_t *oldpkg; - /* Package to replace with. */ + /** Package to replace with. */ alpm_pkg_t *newpkg; - /* DB of 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; @@ -627,6 +802,7 @@ typedef struct _alpm_question_conflict_t { 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; @@ -638,6 +814,7 @@ typedef struct _alpm_question_corrupted_t { 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; @@ -647,6 +824,7 @@ typedef struct _alpm_question_remove_pkgs_t { 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; @@ -658,6 +836,7 @@ typedef struct _alpm_question_select_provider_t { 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; @@ -674,36 +853,71 @@ typedef struct _alpm_question_import_key_t { * 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 */ -typedef void (*alpm_cb_question)(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 *question); -/** Progress */ +/** 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 */ -typedef void (*alpm_cb_progress)(alpm_progress_t, const char *, int, size_t, size_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 + */ +typedef void (*alpm_cb_progress)(alpm_progress_t progress, const char *pkg, + int percent, size_t howmany, size_t current); /* * Downloading @@ -717,6 +931,9 @@ typedef void (*alpm_cb_progress)(alpm_progress_t, const char *, int, size_t, siz typedef void (*alpm_cb_download)(const char *filename, off_t xfered, off_t 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 @@ -729,109 +946,419 @@ typedef void (*alpm_cb_totaldl)(off_t total); typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, int force); -/** Fetch a remote pkg. - * @param handle the context handle - * @param url URL of the package to download - * @return the downloaded filepath on success, NULL on error - */ -char *alpm_fetch_pkgurl(alpm_handle_t *handle, const char *url); +/** 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))); + +/** @} */ + + +/** @addtogroup alpm_options Options + * @brief Libalpm option getters and setters + * @{ + */ -/** @addtogroup alpm_api_options Options - * Libalpm option getters and setters +/** @name Accessors to the log callback * @{ */ -/** Returns the callback used for logging. */ +/** Returns the callback used for logging. + * @param handle the context handle + */ alpm_cb_log alpm_option_get_logcb(alpm_handle_t *handle); -/** Sets the callback used for logging. */ + +/** Sets the callback used for logging. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_logcb(alpm_handle_t *handle, alpm_cb_log cb); +/** @} */ -/** Returns the callback used to report download progress. */ +/** @name Accessors to the download callback + * @{ + */ + +/** Returns the callback used to report download progress. + * @param handle the context handle + */ alpm_cb_download alpm_option_get_dlcb(alpm_handle_t *handle); -/** Sets the callback used to report download progress. */ + +/** Sets the callback used to report download progress. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_dlcb(alpm_handle_t *handle, alpm_cb_download cb); +/** @} */ + +/** @name Accessors to the fetchcb + * @{ + */ -/** Returns the downloading callback. */ +/** Returns the downloading callback. + * @param handle the context handle + */ alpm_cb_fetch alpm_option_get_fetchcb(alpm_handle_t *handle); -/** Sets the downloading callback. */ + +/** Sets the downloading callback. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_fetchcb(alpm_handle_t *handle, alpm_cb_fetch cb); +/** @} */ -/** Returns the callback used to report total download size. */ +/** @name Accessors to the total download callback + * @{ + */ + +/** Returns the callback used to report total download size. + * @param handle the context handle + */ alpm_cb_totaldl alpm_option_get_totaldlcb(alpm_handle_t *handle); -/** Sets the callback used to report total download size. */ + +/** Sets the callback used to report total download size. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_totaldlcb(alpm_handle_t *handle, alpm_cb_totaldl cb); +/** @} */ + +/** @name Accessors to the event callback + * @{ + */ -/** Returns the callback used for events. */ +/** Returns the callback used for events. + * @param handle the context handle */ alpm_cb_event alpm_option_get_eventcb(alpm_handle_t *handle); -/** Sets the callback used for events. */ + +/** Sets the callback used for events. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_eventcb(alpm_handle_t *handle, alpm_cb_event cb); +/** @} */ -/** Returns the callback used for questions. */ +/** @name Accessors to the question callback + * @{ + */ + +/** Returns the callback used for questions. + * @param handle the context handle + */ alpm_cb_question alpm_option_get_questioncb(alpm_handle_t *handle); -/** Sets the callback used for questions. */ + +/** Sets the callback used for questions. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_questioncb(alpm_handle_t *handle, alpm_cb_question cb); +/** @} */ + +/** @name Accessors to the progress callback + * @{ + */ -/** Returns the callback used for operation progress. */ +/**Returns the callback used for operation progress. + * @param handle the contect handle + */ alpm_cb_progress alpm_option_get_progresscb(alpm_handle_t *handle); -/** Sets the callback used for operation progress. */ + +/** Sets the callback used for operation progress. + * @param handle the context handle + * @param cb the cb to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_progresscb(alpm_handle_t *handle, alpm_cb_progress cb); +/** @} */ -/** Returns the root of the destination filesystem. Read-only. */ +/** @name Accessors to the root directory + * + * The root directory is the prefix to which libalpm installs packages to. + * Hooks and scriptlets will also be run in a chroot to ensure they behave correctly + * in alternative roots. + * @{ + */ + +/** Returns the root of the destination filesystem. Read-only. + * @param handle the context handle + */ const char *alpm_option_get_root(alpm_handle_t *handle); +/** @} */ + +/** @name Accessors to the database path + * + * The dbpath is where libalpm downloads databases to and reads from. + * @{ + */ -/** Returns the path to the database directory. Read-only. */ +/** Returns the path to the database directory. Read-only. + * @parama handle the context handle + */ const char *alpm_option_get_dbpath(alpm_handle_t *handle); +/** @} */ -/** Get the name of the database lock file. Read-only. */ +/** @name Accessors to the lockfile + * + * The lockfile is used to ensure two instances of libalpm can not write + * to the database at the same time. The lock file is created when + * committing a transaction and released when the transaction completes. + * Or when calling \link alpm_unlock \endlink. + * @{ + */ + +/** Get the name of the database lock file. Read-only. + * This is the name that the lockfile would have. It does not + * matter if the lockfile is actually presant on disk. + * @param handle the context handle + */ const char *alpm_option_get_lockfile(alpm_handle_t *handle); +/** @} */ /** @name Accessors to the list of package cache directories. + * + * This is where libalpm will store downloaded packages. * @{ */ + +/** Gets the currently configured cachedirs, + * @param handle the context handle + * @return a char* list of cache directories + */ alpm_list_t *alpm_option_get_cachedirs(alpm_handle_t *handle); + +/** Sets the cachedirs. + * @param handle the context handle + * @param cachedirs a char* list of cachdirs. The list will be duped and + * the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_cachedirs(alpm_handle_t *handle, alpm_list_t *cachedirs); + +/** Append a cachedir to the configured cachedirs. + * @param handle the context handle + * @param cachedir the cachedir to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_cachedir(alpm_handle_t *handle, const char *cachedir); + +/** Remove a cachedir from the configured cachedirs. + * @param handle the context handle + * @param cachedir the cachedir to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_cachedir(alpm_handle_t *handle, const char *cachedir); /** @} */ /** @name Accessors to the list of package hook directories. + * + * libalpm will search these directories for hooks to run. A hook in + * a later directory will override previous hooks if they have the same name. * @{ */ + +/** Gets the currently configured hookdirs, + * @param handle the context handle + * @return a char* list of hook directories + */ alpm_list_t *alpm_option_get_hookdirs(alpm_handle_t *handle); + +/** Sets the hookdirs. + * @param handle the context handle + * @param hookdirs a char* list of hookdirs. The list will be duped and + * the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_hookdirs(alpm_handle_t *handle, alpm_list_t *hookdirs); + +/** Append a hookdir to the configured hookdirs. + * @param handle the context handle + * @param hookdir the hookdir to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_hookdir(alpm_handle_t *handle, const char *hookdir); + +/** Remove a hookdir from the configured hookdirs. + * @param handle the context handle + * @param hookdir the hookdir to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_hookdir(alpm_handle_t *handle, const char *hookdir); /** @} */ +/** @name Accessors to the list of overwritable files. + * + * Normally libalpm will refuse to install a package that owns files that + * are already on disk and not owned by that package. + * + * If a conflicting file matches a glob in the overwrite_files list, then no + * conflict will be raised and libalpm will simply overwrite the file. + * @{ + */ + +/** Gets the currently configured overwritable files, + * @param handle the context handle + * @return a char* list of overwritable file globs + */ alpm_list_t *alpm_option_get_overwrite_files(alpm_handle_t *handle); + +/** Sets the overwritable files. + * @param handle the context handle + * @param globs a char* list of overwritable file globs. The list will be duped and + * the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_overwrite_files(alpm_handle_t *handle, alpm_list_t *globs); + +/** Append an overwritable file to the configured overwritable files. + * @param handle the context handle + * @param glob the file glob to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_overwrite_file(alpm_handle_t *handle, const char *glob); + +/** Remove a file glob from the configured overwritable files globs. + * @note The overwritable file list contains a list of globs. The glob to + * remove must exactly match the entry to remove. There is no glob expansion. + * @param handle the context handle + * @param glob the file glob to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_overwrite_file(alpm_handle_t *handle, const char *glob); +/** @} */ + +/** @name Accessors to the log file + * + * This controls where libalpm will save log output to. + * @{ + */ -/** Returns the logfile name. */ + +/** Gets the filepath to the currently set logfile. + * @param handle the context handle + * @return the path to the logfile + */ const char *alpm_option_get_logfile(alpm_handle_t *handle); -/** Sets the logfile name. */ + +/** Sets the logfile path. + * @param handle the context handle + * @param logfile path to the new location of the logfile + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_logfile(alpm_handle_t *handle, const char *logfile); +/** @} */ + +/** @name Accessors to the GPG directory + * + * This controls where libalpm will store GnuPG's files. + * @{ + */ -/** Returns the path to libalpm's GnuPG home directory. */ +/** Returns the path to libalpm's GnuPG home directory. + * @param handle the context handle + * @return the path to libalpms's GnuPG home directory + */ const char *alpm_option_get_gpgdir(alpm_handle_t *handle); -/** Sets the path to libalpm's GnuPG home directory. */ + +/** Sets the path to libalpm's GnuPG home directory. + * @param handle the context handle + * @param gpgdir the gpgdir to set + */ int alpm_option_set_gpgdir(alpm_handle_t *handle, const char *gpgdir); +/** @} */ -/** Returns whether to use syslog (0 is FALSE, TRUE otherwise). */ +/** @name Accessors for use syslog + * + * This controls whether libalpm will also use the syslog. Even if this option + * is enabled, libalpm will still try to log to its log file. + * @{ + */ + +/** Returns whether to use syslog (0 is FALSE, TRUE otherwise). + * @param handle the context handle + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_get_usesyslog(alpm_handle_t *handle); -/** Sets whether to use syslog (0 is FALSE, TRUE otherwise). */ + +/** Sets whether to use syslog (0 is FALSE, TRUE otherwise). + * @param handle the context handle + * @param usesyslog whether to use the 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. * @{ */ + +/** Get the list of no-upgrade files + * @param handle the context handle + * @return the char* list of no-upgrade files + */ alpm_list_t *alpm_option_get_noupgrades(alpm_handle_t *handle); + +/** Add a file to the no-upgrade list + * @param handle the context handle + * @param path the path to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_noupgrade(alpm_handle_t *handle, const char *path); + +/** Sets the list of no-upgrade files + * @param handle the context handle + * @param noupgrade a char* list of file to not upgrade. + * The list will be duped and the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_noupgrades(alpm_handle_t *handle, alpm_list_t *noupgrade); + +/** Remove an entry from the no-upgrade list + * @param handle the context handle + * @param path the path to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_noupgrade(alpm_handle_t *handle, const char *path); + +/** Test if a path matches any of the globs in the no-upgrade list + * @param handle the context handle + * @param path the path to test + * @return 0 is the path matches a glob, negative if there is no match and + * positive is the match was inverted + */ int alpm_option_match_noupgrade(alpm_handle_t *handle, const char *path); /** @} */ @@ -841,75 +1368,297 @@ int alpm_option_match_noupgrade(alpm_handle_t *handle, const char *path); * not be upgraded by a sysupgrade operation. * @{ */ + +/** Get the list of no-extract files + * @param handle the context handle + * @return the char* list of no-extract files + */ alpm_list_t *alpm_option_get_noextracts(alpm_handle_t *handle); + +/** Add a file to the no-extract list + * @param handle the context handle + * @param path the path to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_noextract(alpm_handle_t *handle, const char *path); + +/** Sets the list of no-extract files + * @param handle the context handle + * @param noextract a char* list of file to not extract. + * The list will be duped and the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_noextracts(alpm_handle_t *handle, alpm_list_t *noextract); + +/** Remove an entry from the no-extract list + * @param handle the context handle + * @param path the path to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_noextract(alpm_handle_t *handle, const char *path); + +/** Test if a path matches any of the globs in the no-extract list + * @param handle the context handle + * @param path the path to test + * @return 0 is the path matches a glob, negative if there is no match and + * positive is the match was inverted + */ 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. + * + * Entries in this list may be globs and only match the package's + * name. Providers are not taken into account. * @{ */ + +/** Get the list of ignored packages + * @param handle the context handle + * @return the char* list of ignored packages + */ alpm_list_t *alpm_option_get_ignorepkgs(alpm_handle_t *handle); + +/** Add a file to the ignored package list + * @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_option_add_ignorepkg(alpm_handle_t *handle, const char *pkg); + +/** Sets the list of packages to ignore + * @param handle the context handle + * @param ignorepkgs a char* list of packages to ignore + * The list will be duped and the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_ignorepkgs(alpm_handle_t *handle, alpm_list_t *ignorepkgs); + +/** Remove an entry from the ignorepkg list + * @param handle the context handle + * @param pkg the package to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ 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. + * + * Entries in this list may be globs. * @{ */ + +/** Get the list of ignored groups + * @param handle the context handle + * @return the char* list of ignored groups + */ alpm_list_t *alpm_option_get_ignoregroups(alpm_handle_t *handle); + +/** Add a file to the ignored group list + * @param handle the context handle + * @param grp the group to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_ignoregroup(alpm_handle_t *handle, const char *grp); + +/** Sets the list of groups to ignore + * @param handle the context handle + * @param ignoregrps a char* list of groups to ignore + * The list will be duped and the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_ignoregroups(alpm_handle_t *handle, alpm_list_t *ignoregrps); + +/** Remove an entry from the ignoregroup list + * @param handle the context handle + * @param grp the group to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ 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. + * + * This is effectivley a list of virtual providers that + * packages can use to satisfy their dependencies. * @{ */ + +/** Gets the list of dependencies that are assumed to be met + * @param handle the context handle + * @return a list of alpm_depend_t* + */ alpm_list_t *alpm_option_get_assumeinstalled(alpm_handle_t *handle); + +/** Add a depend to the assumed installed list + * @param handle the context handle + * @param dep the dependency to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_add_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep); + +/** Sets the list of dependnecies that are assumed to be met + * @param handle the context handle + * @param deps a list of *alpm_depend_t + * The list will be duped and the original will still need to be freed by the caller. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_assumeinstalled(alpm_handle_t *handle, alpm_list_t *deps); + +/** Remove an entry from the assume installed list + * @param handle the context handle + * @param dep the dep to remove + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_remove_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep); /** @} */ -/** Returns the targeted architecture. */ +/** @name Accessors for the set architecture + * + * libalpm will only install packages that match the set architecture. + * The architecture does not need to match the physical architecture. + * It can just be treated as a label. + * @{ + */ + +/** Returns the allowed package architecture. + * @param handle the context handle + * @return the configured package architecture + */ const char *alpm_option_get_arch(alpm_handle_t *handle); -/** Sets the targeted architecture. */ + +/** Sets the allowed package architecture. + * @param handle the context handle + * @param arch the architecture to set + */ int alpm_option_set_arch(alpm_handle_t *handle, const char *arch); +/** @} */ + +/** @name Accessors for check space. + * + * This controls whether libalpm will check if there is sufficient before + * installing packages. + * @{ + */ +/** Get whether or not checking for free space before installing packages is enabled. + * @param handle the context handle + * @return 0 if disabled, 1 if enabled + */ int alpm_option_get_checkspace(alpm_handle_t *handle); + +/** Enable/disable checking free space before installing packages. + * @param handle the context handle + * @param checkspace 0 for disabled, 1 for enabled + */ int alpm_option_set_checkspace(alpm_handle_t *handle, int checkspace); +/** @} */ + +/** @name Accessors for the database extension + * + * This controls the extension used for sync databases. libalpm will use this + * extension to both lookup remote databses and as the name used when opening + * reading them. + * + * This is useful for file databases. Seems as files can increase the size of + * a database by quite a lot, a server could hold a database without files under + * one extension, and another with files under another extension. + * + * Which one is downloaded and used then depends on this setting. + * @{ + */ +/** Gets the configured database extension. + * @param handle the context handle + * @return the configured database extension + */ const char *alpm_option_get_dbext(alpm_handle_t *handle); + +/** Sets the database extension. + * @param handle the context handle + * @param dbext the database extension to use + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_dbext(alpm_handle_t *handle, const char *dbext); +/** @} */ +/** @name Accessors for the signature levels + * @{ + */ + +/** Get the default siglevel. + * @param handle the context handle + * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel + */ int alpm_option_get_default_siglevel(alpm_handle_t *handle); + +/** Set the default siglevel. + * @param handle the context handle + * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_default_siglevel(alpm_handle_t *handle, int level); +/** Get the configured local file siglevel. + * @param handle the context handle + * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel + */ int alpm_option_get_local_file_siglevel(alpm_handle_t *handle); + +/** Set the local file siglevel. + * @param handle the context handle + * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_local_file_siglevel(alpm_handle_t *handle, int level); +/** Get the configured remote file siglevel. + * @param handle the context handle + * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel + */ int alpm_option_get_remote_file_siglevel(alpm_handle_t *handle); + +/** Set the remote file siglevel. + * @param handle the context handle + * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_remote_file_siglevel(alpm_handle_t *handle, int level); +/** @} */ +/** @name Accessors for download timeout + * @{ + */ + +/** Enables/disables the download timeout. + * @param handle the context handle + * @param disable_dl_timeout 0 for enabled, 1 for disabled + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int alpm_option_set_disable_dl_timeout(alpm_handle_t *handle, unsigned short disable_dl_timeout); +/** @} */ /** @} */ -/** @addtogroup alpm_api_databases Database Functions - * Functions to query and manipulate the database of libalpm. +/** @addtogroup alpm_databases Database + * @brief Functions to query and manipulate the database of libalpm. * @{ */ +/** Package group */ +typedef struct _alpm_group_t { + /** Group name */ + char *name; + /** List of alpm_pkg_t packages */ + alpm_list_t *packages; +} alpm_group_t; + /** Get the database of locally installed packages. * The returned pointer points to an internal structure * of libalpm which should only be manipulated through @@ -926,7 +1675,8 @@ alpm_db_t *alpm_get_localdb(alpm_handle_t *handle); */ alpm_list_t *alpm_get_syncdbs(alpm_handle_t *handle); -/** Register a sync database of packages. +/** Register a sync database of packages. Databases can not be + * registered while 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 @@ -936,13 +1686,15 @@ alpm_list_t *alpm_get_syncdbs(alpm_handle_t *handle); alpm_db_t *alpm_register_syncdb(alpm_handle_t *handle, const char *treename, int level); -/** Unregister all package databases. +/** Unregister all package databases. Databases can not be + * registered 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. +/** Unregister a package database. Databases can not be + * registered while 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) */ @@ -982,9 +1734,10 @@ 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 a char* list of servers. Note: the database will + * @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 + * @return 0 if valid, -1 if invalid (pm_errno is set accordingly) */ int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers); @@ -1015,13 +1768,13 @@ int alpm_db_remove_server(alpm_db_t *db, const char *url); * * Example: * @code - * alpm_list_t *syncs = alpm_get_syncdbs(); + * alpm_list_t *syncs = alpm_get_syncdbs(handle); * for(i = syncs; i; i = alpm_list_next(i)) { - * alpm_db_t *db = alpm_list_getdata(i); + * alpm_db_t *db = i->data; * result = alpm_db_update(0, db); * * if(result < 0) { - * printf("Unable to update database: %s\n", alpm_strerrorlast()); + * printf("Unable to update database: %s\n", alpm_strerror(alpm_errno(handle))); * } else if(result == 1) { * printf("Database already up to date\n"); * } else { @@ -1031,7 +1784,7 @@ int alpm_db_remove_server(alpm_db_t *db, const char *url); * @endcode * * @note After a successful update, the \link alpm_db_get_pkgcache() - * package cache \endlink will be invalidated + * package cache and all packages within it \endlink will be invalidated * @param force if true, then forces the update, otherwise update only in case * the database isn't up to date * @param db pointer to the package database to update @@ -1053,6 +1806,19 @@ alpm_pkg_t *alpm_db_get_pkg(alpm_db_t *db, const char *name); */ alpm_list_t *alpm_db_get_pkgcache(alpm_db_t *db); +/* + * Groups + */ + +/** 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); + /** Get a group entry from a package database. * @param db pointer to the package database to get the group from * @param name of the group @@ -1076,11 +1842,17 @@ alpm_list_t *alpm_db_get_groupcache(alpm_db_t *db); 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; @@ -1098,13 +1870,79 @@ int alpm_db_set_usage(alpm_db_t *db, int usage); */ int alpm_db_get_usage(alpm_db_t *db, int *usage); +/** 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); + /** @} */ -/** @addtogroup alpm_api_packages Package Functions - * Functions to manipulate libalpm packages +/** @addtogroup alpm_packages Package + * @brief 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; + +/** 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; + /** 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 @@ -1130,6 +1968,9 @@ int alpm_pkg_load(alpm_handle_t *handle, const char *filename, int full, 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) */ @@ -1404,6 +2245,7 @@ size_t alpm_pkg_changelog_read(void *ptr, size_t size, /** 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); @@ -1425,7 +2267,7 @@ int alpm_pkg_mtree_next(const alpm_pkg_t *pkg, struct archive *archive, /** Close a package mtree file. * @param pkg the local package to close the mtree of - * @param the archive to close + * @param archive the archive to close */ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); @@ -1450,6 +2292,12 @@ off_t alpm_pkg_download_size(alpm_pkg_t *newpkg); */ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); +/** Fetch a remote pkg. + * @param handle the context handle + * @param url URL of the package to download + * @return the downloaded filepath on success, NULL on error + */ +char *alpm_fetch_pkgurl(alpm_handle_t *handle, const char *url); /* End of alpm_pkg */ /** @} */ @@ -1458,6 +2306,7 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); * Filelists */ + /** 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 @@ -1468,68 +2317,6 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); */ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); -/* - * Signatures - */ - -/** - * 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 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); - -/* - * Groups - */ - -/** 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); - /* * Sync */ @@ -1539,9 +2326,30 @@ alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); */ 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 +/** @} */ + +/** @addtogroup alpm_trans Transaction + * @brief Functions to manipulate libalpm transactions + * + * Transactions are the way to add/remove packages to/from the system. + * + * Only one transaction can exist at a time. + * + * The basic workflow of a transaction is to: + * + * Initialize with \link alpm_trans_init \endlink + * + * Choose which packages to add with \link alpm_add_pkg \endlink and \link alpm_remove_pkg \endlink + * + * Prepare the transaction with \link alpm_trans_prepare \endlink + * + * Commit the transaction with \link alpm_trans_commit \endlink + * + * Release the transaction with \link alpm_trans_release \endlink + * + * A transaction can be released at any time. A transaction does not have to be committed. * @{ + * */ /** Transaction flags */ @@ -1587,6 +2395,29 @@ typedef enum _alpm_transflag_t { */ int alpm_trans_get_flags(alpm_handle_t *handle); +/** 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); + /** Returns a list of packages added by the transaction. * @param handle the context handle * @return a list of alpm_pkg_t structures @@ -1635,36 +2466,8 @@ int alpm_trans_interrupt(alpm_handle_t *handle); 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); - -/** @} */ - -/** @addtogroup alpm_api_depends Dependency Functions - * Functions dealing with libalpm representation of dependency +/** @addtogroup alpm_depends Dependency + * @brief Functions dealing with libalpm representation of dependency * information. * @{ */ @@ -1731,99 +2534,124 @@ alpm_depend_t *alpm_dep_from_string(const char *depstring); */ 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); -/* - * Helpers +/** + * Free a conflict and its members. + * @param conflict the conflict to free */ +void alpm_conflict_free(alpm_conflict_t *conflict); -/* checksums */ +/** @} */ -/** \addtogroup alpm_misc Miscellaneous Functions - * @brief Various libalpm functions +/** @addtogroup alpm_sig Signature checking + * @brief Functions to check signatures * @{ */ -/** Get the md5 sum of file. - * @param filename name of the file - * @return the checksum on success, NULL on error +/** + * 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) */ -char *alpm_compute_md5sum(const char *filename); +int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); -/** Get the sha256 sum of file. - * @param filename name of the file - * @return the checksum on success, NULL on error +/** + * 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) */ -char *alpm_compute_sha256sum(const char *filename); - -/** @} */ +int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); -/** \addtogroup alpm_interface Interface Functions - * @brief Functions to initialize and release libalpm - * @{ +/** + * 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); -/** 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 +/** + * 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 */ -alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, - alpm_errno_t *err); +int alpm_decode_signature(const char *base64_data, + unsigned char **data, size_t *data_len); -/** 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 myhandle the context handle +/** + * Extract the Issuer Key ID from a signature + * @param handle the context handle + * @param identifier the key's identifier + * @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_release(alpm_handle_t *handle); +int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, + const unsigned char *sig, const size_t len, alpm_list_t **keys); /** @} */ -/** 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. +/** \addtogroup alpm_misc Miscellaneous + * @brief Various libalpm functions + * @{ */ -int alpm_unlock(alpm_handle_t *handle); +/* + * Helpers + */ + +/* checksums */ + +/** 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); + +/** Enum of possible compile time features */ enum alpm_caps { + /** localization */ ALPM_CAPABILITY_NLS = (1 << 0), + /** Ability to download */ ALPM_CAPABILITY_DOWNLOADER = (1 << 1), + /** Signature checking */ 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); - -/** - * Free a fileconflict and its members. - * @param conflict the fileconflict to free */ -void alpm_fileconflict_free(alpm_fileconflict_t *conflict); -void alpm_depmissing_free(alpm_depmissing_t *miss); +int alpm_capabilities(void); -/** - * Free a conflict and its members. - * @param conflict the conflict to free - */ -void alpm_conflict_free(alpm_conflict_t *conflict); +/** @} */ /* End of alpm_api */ /** @} */ diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h index 4e18f36c..c9bfcf9d 100644 --- a/lib/libalpm/alpm_list.h +++ b/lib/libalpm/alpm_list.h @@ -17,6 +17,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. */ + +/** + * @file alpm_list.h + * @author Pacman Development Team + * @date 26 Jan 2020 + * @brief A doubly linked list for use with libalpm + */ #ifndef ALPM_LIST_H #define ALPM_LIST_H @@ -30,13 +37,16 @@ extern "C" { #endif -/** - * @brief Linked list type used by libalpm. +/** \addtogroup alpm_list ALPM List + * + * @brief A doubly linked list for use with libalpm * * It is exposed so front ends can use it to prevent the need to reimplement * lists of their own; however, it is not required that the front end uses * it. */ + + typedef struct __alpm_list_t { /** data held by the list node */ void *data; diff --git a/lib/libalpm/version.c b/lib/libalpm/version.c index ae220ff6..27df0508 100644 --- a/lib/libalpm/version.c +++ b/lib/libalpm/version.c @@ -202,7 +202,7 @@ static int rpmvercmp(const char *a, const char *b) * - if one is empty and two is not an alpha, two is newer. * - if one is an alpha, two is newer. * - otherwise one is newer. - * */ + */ if ( (!*one && !isalpha((int)*two)) || isalpha((int)*one) ) { ret = -1; -- 2.25.0