/*- * Copyright (c) 2008-2013 Juan Romero Pardines. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *- */ #ifndef _XBPS_API_H_ #define _XBPS_API_H_ #include #include #include #include #include #include /** * @file include/xbps_api.h * @brief XBPS Library API header * * This header documents the full API for the XBPS Library. */ /** * @def XBPS_PKGINDEX_VERSION * Current version for the repository package index format. */ #define XBPS_PKGINDEX_VERSION "1.7" #define XBPS_API_VERSION "20130310" #ifndef XBPS_VERSION #define XBPS_VERSION "UNSET" #endif #ifndef XBPS_GIT #define XBPS_GIT "UNSET" #endif /** * @def XBPS_RELVER * Current library release date. */ #define XBPS_RELVER "XBPS: " XBPS_VERSION \ " API: " XBPS_API_VERSION \ " INDEX: " XBPS_PKGINDEX_VERSION \ " GIT: " XBPS_GIT /** * @def XBPS_META_PATH * Default root PATH to store metadata info. */ #define XBPS_META_PATH "var/db/xbps" /** * @def XBPS_CACHE_PATH * Default cache PATH to store downloaded binpkgs. */ #define XBPS_CACHE_PATH "var/cache/xbps" /** * @def XBPS_PKGDB * Filename for the package database. */ #define XBPS_PKGDB "pkgdb-0.21.plist" /** * @def XBPS_PKGPROPS * Filename for package metadata property list. */ #define XBPS_PKGPROPS "props.plist" /** * @def XBPS_PKGFILES * Filename for package metadata files property list. */ #define XBPS_PKGFILES "files.plist" /** * @def XBPS_PKGINDEX * Filename for the repository package index property list. */ #define XBPS_PKGINDEX "index-" XBPS_PKGINDEX_VERSION ".plist" /** * @def XBPS_PKGINDEX_FILES * Filename for the repository package index files property list. */ #define XBPS_PKGINDEX_FILES "index-files.plist" /** * @def XBPS_SYSCONF_PATH * Default configuration PATH to find XBPS_CONF_PLIST. */ #define XBPS_SYSDIR "/xbps" #ifndef XBPS_SYSCONF_PATH #define XBPS_SYSCONF_PATH "/etc" XBPS_SYSDIR #endif /** * @def XBPS_CONF_DEF * Filename for the XBPS plist configuration file. */ #define XBPS_CONF_DEF XBPS_SYSCONF_PATH "/xbps.conf" /** * @def XBPS_FLAG_VERBOSE * Verbose flag that can be used in the function callbacks to alter * its behaviour. Must be set through the xbps_handle::flags member. */ #define XBPS_FLAG_VERBOSE 0x00000001 /** * @def XBPS_FLAG_FORCE_CONFIGURE * Force flag used in xbps_configure_pkg(), if set the package(s) * will be reconfigured even if its state is XBPS_PKG_STATE_INSTALLED. * Must be set through the xbps_handle::flags member. */ #define XBPS_FLAG_FORCE_CONFIGURE 0x00000002 /** * @def XBPS_FLAG_FORCE_REMOVE_FILES * Force flag used in xbps_remove_pkg_files(), if set the package * files will be removed even if its SHA256 hash don't match. * Must be set through the xbps_handle::flags member. */ #define XBPS_FLAG_FORCE_REMOVE_FILES 0x00000004 /** * @def XBPS_FLAG_SYSLOG * Enable syslog logging flag. To make clients aware that syslog * will be used. */ #define XBPS_FLAG_SYSLOG 0x00000008 /** * @def XBPS_FLAG_INSTALL_AUTO * Enabled automatic install mode for a package and all dependencies * installed direct and indirectly. */ #define XBPS_FLAG_INSTALL_AUTO 0x00000010 /** * @def XBPS_FLAG_DEBUG * Enable debug mode to output debugging printfs to stdout/stderr. */ #define XBPS_FLAG_DEBUG 0x00000020 /** * @def XBPS_FLAG_FORCE_UNPACK * Force flag used in xbps_unpack_binary_pkg(). If set its package * files will be unpacked overwritting the current ones. * Must be set through the xbps_handle::flags member. */ #define XBPS_FLAG_FORCE_UNPACK 0x00000040 /** * @def XBPS_FETCH_CACHECONN * Default (global) limit of cached connections used in libfetch. */ #define XBPS_FETCH_CACHECONN 6 /** * @def XBPS_FETCH_CACHECONN_HOST * Default (per host) limit of cached connections used in libfetch. */ #define XBPS_FETCH_CACHECONN_HOST 2 /** * @def XBPS_FETCH_TIMEOUT * Default timeout limit (in seconds) to wait for stalled connections. */ #define XBPS_FETCH_TIMEOUT 30 #ifdef __cplusplus extern "C" { #endif /** @addtogroup initend */ /*@{*/ /** * @enum xbps_state_t * * Integer representing the xbps callback returned state. Possible values: * * - XBPS_STATE_UKKNOWN: state hasn't been prepared or unknown error. * - XBPS_STATE_TRANS_DOWNLOAD: transaction is downloading binary packages. * - XBPS_STATE_TRANS_VERIFY: transaction is verifying binary package integrity. * - XBPS_STATE_TRANS_RUN: transaction is performing operations: * install, update, remove and replace. * - XBPS_STATE_TRANS_CONFIGURE: transaction is configuring all * unpacked packages. * - XBPS_STATE_DOWNLOAD: a binary package is being downloaded. * - XBPS_STATE_VERIFY: a binary package is being verified. * - XBPS_STATE_REMOVE: a package is being removed. * - XBPS_STATE_REMOVE_DONE: a package has been removed successfully. * - XBPS_STATE_REMOVE_FILE: a package file is being removed. * - XBPS_STATE_REMOVE_OBSOLETE: an obsolete package file is being removed. * - XBPS_STATE_REPLACE: a package is being replaced. * - XBPS_STATE_INSTALL: a package is being installed. * - XBPS_STATE_INSTALL_DONE: a package has been installed successfully. * - XBPS_STATE_UPDATE: a package is being updated. * - XBPS_STATE_UPDATE_DONE: a package has been updated successfully. * - XBPS_STATE_UNPACK: a package is being unpacked. * - XBPS_STATE_CONFIGURE: a package is being configured. * - XBPS_STATE_CONFIGURE_DONE: a package has been configured successfully. * - XBPS_STATE_CONFIG_FILE: a package configuration file is being processed. * - XBPS_STATE_REPOSYNC: a remote repository's package index is being * synchronized. * - XBPS_STATE_VERIFY_FAIL: binary package integrity has failed. * - XBPS_STATE_DOWNLOAD_FAIL: binary package download has failed. * - XBPS_STATE_REMOVE_FAIL: a package removal has failed. * - XBPS_STATE_REMOVE_FILE_FAIL: a package file removal has failed. * - XBPS_STATE_REMOVE_FILE_HASH_FAIL: a package file removal due to * its hash has failed. * - XBPS_STATE_REMOVE_FILE_OBSOLETE_FAIL: an obsolete package file * removal has failed. * - XBPS_STATE_CONFIGURE_FAIL: package configure has failed. * - XBPS_STATE_CONFIG_FILE_FAIL: package configuration file operation * has failed. * - XBPS_STATE_UPDATE_FAIL: package update has failed. * - XBPS_STATE_UNPACK_FAIL: package unpack has failed. * - XBPS_STATE_REPOSYNC_FAIL: syncing remote repositories has failed. */ typedef enum xbps_state { XBPS_STATE_UNKNOWN = 0, XBPS_STATE_TRANS_DOWNLOAD, XBPS_STATE_TRANS_VERIFY, XBPS_STATE_TRANS_RUN, XBPS_STATE_TRANS_CONFIGURE, XBPS_STATE_DOWNLOAD, XBPS_STATE_VERIFY, XBPS_STATE_REMOVE, XBPS_STATE_REMOVE_DONE, XBPS_STATE_REMOVE_FILE, XBPS_STATE_REMOVE_FILE_OBSOLETE, XBPS_STATE_PURGE, XBPS_STATE_PURGE_DONE, XBPS_STATE_REPLACE, XBPS_STATE_INSTALL, XBPS_STATE_INSTALL_DONE, XBPS_STATE_UPDATE, XBPS_STATE_UPDATE_DONE, XBPS_STATE_UNPACK, XBPS_STATE_CONFIGURE, XBPS_STATE_CONFIG_FILE, XBPS_STATE_REPOSYNC, XBPS_STATE_VERIFY_FAIL, XBPS_STATE_DOWNLOAD_FAIL, XBPS_STATE_REMOVE_FAIL, XBPS_STATE_REMOVE_FILE_FAIL, XBPS_STATE_REMOVE_FILE_HASH_FAIL, XBPS_STATE_REMOVE_FILE_OBSOLETE_FAIL, XBPS_STATE_PURGE_FAIL, XBPS_STATE_CONFIGURE_FAIL, XBPS_STATE_CONFIG_FILE_FAIL, XBPS_STATE_UPDATE_FAIL, XBPS_STATE_UNPACK_FAIL, XBPS_STATE_REPOSYNC_FAIL, XBPS_STATE_CONFIGURE_DONE } xbps_state_t; /** * @struct xbps_state_cb_data xbps_api.h "xbps_api.h" * @brief Structure to be passed as argument to the state function callback. * All members are read-only and set internally by libxbps. */ struct xbps_state_cb_data { /** * @var xhp * * Pointer to our struct xbps_handle passed to xbps_init(). */ struct xbps_handle *xhp; /** * @var state * * Current state. */ xbps_state_t state; /** * @var desc * * Current state string description. */ const char *desc; /** * @var arg * * State string argument. String set on this * variable may change depending on \a state. */ const char *arg; /** * @var err * * Current state error value (set internally, read-only). */ int err; }; /** * @struct xbps_fetch_cb_data xbps_api.h "xbps_api.h" * @brief Structure to be passed to the fetch function callback. * * This structure is passed as argument to the fetch progress function * callback and its members will be updated when there's any progress. * All members marked as read-only in this struct are set internally by * xbps_unpack_binary_pkg() and shouldn't be modified in the passed * function callback. */ struct xbps_fetch_cb_data { /** * @var xhp * * Pointer to our struct xbps_handle passed to xbps_init(). */ struct xbps_handle *xhp; /** * @var file_size * * Filename size for the file to be fetched. */ off_t file_size; /** * @var file_offset * * Current offset for the filename being fetched. */ off_t file_offset; /** * @var file_dloaded * * Bytes downloaded for the file being fetched. */ off_t file_dloaded; /** * @var file_name * * File name being fetched. */ const char *file_name; /** * @var cb_start * * If true the function callback should be prepared to start * the transfer progress. */ bool cb_start; /** * @var cb_update * * If true the function callback should be prepared to * update the transfer progress. */ bool cb_update; /** * @var cb_end * * If true the function callback should be prepated to * end the transfer progress. */ bool cb_end; }; /** * @struct xbps_unpack_cb_data xbps_api.h "xbps_api.h" * @brief Structure to be passed to the unpack function callback. * * This structure is passed as argument to the unpack progress function * callback and its members will be updated when there's any progress. * All members in this struct are set internally by libxbps * and should be used in read-only mode in the supplied function * callback. */ struct xbps_unpack_cb_data { /** * @var xhp * * Pointer to our struct xbps_handle passed to xbps_init(). */ struct xbps_handle *xhp; /** * @var pkgver * * Package name/version string of package being unpacked. */ const char *pkgver; /** * @var entry * * Entry pathname string. */ const char *entry; /** * @var entry_size * * Entry file size. */ int64_t entry_size; /** * @var entry_extract_count * * Total number of extracted entries. */ ssize_t entry_extract_count; /** * @var entry_total_count * * Total number of entries in package. */ ssize_t entry_total_count; /** * @var entry_is_conf * * If true "entry" is a configuration file. */ bool entry_is_conf; }; /** * @struct xbps_handle xbps_api.h "xbps_api.h" * @brief Generic XBPS structure handler for initialization. * * This structure sets some global properties for libxbps, to set some * function callbacks and data to the fetch, transaction and unpack functions, * the root and cache directory, flags, etc. */ struct xbps_handle { /** * @private */ cfg_t *cfg; /** * @private * * Array of dictionaries with all registered repositories. */ prop_array_t repo_pool; /** * @private pkgdb. * * Internalized proplib dictionary with the master package database * stored in XBPS_META_PATH/XBPS_PKGDB. */ prop_dictionary_t pkgdb; /** * @private * * Proplib dictionary with pkg metafiles. */ prop_dictionary_t pkg_metad; /** * @private pkgdb_revdeps. * * Proplib dictionary with full reverse dependencies from pkgdb. */ prop_dictionary_t pkgdb_revdeps; /** * @var transd; * * Proplib dictionary with transaction details, required by * xbps_transaction_commit(). */ prop_dictionary_t transd; /** * Pointer to the supplifed function callback to be used * in the XBPS possible states. */ void (*state_cb)(struct xbps_state_cb_data *, void *); /** * Pointer to user supplied data to be passed as argument to * the \a xbps_state_cb function callback. */ void *state_cb_data; /** * Pointer to the supplied function callback to be used in * xbps_unpack_binary_pkg(). */ void (*unpack_cb)(struct xbps_unpack_cb_data *, void *); /** * Pointer to user supplied data to be passed as argument to * the \a xbps_unpack_cb function callback. */ void *unpack_cb_data; /** * Pointer to the supplied function callback to be used in * xbps_fetch_file(). */ void (*fetch_cb)(struct xbps_fetch_cb_data *, void *); /** * @var fetch_cb_data * * Pointer to user supplied data to be passed as argument to * the \a xbps_fetch_cb function callback. */ void *fetch_cb_data; /** * @var rootdir * * Root directory for all operations in XBPS. If NULL, * by default it's set to /. */ const char *rootdir; /** * @var cachedir * * Cache directory to store downloaded binary packages. * If NULL default value in \a XBPS_CACHE_PATH is used. */ const char *cachedir; /** * @var metadir * * Metadata directory for all operations in XBPS. * If NULL, defaults to \a XBPS_CACHE_PATH (relative to rootdir). */ const char *metadir; /** * @private */ char *cachedir_priv; char *metadir_priv; char *native_arch; const char *target_arch; /* * @var repository * * Default repository to be used if a configuration file * couldn't be found. */ const char *repository; /** * @var conffile * * Full path to the xbps configuration file. */ const char *conffile; /** * @var fetch_timeout * * Unsigned integer to specify libfetch's timeout limit. * If not set, it defaults to 30 (in seconds). This is set internally * by the API from a setting in configuration file. */ uint16_t fetch_timeout; /** * @var flags * * Flags to be set globally by ORing them, possible values: * - XBPS_FLAG_VERBOSE * - XBPS_FLAG_FORCE_CONFIGURE * - XBPS_FLAG_FORCE_REMOVE_FILES * - XBPS_FLAG_DEBUG * - XBPS_FLAG_SYSLOG * - XBPS_FLAG_INSTALL_AUTO */ int flags; /** * @private */ bool initialized; }; void xbps_dbg_printf(struct xbps_handle *, const char *, ...); void xbps_dbg_printf_append(struct xbps_handle *, const char *, ...); void xbps_error_printf(const char *, ...); void xbps_warn_printf(const char *, ...); /** * Initialize the XBPS library with the following steps: * * - Set function callbacks for fetching and unpacking. * - Set default cache connections for libfetch. * - Parse configuration file. * * @param[in] xhp Pointer to an xbps_handle struct. * @note It's assumed that \a xhp is a valid pointer. * * @return 0 on success, an errno value otherwise. */ int xbps_init(struct xbps_handle *xhp); /** * Releases all resources used by libxbps. * * @param[in] xhp Pointer to an xbps_handle struct. */ void xbps_end(struct xbps_handle *xhp); /*@}*/ /** @addtogroup configure */ /*@{*/ /** * Configure (or force reconfiguration of) a package. * * @param[in] xhp Pointer to an xbps_handle struct. * @param[in] pkgname Package name to configure. * @param[in] check_state Set it to true to check that package is * in unpacked state. * @param[in] update Set it to true if this package is being updated. * @param[in] flush Set it to true to flush state to pkgdb. * * @return 0 on success, otherwise an errno value. */ int xbps_configure_pkg(struct xbps_handle *xhp, const char *pkgname, bool check_state, bool update, bool flush); /** * Configure (or force reconfiguration of) all packages. * * @param[in] xhp Pointer to an xbps_handle struct. * @param[in] flush Set it to true to flush state to pkgdb. * * @return 0 on success, otherwise an errno value. */ int xbps_configure_packages(struct xbps_handle *xhp, bool flush); /*@}*/ /** @addtogroup download */ /*@{*/ /** * Download a file from a remote URL to current working directory. * * @param[in] xhp Pointer to an xbps_handle struct. * @param[in] uri Remote URI string. * @param[in] flags Flags passed to libfetch's fetchXget(). * * @return -1 on error, 0 if not downloaded (because local/remote size/mtime * do not match) and 1 if downloaded successfully. **/ int xbps_fetch_file(struct xbps_handle *xhp, const char *uri, const char *flags); /** * Returns last error string reported by xbps_fetch_file(). * * @return A string with the appropiate error message. */ const char *xbps_fetch_error_string(void); /*@}*/ /** * @ingroup pkg_orphans * * Finds all package orphans currently installed. * * @param[in] xhp Pointer to an xbps_handle struct. * @param[in] orphans Proplib array of strings with package names of * packages that should be treated as they were already removed (optional). * * @return A proplib array of dictionaries with all orphans found, * on error NULL is returned and errno is set appropiately. */ prop_array_t xbps_find_pkg_orphans(struct xbps_handle *xhp, prop_array_t orphans); /** * @ingroup pkg_obsoletes * * Finds obsolete files by comparing installed files dictionary with * a new files dictionary. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] instd Installed package metadata dictionary. * @param[in] newd New package metadata dictionary. * * @return A proplib array of strings with a sorted list of obsolete files. */ prop_array_t xbps_find_pkg_obsoletes(struct xbps_handle *xhp, prop_dictionary_t instd, prop_dictionary_t newd); /** @addtogroup pkgdb */ /*@{*/ /** * Executes a function callback per a package dictionary registered * in master package database (pkgdb) plist (downwards). * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] fn Function callback to run for any pkg dictionary. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success (all objects were processed), otherwise * the value returned by the function callback. */ int xbps_pkgdb_foreach_cb(struct xbps_handle *xhp, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Executes a function callback per a package dictionary registered * in master package database (pkgdb) plist, in reverse order (upwards). * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] fn Function callback to run for any pkg dictionary. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success (all objects were processed), otherwise * the value returned by the funcion callback. */ int xbps_pkgdb_foreach_reverse_cb( struct xbps_handle *xhp, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Returns a package dictionary from master package database (pkgdb) plist, * matching pkgname or pkgver object in \a pkg. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] pkg Package name or name-version to match. * * @return The matching proplib package dictionary, NULL otherwise. */ prop_dictionary_t xbps_pkgdb_get_pkg(struct xbps_handle *xhp, const char *pkg); /** * Returns a package dictionary from master package database (pkgdb) plist, * matching virtual pkgname or pkgver object in \a pkg. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] pkg Package name or name-version to match. * * @return The matching proplib package dictionary, NULL otherwise. */ prop_dictionary_t xbps_pkgdb_get_virtualpkg(struct xbps_handle *xhp, const char *pkg); /** * Returns the package dictionary with all metadata info for \a pkg. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] pkg Package expression to match. * * @return The matching package metadata dictionary, NULL otherwise. */ prop_dictionary_t xbps_pkgdb_get_pkg_metadata(struct xbps_handle *xhp, const char *pkg); /** * Returns a proplib array of strings with reverse dependencies * for \a pkg. The array is generated dynamically based on the list * of packages currently installed. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] pkg Package expression to match. * * @return A proplib array of strings with reverse dependencies for \a pkg. */ prop_array_t xbps_pkgdb_get_pkg_revdeps(struct xbps_handle *xhp, const char *pkg); /** * Updates the master package database (pkgdb) plist with new contents from * disk to the cached copy in memory. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] flush If true the pkgdb plist contents in memory will * be flushed atomically to storage. * * @return 0 on success, otherwise an errno value. */ int xbps_pkgdb_update(struct xbps_handle *xhp, bool flush); /** * Creates a temporary file and executes it in rootdir. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] blob The buffer pointer where the data is stored. * @param[in] blobsiz The size of the buffer data. * @param[in] pkgver The package name/version associated. * @param[in] action The action to execute on the temporary file. * @param[in] update Set to true if package is being updated. * * @return 0 on success, or an errno value otherwise. */ int xbps_pkg_exec_buffer(struct xbps_handle *xhp, const void *blob, const size_t blobsiz, const char *pkgver, const char *action, bool update); /** * Creates a temporary file and executes it in rootdir. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] d Package dictionary where the script data is stored. * @param[in] script Key associated with the script in dictionary. * @param[in] action The action to execute on the temporary file. * @param[in] update Set to true if package is being updated. * * @return 0 on success, or an errno value otherwise. */ int xbps_pkg_exec_script(struct xbps_handle *xhp, prop_dictionary_t d, const char *script, const char *action, bool update); /*@}*/ /** @addtogroup plist */ /*@{*/ /** * Executes a function callback specified in \a fn with \a arg passed * as its argument into they array \a array. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] array Proplib array to iterate. * @param[in] fn Function callback to run on every object in the array. * While running the function callback, the hird parameter (a pointer to * a boolean) can be set to true to stop immediately the loop. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success, otherwise the value returned by the function * callback. */ int xbps_callback_array_iter(struct xbps_handle *xhp, prop_array_t array, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Executes a function callback specified in \a fn with \a arg passed * as its argument into they array \a array in reverse order (upwards). * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] array Proplib array to iterate. * @param[in] fn Function callback to run on every object in the array. * While running the function callback, the hird parameter (a pointer to * a boolean) can be set to true to stop immediately the loop. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success, otherwise the value returned by the function * callback. */ int xbps_callback_array_iter_reverse(struct xbps_handle *xhp, prop_array_t array, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Executes a function callback into the array associated with key \a key, * contained in a proplib dictionary. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] dict Proplib dictionary where the array resides. * @param[in] key Key associated with array. * @param[in] fn Function callback to run on every * object in the array. While running the function callback, the third * parameter (a pointer to a boolean) can be set to true to stop * immediately the loop. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success (all objects were processed), otherwise * the value returned by the function callback. */ int xbps_callback_array_iter_in_dict(struct xbps_handle *xhp, prop_dictionary_t dict, const char *key, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Executes a function callback (in reverse order) into the array * associated with key \a key, contained in a proplib dictionary. * * @param[in] xhp The pointer to the xbps_handle struct. * @param[in] dict Proplib dictionary where the array resides. * @param[in] key Key associated with array. * @param[in] fn Function callback to run on every * object in the array. While running the function callback, the third * parameter (a pointer to a boolean) can be set to true to stop * immediately the loop. * @param[in] arg Argument to be passed to the function callback. * * @return 0 on success (all objects were processed), otherwise * the value returned by the function callback. */ int xbps_callback_array_iter_reverse_in_dict(struct xbps_handle *xhp, prop_dictionary_t dict, const char *key, int (*fn)(struct xbps_handle *, prop_object_t, void *, bool *), void *arg); /** * Match a virtual package name or pattern by looking at package's * dictionary "provides" array object. * * @param[in] pkgd Package dictionary. * @param[in] str Virtual package name or package pattern to match. * @param[in] bypattern If true, \a str should be a package name, * otherwise it should be a package pattern, i.e `foo>=0' or `foo<1'. * * @return True if \a str matches a virtual package in \a pkgd, false * otherwise. */ bool xbps_match_virtual_pkg_in_dict(prop_dictionary_t pkgd, const char *str, bool bypattern); /** * Match any virtual package from array \a provides in they array \a rundeps * with dependencies. * * @param[in] rundeps Proplib array with dependencies as strings, i.e foo>=2.0. * @param[in] provides Proplib array of strings with virtual pkgdeps, i.e * foo-1.0 blah-2.0. * * @return True if \a any virtualpkg has been matched, false otherwise. */ bool xbps_match_any_virtualpkg_in_rundeps(prop_array_t rundeps, prop_array_t provides); /** * Match a package name in the specified array of strings. * * @param[in] array The proplib array to search on. * @param[in] pkgname The package name to match. * * @return true on success, false otherwise and errno is set appropiately. */ bool xbps_match_pkgname_in_array(prop_array_t array, const char *pkgname); /** * Match a package pattern in the specified array of strings. * * @param[in] array The proplib array to search on. * @param[in] pattern The package pattern to match, i.e `foo>=0' or `foo<1'. * * @return true on success, false otherwise and errno is set appropiately. */ bool xbps_match_pkgpattern_in_array(prop_array_t array, const char *pattern); /** * Match a package dependency against any package pattern in the specified * array of strings. * * @param[in] array The proplib array to search on. * @param[in] pkgver The package name-version to match, i.e `foo-1.0'. * * @return true on success, false otherwise and errno is set appropiately. */ bool xbps_match_pkgdep_in_array(prop_array_t array, const char *pkgver); /** * Match a string (exact match) in the specified array of strings. * * @param[in] array The proplib array to search on. * @param[in] val The string to be matched. * * @return true on success, false otherwise and errno is set appropiately. */ bool xbps_match_string_in_array(prop_array_t array, const char *val); /** * Returns a proplib object iterator associated with an array, contained * in a proplib dictionary matching the specified key. * * @param[in] dict Proplib dictionary where to look for the array. * @param[in] key Key associated with the array. * * @return A proplib object iterator on success, NULL otherwise and * errno is set appropiately. */ prop_object_iterator_t xbps_array_iter_from_dict(prop_dictionary_t dict, const char *key); /*@}*/ /** @addtogroup transaction */ /*@{*/ /** * Finds a package by name or by pattern and enqueues it into * the transaction dictionary for future use. If pkg is a pkgname, the best * package version in repository pool will be queued, otherwise the first * repository matching the package pattern wins. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pkg Package name, package/version or package pattern to match, i.e * `foo', `foo-1.0' or `foo>=1.2'. * @param[in] reinstall If true, package will be queued (if \a str matches) * even if package is already installed. * * @return 0 on success, otherwise an errno value. * @retval EEXIST Package is already installed (reinstall wasn't enabled). * @retval ENOENT Package not matched in repository pool. * @retval ENOTSUP No repositories are available. * @retval EINVAL Any other error ocurred in the process. */ int xbps_transaction_install_pkg(struct xbps_handle *xhp, const char *pkg, bool reinstall); /** * Marks a package as "going to be updated" in the transaction dictionary. * All repositories in the pool will be used, and newest version * available will be enqueued if it's greater than current installed * version. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pkgname The package name to update. * * @return 0 on success, otherwise an errno value. */ int xbps_transaction_update_pkg(struct xbps_handle *xhp, const char *pkgname); /** * Finds newer versions for all installed packages by looking at the * repository pool. If a newer version exists, package will be enqueued * into the transaction dictionary. * * @param[in] xhp Pointer to the xbps_handle struct. * @return 0 on success, otherwise an errno value. */ int xbps_transaction_update_packages(struct xbps_handle *xhp); /** * Removes a package currently installed. The package dictionary will * be added into the transaction dictionary. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pkgname Package name to be removed. * @param[in] recursive If true, all packages that are currently depending * on the package to be removed, and if they are orphans, will be added. * * @retval 0 success. * @retval ENOENT Package is not installed. * @retval EEXIST Package has reverse dependencies. * @retval EINVAL * @retval ENXIO A problem ocurred in the process. */ int xbps_transaction_remove_pkg(struct xbps_handle *xhp, const char *pkgname, bool recursive); /** * Finds all package orphans currently installed and adds them into * the transaction dictionary. * * @param[in] xhp Pointer to the xbps_handle struct. * * @retval 0 success. * @retval ENOENT No package orphans were found. * @retval ENXIO * @retval EINVAL A problem ocurred in the process. */ int xbps_transaction_autoremove_pkgs(struct xbps_handle *xhp); /** * Returns the transaction dictionary, as shown above in the image. * Before returning the package list is sorted in the correct order * and total installed/download size for the transaction is computed. * * @param[in] xhp Pointer to the xbps_handle struct. * * @retval 0 success. * @retval ENXIO if transaction dictionary and missing deps array were not created, * due to xbps_transaction_install_pkg() or xbps_transaction_update_pkg() not * previously called. * @retval ENODEV if there are missing dependencies in transaction ("missing_deps" * array of strings object in xhp->transd dictionary). * @retval EAGAIN if there are package conflicts in transaction ("conflicts" * array of strings object in xhp->transd dictionary). * @retval EINVAL There was an error sorting packages or computing the transaction * sizes. */ int xbps_transaction_prepare(struct xbps_handle *xhp); /** * Commit a transaction. The transaction dictionary in xhp->transd contains all * steps to be executed in the transaction, as prepared by * xbps_transaction_prepare(). * * @param[in] xhp Pointer to the xbps_handle struct. * @return 0 on success, otherwise an errno value. */ int xbps_transaction_commit(struct xbps_handle *xhp); /*@}*/ /** @addtogroup plist_fetch */ /*@{*/ /** * Internalizes a plist file in a binary package file stored locally or * remotely as specified in \a fname. * * @param[in] fname Full URL to binary package file (local or remote path). * @param[in] plistf Plist file name to internalize. * * @return An internalized proplib dictionary, otherwise NULL and * errno is set appropiately. */ prop_dictionary_t xbps_get_pkg_plist_from_binpkg(const char *fname, const char *plistf); /*@}*/ /** @addtogroup repopool */ /*@{*/ /** * @struct xbps_rindex xbps_api.h "xbps_api.h" * @brief Repository pool index structure * * Repository index object structure registered in a private simple queue. * The structure contains a dictionary and the URI associated with the * registered repository index. */ struct xbps_rindex { /** * @var repod * * Internalized proplib dictionary of the index plist file * associated with repository. */ prop_dictionary_t repod; /** * @var uri * * URI string associated with repository. */ const char *uri; /** * @var xhp * * Pointer to our xbps_handle struct passed to xbps_rpool_foreach. * (read-only). */ struct xbps_handle *xhp; }; /** * Synchronizes \a file for all remote repositories * as specified in the configuration file or if \a uri argument is * set, just sync \a file for that repository. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] file File to synchronize. * @param[in] uri Repository URI to match for sync (optional). * * @return 0 on success, ENOTSUP if no repositories were found in * the configuration file. */ int xbps_rpool_sync(struct xbps_handle *xhp, const char *file, const char *uri); /** * Iterates over the repository pool and executes the \a fn function * callback passing in the void * \a arg argument to it. The bool pointer * argument can be used in the callbacks to stop immediately the loop if * set to true, otherwise it will only be stopped if it returns a * non-zero value. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] fn Function callback to execute for every repository registered in * the pool. * @param[in] arg Opaque data passed in to the \a fn function callback for * client data. * * @return 0 on success, otherwise an errno value. */ int xbps_rpool_foreach(struct xbps_handle *xhp, int (*fn)(struct xbps_rindex *, void *, bool *), void *arg); /** * Finds a package dictionary in the repository pool by specifying a * package pattern or a package name. This function does not take into * account virtual packages, just matches real packages. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pkg Package pattern, exact pkg or pkg name. * * @return The package dictionary if found, NULL otherwise. * @note When returned dictionary is no longer needed, you must release it * with prop_object_release(3). */ prop_dictionary_t xbps_rpool_get_pkg(struct xbps_handle *xhp, const char *pkg); /** * Finds a package dictionary in repository pool by specifying a * virtual package pattern or a package name. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pkg Virtual package pattern or name to match. * * @return The package dictionary if found, NULL otherwise. * @note When returned dictionary is no longer needed, you must release it * with prop_object_release(3). */ prop_dictionary_t xbps_rpool_get_virtualpkg(struct xbps_handle *xhp, const char *pkg); /** * Iterate over the the repository pool and search for a metadata plist * file in a binary package matching `pattern'. If a package is matched * the plist file \a plistf will be internalized into a proplib dictionary. * * When \a pattern is a pkgname, the newest package available in repositories * will be used. Otherwise the first repository matching \a pattern. * * @param[in] xhp Pointer to the xbps_handle struct. * @param[in] pattern Package name or package pattern to match, i.e `foo>=1.0'. * @param[in] plistf Plist file name to match, i.e XBPS_PKGPROPS or XBPS_PKGFILES. * * @return An internalized proplib dictionary of \a plistf, otherwise NULL * and errno is set appropiately. * * @note if NULL is returned and errno is ENOENT, that means that * binary package file has been found but the plist file could not * be found. */ prop_dictionary_t xbps_rpool_get_pkg_plist(struct xbps_handle *xhp, const char *pattern, const char *plistf); /*@}*/ /** @addtogroup rindex */ /*@{*/ /** * Returns a pkg dictionary from a repository index \a ri matching * the expression \a pkg. * * @param[in] ri Pointer to an xbps_rindex structure. * @param[in] pkg Package expression to match in this repository index. * * @return The pkg dictionary on success, NULL otherwise. */ prop_dictionary_t xbps_rindex_get_pkg(struct xbps_rindex *ri, const char *pkg); /** * Returns a pkg dictionary from a repository index \a ri matching * the expression \a pkg. On match the first package matching the virtual * package expression will be returned. * * @param[in] ri Pointer to an xbps_rindex structure. * @param[in] pkg Package expression to match in this repository index. * * @return The pkg dictionary on success, NULL otherwise. */ prop_dictionary_t xbps_rindex_get_virtualpkg(struct xbps_rindex *ri, const char *pkg); /*@}*/ /** @addtogroup pkgstates */ /*@{*/ /** * @enum pkg_state_t * * Integer representing a state on which a package may be. Possible * values for this are: * * - XBPS_PKG_STATE_UNPACKED: Package has been unpacked correctly * but has not been configured due to unknown reasons. * - XBPS_PKG_STATE_INSTALLED: Package has been installed successfully. * - XBPS_PKG_STATE_BROKEN: not yet used. * - XBPS_PKG_STATE_HALF_REMOVED: Package has been removed but not * completely: the purge action in REMOVE script wasn't executed, pkg * metadata directory still exists and is registered in package database. * - XBPS_PKG_STATE_NOT_INSTALLED: Package going to be installed in * a transaction dictionary but that has not been yet unpacked. */ typedef enum pkg_state { XBPS_PKG_STATE_UNPACKED = 1, XBPS_PKG_STATE_INSTALLED, XBPS_PKG_STATE_BROKEN, XBPS_PKG_STATE_HALF_REMOVED, XBPS_PKG_STATE_NOT_INSTALLED, } pkg_state_t; /** * Gets package state from package \a pkgname, and sets its state * into \a state. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] pkgname Package name. * @param[out] state Package state returned. * * @return 0 on success, otherwise an errno value. */ int xbps_pkg_state_installed(struct xbps_handle *xhp, const char *pkgname, pkg_state_t *state); /** * Gets package state from a package dictionary \a dict, and sets its * state into \a state. * * @param[in] dict Package dictionary. * @param[out] state Package state returned. * * @return 0 on success, otherwise an errno value. */ int xbps_pkg_state_dictionary(prop_dictionary_t dict, pkg_state_t *state); /** * Sets package state \a state in package \a pkgname. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] pkgver Package name/version to match. * @param[in] state Package state to be set. * * @return 0 on success, otherwise an errno value. */ int xbps_set_pkg_state_installed(struct xbps_handle *xhp, const char *pkgver, pkg_state_t state); /** * Sets package state \a state in package dictionary \a dict. * * @param[in] dict Package dictionary. * @param[in] state Package state to be set. * * @return 0 on success, otherwise an errno value. */ int xbps_set_pkg_state_dictionary(prop_dictionary_t dict, pkg_state_t state); /*@}*/ /** @addtogroup util */ /*@{*/ /** * Creates a directory (and required components if necessary). * * @param[in] path Path for final directory. * @param[in] mode Mode for final directory (0755 if not specified). * * @return 0 on success, -1 on error and errno set appropiately. */ int xbps_mkpath(const char *path, mode_t mode); /** * Returns a string by concatenating its variable argument list * as specified by the format string \a fmt. * * @param[in] fmt Format string, see printf(3). * @return A pointer to a malloc(3)ed string, NULL otherwise and errno * is set appropiately. The pointer should be free(3)d when it's * no longer needed. */ char *xbps_xasprintf(const char *fmt, ...); /** * Returns a string with the sha256 hash for the file specified * by \a file. * * @param[in] file Path to a file. * @return A pointer to a malloc(3)ed string, NULL otherwise and errno * is set appropiately. The pointer should be free(3)d when it's no * longer needed. */ char *xbps_file_hash(const char *file); /** * Compares the sha256 hash of the file \a file with the sha256 * string specified by \a sha256. * * @param[in] file Path to a file. * @param[in] sha256 SHA256 hash to compare. * * @return 0 if \a file and \a sha256 have the same hash, ERANGE * if it differs, or any other errno value on error. */ int xbps_file_hash_check(const char *file, const char *sha256); /** * Checks if a package is currently installed by matching \a pkg. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] pkg Package name, version pattern or exact pkg to match. * * @return -1 on error (errno set appropiately), 0 if \a pkg * didn't match installed package, 1 if \a pkg pattern fully * matched installed package. */ int xbps_pkg_is_installed(struct xbps_handle *xhp, const char *pkg); /** * Checks if the URI specified by \a uri is remote or local. * * @param[in] uri URI string. * * @return true if URI is remote, false if local. */ bool xbps_repository_is_remote(const char *uri); /** * Gets the full path to a repository package index plist file, as * specified by \a uri. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] uri Repository URI. * * @return A pointer to a malloc(3)d string, NULL otherwise and * errno is set appropiately. The pointer should be free(3)d when it's * no longer needed. */ char *xbps_pkg_index_plist(struct xbps_handle *xhp, const char *uri); /** * Returns the full path to a repository package index files plist file, * as specified by \a uri. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] uri Repository URI. * * @return A pointer to a malloc(3)ed string, NULL otherwise and * errno is set appropiately. The pointer should be free(3)d when it's * no longer needded. */ char *xbps_pkg_index_files_plist(struct xbps_handle *xhp, const char *uri); /** * Gets the name of a package string. Package strings are composed * by a @/@ pair and separated by the minus * sign, i.e foo-2.0. * * @param[in] pkg Package string. * * @return A pointer to a malloc(3)d string, NULL otherwise and * errno is set appropiately. The pointer should be free(3)d when it's * no longer needed. */ char *xbps_pkg_name(const char *pkg); /** * Gets a the package name of a package pattern string specified by * the \a pattern argument. * * @param[in] pattern A package pattern. Package patterns are composed * by looking at '><=' to split components, i.e foo>=2.0, * blah<1.0, blob==2.0, etc. * * @return A pointer to a malloc(3)ed string with the package name, * NULL otherwise and errno is set appropiately. The pointer should be * free(3)d when it's no longer needed. */ char *xbps_pkgpattern_name(const char *pattern); /** * Gets the package version in a package string, i.e foo-2.0. * * @param[in] pkg Package string. * * @return A string with the version string, NULL if it couldn't * find the version component. */ const char *xbps_pkg_version(const char *pkg); /** * Gets the package version of a package pattern string specified by * the \a pattern argument. * * @param[in] pattern A package pattern. The same rules in * xbps_get_pkgpattern_name() apply here. * * @return A string with the pattern version, NULL otherwise and * errno is set appropiately. */ const char *xbps_pkgpattern_version(const char *pattern); /** * Package pattern matching. * * @param[in] pkgver Package name/version, i.e `foo-1.0'. * @param[in] pattern Package pattern to match against \a pkgver. * There are 3 strategies for version matching: * - simple compare: pattern equals to pkgver. * - shell wildcards: see fnmatch(3). * - relational dewey matching: '>' '<' '>=' '<='. * * @return 1 if \a pkgver is matched against \a pattern, 0 if no match. */ int xbps_pkgpattern_match(const char *pkgver, const char *pattern); /** * Gets the package version revision in a package string. * * @param[in] pkg Package string, i.e foo-2.0_1. * * @return A string with the revision number, NULL if it couldn't * find the revision component. */ const char *xbps_pkg_revision(const char *pkg); /** * Checks if a package has run dependencies. * * @param[in] dict Package dictionary. * * @return True if package has run dependencies, false otherwise. */ bool xbps_pkg_has_rundeps(prop_dictionary_t dict); /** * Returns true if provided string is valid for target architecture. * * @param[in] xhp The pointer to an xbps_handle struct. * @param[in] orig Architecture to match. * @param[in] target If not NULL, \a orig will be matched against it * rather than returned value of uname(2). * * @return True on match, false otherwise. */ bool xbps_pkg_arch_match(struct xbps_handle *xhp, const char *orig, const char *target); /** * Converts the 64 bits signed number specified in \a bytes to * a human parsable string buffer pointed to \a buf. * * @param[out] buf Buffer to store the resulting string. At least * it should have space for 6 chars. * @param[in] bytes 64 bits signed number to convert. * * @return A negative number is returned on error, 0 otherwise. */ int xbps_humanize_number(char *buf, int64_t bytes); /** * Compares package version strings. * * The package version is defined by: * ${VERSION}[_${REVISION}]. * * @param[in] pkg1 a package version string. * @param[in] pkg2 a package version string. * * @return -1, 0 or 1 depending if pkg1 is less than, equal to or * greater than pkg2. */ int xbps_cmpver(const char *pkg1, const char *pkg2); /*@}*/ #ifdef __cplusplus } #endif #endif /* !_XBPS_API_H_ */