@@ -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 */
/** @} */
@@ -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;
@@ -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;