--- lib/libalpm/trans.c | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c index c7317c15..303d2fca 100644 --- a/lib/libalpm/trans.c +++ b/lib/libalpm/trans.c @@ -266,8 +266,6 @@ int SYMEXPORT alpm_trans_release(alpm_handle_t *handle) return 0; } -/** @} */ - void _alpm_trans_free(alpm_trans_t *trans) { if(trans == NULL) { -- 2.29.2

--- lib/libalpm/alpm.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 50c4bb6b..48ba7fdc 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -20,6 +20,19 @@ * 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 7 Dec 2020 + * @brief Arch Linux Package Manager Library + */ + +/** @mainpage alpm + * + * libalpm is a package management library, primaraly used by pacman. + */ + #ifndef ALPM_H #define ALPM_H -- 2.29.2

--- lib/libalpm/alpm.h | 58 ++++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 1c2422ca..178c8f6a 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -243,6 +243,36 @@ const char *alpm_strerror(alpm_errno_t err); /* End of alpm_errors */ /** @} */ + +/** \addtogroup alpm_handle Handle + * @brief Functions to initialize and release libalpm + * @{ + */ + +/** Initializes the library. + * Creates handle, connects to database and creates lockfile. + * This must be called before any other functions are called. + * @param root the root path for all filesystem operations + * @param dbpath the absolute path to the libalpm database + * @param err an optional variable to hold any error return codes + * @return a context handle on success, NULL on error, err will be set if provided + */ +alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, + alpm_errno_t *err); + +/** Release the library. + * Disconnects from the database, removes handle and lockfile + * This should be the last alpm call you make. + * After this returns, handle should be considered invalid and cannot be reused + * in any way. + * @param myhandle the context handle + * @return 0 on success, -1 on error + */ +int alpm_release(alpm_handle_t *handle); + +/* End of alpm_handle */ +/** @} */ + typedef int64_t alpm_time_t; /* @@ -1915,34 +1945,6 @@ char *alpm_compute_sha256sum(const char *filename); /** @} */ -/** \addtogroup alpm_interface Interface Functions - * @brief Functions to initialize and release libalpm - * @{ - */ - -/** Initializes the library. - * Creates handle, connects to database and creates lockfile. - * This must be called before any other functions are called. - * @param root the root path for all filesystem operations - * @param dbpath the absolute path to the libalpm database - * @param err an optional variable to hold any error return codes - * @return a context handle on success, NULL on error, err will be set if provided - */ -alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, - alpm_errno_t *err); - -/** Release the library. - * Disconnects from the database, removes handle and lockfile - * This should be the last alpm call you make. - * After this returns, handle should be considered invalid and cannot be reused - * in any way. - * @param myhandle the context handle - * @return 0 on success, -1 on error - */ -int alpm_release(alpm_handle_t *handle); - -/** @} */ - /** Remove the database lock file * @param handle the context handle * @return 0 on success, -1 on error -- 2.29.2

--- lib/libalpm/alpm.h | 295 +++++++++++++++++++++++++-------------------- 1 file changed, 164 insertions(+), 131 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 43a47d54..ea99a8b3 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -441,49 +441,26 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, /** @} */ -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. +/** @addtogroup alpm_depends Dependency + * @brief Functions dealing with libalpm's dependency and conflict + * information. + * @{ */ -/** 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 { - 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 + /** 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; /** @@ -492,48 +469,187 @@ typedef enum _alpm_depmod_t { * 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; -/* - * Structures - */ - -/** Dependency */ +/** 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; + /** A description of why this dependency is needed (optional) */ char *desc; + /** A hash of name (used internally to speed up conflict checks) */ unsigned long name_hash; + /** How the version should match against the provider */ alpm_depmod_t mod; } alpm_depend_t; -/** Missing dependency */ +/** 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; - /* this is used only in the case of a remove dependency error */ + /** 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; -/** Conflict */ +/** 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; -/** File conflict */ +/** 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; +/** Checks dependencies and returns missing ones in a list. + * Dependencies can include versions with depmod operators. + * @param handle the context handle + * @param pkglist the list of local packages + * @param remove an alpm_list_t* of packages to be removed + * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade) + * @param reversedeps handles the backward dependencies + * @return an alpm_list_t* of alpm_depmissing_t pointers. + */ +alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, alpm_list_t *pkglist, + alpm_list_t *remove, alpm_list_t *upgrade, int reversedeps); + +/** Find a package satisfying a specified dependency. + * The dependency can include versions with depmod operators. + * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched + * @param depstring package or provision name, versioned or not + * @return a alpm_pkg_t* satisfying depstring + */ +alpm_pkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring); + +/** Find a package satisfying a specified dependency. + * First look for a literal, going through each db one by one. Then look for + * providers. The first satisfier that belongs to an installed package is + * returned. If no providers belong to an installed package then an + * alpm_question_select_provider_t is created to select the provider. + * The dependency can include versions with depmod operators. + * + * @param handle the context handle + * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched + * @param depstring package or provision name, versioned or not + * @return a alpm_pkg_t* satisfying depstring + */ +alpm_pkg_t *alpm_find_dbs_satisfier(alpm_handle_t *handle, + alpm_list_t *dbs, const char *depstring); + +/** Check the package conflicts in a database + * + * @param handle the context handle + * @param pkglist the list of packages to check + * + * @return an alpm_list_t of alpm_conflict_t + */ +alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist); + +/** Returns a newly allocated string representing the dependency information. + * @param dep a dependency info structure + * @return a formatted string, e.g. "glibc>=2.12" + */ +char *alpm_dep_compute_string(const alpm_depend_t *dep); + +/** Return a newly allocated dependency information parsed from a string + *\link alpm_dep_free should be used to free the dependency \endlink + * @param depstring a formatted string, e.g. "glibc=2.12" + * @return a dependency info structure + */ +alpm_depend_t *alpm_dep_from_string(const char *depstring); + +/** Free a dependency info structure + * @param dep struct to free + */ +void alpm_dep_free(alpm_depend_t *dep); + +/** Free a fileconflict and its members. + * @param conflict the fileconflict to free + */ +void alpm_fileconflict_free(alpm_fileconflict_t *conflict); + +/** Free a depmissing and its members + * @param miss the depmissing to fre + * */ +void alpm_depmissing_free(alpm_depmissing_t *miss); + +/** + * Free a conflict and its members. + * @param conflict the conflict to free + */ +void alpm_conflict_free(alpm_conflict_t *conflict); + + +/* End of alpm_depends */ +/** @} */ + +/* + * Enumerations + * These ones are used in multiple contexts, so are forward-declared. + */ + +/** 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 { + 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; + +/* + * Structures + */ + /** Package group */ typedef struct _alpm_group_t { /** group name */ @@ -1900,76 +2016,6 @@ 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 - * information. - * @{ - */ - -/** Checks dependencies and returns missing ones in a list. - * Dependencies can include versions with depmod operators. - * @param handle the context handle - * @param pkglist the list of local packages - * @param remove an alpm_list_t* of packages to be removed - * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade) - * @param reversedeps handles the backward dependencies - * @return an alpm_list_t* of alpm_depmissing_t pointers. - */ -alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, alpm_list_t *pkglist, - alpm_list_t *remove, alpm_list_t *upgrade, int reversedeps); - -/** Find a package satisfying a specified dependency. - * The dependency can include versions with depmod operators. - * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched - * @param depstring package or provision name, versioned or not - * @return a alpm_pkg_t* satisfying depstring - */ -alpm_pkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring); - -/** Find a package satisfying a specified dependency. - * First look for a literal, going through each db one by one. Then look for - * providers. The first satisfier that belongs to an installed package is - * returned. If no providers belong to an installed package then an - * alpm_question_select_provider_t is created to select the provider. - * The dependency can include versions with depmod operators. - * - * @param handle the context handle - * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched - * @param depstring package or provision name, versioned or not - * @return a alpm_pkg_t* satisfying depstring - */ -alpm_pkg_t *alpm_find_dbs_satisfier(alpm_handle_t *handle, - alpm_list_t *dbs, const char *depstring); - -/** - * @brief Check the package conflicts in a database - * - * @param handle the context handle - * @param pkglist the list of packages to check - * - * @return an alpm_list_t of alpm_conflict_t - */ -alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist); - -/** Returns a newly allocated string representing the dependency information. - * @param dep a dependency info structure - * @return a formatted string, e.g. "glibc>=2.12" - */ -char *alpm_dep_compute_string(const alpm_depend_t *dep); - -/** Return a newly allocated dependency information parsed from a string - * @param depstring a formatted string, e.g. "glibc=2.12" - * @return a dependency info structure - */ -alpm_depend_t *alpm_dep_from_string(const char *depstring); - -/** Free a dependency info structure - * @param dep struct to free - */ -void alpm_dep_free(alpm_depend_t *dep); - -/** @} */ - /** @} */ /* @@ -2021,19 +2067,6 @@ const char *alpm_version(void); * */ 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); - -/** - * Free a conflict and its members. - * @param conflict the conflict to free - */ -void alpm_conflict_free(alpm_conflict_t *conflict); - /* End of alpm_api */ /** @} */ -- 2.29.2

