From patchwork Mon Dec 7 22:19:36 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: morganamilo X-Patchwork-Id: 1812 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 6C2911C996712 for ; Mon, 7 Dec 2020 22:22:24 +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,RCVD_IN_MSPIKE_H4=-0.01,RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_PASS=-0.001,T_DMARC_POLICY_NONE=0.01 autolearn=ham autolearn_force=no version=3.4.4 X-Spam-BL-Results: [127.0.0.19] Received: from mail.archlinux.org (mail.archlinux.org [95.216.189.61]) by apollo.archlinux.org (Postfix) with ESMTPS for ; Mon, 7 Dec 2020 22:22:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=archlinux.org; s=luna2; t=1607379728; bh=Fu2M/Kj/5AsDGRc0Mb5JIfPTYLC9aeO6epNLxyQ4q14=; h=From:To:Date:In-Reply-To:References:Subject:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: Reply-To; b=K+0PoBvlkq6Z95DUIqR5kyCU/ogSY2GvU/9g3d2hLhzd7QGjzFjZ+X2ItD/AePm5Y 3siRJ0KI+CKnJlO/ro00nfb6XuaFQuVvCQpl59JEyrUAl0gujcX4zEdmOE01KMsU/z l7BztI6mIgwAeWbfwNeW2mEl6SqBtS7oiY//M4fCHw9LzdKy7VuJp5lYv+PEb7TWZk 64hTJt3PAJOlwnSn+6/d3/SXCRjaeM2isI6N6J+JvkmToW5t3Tv3SQHpuKe2MwfQTP zU51ATD/laAZ0AE5C9YapIkJlAgYLHhNcG8ARGUWafQ8Jztwi81FncjuKGBSMkJgIK BDALoEajl6eyf9dwaciEt10s7Q4zEGnXpRGbc2FFseqvRedd/vPHPjKDbAnzkPUegJ ipk/K2/o/8bvI/WtOErxcce3dQZOo9+QrLBSfGOXeE99WadrS6ZUuT8XeBzLQbxy1g B+sMCMOTSjbnrY608r9HV0nhfvFTEa12+v9MrGF1JqgEY0FWYZYsQic95d3Bfvzroa LH7v8M262T47tICq6kr8BzN8Qrf/Qvqg3ypfj28rzI8/ob6N4VvjB2HhLUSsOKiUOA i49ehUJ7zB05fqOY55I+ZvdvkFwqaPN/XmNNi08VB1EahXWZJLQIIfpXhfOJvqOs8s hJD/842TTdkGQgXqW4SBxLKc= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607379730; 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=x9K+fEjMABNWEC0XNIvj8xE5reYj0gBbe9qH0gQVTh4=; b=z5corx2G0uZorqqg3h5jio16eVW+4CX5HFFZgiyclbQWnDi6NB6GNwiLFCQQAh7Jq/N6CF 9lk6welRiFoQd1kLqG5Fs6NCVziKuxs7GZ+5fhv2p22fLe7NyeHz2W+/FM2ipflxpA1h1h w+1vWUVyEht7vZFsDRAO+62/VXAtlJB71/75cgJzq2MIY4JeNuhV01q0pe17JOlTQYift6 FsLfz3kyU0XFQxBGNw3zm7WB8NbZ7ylhCs1YNfQehkqUSzZ1ws3DuYkyPCIX8vPv2QxSsS LplYqKFky+6c8NW38TA4LLrqkScFEZ+v7qAJtqEbGgom4ahrJOdIMiD08/pFChn3aNJGeq QvXjkQeZyNR6cJln1QQH7CaE7HBC6HvJ3sFeHxXYxN6qOXq+2JCTf8tei9PiPBZe4BtKIm 7KS7EH50mMiIPynMv15+gAXpDOQ2RguOHVSYb09qnbsW34/VMjszN6dxLwAZWfioAUo60T Q69gl/iiQFgT/zFG8tj5l60oYXyewTXpxKfnNIHkzRtj1tRb8O3F37vAVeFtK2JAcmMjxV 04XaPgD4jkOYX28t8oVuAgQNUDeKcYNkdTYBvJCr4AYb4pNaji9ExDXK3MpHX6Pr6Z9+c0 osB3wvB4udbgfrqjgZLya46YT4DWeY+UIGT3/U8AhGZwOIASe/no8= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607379730; 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=x9K+fEjMABNWEC0XNIvj8xE5reYj0gBbe9qH0gQVTh4=; b=jkuiP/XqiHgcgqEWg0rEqETUZ5O492BOYSFzYMuyZ4xHskgCw61XolEcuWxkA4agAMlfLJ 5RRmGBxJ2WFfMvAA== From: morganamilo DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-rsa; t=1607379724; 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=x9K+fEjMABNWEC0XNIvj8xE5reYj0gBbe9qH0gQVTh4=; b=SnSRWQHHtyjdMri88lFSVED+XvW+Ymp5pU4spw71OO2E/GVS2jfZyraBI5gtXerJald85V q1OmB0k5knthDw7qEKn9oL/fjKHl0AQvZi2J694Rx/KTkSueOFb9lvx/QBmyx3d5ZF/WWS mDyRbTV6OOFAyZAgKkkk/oBhJ9ht1dv2ZRcZMaKyCe2crXn/3rAEwJry9LGitRTNa+XorE 4ShkHNJ/MWW2MHThM8uuO1lBDWa4fVvqIGgjRH9oLZp2qfakcEaKrJYKUfEDiuPG74j7In 3t0MT+XtGeMAEXoxUAVfcU5+JEKKijcx9qFPzVyYrt1623gxe5hIt5khXzyhXShtunvtxe wp3koWaeug++G8yacnW2DDp2IfMYSFMwR3U88HfWbgyXs8JJYY6UFzwQZxbBbZ6Vf6aMCR iGijroVRBIeHlGjjbed6vjpo0TwLseDE5sapSFXlruLgkPJDXL6nzS2f4wLI8rAtTkKdbI quFCl3ZVUWcTbfh0MSYAGQpc3nYZ7bkRCNBIefKapKgNd6Y5VPDQWXMoHu/DTqO9JtpMDc 9TbnbxtItRRmF4QrY2YzaSyq93weTxWjjd5eTNNgmtSndxZ7UyIdhe1eSOywRWREHvT0ZV W2fl0s7okZnmdryUREbma9t9WHxp6qKLtPeIpKYPO6mW3Vh6YhpIY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=archlinux.org; s=dkim-ed25519; t=1607379724; 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=x9K+fEjMABNWEC0XNIvj8xE5reYj0gBbe9qH0gQVTh4=; b=WcEonef1JYO7XEZnsnIyy2n0FdmpQ9Wyfv6ZwIkQ7ra7TVlhXwyz+p68xauLjeZ7OmKn6f 5KkT9cYhGSOiBxAw== To: pacman-dev@archlinux.org Date: Mon, 7 Dec 2020 22:19:36 +0000 Message-Id: <20201207221956.667322-4-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 03/23] doc: document error 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 | 122 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 109 insertions(+), 13 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 48ba7fdc..1c2422ca 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -51,102 +51,198 @@ 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 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 + * Error codes returned 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, + /** Failed to write to the database */ ALPM_ERR_DB_WRITE, + /** Failed 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, + /** Tried to commit transaction 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 */ +/* End of alpm_errors */ /** @} */ -/** @addtogroup alpm_api Public API - * The libalpm Public API - * @{ - */ - typedef int64_t alpm_time_t; /*