From patchwork Mon Dec 7 22:19:43 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1815 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 8596C1C996DA9 for ; Mon, 7 Dec 2020 22:31:38 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on apollo.archlinux.org X-Spam-Level: X-Spam-Status: No, score=-1.1 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,SPF_HELO_PASS=-0.001,T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.4 X-Spam-BL-Results: Received: from mail.archlinux.org (mail.archlinux.org [IPv6:2a01:4f9:c010:3052::1]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Mon, 7 Dec 2020 22:31:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1607379736; bh=ZMN3m1PRnTRqqzlqf9UDp6onnraHtZSQLJuwNmAmu7A=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=sKgdukVMN95UoKwlk/d/+PoXIo/lQtYydDnpKziSZTTOv78hH01fRwbbyYI8/Muek 5FtxCMVRvBP7I9i7a5XqnfyrEnzhEvRSWj9MZjySQFqgagNVOXhO4prDdArY/B2M6X AYYkcIMtkH2G7Q/WWyL6dxVMcHFiSOynJ+4bFsFaTru8YlX2XlmRqSVjMO53RFQKYT kAqEHRIrkeUnU2uSF8QOFh/qwiQGtpZES7xniw2izt7shIRSX0GfdqkDikxsweoMpo tiYYl7nmq0PnEVMSxDQM3mhj+ivQ1yBvT1ogkefjJ1oGjrEznQFPrHZARvbWFaJw46 Slkt4CaXNLvmcsxyJ/xXuW2xA2h6pV89viCUkJivd+ukiY5wj6cj0cX/Bwoloxjzow RV81jyn5ucj4Qt9fMC6Wh9pEE6uxRLsnEGxyeAh/Vu9lYAQtje14P4ilwH+Khg/1W0 VqUE2wijVvi2Jn0kwLUGvKtdhsD6h8SyYASxEfNZo3+nUVIoi4nG9uTiyqmPKlY9El /Ru/Qz4674eTOtPxoa7p682YOTAFyE3OIu3oXoBhYKgvhszmvFeriaWyPo4SOLOg+Y sRH8pNBjW3FF/EvGEYztTNxIvkhngHNQB6AyKK7J/1PytzjoqT4+vlFHogdKhvgi4c ujAAwfVvCLWq/vxfBXCAiVP4= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607380288; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Hi6QdxO85VxhypBoMgFzVsJJt3lbQXiFGx4Sh3Ou6Dc=; b=adYqqstG7YRvtqHcv2iA0vLwE1eQFb7f2MSZmggTEuJ5+S/40ek8bV9gVYfZwuvN0gdn5+ P0qQBV3wHli8latH5gdSrk2eFGD1vJxpUYIfaMHLmqvcSJyb/kovUPInsSErVFdZ6CVf6S +SbUJd4EtcSyMi9knRvRYPnSGBSiV9Xa70AadCSiVB7G+G1SfJfH3uUZy13//sg/YMGPQh gJviKXoVoM84+1JAPJR3anY6HCtCDgpFu8ovTYvvEUzSBwKCZRW+6yMdGjVHnX4jhVIGCZ bV9kdFacknUlYlCPPQyTBTtpmMgTpMU8wgHfVg3FLBlx6VlY5ldPQw/wTyF27cC8A7wnxf Bfhve1mX5M4BjCO8PGITEmg6yZ94/8eh6OTleqEEt78sauzFZwnoKZiIZbsvhu+pX8kBIu 9VsT9vxp6jUYODOuzJ771imStkJ33nDiC7Sq/Q54TBcv7dz9Q2TsIFvOdpM531ILI3q4Wo Vy51DHz1W7fy1vXbIWvVOwtbahlluZnTPkSX3fm+NgV5uz3WwygocicFFUMnEoNy8kVzU/ qoq31PNBj4TdygNlO1hZZtjNmVn4NsmlOG+XstRJEivBWV+w81TrW3gcfE/IHEN2f0T+Si yL8lm/iEeHKK9Fes6xXBccfyrkHaZVw2e7fLC67YpiDuUMJEiXoDc= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607380288; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Hi6QdxO85VxhypBoMgFzVsJJt3lbQXiFGx4Sh3Ou6Dc=; b=cI3w6v2SjabGxeZ6j69nFi8Mzyq1QoyTOrP6A9IaJvRF+mGS1ZAtiDtHIFjr6Cbs9OWq4C eyuxllMlKAwq9uBg== From: morganamilo DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607379731; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Hi6QdxO85VxhypBoMgFzVsJJt3lbQXiFGx4Sh3Ou6Dc=; b=Pqcn3yjDtfnr4lNSO9JmXQk66mgjZFacyq/sIBw7wtpuRPxB2YpkN2P+d6wPZVQZZHngRH UNrSXjM68HQOgA93pbdDlA+6wuZKdH+EJ4FlHAflsQMIUfUwfgK2yYpouA768Wl+MuTEla dnFBj81pyMaDroaGJRfvWIRg2S7+qlEf1SRSTBLJjsIS9D5i4OQqRtm/P79LsWNY5xJizX hF0WT8p/xrlto4gDug1GW4BDxfChGHNMWMnfnGm0soSGZGfF6V0fZWl6+4PW/hnVWFOiBb 8jGF9PrhrwjAf4lxNjHgMPY222712yfSnO2JQk4nma4YwQZbv2+s/++dHbblHg66gIzOuR V4SyuJw6MXAQjTINIdNr2Ef5ZO6zokm/7Bv7x4Mt5PcFPy0XiIQfWscSJRvbPcF+Jjju0l to6jGytmNLWLIg79kJB4bDy+Tr302jPspuEQk/CKVyhzB0s+obtHu2P3NkniCpWb0edif4 qLPys//ccgXTrtI+KZhYv0GbbK/ayoCLNAC6udikiVKIrt77lF/POLDyiHctJrxoSczQhR HZTjrFeqeZDmly4lIpfyKcvlt6yKPI667haauwAgsUs9CeoEVXFYEdoLaR1r1fbOkBdiE7 Q88L7+inWjJIK1D1u0Qn86ZEFA8+MKgtdDmRq5T9UJ+2kDcbiXAC0= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607379731; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Hi6QdxO85VxhypBoMgFzVsJJt3lbQXiFGx4Sh3Ou6Dc=; b=zEg144prYp1r8APzzR5RYUGqYZOVfEB/dzob/kKzs/Z3frl5FoPitlsDpi7VbqoI51sGgO q+Hr7Q/gKO+gUEDQ== To: pacman-dev@archlinux.org Date: Mon, 7 Dec 2020 22:19:43 +0000 Message-Id: <20201207221956.667322-11-morganamilo@archlinux.org> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20201207221956.667322-1-morganamilo@archlinux.org> References: <20201207221956.667322-1-morganamilo@archlinux.org> MIME-Version: 1.0 Subject: [pacman-dev] [PATCH 10/23] doc: document packages X-BeenThere: pacman-dev@archlinux.org X-Mailman-Version: 2.1.34 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" Authentication-Results: mail.archlinux.org; auth=pass smtp.auth=luna smtp.mailfrom=pacman-dev-bounces@archlinux.org --- lib/libalpm/alpm.h | 164 ++++++++++++++++++++++++++------------------- 1 file changed, 96 insertions(+), 68 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index ea690abc..5ee99711 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -1368,43 +1368,11 @@ int alpm_db_get_usage(alpm_db_t *db, int *usage); /* End of usage accessors */ /** @} */ + /* End of alpm_databases */ /** @} */ -/* - * Enumerations - * These ones are used in multiple contexts, so are forward-declared. - */ - -/** Package install reasons. */ -typedef enum _alpm_pkgreason_t { - /** Explicitly requested by the user. */ - ALPM_PKG_REASON_EXPLICIT = 0, - /** Installed as a dependency for another package. */ - ALPM_PKG_REASON_DEPEND = 1 -} alpm_pkgreason_t; - -/** Location a package object was loaded from. */ -typedef enum _alpm_pkgfrom_t { - ALPM_PKG_FROM_FILE = 1, - ALPM_PKG_FROM_LOCALDB, - ALPM_PKG_FROM_SYNCDB -} alpm_pkgfrom_t; - -/** Method used to validate a package. */ -typedef enum _alpm_pkgvalidation_t { - ALPM_PKG_VALIDATION_UNKNOWN = 0, - ALPM_PKG_VALIDATION_NONE = (1 << 0), - ALPM_PKG_VALIDATION_MD5SUM = (1 << 1), - ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2), - ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3) -} alpm_pkgvalidation_t; - -/* - * Logging facilities - */ - /** \addtogroup alpm_log Logging Functions * @brief Functions to log using libalpm * @{ @@ -1446,17 +1414,6 @@ int alpm_logaction(alpm_handle_t *handle, const char *prefix, /* End of alpm_log */ /** @} */ -/** Fetch a list of remote packages. - * @param handle the context handle - * @param urls list of package URLs to download - * @param fetched list of filepaths to the fetched packages, each item - * corresponds to one in `urls` list. This is an output parameter, - * the caller should provide a pointer to an empty list - * (*fetched === NULL) and the callee fills the list with data. - * @return 0 on success or -1 on failure - */ -int alpm_fetch_pkgurl(alpm_handle_t *handle, const alpm_list_t *urls, - alpm_list_t **fetched); /** @addtogroup alpm_api_options Options * Libalpm option getters and setters @@ -1638,11 +1595,44 @@ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_s /** @} */ -/** @addtogroup alpm_api_packages Package Functions +/** @addtogroup alpm_packages Package Functions * 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; + /** 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 @@ -1660,6 +1650,18 @@ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_s int alpm_pkg_load(alpm_handle_t *handle, const char *filename, int full, int level, alpm_pkg_t **pkg); +/** Fetch a list of remote packages. + * @param handle the context handle + * @param urls list of package URLs to download + * @param fetched list of filepaths to the fetched packages, each item + * corresponds to one in `urls` list. This is an output parameter, + * the caller should provide a pointer to an empty list + * (*fetched === NULL) and the callee fills the list with data. + * @return 0 on success or -1 on failure + */ +int alpm_fetch_pkgurl(alpm_handle_t *handle, const alpm_list_t *urls, + alpm_list_t **fetched); + /** Find a package in a list by name. * @param haystack a list of alpm_pkg_t * @param needle the package name @@ -1668,6 +1670,8 @@ 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) */ @@ -1724,6 +1728,9 @@ int alpm_pkg_should_ignore(alpm_handle_t *handle, alpm_pkg_t *pkg); * Any pointer returned by these functions points to internal structures * allocated by libalpm. They should not be freed nor modified in any * way. + * + * For loaded packages, they will be freed when \link alpm_pkg_free \endlink is called. + * For database packages, they will be freed when the database is unregistered. * @{ */ @@ -1927,8 +1934,36 @@ int alpm_pkg_get_sig(alpm_pkg_t *pkg, unsigned char **sig, size_t *sig_len); */ int alpm_pkg_get_validation(alpm_pkg_t *pkg); +/** Returns whether the package has an install scriptlet. + * @return 0 if FALSE, TRUE otherwise + */ +int alpm_pkg_has_scriptlet(alpm_pkg_t *pkg); + +/** 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 alpm_pkg_download_size(alpm_pkg_t *newpkg); + +/** Set install reason for a package in the local database. + * The provided package object must be from the local database or this method + * will fail. The write to the local database is performed immediately. + * @param pkg the package to update + * @param reason the new install reason + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ +int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); + + /* End of alpm_pkg_t accessors */ -/* @} */ +/** @} */ + + +/** @name Changelog functions + * Functions for reading the changelog + * @{ + */ /** Open a package changelog for reading. * Similar to fopen in functionality, except that the returned 'file @@ -1953,10 +1988,20 @@ 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); +/* End of changelog accessors */ +/** @} */ + + +/** @name Mtree functions + * Functions for reading the mtree + * @{ + */ + /** Open a package mtree file for reading. * @param pkg the local package to read the mtree of * @return an archive structure for the package mtree file @@ -1974,35 +2019,18 @@ 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); -/** Returns whether the package has an install scriptlet. - * @return 0 if FALSE, TRUE otherwise - */ -int alpm_pkg_has_scriptlet(alpm_pkg_t *pkg); - -/** 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 alpm_pkg_download_size(alpm_pkg_t *newpkg); - -/** Set install reason for a package in the local database. - * The provided package object must be from the local database or this method - * will fail. The write to the local database is performed immediately. - * @param pkg the package to update - * @param reason the new install reason - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ -int alpm_pkg_set_reason(alpm_pkg_t *pkg, alpm_pkgreason_t reason); +/* End of mtree accessors */ +/** @} */ -/* End of alpm_pkg */ +/* End of alpm_packages */ /** @} */ + /* * Filelists */