[pacman-dev] [PATCH 1/2] Docs docs docs
morganamilo
morganamilo at archlinux.org
Sun Jan 26 07:01:42 UTC 2020
libalpm: move docs from .c files into alpm.h And fix/expand some
along the way.
---
lib/libalpm/add.c | 1 -
lib/libalpm/alpm.c | 33 ------
lib/libalpm/alpm.h | 247 ++++++++++++++++++++++++++++++++++++++++-
lib/libalpm/be_sync.c | 35 ------
lib/libalpm/conflict.c | 14 ---
lib/libalpm/db.c | 34 ------
lib/libalpm/deps.c | 32 ------
lib/libalpm/dload.c | 1 -
lib/libalpm/handle.c | 6 -
lib/libalpm/log.c | 13 ---
lib/libalpm/package.c | 28 -----
lib/libalpm/remove.c | 8 --
lib/libalpm/signing.c | 34 ------
lib/libalpm/sync.c | 17 ---
lib/libalpm/trans.c | 12 --
lib/libalpm/util.c | 10 --
lib/libalpm/version.c | 14 ---
17 files changed, 241 insertions(+), 298 deletions(-)
diff --git a/lib/libalpm/add.c b/lib/libalpm/add.c
index b949976d..2cfb3974 100644
--- a/lib/libalpm/add.c
+++ b/lib/libalpm/add.c
@@ -47,7 +47,6 @@
#include "remove.h"
#include "handle.h"
-/** Add a package to the transaction. */
int SYMEXPORT alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
{
const char *pkgname, *pkgver;
diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c
index 1a378db9..cb2ab795 100644
--- a/lib/libalpm/alpm.c
+++ b/lib/libalpm/alpm.c
@@ -32,19 +32,6 @@
#include "log.h"
#include "util.h"
-/** \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 SYMEXPORT *alpm_initialize(const char *root, const char *dbpath,
alpm_errno_t *err)
{
@@ -99,14 +86,6 @@ cleanup:
return NULL;
}
-/** 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 SYMEXPORT alpm_release(alpm_handle_t *myhandle)
{
int ret = 0;
@@ -135,23 +114,11 @@ int SYMEXPORT alpm_release(alpm_handle_t *myhandle)
return ret;
}
-/** @} */
-
-/** @defgroup alpm_misc Miscellaneous Functions
- * @brief Various libalpm functions
- */
-
-/** Get the version of library.
- * @return the library version, e.g. "6.0.4"
- * */
const char SYMEXPORT *alpm_version(void)
{
return LIB_VERSION;
}
-/** Get the capabilities of the library.
- * @return a bitmask of the capabilities
- * */
int SYMEXPORT alpm_capabilities(void)
{
return 0
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 956284bd..4a2d2fc1 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -335,6 +335,11 @@ typedef enum _alpm_hook_when_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,
@@ -345,9 +350,17 @@ typedef enum _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.
*/
@@ -960,12 +973,71 @@ int alpm_db_get_valid(alpm_db_t *db);
/** @name Accessors to the list of servers for a database.
* @{
*/
+
+/** Get the list of servers assigned to this db.
+ * @param db pointer to the database to get the servers from
+ * @return a char* list of servers
+ */
alpm_list_t *alpm_db_get_servers(const alpm_db_t *db);
+
+/** Sets the list of servers for the database to use.
+ * @param db the database to set the servers
+ * @param a char* list of servers. Note: the database will
+ * take ownership of the list and it should no longer be
+ * freed by the caller
+ */
int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers);
+
+/** Add a download server to a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
int alpm_db_add_server(alpm_db_t *db, const char *url);
+
+/** Remove a download server from a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, 1 on server not present,
+ * -1 on error (pm_errno is set accordingly)
+ */
int alpm_db_remove_server(alpm_db_t *db, const char *url);
/** @} */
+/** Update a package database
+ *
+ * An update of the package database \a db will be attempted. Unless
+ * \a force is true, the update will only be performed if the remote
+ * database was modified since the last update.
+ *
+ * This operation requires a database lock, and will return an applicable error
+ * if the lock could not be obtained.
+ *
+ * Example:
+ * @code
+ * alpm_list_t *syncs = alpm_get_syncdbs();
+ * for(i = syncs; i; i = alpm_list_next(i)) {
+ * alpm_db_t *db = alpm_list_getdata(i);
+ * result = alpm_db_update(0, db);
+ *
+ * if(result < 0) {
+ * printf("Unable to update database: %s\n", alpm_strerrorlast());
+ * } else if(result == 1) {
+ * printf("Database already up to date\n");
+ * } else {
+ * printf("Database updated\n");
+ * }
+ * }
+ * @endcode
+ *
+ * @note After a successful update, the \link alpm_db_get_pkgcache()
+ * package cache \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
+ * @return 0 on success, -1 on error (pm_errno is set accordingly), 1 if up to
+ * to date
+ */
int alpm_db_update(int force, alpm_db_t *db);
/** Get a package entry from a package database.
@@ -1069,7 +1141,20 @@ int alpm_pkg_free(alpm_pkg_t *pkg);
*/
int alpm_pkg_checkmd5sum(alpm_pkg_t *pkg);
-/** Compare two version strings and determine which one is 'newer'. */
+/** Compare two version strings and determine which one is 'newer'.
+ * Returns a value comparable to the way strcmp works. Returns 1
+ * if a is newer than b, 0 if a and b are the same version, or -1
+ * if b is newer than a.
+ *
+ * Different epoch values for version strings will override any further
+ * comparison. If no epoch is provided, 0 is assumed.
+ *
+ * Keep in mind that the pkgrel is only compared if it is available
+ * on both versions handed to this function. For example, comparing
+ * 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield
+ * -1 as expected. This is mainly for supporting versioned dependencies
+ * that do not include the pkgrel.
+ */
int alpm_pkg_vercmp(const char *a, const char *b);
/** Computes the list of packages requiring a given package.
@@ -1317,11 +1402,15 @@ void *alpm_pkg_changelog_open(alpm_pkg_t *pkg);
size_t alpm_pkg_changelog_read(void *ptr, size_t size,
const alpm_pkg_t *pkg, void *fp);
+/** Close a package changelog for reading.
+ * @param pkg the package to close the changelog of (either file or db)
+ * @return 0 on success, -1 on error
+ */
int alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp);
/** Open a package mtree file for reading.
- * @param pkg the local package to read the changelog of
- * @return a archive structure for the package mtree file
+ * @param pkg the local package to read the mtree of
+ * @return an archive structure for the package mtree file
*/
struct archive *alpm_pkg_mtree_open(alpm_pkg_t *pkg);
@@ -1334,6 +1423,10 @@ struct archive *alpm_pkg_mtree_open(alpm_pkg_t *pkg);
int alpm_pkg_mtree_next(const alpm_pkg_t *pkg, struct archive *archive,
struct archive_entry **entry);
+/** Close a package mtree file.
+ * @param pkg the local package to close the mtree of
+ * @param the archive to close
+ */
int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive);
/** Returns whether the package has an install scriptlet.
@@ -1341,8 +1434,7 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive);
*/
int alpm_pkg_has_scriptlet(alpm_pkg_t *pkg);
-/** Returns the size of download.
- * Returns the size of the files that will be downloaded to install a
+/** Returns the size of the files that will be downloaded to install a
* package.
* @param newpkg the new package to upgrade to
* @return the size of the download
@@ -1380,15 +1472,48 @@ 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);
@@ -1396,12 +1521,22 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
* 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
*/
+/** Check for new version of pkg in sync repos
+ * (only the first occurrence is considered in sync)
+ */
alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync);
/** @addtogroup alpm_api_trans Transaction Functions
@@ -1534,12 +1669,49 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
* @{
*/
+/** 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.
@@ -1568,12 +1740,60 @@ void alpm_dep_free(alpm_depend_t *dep);
*/
/* checksums */
+
+/** \addtogroup alpm_misc Miscellaneous Functions
+ * @brief Various libalpm functions
+ * @{
+ */
+
+/** Get the md5 sum of file.
+ * @param filename name of the file
+ * @return the checksum on success, NULL on error
+ */
char *alpm_compute_md5sum(const char *filename);
+
+/** Get the sha256 sum of file.
+ * @param filename name of the file
+ * @return the checksum on success, NULL on error
+ */
char *alpm_compute_sha256sum(const char *filename);
+/** @} */
+
+/** \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
+ *
+ * @note Safe to call from inside signal handlers.
+ */
int alpm_unlock(alpm_handle_t *handle);
enum alpm_caps {
@@ -1582,12 +1802,27 @@ enum alpm_caps {
ALPM_CAPABILITY_SIGNATURES = (1 << 2)
};
+/** Get the version of library.
+ * @return the library version, e.g. "6.0.4"
+ * */
const char *alpm_version(void);
-/* Return a bitfield of capabilities using values from 'enum alpm_caps' */
+
+/** 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);
+
+/**
+ * Free a conflict and its members.
+ * @param conflict the conflict to free
+ */
void alpm_conflict_free(alpm_conflict_t *conflict);
/* End of alpm_api */
diff --git a/lib/libalpm/be_sync.c b/lib/libalpm/be_sync.c
index 07d2b4ae..5a97d31e 100644
--- a/lib/libalpm/be_sync.c
+++ b/lib/libalpm/be_sync.c
@@ -136,41 +136,6 @@ valid:
return 0;
}
-/** Update a package database
- *
- * An update of the package database \a db will be attempted. Unless
- * \a force is true, the update will only be performed if the remote
- * database was modified since the last update.
- *
- * This operation requires a database lock, and will return an applicable error
- * if the lock could not be obtained.
- *
- * Example:
- * @code
- * alpm_list_t *syncs = alpm_get_syncdbs();
- * for(i = syncs; i; i = alpm_list_next(i)) {
- * alpm_db_t *db = alpm_list_getdata(i);
- * result = alpm_db_update(0, db);
- *
- * if(result < 0) {
- * printf("Unable to update database: %s\n", alpm_strerrorlast());
- * } else if(result == 1) {
- * printf("Database already up to date\n");
- * } else {
- * printf("Database updated\n");
- * }
- * }
- * @endcode
- *
- * @ingroup alpm_databases
- * @note After a successful update, the \link alpm_db_get_pkgcache()
- * package cache \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
- * @return 0 on success, -1 on error (pm_errno is set accordingly), 1 if up to
- * to date
- */
int SYMEXPORT alpm_db_update(int force, alpm_db_t *db)
{
char *syncpath;
diff --git a/lib/libalpm/conflict.c b/lib/libalpm/conflict.c
index 80827ed6..65026f7c 100644
--- a/lib/libalpm/conflict.c
+++ b/lib/libalpm/conflict.c
@@ -63,9 +63,6 @@ error:
return NULL;
}
-/**
- * @brief Free a conflict and its members.
- */
void SYMEXPORT alpm_conflict_free(alpm_conflict_t *conflict)
{
ASSERT(conflict != NULL, return);
@@ -243,14 +240,6 @@ alpm_list_t *_alpm_outerconflicts(alpm_db_t *db, alpm_list_t *packages)
return baddeps;
}
-/**
- * @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 SYMEXPORT *alpm_checkconflicts(alpm_handle_t *handle,
alpm_list_t *pkglist)
{
@@ -300,9 +289,6 @@ error:
RET_ERR(handle, ALPM_ERR_MEMORY, conflicts);
}
-/**
- * @brief Frees a conflict and its members.
- */
void SYMEXPORT alpm_fileconflict_free(alpm_fileconflict_t *conflict)
{
ASSERT(conflict != NULL, return);
diff --git a/lib/libalpm/db.c b/lib/libalpm/db.c
index 43ca1fc8..8a18c5a8 100644
--- a/lib/libalpm/db.c
+++ b/lib/libalpm/db.c
@@ -37,12 +37,6 @@
#include "package.h"
#include "group.h"
-/** \addtogroup alpm_databases Database Functions
- * @brief Functions to query and manipulate the database of libalpm
- * @{
- */
-
-/** Register a sync database of packages. */
alpm_db_t SYMEXPORT *alpm_register_syncdb(alpm_handle_t *handle,
const char *treename, int siglevel)
{
@@ -81,7 +75,6 @@ void _alpm_db_unregister(alpm_db_t *db)
_alpm_db_free(db);
}
-/** Unregister all package databases. */
int SYMEXPORT alpm_unregister_all_syncdbs(alpm_handle_t *handle)
{
alpm_list_t *i;
@@ -102,7 +95,6 @@ int SYMEXPORT alpm_unregister_all_syncdbs(alpm_handle_t *handle)
return 0;
}
-/** Unregister a package database. */
int SYMEXPORT alpm_db_unregister(alpm_db_t *db)
{
int found = 0;
@@ -139,14 +131,12 @@ int SYMEXPORT alpm_db_unregister(alpm_db_t *db)
return 0;
}
-/** Get the serverlist of a database. */
alpm_list_t SYMEXPORT *alpm_db_get_servers(const alpm_db_t *db)
{
ASSERT(db != NULL, return NULL);
return db->servers;
}
-/** Set the serverlist of a database. */
int SYMEXPORT alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers)
{
ASSERT(db != NULL, return -1);
@@ -168,11 +158,6 @@ static char *sanitize_url(const char *url)
return newurl;
}
-/** Add a download server to a database.
- * @param db database pointer
- * @param url url of the server
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
int SYMEXPORT alpm_db_add_server(alpm_db_t *db, const char *url)
{
char *newurl;
@@ -193,12 +178,6 @@ int SYMEXPORT alpm_db_add_server(alpm_db_t *db, const char *url)
return 0;
}
-/** Remove a download server from a database.
- * @param db database pointer
- * @param url url of the server
- * @return 0 on success, 1 on server not present,
- * -1 on error (pm_errno is set accordingly)
- */
int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
{
char *newurl, *vdata = NULL;
@@ -227,14 +206,12 @@ int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
return ret;
}
-/** Get the name of a package database. */
const char SYMEXPORT *alpm_db_get_name(const alpm_db_t *db)
{
ASSERT(db != NULL, return NULL);
return db->treename;
}
-/** Get the signature verification level for a database. */
int SYMEXPORT alpm_db_get_siglevel(alpm_db_t *db)
{
ASSERT(db != NULL, return -1);
@@ -245,7 +222,6 @@ int SYMEXPORT alpm_db_get_siglevel(alpm_db_t *db)
}
}
-/** Check the validity of a database. */
int SYMEXPORT alpm_db_get_valid(alpm_db_t *db)
{
ASSERT(db != NULL, return -1);
@@ -253,7 +229,6 @@ int SYMEXPORT alpm_db_get_valid(alpm_db_t *db)
return db->ops->validate(db);
}
-/** Get a package entry from a package database. */
alpm_pkg_t SYMEXPORT *alpm_db_get_pkg(alpm_db_t *db, const char *name)
{
alpm_pkg_t *pkg;
@@ -269,7 +244,6 @@ alpm_pkg_t SYMEXPORT *alpm_db_get_pkg(alpm_db_t *db, const char *name)
return pkg;
}
-/** Get the package cache of a package database. */
alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(alpm_db_t *db)
{
ASSERT(db != NULL, return NULL);
@@ -277,7 +251,6 @@ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(alpm_db_t *db)
return _alpm_db_get_pkgcache(db);
}
-/** Get a group entry from a package database. */
alpm_group_t SYMEXPORT *alpm_db_get_group(alpm_db_t *db, const char *name)
{
ASSERT(db != NULL, return NULL);
@@ -288,7 +261,6 @@ alpm_group_t SYMEXPORT *alpm_db_get_group(alpm_db_t *db, const char *name)
return _alpm_db_get_groupfromcache(db, name);
}
-/** Get the group cache of a package database. */
alpm_list_t SYMEXPORT *alpm_db_get_groupcache(alpm_db_t *db)
{
ASSERT(db != NULL, return NULL);
@@ -297,7 +269,6 @@ alpm_list_t SYMEXPORT *alpm_db_get_groupcache(alpm_db_t *db)
return _alpm_db_get_groupcache(db);
}
-/** Searches a database. */
int SYMEXPORT alpm_db_search(alpm_db_t *db, const alpm_list_t *needles,
alpm_list_t **ret)
{
@@ -308,7 +279,6 @@ int SYMEXPORT alpm_db_search(alpm_db_t *db, const alpm_list_t *needles,
return _alpm_db_search(db, needles, ret);
}
-/** Sets the usage bitmask for a repo */
int SYMEXPORT alpm_db_set_usage(alpm_db_t *db, int usage)
{
ASSERT(db != NULL, return -1);
@@ -316,7 +286,6 @@ int SYMEXPORT alpm_db_set_usage(alpm_db_t *db, int usage)
return 0;
}
-/** Gets the usage bitmask for a repo */
int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, int *usage)
{
ASSERT(db != NULL, return -1);
@@ -325,9 +294,6 @@ int SYMEXPORT alpm_db_get_usage(alpm_db_t *db, int *usage)
return 0;
}
-
-/** @} */
-
alpm_db_t *_alpm_db_new(const char *treename, int is_local)
{
alpm_db_t *db;
diff --git a/lib/libalpm/deps.c b/lib/libalpm/deps.c
index b3732870..fc0a5308 100644
--- a/lib/libalpm/deps.c
+++ b/lib/libalpm/deps.c
@@ -286,12 +286,6 @@ static int no_dep_version(alpm_handle_t *handle)
return (handle->trans->flags & ALPM_TRANS_FLAG_NODEPVERSION);
}
-/** 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 SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring)
{
alpm_depend_t *dep = alpm_dep_from_string(depstring);
@@ -303,15 +297,6 @@ alpm_pkg_t SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstri
return pkg;
}
-/** 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 SYMEXPORT *alpm_checkdeps(alpm_handle_t *handle,
alpm_list_t *pkglist, alpm_list_t *rem, alpm_list_t *upgrade,
int reversedeps)
@@ -763,18 +748,6 @@ static alpm_pkg_t *resolvedep(alpm_handle_t *handle, alpm_depend_t *dep,
return NULL;
}
-/** 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 SYMEXPORT *alpm_find_dbs_satisfier(alpm_handle_t *handle,
alpm_list_t *dbs, const char *depstring)
{
@@ -889,11 +862,6 @@ int _alpm_resolvedeps(alpm_handle_t *handle, alpm_list_t *localpkgs,
return ret;
}
-/** Reverse of splitdep; make a dep string from a alpm_depend_t struct.
- * The string must be freed!
- * @param dep the depend to turn into a string
- * @return a string-formatted dependency with operator if necessary
- */
char SYMEXPORT *alpm_dep_compute_string(const alpm_depend_t *dep)
{
const char *name, *opr, *ver, *desc_delim, *desc;
diff --git a/lib/libalpm/dload.c b/lib/libalpm/dload.c
index b3e6a411..72e3ca60 100644
--- a/lib/libalpm/dload.c
+++ b/lib/libalpm/dload.c
@@ -652,7 +652,6 @@ static char *filecache_find_url(alpm_handle_t *handle, const char *url)
return _alpm_filecache_find(handle, filebase);
}
-/** Fetch a remote pkg. */
char SYMEXPORT *alpm_fetch_pkgurl(alpm_handle_t *handle, const char *url)
{
char *filepath;
diff --git a/lib/libalpm/handle.c b/lib/libalpm/handle.c
index e3193f40..c4814b9f 100644
--- a/lib/libalpm/handle.c
+++ b/lib/libalpm/handle.c
@@ -123,12 +123,6 @@ int _alpm_handle_lock(alpm_handle_t *handle)
return (handle->lockfd >= 0 ? 0 : -1);
}
-/** 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 SYMEXPORT alpm_unlock(alpm_handle_t *handle)
{
ASSERT(handle != NULL, return -1);
diff --git a/lib/libalpm/log.c b/lib/libalpm/log.c
index bae92f1f..a6702782 100644
--- a/lib/libalpm/log.c
+++ b/lib/libalpm/log.c
@@ -30,11 +30,6 @@
#include "util.h"
#include "alpm.h"
-/** \addtogroup alpm_log Logging Functions
- * @brief Functions to log using libalpm
- * @{
- */
-
static int _alpm_log_leader(FILE *f, const char *prefix)
{
time_t t = time(NULL);
@@ -47,12 +42,6 @@ static int _alpm_log_leader(FILE *f, const char *prefix)
return fprintf(f, "[%s] [%s] ", timestamp, prefix);
}
-/** 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 SYMEXPORT alpm_logaction(alpm_handle_t *handle, const char *prefix,
const char *fmt, ...)
{
@@ -109,8 +98,6 @@ int SYMEXPORT alpm_logaction(alpm_handle_t *handle, const char *prefix,
return ret;
}
-/** @} */
-
void _alpm_log(alpm_handle_t *handle, alpm_loglevel_t flag, const char *fmt, ...)
{
va_list args;
diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c
index 4b391a9c..11d37d43 100644
--- a/lib/libalpm/package.c
+++ b/lib/libalpm/package.c
@@ -34,12 +34,6 @@
#include "handle.h"
#include "deps.h"
-/** \addtogroup alpm_packages Package Functions
- * @brief Functions to manipulate libalpm packages
- * @{
- */
-
-/** Free a package. */
int SYMEXPORT alpm_pkg_free(alpm_pkg_t *pkg)
{
ASSERT(pkg != NULL, return -1);
@@ -52,7 +46,6 @@ int SYMEXPORT alpm_pkg_free(alpm_pkg_t *pkg)
return 0;
}
-/** Check the integrity (with md5) of a package from the sync cache. */
int SYMEXPORT alpm_pkg_checkmd5sum(alpm_pkg_t *pkg)
{
char *fpath;
@@ -397,7 +390,6 @@ alpm_db_t SYMEXPORT *alpm_pkg_get_db(alpm_pkg_t *pkg)
return pkg->origin_data.db;
}
-/** Open a package changelog for reading. */
void SYMEXPORT *alpm_pkg_changelog_open(alpm_pkg_t *pkg)
{
ASSERT(pkg != NULL, return NULL);
@@ -405,7 +397,6 @@ void SYMEXPORT *alpm_pkg_changelog_open(alpm_pkg_t *pkg)
return pkg->ops->changelog_open(pkg);
}
-/** Read data from an open changelog 'file stream'. */
size_t SYMEXPORT alpm_pkg_changelog_read(void *ptr, size_t size,
const alpm_pkg_t *pkg, void *fp)
{
@@ -414,7 +405,6 @@ size_t SYMEXPORT alpm_pkg_changelog_read(void *ptr, size_t size,
return pkg->ops->changelog_read(ptr, size, pkg, fp);
}
-/** Close a package changelog for reading. */
int SYMEXPORT alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp)
{
ASSERT(pkg != NULL, return -1);
@@ -422,7 +412,6 @@ int SYMEXPORT alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp)
return pkg->ops->changelog_close(pkg, fp);
}
-/** Open a package mtree file for reading. */
struct archive SYMEXPORT *alpm_pkg_mtree_open(alpm_pkg_t * pkg)
{
ASSERT(pkg != NULL, return NULL);
@@ -430,7 +419,6 @@ struct archive SYMEXPORT *alpm_pkg_mtree_open(alpm_pkg_t * pkg)
return pkg->ops->mtree_open(pkg);
}
-/** Read entry from an open mtree file. */
int SYMEXPORT alpm_pkg_mtree_next(const alpm_pkg_t * pkg, struct archive *archive,
struct archive_entry **entry)
{
@@ -439,7 +427,6 @@ int SYMEXPORT alpm_pkg_mtree_next(const alpm_pkg_t * pkg, struct archive *archiv
return pkg->ops->mtree_next(pkg, archive, entry);
}
-/** Close a package mtree file for reading. */
int SYMEXPORT alpm_pkg_mtree_close(const alpm_pkg_t * pkg, struct archive *archive)
{
ASSERT(pkg != NULL, return -1);
@@ -510,21 +497,16 @@ static alpm_list_t *compute_requiredby(alpm_pkg_t *pkg, int optional)
return reqs;
}
-/** Compute the packages requiring a given package. */
alpm_list_t SYMEXPORT *alpm_pkg_compute_requiredby(alpm_pkg_t *pkg)
{
return compute_requiredby(pkg, 0);
}
-/** Compute the packages optionally requiring a given package. */
alpm_list_t SYMEXPORT *alpm_pkg_compute_optionalfor(alpm_pkg_t *pkg)
{
return compute_requiredby(pkg, 1);
}
-
-/** @} */
-
alpm_file_t *_alpm_file_copy(alpm_file_t *dest,
const alpm_file_t *src)
{
@@ -764,16 +746,6 @@ alpm_pkg_t SYMEXPORT *alpm_pkg_find(alpm_list_t *haystack, const char *needle)
return NULL;
}
-/** Test if a package should be ignored.
- *
- * Checks if the package is ignored via IgnorePkg, or if the package is
- * in a group ignored via IgnoreGroup.
- *
- * @param handle the context handle
- * @param pkg the package to test
- *
- * @return 1 if the package should be ignored, 0 otherwise
- */
int SYMEXPORT alpm_pkg_should_ignore(alpm_handle_t *handle, alpm_pkg_t *pkg)
{
alpm_list_t *groups = NULL;
diff --git a/lib/libalpm/remove.c b/lib/libalpm/remove.c
index 9030bfee..e0b08586 100644
--- a/lib/libalpm/remove.c
+++ b/lib/libalpm/remove.c
@@ -46,14 +46,6 @@
#include "handle.h"
#include "filelist.h"
-/**
- * @brief 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
- */
int SYMEXPORT alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
{
const char *pkgname;
diff --git a/lib/libalpm/signing.c b/lib/libalpm/signing.c
index 257a287f..bae52a58 100644
--- a/lib/libalpm/signing.c
+++ b/lib/libalpm/signing.c
@@ -35,14 +35,6 @@
#include "alpm.h"
#include "handle.h"
-/**
- * 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 SYMEXPORT alpm_decode_signature(const char *base64_data,
unsigned char **data, size_t *data_len)
{
@@ -999,12 +991,6 @@ int _alpm_process_siglist(alpm_handle_t *handle, const char *identifier,
return retry;
}
-/**
- * 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 SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg,
alpm_siglist_t *siglist)
{
@@ -1016,12 +1002,6 @@ int SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg,
pkg->base64_sig, 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 SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db,
alpm_siglist_t *siglist)
{
@@ -1032,13 +1012,6 @@ int SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db,
return _alpm_gpgme_checksig(db->handle, _alpm_db_path(db), NULL, 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 SYMEXPORT alpm_siglist_cleanup(alpm_siglist_t *siglist)
{
ASSERT(siglist != NULL, return -1);
@@ -1119,13 +1092,6 @@ static int parse_subpacket(alpm_handle_t *handle, const char *identifier,
return 0;
}
-/**
- * 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 SYMEXPORT alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
const unsigned char *sig, const size_t len, alpm_list_t **keys)
{
diff --git a/lib/libalpm/sync.c b/lib/libalpm/sync.c
index 97a351fe..d02a435f 100644
--- a/lib/libalpm/sync.c
+++ b/lib/libalpm/sync.c
@@ -52,10 +52,6 @@ struct keyinfo_t {
char* keyid;
};
-
-/** Check for new version of pkg in sync repos
- * (only the first occurrence is considered in sync)
- */
alpm_pkg_t SYMEXPORT *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync)
{
alpm_list_t *i;
@@ -200,7 +196,6 @@ static alpm_list_t *check_replacers(alpm_handle_t *handle, alpm_pkg_t *lpkg,
return replacers;
}
-/** Search for packages to upgrade and add them to the transaction. */
int SYMEXPORT alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade)
{
alpm_list_t *i, *j;
@@ -256,13 +251,6 @@ int SYMEXPORT alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade)
return 0;
}
-/** 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 SYMEXPORT *alpm_find_group_pkgs(alpm_list_t *dbs,
const char *name)
{
@@ -673,11 +661,6 @@ cleanup:
return ret;
}
-/** Returns the size of the files that will be downloaded to install a
- * package.
- * @param newpkg the new package to upgrade to
- * @return the size of the download
- */
off_t SYMEXPORT alpm_pkg_download_size(alpm_pkg_t *newpkg)
{
if(!(newpkg->infolevel & INFRQ_DSIZE)) {
diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c
index 14f7d5e3..8909b9e3 100644
--- a/lib/libalpm/trans.c
+++ b/lib/libalpm/trans.c
@@ -42,12 +42,6 @@
#include "deps.h"
#include "hook.h"
-/** \addtogroup alpm_trans Transaction Functions
- * @brief Functions to manipulate libalpm transactions
- * @{
- */
-
-/** Initialize the transaction. */
int SYMEXPORT alpm_trans_init(alpm_handle_t *handle, int flags)
{
alpm_trans_t *trans;
@@ -97,7 +91,6 @@ static alpm_list_t *check_arch(alpm_handle_t *handle, alpm_list_t *pkgs)
return invalid;
}
-/** Prepare a transaction. */
int SYMEXPORT alpm_trans_prepare(alpm_handle_t *handle, alpm_list_t **data)
{
alpm_trans_t *trans;
@@ -156,7 +149,6 @@ int SYMEXPORT alpm_trans_prepare(alpm_handle_t *handle, alpm_list_t **data)
return 0;
}
-/** Commit a transaction. */
int SYMEXPORT alpm_trans_commit(alpm_handle_t *handle, alpm_list_t **data)
{
alpm_trans_t *trans;
@@ -233,9 +225,6 @@ int SYMEXPORT alpm_trans_commit(alpm_handle_t *handle, alpm_list_t **data)
return 0;
}
-/** Interrupt a transaction.
- * @note Safe to call from inside signal handlers.
- */
int SYMEXPORT alpm_trans_interrupt(alpm_handle_t *handle)
{
alpm_trans_t *trans;
@@ -253,7 +242,6 @@ int SYMEXPORT alpm_trans_interrupt(alpm_handle_t *handle)
return 0;
}
-/** Release a transaction. */
int SYMEXPORT alpm_trans_release(alpm_handle_t *handle)
{
alpm_trans_t *trans;
diff --git a/lib/libalpm/util.c b/lib/libalpm/util.c
index d12a4403..128d3cd7 100644
--- a/lib/libalpm/util.c
+++ b/lib/libalpm/util.c
@@ -1023,11 +1023,6 @@ static char *hex_representation(unsigned char *bytes, size_t size)
return str;
}
-/** Get the md5 sum of file.
- * @param filename name of the file
- * @return the checksum on success, NULL on error
- * @addtogroup alpm_misc
- */
char SYMEXPORT *alpm_compute_md5sum(const char *filename)
{
unsigned char output[16];
@@ -1041,11 +1036,6 @@ char SYMEXPORT *alpm_compute_md5sum(const char *filename)
return hex_representation(output, 16);
}
-/** Get the sha256 sum of file.
- * @param filename name of the file
- * @return the checksum on success, NULL on error
- * @addtogroup alpm_misc
- */
char SYMEXPORT *alpm_compute_sha256sum(const char *filename)
{
unsigned char output[32];
diff --git a/lib/libalpm/version.c b/lib/libalpm/version.c
index 5ae3b341..ae220ff6 100644
--- a/lib/libalpm/version.c
+++ b/lib/libalpm/version.c
@@ -216,20 +216,6 @@ cleanup:
return ret;
}
-/** Compare two version strings and determine which one is 'newer'.
- * Returns a value comparable to the way strcmp works. Returns 1
- * if a is newer than b, 0 if a and b are the same version, or -1
- * if b is newer than a.
- *
- * Different epoch values for version strings will override any further
- * comparison. If no epoch is provided, 0 is assumed.
- *
- * Keep in mind that the pkgrel is only compared if it is available
- * on both versions handed to this function. For example, comparing
- * 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield
- * -1 as expected. This is mainly for supporting versioned dependencies
- * that do not include the pkgrel.
- */
int SYMEXPORT alpm_pkg_vercmp(const char *a, const char *b)
{
char *full1, *full2;
--
2.25.0
More information about the pacman-dev
mailing list