From d0c487d4dcc6fec6f4bd8e1cefa1de9ffbe0e460 Mon Sep 17 00:00:00 2001 From: morganamilo Date: Sun, 26 Jan 2020 07:01:42 +0000 Subject: Docs docs docs libalpm: move docs from .c files into alpm.h And fix/expand some along the way. Signed-off-by: Allan McRae --- 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(-) (limited to 'lib') 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 e33ec7bd..f79c8a76 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 e72a0b2a..caa2935b 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 23464045..9bedf568 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; -- cgit v1.2.3-70-g09d2