--- lib/libalpm/alpm.h | 439 ++++++++++++++++++++++++++++----------------- 1 file changed, 271 insertions(+), 168 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index ea99a8b3..a8d48432 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -617,105 +617,12 @@ void alpm_conflict_free(alpm_conflict_t *conflict); /* End of alpm_depends */ /** @} */ -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. - */ - -/** 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 { - 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; - -/* - * Structures - */ - -/** 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; - -/* - * Hooks - */ - -typedef enum _alpm_hook_when_t { - ALPM_HOOK_PRE_TRANSACTION = 1, - ALPM_HOOK_POST_TRANSACTION -} alpm_hook_when_t; - -/* - * Logging facilities - */ - -/** \addtogroup alpm_log Logging Functions - * @brief Functions to log using libalpm +/** \addtogroup alpm_cb Callbacks + * @brief Functions and structures for libalpm's callbacks * @{ */ -/** 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; - -typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); - -/** 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))); - -/** @} */ - /** * Type of events. */ @@ -790,7 +697,7 @@ typedef enum _alpm_event_type_t { /** A .pacnew file was created; See alpm_event_pacnew_created_t for arguments. */ ALPM_EVENT_PACNEW_CREATED, /** A .pacsave file was created; See alpm_event_pacsave_created_t for - * arguments */ + * arguments. */ ALPM_EVENT_PACSAVE_CREATED, /** Processing hooks will be started. */ ALPM_EVENT_HOOK_START, @@ -798,100 +705,123 @@ typedef enum _alpm_event_type_t { ALPM_EVENT_HOOK_DONE, /** A hook is starting */ ALPM_EVENT_HOOK_RUN_START, - /** A hook has finished running */ + /** A hook has finished running. */ ALPM_EVENT_HOOK_RUN_DONE } alpm_event_type_t; +/** An event that may reprisent any event. */ typedef struct _alpm_event_any_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; } alpm_event_any_t; +/** An enum over the kind of package operations. */ typedef enum _alpm_package_operation_t { /** Package (to be) installed. (No oldpkg) */ ALPM_PACKAGE_INSTALL = 1, /** Package (to be) upgraded */ ALPM_PACKAGE_UPGRADE, - /** Package (to be) re-installed. */ + /** Package (to be) re-installed */ ALPM_PACKAGE_REINSTALL, - /** Package (to be) downgraded. */ + /** Package (to be) downgraded */ ALPM_PACKAGE_DOWNGRADE, - /** Package (to be) removed. (No newpkg) */ + /** Package (to be) removed (No newpkg) */ ALPM_PACKAGE_REMOVE } alpm_package_operation_t; +/** A package operation event occurred. */ typedef struct _alpm_event_package_operation_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Type of operation. */ + /** Type of operation */ alpm_package_operation_t operation; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** New package. */ + /** New package */ alpm_pkg_t *newpkg; } alpm_event_package_operation_t; +/** An optional dependency was removed. */ typedef struct _alpm_event_optdep_removal_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Package with the optdep. */ + /** Package with the optdep */ alpm_pkg_t *pkg; - /** Optdep being removed. */ + /** Optdep being removed */ alpm_depend_t *optdep; } alpm_event_optdep_removal_t; +/** A scriptlet was ran. */ typedef struct _alpm_event_scriptlet_info_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Line of scriptlet output. */ + /** Line of scriptlet output */ const char *line; } alpm_event_scriptlet_info_t; + +/** A database is missing. + * + * The database is registered but has not been downloaded + */ typedef struct _alpm_event_database_missing_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Name of the database. */ + /** Name of the database */ const char *dbname; } alpm_event_database_missing_t; +/** A package was downloaded. */ typedef struct _alpm_event_pkgdownload_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; /** Name of the file */ const char *file; } alpm_event_pkgdownload_t; +/** A pacnew file was created. */ typedef struct _alpm_event_pacnew_created_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; /** Whether the creation was result of a NoUpgrade or not */ int from_noupgrade; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** New Package. */ + /** New Package */ alpm_pkg_t *newpkg; /** Filename of the file without the .pacnew suffix */ const char *file; } alpm_event_pacnew_created_t; +/** A pacsave file was created. */ typedef struct _alpm_event_pacsave_created_t { - /** Type of event. */ + /** Type of event */ alpm_event_type_t type; - /** Old package. */ + /** Old package */ alpm_pkg_t *oldpkg; - /** Filename of the file without the .pacsave suffix. */ + /** Filename of the file without the .pacsave suffix */ const char *file; } alpm_event_pacsave_created_t; +/** Kind of hook. */ +typedef enum _alpm_hook_when_t { + /* Pre transaction hook */ + ALPM_HOOK_PRE_TRANSACTION = 1, + /* Post transaction hook */ + ALPM_HOOK_POST_TRANSACTION +} alpm_hook_when_t; + +/** pre/post transaction hooks are to be ran. */ typedef struct _alpm_event_hook_t { - /** Type of event.*/ + /** Type of event*/ alpm_event_type_t type; - /** Type of hooks. */ + /** Type of hook */ alpm_hook_when_t when; } alpm_event_hook_t; +/** A pre/post transaction hook was ran. */ typedef struct _alpm_event_hook_run_t { - /** Type of event.*/ + /** Type of event */ alpm_event_type_t type; /** Name of hook */ const char *name; @@ -904,185 +834,260 @@ typedef struct _alpm_event_hook_run_t { } alpm_event_hook_run_t; /** Events. - * This is an union passed to the callback, that allows the frontend to know + * This is a union passed to the callback that allows the frontend to know * which type of event was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access event-specific data. */ typedef union _alpm_event_t { + /** Type of event it's always safe to access this. */ alpm_event_type_t type; + /** The any event type. It's always safe to access this. */ alpm_event_any_t any; + /** Package operation */ alpm_event_package_operation_t package_operation; + /** An optdept was remove */ alpm_event_optdep_removal_t optdep_removal; + /** A scriptlet was ran */ alpm_event_scriptlet_info_t scriptlet_info; + /** A database is missing */ alpm_event_database_missing_t database_missing; + /** A package was downloaded */ alpm_event_pkgdownload_t pkgdownload; + /** A pacnew file was created */ alpm_event_pacnew_created_t pacnew_created; + /** A pacsave file was created */ alpm_event_pacsave_created_t pacsave_created; + /** Pre/post transaction hooks are being ran */ alpm_event_hook_t hook; + /** A hook was ran */ alpm_event_hook_run_t hook_run; } alpm_event_t; -/** Event callback. */ +/** Event callback. + * + * Called when an event occurs + * @param event the event that occurred */ typedef void (*alpm_cb_event)(alpm_event_t *); /** - * Type of questions. + * Type of question. * Unlike the events or progress enumerations, this enum has bitmask values * so a frontend can use a bitmask map to supply preselected answers to the * different types of questions. */ typedef enum _alpm_question_type_t { + /** Should target in ignorepkg be installed anyway? */ ALPM_QUESTION_INSTALL_IGNOREPKG = (1 << 0), + /** Should a package be replaced? */ ALPM_QUESTION_REPLACE_PKG = (1 << 1), + /** Should a conflicting package be removed? */ ALPM_QUESTION_CONFLICT_PKG = (1 << 2), + /** Should a corrupted package be deleted? */ ALPM_QUESTION_CORRUPTED_PKG = (1 << 3), + /** Should unresolvable targets be removed from the transaction? */ ALPM_QUESTION_REMOVE_PKGS = (1 << 4), + /** Provider selection */ ALPM_QUESTION_SELECT_PROVIDER = (1 << 5), + /** Should a key be imported? */ ALPM_QUESTION_IMPORT_KEY = (1 << 6) } alpm_question_type_t; +/** A question that can represent any other question. */ typedef struct _alpm_question_any_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer. */ + /** Answer */ int answer; } alpm_question_any_t; +/** Should target in ignorepkg be installed anyway? */ typedef struct _alpm_question_install_ignorepkg_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to install pkg anyway. */ + /** Answer: whether or not to install pkg anyway */ int install; - /* Package in IgnorePkg/IgnoreGroup. */ + /** The ignored package that we are deciding whether to install */ alpm_pkg_t *pkg; } alpm_question_install_ignorepkg_t; +/** Should a package be replaced? */ typedef struct _alpm_question_replace_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to replace oldpkg with newpkg. */ + /** 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. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to remove conflict->package2. */ + /** Answer: whether or not to remove conflict->package2 */ int remove; - /** Conflict info. */ + /** Conflict info */ alpm_conflict_t *conflict; } alpm_question_conflict_t; +/** Should a corrupted package be deleted? */ typedef struct _alpm_question_corrupted_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to remove filepath. */ + /** Answer: whether or not to remove filepath */ int remove; - /** Filename to remove */ + /** File to remove */ const char *filepath; /** Error code indicating the reason for package invalidity */ alpm_errno_t reason; } alpm_question_corrupted_t; +/** Should unresolvable targets be removed from the transaction? */ typedef struct _alpm_question_remove_pkgs_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to skip packages. */ + /** Answer: whether or not to skip packages */ int skip; - /** List of alpm_pkg_t* with unresolved dependencies. */ + /** List of alpm_pkg_t* with unresolved dependencies */ alpm_list_t *packages; } alpm_question_remove_pkgs_t; +/** Provider selection */ typedef struct _alpm_question_select_provider_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: which provider to use (index from providers). */ + /** Answer: which provider to use (index from providers) */ int use_index; - /** List of alpm_pkg_t* as possible providers. */ + /** List of alpm_pkg_t* as possible providers */ alpm_list_t *providers; - /** What providers provide for. */ + /** What providers provide for */ alpm_depend_t *depend; } alpm_question_select_provider_t; +/** Should a key be imported? */ typedef struct _alpm_question_import_key_t { - /** Type of question. */ + /** Type of question */ alpm_question_type_t type; - /** Answer: whether or not to import key. */ + /** Answer: whether or not to import key */ int import; - /** The key to import. */ + /** The key to import */ alpm_pgpkey_t *key; } alpm_question_import_key_t; /** * Questions. - * This is an union passed to the callback, that allows the frontend to know + * This is an union passed to the callback that allows the frontend to know * which type of question was triggered (via type). It is then possible to * typecast the pointer to the right structure, or use the union field, in order * to access question-specific data. */ typedef union _alpm_question_t { + /** The type of question. It's always safe to access this. */ alpm_question_type_t type; + /** A question that can represent any question. + * It's always safe to access this. */ alpm_question_any_t any; + /** Should target in ignorepkg be installed anyway? */ alpm_question_install_ignorepkg_t install_ignorepkg; + /** Should a package be replaced? */ alpm_question_replace_t replace; + /** Should a conflicting package be removed? */ alpm_question_conflict_t conflict; + /** Should a corrupted package be deleted? */ alpm_question_corrupted_t corrupted; + /** Should unresolvable targets be removed from the transaction? */ alpm_question_remove_pkgs_t remove_pkgs; + /** Provider selection */ alpm_question_select_provider_t select_provider; + /** Should a key be imported? */ alpm_question_import_key_t import_key; } alpm_question_t; -/** Question callback */ +/** 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 *); -/** 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 + * + * Alert the front end about the progress of certain events. + * Allows the implementation of loading bars for events that + * make take a while to complete. + * @param progress the kind of event that is progressing + * @param pkg for package operations, the name of the package being operated on + * @param percent the percent completion of the action + * @param howmany the total amount of items in the action + * @param current the current amount of items completed + */ /** Progress callback */ -typedef void (*alpm_cb_progress)(alpm_progress_t, const char *, int, size_t, size_t); +typedef void (*alpm_cb_progress)(alpm_progress_t progress, const char *pkg, + int percent, size_t howmany, size_t current); /* * Downloading */ -/* File download events. +/** File download events. * These events are reported by ALPM via download callback. */ -typedef enum { - ALPM_DOWNLOAD_INIT, /* alpm initializes file download logic */ - ALPM_DOWNLOAD_PROGRESS, /* download progress reported */ - ALPM_DOWNLOAD_COMPLETED /* alpm is about to release data related to the file */ +typedef enum _alpm_download_event_type_t { + /** A download was started */ + ALPM_DOWNLOAD_INIT, + /** A download made progress */ + ALPM_DOWNLOAD_PROGRESS, + /** A download completed */ + ALPM_DOWNLOAD_COMPLETED } alpm_download_event_type_t; -typedef struct { - int optional; /* whether this file is optional and thus the errors could be ignored */ +/** Context struct for when a download starts. */ +typedef struct _alpm_download_event_init_t { + /** whether this file is optional and thus the errors could be ignored */ + int optional; } alpm_download_event_init_t; -typedef struct { - off_t downloaded; /* amount of data downloaded */ - off_t total; /* total amount need to be downloaded */ +/** Context struct for when a download progresses. */ +typedef struct _alpm_download_event_progress_t { + /** Amount of data downloaded */ + off_t downloaded; + /** Total amount need to be downloaded */ + off_t total; } alpm_download_event_progress_t; -typedef struct { - /* total bytes in file */ + +/** Context struct for when a download completes. */ +typedef struct _alpm_download_event_completed_t { + /** Total bytes in file */ off_t total; - /* download result code: + /** download result code: * 0 - download completed successfully * 1 - the file is up-to-date * -1 - error @@ -1098,6 +1103,10 @@ typedef struct { typedef void (*alpm_cb_download)(const char *filename, alpm_download_event_type_t event, void *data); + +/** Total Download callback. + * @param total amount that will be downloaded during \link alpm_trans_commit \endlink. + */ typedef void (*alpm_cb_totaldl)(off_t total); /** A callback for downloading files @@ -1110,6 +1119,100 @@ typedef void (*alpm_cb_totaldl)(off_t total); typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, int force); +/* End of alpm_cb */ +/** @} */ + + +/* + * Enumerations + * These ones are used in multiple contexts, so are forward-declared. + */ + +/** 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 { + 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; + +/* + * Structures + */ + +/** 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; + +/* + * Logging facilities + */ + +/** \addtogroup alpm_log Logging Functions + * @brief Functions to log using libalpm + * @{ + */ + +/** 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; + +typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); + +/** 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))); + +/** @} */ + /** Fetch a list of remote packages. * @param handle the context handle * @param urls list of package URLs to download -- 2.29.2

--- lib/libalpm/alpm.h | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index c71c275f..ea690abc 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -1412,13 +1412,27 @@ typedef enum _alpm_pkgvalidation_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) + /** 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; -typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); + +/** 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 @@ -1429,6 +1443,7 @@ typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list); int alpm_logaction(alpm_handle_t *handle, const char *prefix, const char *fmt, ...) __attribute__((format(printf, 3, 4))); +/* End of alpm_log */ /** @} */ /** Fetch a list of remote packages. -- 2.29.2

--- lib/libalpm/alpm.h | 102 +++++++++++++++++++++++++-------------------- 1 file changed, 56 insertions(+), 46 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 5ee99711..30bfb06d 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -94,44 +94,82 @@ typedef struct __alpm_pkg_t alpm_pkg_t; /** Transaction structure used internally by libalpm */ typedef struct __alpm_trans_t alpm_trans_t; -/* - * Structures +/** @addtogroup alpm_api ALPM + * @brief The libalpm Public API + * @{ */ -/** Package group */ -typedef struct _alpm_group_t { - /** group name */ - char *name; - /** list of alpm_pkg_t packages */ - alpm_list_t *packages; -} alpm_group_t; +/** @addtogroup alpm_files Files + * @brief Functions for package files + * @{ + */ /** File in a package */ typedef struct _alpm_file_t { - char *name; - off_t size; - mode_t mode; + /** 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 { - size_t count; - alpm_file_t *files; + /** 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 { - char *name; - char *hash; + /** Name of the file (without .pacsave extension) */ + char *name; + /** Hash of the filename (used internally) */ + char *hash; } alpm_backup_t; +/** Determines whether a package filelist contains a given path. + * The provided path should be relative to the install root with no leading + * slashes, e.g. "etc/localtime". When searching for directories, the path must + * have a trailing slash. + * @param filelist a pointer to a package filelist + * @param path the path to search for in the package + * @return a pointer to the matching file or NULL if not found + */ +alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); + +/* End of alpm_files */ +/** @} */ -/** @addtogroup alpm_api ALPM - * @brief The libalpm Public API +/** @addtogroup alpm_groups Groups + * @brief Functions for package groups * @{ */ +/** Package group */ +typedef struct _alpm_group_t { + /** group name */ + char *name; + /** list of alpm_pkg_t packages */ + alpm_list_t *packages; +} alpm_group_t; + +/** Find group members across a list of databases. + * If a member exists in several databases, only the first database is used. + * IgnorePkg is also handled. + * @param dbs the list of alpm_db_t * + * @param name the name of the group + * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free) + */ +alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); + +/* End of alpm_groups */ +/** @} */ + + /** @addtogroup alpm_errors Error Codes * Error codes returned by libalpm. * @{ @@ -2031,34 +2069,6 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); /** @} */ -/* - * 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 - * have a trailing slash. - * @param filelist a pointer to a package filelist - * @param path the path to search for in the package - * @return a pointer to the matching file or NULL if not found - */ -alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); - - -/* - * 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 */ -- 2.29.2

--- lib/libalpm/alpm.h | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 76ae5722..494a8319 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -2068,11 +2068,6 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); /* End of alpm_packages */ /** @} */ -/** Check for new version of pkg in sync repos - * (only the first occurrence is considered in sync) - */ -alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync); - /** @addtogroup alpm_trans Transaction * @brief Functions to manipulate libalpm transactions * @@ -2212,20 +2207,25 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); /* End of add/remove packages */ /** @} */ + /* End of alpm_trans */ /** @} */ -/* - * Helpers - */ - -/* checksums */ /** \addtogroup alpm_misc Miscellaneous Functions * @brief Various libalpm functions * @{ */ +/** Check for new version of pkg in syncdbs. + * + * If the same package appears multiple dbs only the first will be checked + * + * This only checks the syncdb for a newer version. It does not access the network at all. + * See \link alpm_db_update \endlink to update a database. + */ +alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync); + /** Get the md5 sum of file. * @param filename name of the file * @return the checksum on success, NULL on error @@ -2238,8 +2238,6 @@ char *alpm_compute_md5sum(const char *filename); */ char *alpm_compute_sha256sum(const char *filename); -/** @} */ - /** Remove the database lock file * @param handle the context handle * @return 0 on success, -1 on error @@ -2248,10 +2246,14 @@ char *alpm_compute_sha256sum(const char *filename); */ int alpm_unlock(alpm_handle_t *handle); +/** Enum of possible compile time features */ enum alpm_caps { - ALPM_CAPABILITY_NLS = (1 << 0), - ALPM_CAPABILITY_DOWNLOADER = (1 << 1), - ALPM_CAPABILITY_SIGNATURES = (1 << 2) + /** 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. @@ -2264,6 +2266,9 @@ const char *alpm_version(void); * */ int alpm_capabilities(void); +/* End of alpm_misc */ +/** @} */ + /* End of alpm_api */ /** @} */ -- 2.29.2

--- lib/libalpm/alpm.h | 592 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 564 insertions(+), 28 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 494a8319..05dec6c7 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -1453,186 +1453,722 @@ int alpm_logaction(alpm_handle_t *handle, const char *prefix, /** @} */ -/** @addtogroup alpm_api_options Options +/** @addtogroup alpm_options Options * Libalpm option getters and setters * @{ */ -/** Returns the callback used for logging. */ +/** @name Accessors for callbacks + * @{ + */ + +/** Returns the callback used for logging. + * @param handle the context handle + * @return the currently set log callback + */ 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. */ +/** Returns the callback used to report download progress. + * @param handle the context handle + * @return the currently set download callback + */ 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); -/** Returns the downloading callback. */ +/** Returns the downloading callback. + * @param handle the context handle + * @return the currently set fetch callback + */ 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. */ +/** Returns the callback used to report total download size. + * @param handle the context handle + * @return the currently set total download callback + */ 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); -/** Returns the callback used for events. */ + +/** Returns the callback used for events. + * @param handle the context handle + * @return the currently set event callback + */ 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. */ +/** Returns the callback used for questions. + * @param handle the context handle + * @return the currently set question callback + */ 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); -/** Returns the callback used for operation progress. */ + +/**Returns the callback used for operation progress. + * @param handle the context handle + * @return the currently set progress callback + */ 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); +/* End of callback accessors */ +/** @} */ + + +/** @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. */ +/** Returns the root path. Read-only. + * @param handle the context handle + */ const char *alpm_option_get_root(alpm_handle_t *handle); +/* End of root accessors */ +/** @} */ + + +/** @name Accessors to the database path + * + * The dbpath is where libalpm stores the local db and + * downloads sync databases. + * @{ + */ -/** Returns the path to the database directory. Read-only. */ +/** Returns the path to the database directory. Read-only. + * @param handle the context handle + */ const char *alpm_option_get_dbpath(alpm_handle_t *handle); +/* End of dbpath accessors */ +/** @} */ + + +/** @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. */ +/** 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 actually exists on disk. + * @param handle the context handle + */ const char *alpm_option_get_lockfile(alpm_handle_t *handle); +/* End of lockfile accessors */ +/** @} */ /** @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); +/* End of cachedir accessors */ /** @} */ + /** @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); +/* End of hookdir accessors */ /** @} */ + +/** @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); +/* End of overwrite accessors */ +/** @} */ + -/** Returns the logfile name. */ +/** @name Accessors to the log file + * + * This controls where libalpm will save log output to. + * @{ + */ + +/** 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); +/* End of logfile accessors */ +/** @} */ + + +/** @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); +/* End of gpdir accessors */ +/** @} */ + -/** 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); +/* End of usesyslog accessors */ +/** @} */ + /** @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); +/* End of noupgrade accessors */ /** @} */ + /** @name Accessors to the list of no-extract files. * These functions modify the list of filenames which should * be skipped packages which should * not be upgraded by a sysupgrade operation. * @{ */ + +/** 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); +/* End of noextract accessors */ /** @} */ + /** @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); +/* End of ignorepkg accessors */ /** @} */ + /** @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); +/* End of ignoregroup accessors */ /** @} */ + /** @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); +/* End of assunmeinstalled accessors */ /** @} */ -/** Returns the targeted architecture. */ + +/** @name Accessors for the configured architecture + * + * libalpm will only install packages that match the configured 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); +/* End of arch accessors */ +/** @} */ + + +/** @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); +/* End of checkspace accessors */ +/** @} */ + + +/** @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); +/* End of dbext accessors */ +/** @} */ + + +/** @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); +/* End of signature accessors */ +/** @} */ + +/** @name Accessors for download timeout + * + * By default, libalpm will timeout if a download has been transferring + * less than 1 byte for 10 seconds. + * @{ + */ + +/** 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); +/* End of disable_dl_timeout accessors */ +/** @} */ + +/** @name Accessors for parallel downloads + * \link alpm_db_update \endlink, \link alpm_fetch_pkgurl \endlink and + * \link alpm_trans_commit \endlink can all download packages in parallel. + * This setting configures how many packages can be downloaded in parallel, + * + * By default this value is set to 1, meaning packages are downloading + * sequentially. + * + * @{ + */ + +/** Gets the number of parallel streams to download database and package files. + * @param handle the context handle + * @return the number of parallel streams to download database and package files + */ int alpm_option_get_parallel_downloads(alpm_handle_t *handle); /** Sets number of parallel streams to download database and package files. - * If the function is not called then the default value of '1' stream - * (i.e. sequential download) is used. * @param handle the context handle * @param num_streams number of parallel download streams * @return 0 on success, -1 on error */ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_streams); +/* End of parallel_downloads accessors */ +/** @} */ + +/* End of alpm_options */ /** @} */ + /** @addtogroup alpm_packages Package Functions * Functions to manipulate libalpm packages * @{ -- 2.29.2

--- lib/libalpm/alpm.h | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 4673f639..e9cc7c85 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -62,6 +62,7 @@ extern "C" { /** The libalpm context handle. * * This struct represents an instance of libalpm. + * @ingroup alpm_handle */ typedef struct __alpm_handle_t alpm_handle_t; @@ -81,6 +82,7 @@ typedef struct __alpm_handle_t alpm_handle_t; * the user. They will be freed when the database is unregistered. * * Databases are automatically unregistered when the \link alpm_handle_t \endlink is released. + * @ingroup alpm_databases */ typedef struct __alpm_db_t alpm_db_t; @@ -93,12 +95,20 @@ typedef struct __alpm_db_t alpm_db_t; * * 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. + * @ingroup alpm_packages */ typedef struct __alpm_pkg_t alpm_pkg_t; -/** Transaction structure used internally by libalpm */ +/** Transaction structure used internally by libalpm + * @ingroup alpm_trans + * */ typedef struct __alpm_trans_t alpm_trans_t; + +/** The time type used by libalpm. Represents a unix time stamp + * @ingroup alpm_misc */ +typedef int64_t alpm_time_t; + /** @addtogroup alpm_files Files * @brief Functions for package files * @{ @@ -343,7 +353,6 @@ int alpm_release(alpm_handle_t *handle); /* End of alpm_handle */ /** @} */ -typedef int64_t alpm_time_t; /** @addtogroup alpm_sig Signature checking * @brief Functions to check signatures -- 2.29.2

--- doc/Doxyfile.in | 81 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 59 insertions(+), 22 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index e2101a28..776318da 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.2 +# Doxyfile 1.8.20 #--------------------------------------------------------------------------- # Project related configuration options @@ -10,7 +10,9 @@ PROJECT_BRIEF = "Arch Linux Package Manager Library" PROJECT_LOGO = OUTPUT_DIRECTORY = @OUTPUT_DIRECTORY@ CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English +OUTPUT_TEXT_DIRECTION = None BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class" \ @@ -31,36 +33,41 @@ STRIP_FROM_PATH = STRIP_FROM_INC_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES +JAVADOC_BANNER = NO QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 4 ALIASES = -TCL_SUBST = OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 AUTOLINK_SUPPORT = YES BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO SUBGROUPING = YES INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO +INLINE_SIMPLE_STRUCTS = YES TYPEDEF_HIDES_STRUCT = YES -SYMBOL_CACHE_SIZE = 0 LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- EXTRACT_ALL = NO EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO EXTRACT_PACKAGE = NO EXTRACT_STATIC = NO EXTRACT_LOCAL_CLASSES = YES @@ -73,7 +80,9 @@ HIDE_IN_BODY_DOCS = YES INTERNAL_DOCS = NO CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = NO INLINE_INFO = YES SORT_MEMBER_DOCS = YES @@ -95,26 +104,29 @@ FILE_VERSION_FILTER = LAYOUT_FILE = CITE_BIB_FILES = #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO WARN_FORMAT = "$file:$line: $text" WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = ../lib/libalpm/alpm.h ../lib/libalpm/alpm_list.h +INPUT = ../lib/libalpm/alpm.h \ + ../lib/libalpm/alpm_list.h INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = _alpm_* __alpm_* +EXCLUDE_SYMBOLS = _alpm_* \ + __alpm_* EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO @@ -123,8 +135,9 @@ INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- SOURCE_BROWSER = NO INLINE_SOURCES = NO @@ -132,16 +145,17 @@ STRIP_CODE_COMMENTS = NO REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES USE_HTAGS = NO VERBATIM_HEADERS = YES #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = NO COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = NO HTML_OUTPUT = html @@ -155,6 +169,7 @@ HTML_COLORSTYLE_HUE = 220 HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = YES +HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO HTML_INDEX_NUM_ENTRIES = 100 GENERATE_DOCSET = NO @@ -184,33 +199,47 @@ GENERATE_TREEVIEW = NO ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +HTML_FORMULA_FORMAT = png FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +FORMULA_MACROFILE = USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS MATHJAX_RELPATH = http://www.mathjax.org/mathjax MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = SEARCHENGINE = NO SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- GENERATE_LATEX = NO LATEX_OUTPUT = latex LATEX_CMD_NAME = latex MAKEINDEX_CMD_NAME = makeindex +LATEX_MAKEINDEX_CMD = makeindex COMPACT_LATEX = NO PAPER_TYPE = letter EXTRA_PACKAGES = LATEX_HEADER = LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = PDF_HYPERLINKS = NO USE_PDFLATEX = NO LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain +LATEX_TIMESTAMP = NO +LATEX_EMOJI_DIRECTORY = #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- GENERATE_RTF = NO RTF_OUTPUT = rtf @@ -218,27 +247,31 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = +RTF_SOURCE_CODE = NO #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- GENERATE_MAN = YES MAN_OUTPUT = . MAN_EXTENSION = .3 +MAN_SUBDIR = MAN_LINKS = NO #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = XML_PROGRAMLISTING = YES +XML_NS_MEMB_FILE_SCOPE = NO #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- GENERATE_PERLMOD = NO PERLMOD_LATEX = NO @@ -262,18 +295,18 @@ PREDEFINED = HAVE_CONFIG_H= \ EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- TAGFILES = GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES -PERL_PATH = /usr/bin/perl +EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = NO -MSCGEN_PATH = +DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES DOT_NUM_THREADS = 0 @@ -297,6 +330,10 @@ INTERACTIVE_SVG = NO DOT_PATH = DOTFILE_DIRS = MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 3 DOT_TRANSPARENT = NO -- 2.29.2

--- lib/libalpm/alpm.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index e9cc7c85..a0de9b13 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -50,7 +50,7 @@ extern "C" { #include <alpm_list.h> -/** @addtogroup alpm_api ALPM +/** @addtogroup alpm alpm * @brief The libalpm Public API * @{ */ -- 2.29.2

