From patchwork Sun Jan 26 07:01:42 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1467 Return-Path: Delivered-To: patchwork@archlinux.org Received: from apollo.archlinux.org (localhost [127.0.0.1]) by apollo.archlinux.org (Postfix) with ESMTP id D50B9169BCB9F for ; Sun, 26 Jan 2020 07:04:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.3 (2019-12-06) on apollo.archlinux.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1, MAILING_LIST_MULTI=-1,RCVD_IN_DNSWL_MED=-2.3,SPF_HELO_NONE=0.001, T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.3 X-Spam-BL-Results: [127.0.9.2] [127.0.0.10] Received: from orion.archlinux.org (orion.archlinux.org [88.198.91.70]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Sun, 26 Jan 2020 07:04:20 +0000 (UTC) Received: from orion.archlinux.org (localhost [127.0.0.1]) by orion.archlinux.org (Postfix) with ESMTP id 68949185EAFBA2; Sun, 26 Jan 2020 07:04:10 +0000 (UTC) Received: from luna.archlinux.org (luna.archlinux.org [5.9.250.164]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits)) (No client certificate requested) (Authenticated sender: luna) by orion.archlinux.org (Postfix) with ESMTPSA id B2035185EAFB56; Sun, 26 Jan 2020 07:03:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=orion; t=1580022239; bh=kOkYWlbl6e3qGdZAHBHTNH6cLWeOTHqIu4hkJlFDWpM=; h=From:To:Date:Subject:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:Reply-To; b=HuT7m0ZTuqJ3z8AnvJzJSHIarAR/GCvmDoFGsj/2SPmgBcl14ryTtwSXj5ow8f8tE 4R9nnaYUFo0/xfr6uzZT5CdMx4yJ8ruRNUJsWK/8rTlfnOf34GCeGqRmel/MzxDYIS J61mNohaEtFoU/btXvLagkDTxMuYQAtQdZR5Izk05vxheb7Hv75zT+sGydGtutirZh lRuVJrGp9HjOsXYM2ZIz8KPyR9cM0TmtHqLl1uAdihYnrwlIqqEy5Z7R3odEqVlBzV mzY7f/JIGBQohZ2Jx+9oietbGMrLjMtFFVZ3SGXjmzLUgMNDtLgqvSeDABq5UjWJwy 6zP7RydBvQL5zsJokDalXzp/pbpygDQz+pblPdw0MF8MYIWD7DVywkZZLh//D/MxPl hGVo9mdlsg5XqJ5G6AWeyHqszVin8/2y5UH73PXx89H/2mC249IcKhkEjn0x7iJ7dr t76y5y02wKyKjvl30LMLSzWv5FCTmkqNZKIjrMBbSM8jKF1ZUpRqqiOfo9fw849Tzt jUlsZvkRElZSxoDG+saTBfSkVnOK7FW2ux9yz9mwJLVgXRrsDYU253Lk41sszv4Tgr w/kiyLOr+O+OhtZ29NOPWgf+4XmsO2uvCsi+gSREeq39HXCjmNe5R3wZgo3o7gqLkC Jfp4jOkW+wF/RAU7U+CeLIpw= Received: from luna.archlinux.org (luna.archlinux.org [127.0.0.1]) by luna.archlinux.org (Postfix) with ESMTP id A28412BFE0; Sun, 26 Jan 2020 07:03:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1580022239; bh=kOkYWlbl6e3qGdZAHBHTNH6cLWeOTHqIu4hkJlFDWpM=; h=From:To:Date:Subject:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:Reply-To; b=JdBp6djUeHzklpL6lNGl9h5xkj521G1s1O4cAQtxmcXVJajOQH5YCZ+Gvb5zIX0Y4 d47gbocEaGUW8gfZMbq7d9gRSICrVQIbGPQmh6ijzp9jXvUCo9JMhbfsWvVHuITsqe oXsLpPkyuiUFA5vLGyTBmYuq7ZFgvDgq5DEceeS90+Nn1znWmIEFa91eGOhdyyWwSu M76up1rUJXKmy6zQ1R13/n3F/yQyHEEmaHNzhVA5W6jOPWNu3UbbhtsHvjQ1VlTI44 hkuqUUYgBtaFhbZ+8A1OTsjlx2hF+BwBu7/+k/jYynDDlZddGXzyZHcE/ie4YMRcat 2/7q6tmStTnSGQEm/eDF2gMEwmupOnTQYo9/Sm6Qz/FWbwKjSFBLgJ/JZonODenqNM V+9SKynvC2MnT0gD5P1QryMKMVE0T02wAiLzsB+nDU9JG2yxbXT+ad2dN1mDJXfnTQ FiA7Y6xbmHFmzI78UiFHk/+N+n5C5hd4sGi910XftkxrEQRIXn4MW/3AR3fjdq6X+a CfvQpZB60vwymedDjD3XqPiAgMR3VT7J9aiI3vp99bFiZ2V0PrsmsrWtqUlMLGt10p TjTJHwCP+oLjT00q5j0Q7j0tEA9bjaFrMhDhwTKJr44Tg5bbt1vI0NpaV05yxVnKTV OB4w0OD5d/9HHvbvMITIfNcY= Received: from luna.archlinux.org (luna.archlinux.org [127.0.0.1]) by luna.archlinux.org (Postfix) with ESMTP id 33BDA2BFE0 for ; Sun, 26 Jan 2020 07:03:56 +0000 (UTC) Received: from orion.archlinux.org (orion.archlinux.org [88.198.91.70]) by luna.archlinux.org (Postfix) with ESMTPS for ; Sun, 26 Jan 2020 07:03:56 +0000 (UTC) Received: from orion.archlinux.org (localhost [127.0.0.1]) by orion.archlinux.org (Postfix) with ESMTP id 78DAB185EAFB3E; Sun, 26 Jan 2020 07:03:46 +0000 (UTC) Received: from localhost.localdomain (host-92-14-139-121.as43234.net [92.14.139.121]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: morganamilo) by orion.archlinux.org (Postfix) with ESMTPSA id 292D4185EAFB3D; Sun, 26 Jan 2020 07:03:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=orion; t=1580022226; bh=kOkYWlbl6e3qGdZAHBHTNH6cLWeOTHqIu4hkJlFDWpM=; h=From:To:Cc:Subject:Date; b=EIPZJwcz9XmS3DuArB21bwI3dndYERDAbpe9xl4aBdxIzi8bXeQl20SlJ/04GZ/0I D91fiEw+4Rulgtdju7yCZaPO2DOGHJ9ofXTCdvwSSPstoWVKwr5vxDGwuEeEdvHJR7 hk0Y5Pt3+yPXBOUtKSaBPpyTvpaA9z54e7Ht2ZDXH09zFub1RZwS+ruCswz0AfKYVu 1cWkP4jpgxCBsjpLI8JsswOqKWrOlVhRw9FM98oCY4X5FFg5YW4/Rwyw8Kr53NOxcG SzBLwI0IA/pZQ4Z5vqLtf7oMMWdzdRlFhCdzmEQUXLKOlyGuYte1uZCQWRh/WgPgY0 50I2xyE4Up8bNEd2EQjdPi0tGrKFdL/Pd7CMbhdQ1tvEnT4uhWsrz9w6QmWFdxbLsG OZ18Guc1VPftnyODjDp6r/I8QIhw/upjSJrTRsx6/7qxJNExcBMMpUZ1IZKtQSq/fT BES1KAPfjopzi7QR7L2ksAu9O6EVQTamtKfK2SmIL0xkGdy1wR5AFVilI+uk+MLTTH jKaOOqxF2+rRJp8gnK69PLDm8pJZedRcADcUzfq5OjVDIl9aYEjT7h/T5QdPtxrVtc INi4HV6yPkceZsoyY2N7NCLkWC+SjIiQcriCGQUjdOsF5oFE5IJKGeCtH8B3OL28If P5c1nLdx1lWpMmk2cLh9pF1s= From: morganamilo To: pacman-dev@archlinux.org Date: Sun, 26 Jan 2020 07:01:42 +0000 Message-Id: <20200126070143.239135-1-morganamilo@archlinux.org> X-Mailer: git-send-email 2.25.0 MIME-Version: 1.0 Subject: [pacman-dev] [PATCH 1/2] Docs docs docs X-BeenThere: pacman-dev@archlinux.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion list for pacman development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Discussion list for pacman development Errors-To: pacman-dev-bounces@archlinux.org Sender: "pacman-dev" 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; From patchwork Sun Jan 26 07:01:43 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1466 Return-Path: Delivered-To: patchwork@archlinux.org Received: from apollo.archlinux.org (localhost [127.0.0.1]) by apollo.archlinux.org (Postfix) with ESMTP id EEBD9169BCB29 for ; Sun, 26 Jan 2020 07:04:06 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.3 (2019-12-06) on apollo.archlinux.org X-Spam-Level: X-Spam-Status: No, score=-2.9 required=5.0 tests=DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1, LOCAL_FAKEBUSINESS=0.5,MAILING_LIST_MULTI=-1,RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001,T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.3 X-Spam-BL-Results: [127.0.9.2] [127.0.0.10] Received: from orion.archlinux.org (orion.archlinux.org [88.198.91.70]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Sun, 26 Jan 2020 07:04:06 +0000 (UTC) Received: from orion.archlinux.org (localhost [127.0.0.1]) by orion.archlinux.org (Postfix) with ESMTP id 8D9AF185EAFB4C; Sun, 26 Jan 2020 07:03:57 +0000 (UTC) Received: from luna.archlinux.org (luna.archlinux.org [5.9.250.164]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits)) (No client certificate requested) (Authenticated sender: luna) by orion.archlinux.org (Postfix) with ESMTPSA id 5B697185EAFB45; Sun, 26 Jan 2020 07:03:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=orion; t=1580022237; bh=/uCaqdK/y4DAGj7mrmMm7aJl18Ee98x8XUeccbnnWPo=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=FEyl5aWBxwy0MajKzr8tHHXOYR6rfaARM84vbSZH73ueBmpjMVxcgUWxhHdChrufG huVX9/BeTpOSVVlTXpfkoRLQOpA2g9XTCna2OGMjV94RrfnsxL2/NZgw/Yw+GpfUct c9qoJ4XED5ERt2ZdGaslshKCvqboSlSRkuHt6kWH/chgN7oF5toToLLDBM1NuM+D/I HV+vqH6DfMdSYAOI8Wa/D2NKeKqSBG9/fZOlBsbb0ll+t/mwUP5gE5gLO5TncJLqUl kvbSYCOKLPt83TaX6bD+ruAQxwLTohSzfPmFfOsCezwk3O2N6kfwihLAfBa9P72OGS cOKyHFnaxjqen2w43y8A9jZWrYJx6aRH6u7HVIQ2MwC/cruAvLWtqc3LgWYl/iqNnA WinvZMCOBXlUdnFy7+W9HzBIPcYE3Oo9lW1Z5k/bpci08Thr9qadxpO2j0856pzRKK USCiANoOcBuKC/1kHU0DDklpo3rhWo0iWOATvithkaQUMrn1H5CNb/qzFHBpKMhPiz eCDWcXAo9Sj9ecnsY7M7JRmp8L9dCRbNQQm1p71gPSszf6uZYc2XQmlDYa2WhNXLTX Zooq0JlkE4ljzDq4FQmSO1MYrP39ZsJqMuEea/Vm/Z0LbQOAb+uLaFDuvrj1bpBrSo coCsAfjpV7gyKdwJPVAe50Jk= Received: from luna.archlinux.org (luna.archlinux.org [127.0.0.1]) by luna.archlinux.org (Postfix) with ESMTP id 470882BFE4; Sun, 26 Jan 2020 07:03:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1580022237; bh=/uCaqdK/y4DAGj7mrmMm7aJl18Ee98x8XUeccbnnWPo=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=SpOj8w+shL2xW+R9w0LAmXRvcjK+D6fwC4uKt5ik6QZltS9MZnuOlS1bjO+ScoFWE Rg6N6c3r74R/bszxMUdMczImgLijSXO0yeyjgA7SPAtyTNoYoPA/QXhFC4qmwADS+n G2bt7Z3GQmKPGDDzq0MMOwBTkCe9E/pwcrsxOQaZeivsIljtJziKfQP3iCpQ8eGtT5 mdw9R3MkQVXClnTpAQ+l+EDcwnc4tKnq/NUgdpig1FOZ8rRJIhE9p1FmddQs34MtuZ BiEF0zLmtb+hYG1o82bD0xWwmVFpYrK3ZXwRdpqgpr1NxeR/9Mk2SSVWs9dsJG2d7g oSQd2zMRLYCaFzPmCJa3zQ2Kyx3WAjtxV10IJ9ZvQUzKTdtmoxxquRIj2Vf1PT+sZW kluuFgGAWrMFa4oBkHYVX2zvF43Dp25OBvnLKab7PtZ5a84gQnrc+TqzwmhgwiWR8v 72Fpiw9OH8fpoWMXv7MhNIh18DtHhO7mQc7Ha/d/zApSwKJHbvImMwABciLlQRtRJA h4kID4+YahXOlOEd5QjiejPTp7Y3usQ5lVYf8qj4gk9mOGZd64JnNDT3jPXJEtmnyh DJuYEjHVDh3jq6ifv+XMHBsL6/F7Zu/87Q53KKxtkuuZOFOPf1ed/K1YdUKZgiVzpf IuNfs9DwrDyHfpfX7Sfhvov4= Received: from luna.archlinux.org (luna.archlinux.org [127.0.0.1]) by luna.archlinux.org (Postfix) with ESMTP id 441F62BE67 for ; Sun, 26 Jan 2020 07:03:53 +0000 (UTC) Received: from orion.archlinux.org (orion.archlinux.org [IPv6:2a01:4f8:160:6087::1]) by luna.archlinux.org (Postfix) with ESMTPS for ; Sun, 26 Jan 2020 07:03:53 +0000 (UTC) Received: from orion.archlinux.org (localhost [127.0.0.1]) by orion.archlinux.org (Postfix) with ESMTP id C2E2E185EAFB40; Sun, 26 Jan 2020 07:03:46 +0000 (UTC) Received: from localhost.localdomain (host-92-14-139-121.as43234.net [92.14.139.121]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: morganamilo) by orion.archlinux.org (Postfix) with ESMTPSA id 7CA4A185EAFB3F; Sun, 26 Jan 2020 07:03:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=orion; t=1580022226; bh=/uCaqdK/y4DAGj7mrmMm7aJl18Ee98x8XUeccbnnWPo=; h=From:To:Cc:Subject:Date:In-Reply-To:References; b=vrr09EGAv+Xy2ppi1zChYO4a+34jK4KWpyj4MPwKpzSlPM0+1VHKgcr6fRuapsRKM aWC6IXWM7XJt8MMIQuTuV6XpTmmTFWoLmpG8WtHzNYMNyzZLgblf3RJJCyGg6A52En 2Cj3aF0kluEIq4xmgJuXIUt+z1H0bcfZWvsJvhRiI2iCWcYItLES0tM3Es6powQLMm 8xa69kpkcKlqeBdczMNrTqBgHrhr9xTzcNt8vM7AW/WoMgAujGwlbFDlumGSveIQNS HZRGq/csU3muI/AtXNKyTceYNyLX7TcY9Td6Q0KivlFYVNsfoWUoOBvbF4mlNz91OB DTkmnV6nYIzYXGiothX72hRwz03ABkTeJGWGQwbc4enl4QWs1y0WVjOeDdVMe2rJjq WO2mTvIyA4nZp5LUtfGWzROTZPtJw5ju3ZM7YkyZz8EnIeZhoKm1B7c+0zQxss6ZUg AQ48pWQ4nUJoE7Y9VKPMCTs0UJCQ7rFKTmsiV/lZIfYsGAyVSTTXcK7giEqW3BRbou bjByrAy5W35nKj5f6ZbaGK/kE1SzrHdzERvy0FSfQWz1RRibsjMud92XO6PkvI0jwF F1egbCwmVEeP6w/oM0FSMn6ELF/LfZ/RJJv8PjxNkiIiRMouAHfSx9XrAdM0JuGell RsBXiGsYaJLHH9ERxJwbpnd4= From: morganamilo To: pacman-dev@archlinux.org Date: Sun, 26 Jan 2020 07:01:43 +0000 Message-Id: <20200126070143.239135-2-morganamilo@archlinux.org> X-Mailer: git-send-email 2.25.0 In-Reply-To: <20200126070143.239135-1-morganamilo@archlinux.org> References: <20200126070143.239135-1-morganamilo@archlinux.org> MIME-Version: 1.0 Subject: [pacman-dev] [PATCH 2/2] Docs docs docs and more docs X-BeenThere: pacman-dev@archlinux.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion list for pacman development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Discussion list for pacman development Errors-To: pacman-dev-bounces@archlinux.org Sender: "pacman-dev" Write docs for every public alpm member and expand on the existing documentation for other members. --- The entire .h file has basically been restructed. The best way to see the end result is either to read the generated man pages or enabled html and view the generated html. Also note alpm_list is still not documented. --- lib/libalpm/alpm.h | 1546 ++++++++++++++++++++++++++++++--------- lib/libalpm/alpm_list.h | 14 +- lib/libalpm/version.c | 2 +- 3 files changed, 1200 insertions(+), 362 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 4a2d2fc1..51e9e5b4 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -20,6 +20,16 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ + +/** + * @file alpm.h + * @author Pacman Development Team + * @date 26 Jan 2020 + * @brief Arch Linux Package Manager Library + * + * bork + */ + #ifndef ALPM_H #define ALPM_H @@ -38,267 +48,313 @@ extern "C" { #include /* - * Arch Linux Package Management library + * Opaque Structures */ -/* - * Opaque Structures +/** The libalpm context handle. + * + * This struct represents an instance of libalpm. */ typedef struct __alpm_handle_t alpm_handle_t; + +/** A database. + * + * A database is a container that stores metadata about packages. + * + * A database can be located on the local filesystem or on a remote server. + * + * To use a database, it must first be registered via \link alpm_register_syncdb \endlink. + * If the database is already preasant in the dbpath then it will be usable. Otherwise, + * the database needs to be downloaded using \link alpm_db_update \endlink. Even if the + * source of the database is the local filesystem. + * + * After this, the database can be used to query packages and groups. Any packages or groups + * from the database will continue to be owned by the database and do not need to be freed by + * the user. They will be freed when the database is unregistered. + * + * Databases are automatically unregistered when the \link alpm_handle_t \endlink is released. + */ typedef struct __alpm_db_t alpm_db_t; + +/** A package + * + * A package can be loaded from disk via \link alpm_pkg_load \endlink or retrieved from a database. + * Packages from databases are automatically freed when the database is unregistered. Packages loaded + * from a file must be freed manually. + * + * Packages can then be queried for metadata or added to a \link alpm_trans_t transaction \endlink + * to be added or removed from the system. + */ typedef struct __alpm_pkg_t alpm_pkg_t; + +/** Transaction structure used internally by libalpm */ typedef struct __alpm_trans_t alpm_trans_t; -/** @addtogroup alpm_api_errors Error Codes +/** @addtogroup alpm_api ALPM + * @brief The libalpm Public API + * @{ + */ + +/** @addtogroup alpm_errors Error Codes + * @brief The error codes used by libalpm * @{ */ + +/** libalpm's error type */ typedef enum _alpm_errno_t { + /** No error */ ALPM_ERR_OK = 0, + /** Failed to allocate memory */ ALPM_ERR_MEMORY, + /** A system error occurred */ ALPM_ERR_SYSTEM, + /** Permmision denied */ ALPM_ERR_BADPERMS, + /** Should be a file */ ALPM_ERR_NOT_A_FILE, + /** Should be a directory */ ALPM_ERR_NOT_A_DIR, + /** Function was called with invalid arguments */ ALPM_ERR_WRONG_ARGS, + /** Insufficient disk space */ ALPM_ERR_DISK_SPACE, /* Interface */ + /** Handle should be null */ ALPM_ERR_HANDLE_NULL, + /** Handle should not be null */ ALPM_ERR_HANDLE_NOT_NULL, + /** Failed to acquire lock */ ALPM_ERR_HANDLE_LOCK, /* Databases */ + /** Failed to open database */ ALPM_ERR_DB_OPEN, + /** Failed to create database */ ALPM_ERR_DB_CREATE, + /** Database should not be null */ ALPM_ERR_DB_NULL, + /** Database should be null */ ALPM_ERR_DB_NOT_NULL, + /** The database could not be found */ ALPM_ERR_DB_NOT_FOUND, + /** Database is invalid */ ALPM_ERR_DB_INVALID, + /** Database has an invalid signature */ ALPM_ERR_DB_INVALID_SIG, + /** The localdb is in a newer/older format than libalpm expects */ ALPM_ERR_DB_VERSION, + /** Fauked to write to the database */ ALPM_ERR_DB_WRITE, + /** Fauked to remove entry from database */ ALPM_ERR_DB_REMOVE, /* Servers */ + /** Server URL is in an invalid format */ ALPM_ERR_SERVER_BAD_URL, + /** The database has no configured servers */ ALPM_ERR_SERVER_NONE, /* Transactions */ + /** A transaction is already initialized */ ALPM_ERR_TRANS_NOT_NULL, + /** A transaction has not been initialized */ ALPM_ERR_TRANS_NULL, + /** Duplicate target in transaction */ ALPM_ERR_TRANS_DUP_TARGET, + /** A transaction has not been initialized */ ALPM_ERR_TRANS_NOT_INITIALIZED, + /** Transaction has not been prepared */ ALPM_ERR_TRANS_NOT_PREPARED, + /** Transaction was aborted */ ALPM_ERR_TRANS_ABORT, + /** Failed to interrupt transaction */ ALPM_ERR_TRANS_TYPE, + /** Transaction tried to commit without locking the database */ ALPM_ERR_TRANS_NOT_LOCKED, + /** A hook failed to run */ ALPM_ERR_TRANS_HOOK_FAILED, /* Packages */ + /** Package not found */ ALPM_ERR_PKG_NOT_FOUND, + /** Package is in ignorepkg */ ALPM_ERR_PKG_IGNORED, + /** Package is invalid */ ALPM_ERR_PKG_INVALID, + /** Package has an invalid checksum */ ALPM_ERR_PKG_INVALID_CHECKSUM, + /** Package has an invalid signature */ ALPM_ERR_PKG_INVALID_SIG, + /** Package does not have a signature */ ALPM_ERR_PKG_MISSING_SIG, + /** Cannot open the package file */ ALPM_ERR_PKG_OPEN, + /** Failed to remove package files */ ALPM_ERR_PKG_CANT_REMOVE, + /** Package has an invalid name */ ALPM_ERR_PKG_INVALID_NAME, + /** Package has an invalid architecute */ ALPM_ERR_PKG_INVALID_ARCH, + /** Unused */ ALPM_ERR_PKG_REPO_NOT_FOUND, /* Signatures */ + /** Signatues are missing */ ALPM_ERR_SIG_MISSING, + /** Signatures are invalid */ ALPM_ERR_SIG_INVALID, /* Dependencies */ + /** Dependencies could not be satisfied */ ALPM_ERR_UNSATISFIED_DEPS, + /** Conflicting dependencies */ ALPM_ERR_CONFLICTING_DEPS, + /** Files conflict. */ ALPM_ERR_FILE_CONFLICTS, /* Misc */ + /** Download failed */ ALPM_ERR_RETRIEVE, + /** Invalid Regex */ ALPM_ERR_INVALID_REGEX, /* External library errors */ + /** Error in libarchive */ ALPM_ERR_LIBARCHIVE, + /** Error in libcurl */ ALPM_ERR_LIBCURL, + /** Error in external download program */ ALPM_ERR_EXTERNAL_DOWNLOAD, + /** Error in gpgme */ ALPM_ERR_GPGME, - /* Missing compile-time features */ + /** Missing compile-time features */ ALPM_ERR_MISSING_CAPABILITY_SIGNATURES } alpm_errno_t; -/** Returns the current error code from the handle. */ +/** Returns the current error code from the handle. + * @param handle the context handle + * @return the current error code of the handle + */ alpm_errno_t alpm_errno(alpm_handle_t *handle); -/** Returns the string corresponding to an error number. */ +/** Returns the string corresponding to an error number. + * @param err the error code to get the string for + * @return the string relating to the given error code + */ const char *alpm_strerror(alpm_errno_t err); /* End of alpm_api_errors */ /** @} */ -/** @addtogroup alpm_api Public API - * The libalpm Public API +/** \addtogroup alpm_handle Handle + * @brief Functions to initialize and release libalpm * @{ */ -typedef int64_t alpm_time_t; - -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. +/** Initializes the library. + * Creates handle, connects to database and creates lockfile. + * This must be called before any other functions are called. + * @param root the root path for all filesystem operations + * @param dbpath the absolute path to the libalpm database + * @param err an optional variable to hold any error return codes + * @return a context handle on success, NULL on error, err will be set if provided */ +alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, + alpm_errno_t *err); -/** Package install reasons. */ -typedef enum _alpm_pkgreason_t { - /** Explicitly requested by the user. */ - ALPM_PKG_REASON_EXPLICIT = 0, - /** Installed as a dependency for another package. */ - ALPM_PKG_REASON_DEPEND = 1 -} alpm_pkgreason_t; +/** Release the library. + * Disconnects from the database, releases transaction, removes handle and lockfile + * This should be the last alpm call you make. + * After this returns, handle should be considered invalid and cannot be reused + * in any way. + * @param handle the context handle + * @return 0 on success, -1 on error + */ +int alpm_release(alpm_handle_t *handle); -/** Location a package object was loaded from. */ -typedef enum _alpm_pkgfrom_t { - ALPM_PKG_FROM_FILE = 1, - ALPM_PKG_FROM_LOCALDB, - ALPM_PKG_FROM_SYNCDB -} alpm_pkgfrom_t; +/** @} */ -/** Method used to validate a package. */ -typedef enum _alpm_pkgvalidation_t { - ALPM_PKG_VALIDATION_UNKNOWN = 0, - ALPM_PKG_VALIDATION_NONE = (1 << 0), - ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), - ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), - ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) -} alpm_pkgvalidation_t; -/** Types of version constraints in dependency specs. */ -typedef enum _alpm_depmod_t { - /** No version constraint */ - ALPM_DEP_MOD_ANY = 1, - /** Test version equality (package=x.y.z) */ - ALPM_DEP_MOD_EQ, - /** Test for at least a version (package>=x.y.z) */ - ALPM_DEP_MOD_GE, - /** Test for at most a version (package<=x.y.z) */ - ALPM_DEP_MOD_LE, - /** Test for greater than some version (package>x.y.z) */ - ALPM_DEP_MOD_GT, - /** Test for less than some version (package=x.y.z) */ + ALPM_DEP_MOD_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 (packagedata; * result = alpm_db_update(0, db); * * if(result < 0) { - * printf("Unable to update database: %s\n", alpm_strerrorlast()); + * printf("Unable to update database: %s\n", alpm_strerror(alpm_errno(handle))); * } else if(result == 1) { * printf("Database already up to date\n"); * } else { @@ -1031,7 +1784,7 @@ int alpm_db_remove_server(alpm_db_t *db, const char *url); * @endcode * * @note After a successful update, the \link alpm_db_get_pkgcache() - * package cache \endlink will be invalidated + * package cache and all packages within it \endlink will be invalidated * @param force if true, then forces the update, otherwise update only in case * the database isn't up to date * @param db pointer to the package database to update @@ -1053,6 +1806,19 @@ alpm_pkg_t *alpm_db_get_pkg(alpm_db_t *db, const char *name); */ alpm_list_t *alpm_db_get_pkgcache(alpm_db_t *db); +/* + * Groups + */ + +/** Find group members across a list of databases. + * If a member exists in several databases, only the first database is used. + * IgnorePkg is also handled. + * @param dbs the list of alpm_db_t * + * @param name the name of the group + * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free) + */ +alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); + /** Get a group entry from a package database. * @param db pointer to the package database to get the group from * @param name of the group @@ -1076,11 +1842,17 @@ alpm_list_t *alpm_db_get_groupcache(alpm_db_t *db); int alpm_db_search(alpm_db_t *db, const alpm_list_t *needles, alpm_list_t **ret); +/** The usage level of a database */ typedef enum _alpm_db_usage_t { + /** Enable refreshes for this database */ ALPM_DB_USAGE_SYNC = 1, + /** Enable search for this database */ ALPM_DB_USAGE_SEARCH = (1 << 1), + /** Enable installing packages from this database */ ALPM_DB_USAGE_INSTALL = (1 << 2), + /** Enable sysupgrades with this database */ ALPM_DB_USAGE_UPGRADE = (1 << 3), + /** Enable all usage levels */ ALPM_DB_USAGE_ALL = (1 << 4) - 1, } alpm_db_usage_t; @@ -1098,13 +1870,79 @@ int alpm_db_set_usage(alpm_db_t *db, int usage); */ int alpm_db_get_usage(alpm_db_t *db, int *usage); +/** Remove the database lock file + * @param handle the context handle + * @return 0 on success, -1 on error + * + * @note Safe to call from inside signal handlers. + */ +int alpm_unlock(alpm_handle_t *handle); + /** @} */ -/** @addtogroup alpm_api_packages Package Functions - * Functions to manipulate libalpm packages +/** @addtogroup alpm_packages Package + * @brief Functions to manipulate libalpm packages * @{ */ +/** Package install reasons. */ +typedef enum _alpm_pkgreason_t { + /** Explicitly requested by the user. */ + ALPM_PKG_REASON_EXPLICIT = 0, + /** Installed as a dependency for another package. */ + ALPM_PKG_REASON_DEPEND = 1 +} alpm_pkgreason_t; + +/** Location a package object was loaded from. */ +typedef enum _alpm_pkgfrom_t { + /** Loaded from a file via \link alpm_pkg_load \endlink */ + ALPM_PKG_FROM_FILE = 1, + /** From the local database */ + ALPM_PKG_FROM_LOCALDB, + /** From a sync database */ + ALPM_PKG_FROM_SYNCDB +} alpm_pkgfrom_t; + +/** Method used to validate a package. */ +typedef enum _alpm_pkgvalidation_t { + /** The package's validation type is unknown */ + ALPM_PKG_VALIDATION_UNKNOWN = 0, + /** The package does not have any validation */ + ALPM_PKG_VALIDATION_NONE = (1 << 0), + /** The package is validated with md5 */ + ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), + /** The package is validated with sha256 */ + ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), + /** The package is validated with a PGP signature */ + ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) +} alpm_pkgvalidation_t; + +/** File in a package */ +typedef struct _alpm_file_t { + /** Name of the file */ + char *name; + /** Size of the file */ + off_t size; + /** The file's permissions */ + mode_t mode; +} alpm_file_t; + +/** Package filelist container */ +typedef struct _alpm_filelist_t { + /** Amount of files in the array */ + size_t count; + /** An array of files */ + alpm_file_t *files; +} alpm_filelist_t; + +/** Local package or package file backup entry */ +typedef struct _alpm_backup_t { + /** Name of the file (without .pacsave extension) */ + char *name; + /** Hash of the filename (used internally) */ + char *hash; +} alpm_backup_t; + /** Create a package from a file. * If full is false, the archive is read only until all necessary * metadata is found. If it is true, the entire archive is read, which @@ -1130,6 +1968,9 @@ int alpm_pkg_load(alpm_handle_t *handle, const char *filename, int full, alpm_pkg_t *alpm_pkg_find(alpm_list_t *haystack, const char *needle); /** Free a package. + * + * Only packages loaded with \link alpm_pkg_load \endlink can be freed. + * Packages from databases will be freed by libalpm when they are unregistered. * @param pkg package pointer to free * @return 0 on success, -1 on error (pm_errno is set accordingly) */ @@ -1404,6 +2245,7 @@ size_t alpm_pkg_changelog_read(void *ptr, size_t size, /** Close a package changelog for reading. * @param pkg the package to close the changelog of (either file or db) + * @param fp the 'file stream' to the package changelog to close * @return 0 on success, -1 on error */ int alpm_pkg_changelog_close(const alpm_pkg_t *pkg, void *fp); @@ -1425,7 +2267,7 @@ int alpm_pkg_mtree_next(const alpm_pkg_t *pkg, struct archive *archive, /** Close a package mtree file. * @param pkg the local package to close the mtree of - * @param the archive to close + * @param archive the archive to close */ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive); @@ -1450,6 +2292,12 @@ off_t alpm_pkg_download_size(alpm_pkg_t *newpkg); */ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); +/** Fetch a remote pkg. + * @param handle the context handle + * @param url URL of the package to download + * @return the downloaded filepath on success, NULL on error + */ +char *alpm_fetch_pkgurl(alpm_handle_t *handle, const char *url); /* End of alpm_pkg */ /** @} */ @@ -1458,6 +2306,7 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); * Filelists */ + /** Determines whether a package filelist contains a given path. * The provided path should be relative to the install root with no leading * slashes, e.g. "etc/localtime". When searching for directories, the path must @@ -1468,68 +2317,6 @@ int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); */ alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char *path); -/* - * Signatures - */ - -/** - * Check the PGP signature for the given package file. - * @param pkg the package to check - * @param siglist a pointer to storage for signature results - * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) - */ -int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); - -/** - * Check the PGP signature for the given database. - * @param db the database to check - * @param siglist a pointer to storage for signature results - * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) - */ -int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); - -/** - * Clean up and free a signature result list. - * Note that this does not free the siglist object itself in case that - * was allocated on the stack; this is the responsibility of the caller. - * @param siglist a pointer to storage for signature results - * @return 0 on success, -1 on error - */ -int alpm_siglist_cleanup(alpm_siglist_t *siglist); - -/** - * Decode a loaded signature in base64 form. - * @param base64_data the signature to attempt to decode - * @param data the decoded data; must be freed by the caller - * @param data_len the length of the returned data - * @return 0 on success, -1 on failure to properly decode - */ -int alpm_decode_signature(const char *base64_data, - unsigned char **data, size_t *data_len); - -/** - * Extract the Issuer Key ID from a signature - * @param sig PGP signature - * @param len length of signature - * @param keys a pointer to storage for key IDs - * @return 0 on success, -1 on error - */ -int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, - const unsigned char *sig, const size_t len, alpm_list_t **keys); - -/* - * Groups - */ - -/** Find group members across a list of databases. - * If a member exists in several databases, only the first database is used. - * IgnorePkg is also handled. - * @param dbs the list of alpm_db_t * - * @param name the name of the group - * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free) - */ -alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); - /* * Sync */ @@ -1539,9 +2326,30 @@ alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name); */ alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync); -/** @addtogroup alpm_api_trans Transaction Functions - * Functions to manipulate libalpm transactions +/** @} */ + +/** @addtogroup alpm_trans Transaction + * @brief Functions to manipulate libalpm transactions + * + * Transactions are the way to add/remove packages to/from the system. + * + * Only one transaction can exist at a time. + * + * The basic workflow of a transaction is to: + * + * Initialize with \link alpm_trans_init \endlink + * + * Choose which packages to add with \link alpm_add_pkg \endlink and \link alpm_remove_pkg \endlink + * + * Prepare the transaction with \link alpm_trans_prepare \endlink + * + * Commit the transaction with \link alpm_trans_commit \endlink + * + * Release the transaction with \link alpm_trans_release \endlink + * + * A transaction can be released at any time. A transaction does not have to be committed. * @{ + * */ /** Transaction flags */ @@ -1587,6 +2395,29 @@ typedef enum _alpm_transflag_t { */ int alpm_trans_get_flags(alpm_handle_t *handle); +/** Search for packages to upgrade and add them to the transaction. + * @param handle the context handle + * @param enable_downgrade allow downgrading of packages if the remote version is lower + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ +int alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade); + +/** Add a package to the transaction. + * If the package was loaded by alpm_pkg_load(), it will be freed upon + * alpm_trans_release() invocation. + * @param handle the context handle + * @param pkg the package to add + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ +int alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); + +/** Add a package removal action to the transaction. + * @param handle the context handle + * @param pkg the package to uninstall + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ +int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); + /** Returns a list of packages added by the transaction. * @param handle the context handle * @return a list of alpm_pkg_t structures @@ -1635,36 +2466,8 @@ int alpm_trans_interrupt(alpm_handle_t *handle); int alpm_trans_release(alpm_handle_t *handle); /** @} */ -/** @name Common Transactions */ -/** @{ */ - -/** Search for packages to upgrade and add them to the transaction. - * @param handle the context handle - * @param enable_downgrade allow downgrading of packages if the remote version is lower - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ -int alpm_sync_sysupgrade(alpm_handle_t *handle, int enable_downgrade); - -/** Add a package to the transaction. - * If the package was loaded by alpm_pkg_load(), it will be freed upon - * alpm_trans_release() invocation. - * @param handle the context handle - * @param pkg the package to add - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ -int alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); - -/** Add a package removal action to the transaction. - * @param handle the context handle - * @param pkg the package to uninstall - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ -int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg); - -/** @} */ - -/** @addtogroup alpm_api_depends Dependency Functions - * Functions dealing with libalpm representation of dependency +/** @addtogroup alpm_depends Dependency + * @brief Functions dealing with libalpm representation of dependency * information. * @{ */ @@ -1731,99 +2534,124 @@ alpm_depend_t *alpm_dep_from_string(const char *depstring); */ void alpm_dep_free(alpm_depend_t *dep); -/** @} */ +/** + * Free a fileconflict and its members. + * @param conflict the fileconflict to free + */ +void alpm_fileconflict_free(alpm_fileconflict_t *conflict); -/** @} */ +/** + * Free a depmissing and its members. + * @param miss the depmissing to free + */ +void alpm_depmissing_free(alpm_depmissing_t *miss); -/* - * Helpers +/** + * Free a conflict and its members. + * @param conflict the conflict to free */ +void alpm_conflict_free(alpm_conflict_t *conflict); -/* checksums */ +/** @} */ -/** \addtogroup alpm_misc Miscellaneous Functions - * @brief Various libalpm functions +/** @addtogroup alpm_sig Signature checking + * @brief Functions to check signatures * @{ */ -/** Get the md5 sum of file. - * @param filename name of the file - * @return the checksum on success, NULL on error +/** + * Check the PGP signature for the given package file. + * @param pkg the package to check + * @param siglist a pointer to storage for signature results + * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ -char *alpm_compute_md5sum(const char *filename); +int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist); -/** Get the sha256 sum of file. - * @param filename name of the file - * @return the checksum on success, NULL on error +/** + * Check the PGP signature for the given database. + * @param db the database to check + * @param siglist a pointer to storage for signature results + * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ -char *alpm_compute_sha256sum(const char *filename); - -/** @} */ +int alpm_db_check_pgp_signature(alpm_db_t *db, alpm_siglist_t *siglist); -/** \addtogroup alpm_interface Interface Functions - * @brief Functions to initialize and release libalpm - * @{ +/** + * Clean up and free a signature result list. + * Note that this does not free the siglist object itself in case that + * was allocated on the stack; this is the responsibility of the caller. + * @param siglist a pointer to storage for signature results + * @return 0 on success, -1 on error */ +int alpm_siglist_cleanup(alpm_siglist_t *siglist); -/** Initializes the library. - * Creates handle, connects to database and creates lockfile. - * This must be called before any other functions are called. - * @param root the root path for all filesystem operations - * @param dbpath the absolute path to the libalpm database - * @param err an optional variable to hold any error return codes - * @return a context handle on success, NULL on error, err will be set if provided +/** + * Decode a loaded signature in base64 form. + * @param base64_data the signature to attempt to decode + * @param data the decoded data; must be freed by the caller + * @param data_len the length of the returned data + * @return 0 on success, -1 on failure to properly decode */ -alpm_handle_t *alpm_initialize(const char *root, const char *dbpath, - alpm_errno_t *err); +int alpm_decode_signature(const char *base64_data, + unsigned char **data, size_t *data_len); -/** Release the library. - * Disconnects from the database, removes handle and lockfile - * This should be the last alpm call you make. - * After this returns, handle should be considered invalid and cannot be reused - * in any way. - * @param myhandle the context handle +/** + * Extract the Issuer Key ID from a signature + * @param handle the context handle + * @param identifier the key's identifier + * @param sig PGP signature + * @param len length of signature + * @param keys a pointer to storage for key IDs * @return 0 on success, -1 on error */ -int alpm_release(alpm_handle_t *handle); +int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier, + const unsigned char *sig, const size_t len, alpm_list_t **keys); /** @} */ -/** Remove the database lock file - * @param handle the context handle - * @return 0 on success, -1 on error - * - * @note Safe to call from inside signal handlers. +/** \addtogroup alpm_misc Miscellaneous + * @brief Various libalpm functions + * @{ */ -int alpm_unlock(alpm_handle_t *handle); +/* + * Helpers + */ + +/* checksums */ + +/** Get the md5 sum of file. + * @param filename name of the file + * @return the checksum on success, NULL on error + */ +char *alpm_compute_md5sum(const char *filename); + +/** Get the sha256 sum of file. + * @param filename name of the file + * @return the checksum on success, NULL on error + */ +char *alpm_compute_sha256sum(const char *filename); + +/** Enum of possible compile time features */ enum alpm_caps { + /** localization */ ALPM_CAPABILITY_NLS = (1 << 0), + /** Ability to download */ ALPM_CAPABILITY_DOWNLOADER = (1 << 1), + /** Signature checking */ ALPM_CAPABILITY_SIGNATURES = (1 << 2) }; /** Get the version of library. * @return the library version, e.g. "6.0.4" - * */ + */ const char *alpm_version(void); /** Get the capabilities of the library. * @return a bitmask of the capabilities - * */ -int alpm_capabilities(void); - -/** - * Free a fileconflict and its members. - * @param conflict the fileconflict to free */ -void alpm_fileconflict_free(alpm_fileconflict_t *conflict); -void alpm_depmissing_free(alpm_depmissing_t *miss); +int alpm_capabilities(void); -/** - * Free a conflict and its members. - * @param conflict the conflict to free - */ -void alpm_conflict_free(alpm_conflict_t *conflict); +/** @} */ /* End of alpm_api */ /** @} */ diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h index 4e18f36c..c9bfcf9d 100644 --- a/lib/libalpm/alpm_list.h +++ b/lib/libalpm/alpm_list.h @@ -17,6 +17,13 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ + +/** + * @file alpm_list.h + * @author Pacman Development Team + * @date 26 Jan 2020 + * @brief A doubly linked list for use with libalpm + */ #ifndef ALPM_LIST_H #define ALPM_LIST_H @@ -30,13 +37,16 @@ extern "C" { #endif -/** - * @brief Linked list type used by libalpm. +/** \addtogroup alpm_list ALPM List + * + * @brief A doubly linked list for use with libalpm * * It is exposed so front ends can use it to prevent the need to reimplement * lists of their own; however, it is not required that the front end uses * it. */ + + typedef struct __alpm_list_t { /** data held by the list node */ void *data; diff --git a/lib/libalpm/version.c b/lib/libalpm/version.c index ae220ff6..27df0508 100644 --- a/lib/libalpm/version.c +++ b/lib/libalpm/version.c @@ -202,7 +202,7 @@ static int rpmvercmp(const char *a, const char *b) * - if one is empty and two is not an alpha, two is newer. * - if one is an alpha, two is newer. * - otherwise one is newer. - * */ + */ if ( (!*one && !isalpha((int)*two)) || isalpha((int)*one) ) { ret = -1;