Also change the group's title to point to the group's man page. This makes generated man pages be named libalpm_* which is more consistent with what library man pages are usually called. --- doc/meson.build | 1 - lib/libalpm/alpm.h | 80 +++++++++++++++++++++++++---------------- lib/libalpm/alpm_list.h | 22 ++---------- 3 files changed, 53 insertions(+), 50 deletions(-) diff --git a/doc/meson.build b/doc/meson.build index e24172fd..570dc765 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -9,7 +9,6 @@ manpages = [ { 'name': 'PKGBUILD.5', 'extra_depends' : [ 'PKGBUILD-example.txt' ] }, { 'name': 'makepkg.conf.5' }, { 'name': 'pacman.conf.5' }, - { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, { 'name': 'pacman-conf.8' }, ] diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index b2772f19..dd28b191 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -21,13 +21,6 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ -/** - * @file alpm.h - * @author Pacman Development Team - * @date 7 Dec 2020 - * @brief Arch Linux Package Manager Library - */ - /** @mainpage alpm * * libalpm is a package management library, primaraly used by pacman. @@ -50,14 +43,41 @@ extern "C" { #include <alpm_list.h> -/** @addtogroup alpm The libalpm Public API +/** @addtogroup libalpm The libalpm Public API + * + * + * libalpm is a package management library, primaraly used by pacman. + * + * For ease of access, the libalpm manual has been split up into several sections. * - * @section see_also See Also - * \b alpm_list(3), + * @section bugs Bugs + * Bugs? You must be kidding; there are no bugs in this software. But if we happen to be wrong, + * submit a bug report with as much detail as possible at the Arch Linux Bug Tracker in the + * Pacman section. + * + * @section see_also See also + * \b libalpm-list(3), * \b alpm-hooks(5), * \b makepkg(8), - * \b pacman(8), - * \b pacman.conf(5) + * + * @section maintainers Maintainers + * Current maintainers: + * + * - Allan McRae <allan@archlinux.org> + * - Andrew Gregory <andrew.gregory.8@gmail.com> + * - Dave Reisner <dreisner@archlinux.org> + * - Eli Schwartz <eschwartz@archlinux.org> + * + * Past major contributors: + * + * - Judd Vinet <jvinet@zeroflux.org> + * - Aurelien Foret <aurelien@archlinux.org> + * - Aaron Griffin <aaron@archlinux.org> + * - Dan McGee <dan@archlinux.org> + * - Xavier Chantry <shiningxc@gmail.com> + * - Nagy Gabor <ngaba@bibl.u-szeged.hu> + * + * For additional contributors, use git shortlog -s on the pacman.git repository. * @{ */ @@ -68,7 +88,7 @@ extern "C" { /** The libalpm context handle. * * This struct represents an instance of libalpm. - * @ingroup alpm_handle + * @ingroup libalpm-handle */ typedef struct __alpm_handle_t alpm_handle_t; @@ -88,7 +108,7 @@ typedef struct __alpm_handle_t alpm_handle_t; * the user. They will be freed when the database is unregistered. * * Databases are automatically unregistered when the \link alpm_handle_t \endlink is released. - * @ingroup alpm_databases + * @ingroup libalpm-databases */ typedef struct __alpm_db_t alpm_db_t; @@ -101,21 +121,21 @@ typedef struct __alpm_db_t alpm_db_t; * * 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. - * @ingroup alpm_packages + * @ingroup libalpm-packages */ typedef struct __alpm_pkg_t alpm_pkg_t; /** Transaction structure used internally by libalpm - * @ingroup alpm_trans + * @ingroup libalpm-trans * */ typedef struct __alpm_trans_t alpm_trans_t; /** The time type used by libalpm. Represents a unix time stamp - * @ingroup alpm_misc */ + * @ingroup libalpm-misc */ typedef int64_t alpm_time_t; -/** @addtogroup alpm_files Files +/** @addtogroup libalpm-files libalpm-files(3) * @brief Functions for package files * @{ */ @@ -160,7 +180,7 @@ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path) /** @} */ -/** @addtogroup alpm_groups Groups +/** @addtogroup libalpm-groups libalpm-groups(3) * @brief Functions for package groups * @{ */ @@ -186,7 +206,7 @@ alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); /** @} */ -/** @addtogroup alpm_errors Error Codes +/** @addtogroup libalpm-errors libalpm-errors(3) * Error codes returned by libalpm. * @{ */ @@ -330,7 +350,7 @@ const char *alpm_strerror(alpm_errno_t err); /** @} */ -/** \addtogroup alpm_handle Handle +/** \addtogroup libalpm-handle libalpm-handle(3) * @brief Functions to initialize and release libalpm * @{ */ @@ -360,7 +380,7 @@ int alpm_release(alpm_handle_t *handle); /** @} */ -/** @addtogroup alpm_sig Signature checking +/** @addtogroup libalpm-sig libalpm-sig(3) * @brief Functions to check signatures * @{ */ @@ -526,7 +546,7 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, /** @} */ -/** @addtogroup alpm_depends Dependency +/** @addtogroup libalpm-depends libalpm-depends(3) * @brief Functions dealing with libalpm's dependency and conflict * information. * @{ @@ -703,7 +723,7 @@ void alpm_conflict_free(alpm_conflict_t *conflict); /** @} */ -/** \addtogroup alpm_cb Callbacks +/** \addtogroup libalpm-cb libalpm-cb(3) * @brief Functions and structures for libalpm's callbacks * @{ */ @@ -1208,7 +1228,7 @@ typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, /** @} */ -/** @addtogroup alpm_databases Database +/** @addtogroup libalpm-databases libalpm-database(3) * @brief Functions to query and manipulate the database of libalpm. * @{ */ @@ -1426,7 +1446,7 @@ int alpm_db_get_usage(alpm_db_t *db, int *usage); /** @} */ -/** \addtogroup alpm_log Logging Functions +/** \addtogroup libalpm-log alpm-log(3) * @brief Functions to log using libalpm * @{ */ @@ -1468,7 +1488,7 @@ int alpm_logaction(alpm_handle_t *handle, const char *prefix, /** @} */ -/** @addtogroup alpm_options Options +/** @addtogroup libalpm-options libalpm-options(3) * Libalpm option getters and setters * @{ */ @@ -2184,7 +2204,7 @@ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_s /** @} */ -/** @addtogroup alpm_packages Package Functions +/** @addtogroup libalpm-packages libalpm-packages(3) * Functions to manipulate libalpm packages * @{ */ @@ -2619,7 +2639,7 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); /* End of alpm_packages */ /** @} */ -/** @addtogroup alpm_trans Transaction +/** @addtogroup libalpm-trans libalpm-trans(3) * @brief Functions to manipulate libalpm transactions * * Transactions are the way to add/remove packages to/from the system. @@ -2763,7 +2783,7 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); /** @} */ -/** \addtogroup alpm_misc Miscellaneous Functions +/** \addtogroup libalpm-misc libalpm-misc(3) * @brief Various libalpm functions * @{ */ diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h index 01fa092c..620cfbfd 100644 --- a/lib/libalpm/alpm_list.h +++ b/lib/libalpm/alpm_list.h @@ -19,23 +19,6 @@ */ -/** - * @file alpm_list.h - * @author Pacman Development Team - * @date 7 Dec 2020 - * @brief A doubly linked list for use with libalpm - * - * @section see_also See Also - * \b alpm(3), - * \b alpm-hooks(5), - * \b makepkg(8), - * \b pacman(8), - * \b pacman.conf(5) - * @{ - */ - - */ - #ifndef ALPM_LIST_H #define ALPM_LIST_H @@ -50,7 +33,8 @@ extern "C" { #endif /** - * @addtogroup alpm_list List Functions + * @ingroup libalpm + * @addtogroup libalpm-list libalpm-list(3) * @brief Functions to manipulate alpm_list_t lists. * * These functions are designed to create, destroy, and modify lists of @@ -60,7 +44,7 @@ extern "C" { * 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. - * @{ + * @{ */ /** A doubly linked list */ -- 2.29.2