emo/xbps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
45d55698d8
xbps/include/xbps_api.h

1670 lines
48 KiB
C
Raw Blame History

/*-
* Copyright (c) 2008-2011 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 <stdio.h>
#include <inttypes.h>
#include <archive.h>
#include <archive_entry.h>
#include <prop/proplib.h>
#ifdef __cplusplus
# define __BEGIN_DECLS extern "C" {
# define __END_DECLS }
#else
# define __BEGIN_DECLS
# define __END_DECLS
#endif
/**
* @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.3"
#define XBPS_API_VERSION "20111110"
#define XBPS_VERSION "0.11.0"
/**
* @def XBPS_RELVER
* Current library release date.
*/
#define XBPS_RELVER "XBPS: " XBPS_VERSION \
" API: " XBPS_API_VERSION \
" INDEX: " XBPS_PKGINDEX_VERSION
/**
* @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_REGPKGDB
* Filename for the global package register database.
*/
#define XBPS_REGPKGDB "regpkgdb.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.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_PLIST
* Filename for the XBPS plist configuration file.
*/
#define XBPS_CONF_PLIST "conf.plist"
/**
* @def XBPS_CONF_REPOS_PLIST
* Filename for the XBPS repositories plist configuration file.
*/
#define XBPS_CONF_REPOS_PLIST "repositories.plist"
/**
* @def XBPS_VIRTUALPKGD_PATH
* Default directory to load virtualpkg plist files, by default set
* to XBPS_SYSCONF_PATH + "/" + XBPS_VIRTUALPKGD_PATH.
*/
#define XBPS_VIRTUALPKGD_PATH "virtualpkg.d.wants"
/**
* @def XBPS_FLAG_VERBOSE
* Verbose flag used in xbps_unpack_binary_pkg() (for now).
* Must be set through the xbps_init::flags member.
*/
#define XBPS_FLAG_VERBOSE 0x00000001
/**
* @def XBPS_FLAG_FORCE
* Force flag used in xbps_configure_pkg() (for now).
* Must be set through the xbps_init::flags member.
*/
#define XBPS_FLAG_FORCE 0x00000002
__BEGIN_DECLS
void xbps_printf(const char *, ...);
void xbps_dbg_printf(const char *, ...);
void xbps_dbg_printf_append(const char *, ...);
void xbps_error_printf(const char *, ...);
void xbps_warn_printf(const char *, ...);
/** @addtogroup initend */
/*@{*/
/**
* @enum trans_state_t
*
* Integer representing the transaction state. Possible values:
*
* <b>XBPS_TRANS_STATE_UKKNOWN</b>: unknown, transaction hasn't been
* prepared or some unknown error ocurred.
*
* <b>XBPS_TRANS_STATE_DOWNLOAD</b>: a binary package is being downloaded.
*
* <b>XBPS_TRANS_STATE_VERIFY</b>: a binary package is being verified.
*
* <b>XBPS_TRANS_STATE_REMOVE</b>: a package is being removed.
*
* <b>XBPS_TRANS_STATE_PURGE</b>: a package is being purged.
*
* <b>XBPS_TRANS_STATE_REPLACE</b>: a package is being replaced.
*
* <b>XBPS_TRANS_STATE_INSTALL</b>: a package is being installed.
*
* <b>XBPS_TRANS_STATE_UPDATE</b>: a package is being updated.
*
* <b>XBPS_TRANS_STATE_UNPACK</b>: a package is being unpacked.
*
* <b>XBPS_TRANS_STATE_CONFIGURE</b>: a package is being configured.
*
* <b>XBPS_TRANS_STATE_REGISTER</b>: a package is being registered.
*
* <b>XBPS_TRANS_STATE_REPOSYNC</b>: a remote repository's
* pkg index is being synchronized.
*/
typedef enum trans_state {
XBPS_TRANS_STATE_UNKNOWN = 0,
XBPS_TRANS_STATE_DOWNLOAD,
XBPS_TRANS_STATE_VERIFY,
XBPS_TRANS_STATE_REMOVE,
XBPS_TRANS_STATE_PURGE,
XBPS_TRANS_STATE_REPLACE,
XBPS_TRANS_STATE_INSTALL,
XBPS_TRANS_STATE_UPDATE,
XBPS_TRANS_STATE_UNPACK,
XBPS_TRANS_STATE_CONFIGURE,
XBPS_TRANS_STATE_REGISTER,
XBPS_TRANS_STATE_REPOSYNC
} trans_state_t;
/**
* @struct xbps_transaction_cb_data xbps_api.h "xbps_api.h"
* @brief Structure to be passed as argument to the transaction
* function callbacks.
*/
struct xbps_transaction_cb_data {
/**
* @var state
*
* Transaction's state (set internally, read-only).
*/
trans_state_t state;
/**
* @var desc
*
* Transaction's string description (set internally, read-only).
*/
const char *desc;
/**
* @var pkgver
*
* Transaction's current pkgname/version string
* (set internally, read-only).
*/
const char *pkgver;
/**
* @var binpkg_fname
*
* Binary package's filename (set internally, read-only).
*/
const char *binpkg_fname;
/**
* @var repourl
*
* Repository URL (set internally, read-only).
*/
const char *repourl;
/**
* @var err
*
* Transaction error value (set internally, read-only).
*/
int err;
/**
* @var cookie
*
* Pointer to user supplied data.
*/
void *cookie;
};
/**
* @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 file_size
*
* Filename size for the file to be fetched (set internally,
* read-only).
*/
off_t file_size;
/**
* @var file_offset
*
* Current offset for the filename being fetched (set internally,
* read-only).
*/
off_t file_offset;
/**
* @var file_dloaded
*
* Bytes downloaded for the file being fetched
* (set internally, read-only).
*/
off_t file_dloaded;
/**
* @var file_name
*
* File name being fetched (set internally, read-only).
*/
const char *file_name;
/**
* @var cb_start
*
* If true the function callback should be prepared to start
* the transfer progress (set internally, read-only).
*/
bool cb_start;
/**
* @var cb_update
*
* If true the function callback should be prepared to
* update the transfer progress (set internally, read-only).
*/
bool cb_update;
/**
* @var cb_end
*
* If true the function callback should be prepated to
* end the transfer progress (set internally, read-only).
*/
bool cb_end;
/**
* @var cookie
*
* Pointer to private user data.
*/
void *cookie;
};
/**
* @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 xbps_unpack_binary_pkg()
* and should be used in read-only mode in the function callback.
* The \a cookie member can be used to pass user supplied data.
*/
struct xbps_unpack_cb_data {
/**
* @var entry
*
* Entry pathname string (set internally, read-only).
*/
const char *entry;
/**
* @var entry_size
*
* Entry file size (set internally, read-only).
*/
int64_t entry_size;
/**
* @var entry_extract_count
*
* Total number of extracted entries (set internally, read-only).
*/
ssize_t entry_extract_count;
/**
* @var entry_total_count
*
* Total number of entries in package (set internally, read-only).
*/
ssize_t entry_total_count;
/**
* @var entry_is_metadata
*
* If true "entry" is a package metadata file (set internally,
* read-only).
*/
bool entry_is_metadata;
/**
* @var entry_is_conf
*
* If true "entry" is a configuration file (set internally,
* read-only).
*/
bool entry_is_conf;
/**
* @var cookie
*
* Pointer to private user data.
*/
void *cookie;
};
/**
* @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
*/
prop_array_t virtualpkgs_array;
/**
* @private repos_array
*
* Internalized proplib array from XBPS_CONF_REPOS_PLIST file.
* Used internally by xbps_init(), do not use it.
*/
prop_array_t repos_array;
/**
* @var regpkgdb_dictionary.
*
* Internalized proplib dictionary with the registed package database
* stored in XBPS_META_PATH/XBPS_REGPKGDB.
*/
prop_dictionary_t regpkgdb_dictionary;
/**
* @var xbps_transaction_cb
*
* Pointer to the supplifed function callback to be used
* in a transaction.
*/
void (*xbps_transaction_cb)(struct xbps_transaction_cb_data *);
/**
* @var xbps_transaction_err_cb
*
* Pointer the the supplied function callback to be used in
* a transaction when an error happens.
*/
void (*xbps_transaction_err_cb)(struct xbps_transaction_cb_data *);
/**
* @var xtcd
*
* Pointer to a xbps_transaction_cb_data structure, to be passed as
* argument to the \a xbps_transaction_cb and
* \a xbps_transaction_err_cb function callbacks.
*/
struct xbps_transaction_cb_data *xtcd;
/**
* @var xbps_unpack_cb
*
* Pointer to the supplied function callback to be used in
* xbps_unpack_binary_pkg().
*/
void (*xbps_unpack_cb)(struct xbps_unpack_cb_data *);
/**
* @var xucd
*
* Pointer to a xbps_unpack_cb_data structure to be passed
* as argument to the \a xbps_unpack_cb function callback.
*/
struct xbps_unpack_cb_data *xucd;
/**
* @var xbps_fetch_cb
*
* Pointer to the supplied function callback to be used in
* xbps_fetch_file().
*/
void (*xbps_fetch_cb)(struct xbps_fetch_cb_data *);
/**
* @var xfcd
*
* Pointer to a xbps_fetch_cb_data structure to be passed
* as argument to the \a xbps_fetch_cb function callback.
*/
struct xbps_fetch_cb_data *xfcd;
/**
* @var rootdir
*
* Root directory for all operations in XBPS. If NULL,
* by default it's set to /.
*/
prop_string_t rootdir;
/**
* @var cachedir
*
* Cache directory to store downloaded binary packages.
* If NULL default value in \a XBPS_CACHE_PATH is used.
*/
prop_string_t cachedir;
/**
* @var confdir
*
* Full path to the XBPS_SYSCONF_PATH directory.
*/
prop_string_t confdir;
/**
* @private 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, possible values:
*
* - XBPS_FLAG_VERBOSE
*
* - XBPS_FLAG_FORCE
*/
int flags;
/**
* @var debug
*
* Set to true to enable debugging messages to stderr.
*/
bool debug;
/**
* @var install_reason_auto
*
* Set to true to make installed or updated target package
* (and its dependencies) marked with automatic installation,
* thus it will be found as orphan if no packages are depending
* on it.
*/
bool install_reason_auto;
/**
* @var install_reason_manual
*
* Set to true to make installed or updated target package
* (and its dependencies) marked with manual installation, thus
* it will never will be found as orphan.
*/
bool install_reason_manual;
};
/**
* Initialize the XBPS library with the following steps:
*
* - Set function callbacks for fetching and unpacking.
* - Set root directory (if not set, defaults to /).
* - Set cache directory (if not set, defaults to XBPS_CACHE_PATH).
* - Set global flags.
* - Set default cache connections for libfetch.
* - Initialize the debug printfs.
* - Internalize the proplib dictionary in config file.
* - Internalize the regpkgdb dictionary (if available).
*
* @param[in] xhp Pointer to an xbps_handle structure, as returned by
* \a xbps_handle_alloc().
* @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 structure, as returned
* by \a xbps_handle_alloc().
* @note It's assumed that \a xhp is a valid pointer.
*/
void xbps_end(struct xbps_handle *xhp);
/**
* Allocated an xbps_handle structure.
*
* @return A pointer to the allocated xbps_handle structure, NULL
* otherwise.
*/
struct xbps_handle *xbps_handle_alloc(void);
/**
* Returns a pointer to the xbps_handle structure set by xbps_init().
*/
struct xbps_handle *xbps_handle_get(void);
/*@}*/
/** @addtogroup configure */
/*@{*/
/**
* Configure (or force reconfiguration of) a package.
*
* @param[in] pkgname Package name to configure.
* @param[in] version Package version (<b>optional</b>).
* @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.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_configure_pkg(const char *pkgname,
const char *version,
bool check_state,
bool update);
/**
* Configure (or force reconfiguration of) all packages.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_configure_packages(void);
/*@}*/
/**
* @ingroup vermatch
*
* Compares package version strings.
*
* The package version is defined by:
* ${VERSION}[_${REVISION}].
*
* ${VERSION} supersedes ${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);
/** @addtogroup download */
/*@{*/
/**
* Download a file from a remote URL.
*
* @param[in] uri Remote URI string.
* @param[in] outputdir Directory string to store downloaded file.
* @param[in] refetch If true and local/remote size/mtime do not match,
* fetch the file from scratch.
* @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(const char *uri,
const char *outputdir,
bool refetch,
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] 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(prop_array_t orphans);
/**
* @ingroup vermatch
*
* Package pattern matching.
*
* @param[in] instpkg Package/version string of an installed package.
* @param[in] pattern Pattern required for \a instpkg to match.
*
* @return 1 if \a instpkg is matched against \a pattern, 0 if no match.
*/
int xbps_pkgpattern_match(const char *instpkg, const char *pattern);
/** @addtogroup plist */
/*@{*/
/**
* Adds a proplib object into a proplib dictionary with specified key.
*
* @param[in] dict Proplib dictionary to insert the object to.
* @param[in] obj Proplib object to be inserted.
* @param[in] key Key associated with \a obj.
*
* @return true on success, false otherwise and errno set appropiately.
*/
bool xbps_add_obj_to_dict(prop_dictionary_t dict,
prop_object_t obj,
const char *key);
/**
* Adds a proplib object into a proplib array.
*
* @param[in] array Proplib array to insert the object to.
* @param[in] obj Proplib object to be inserted.
*
* @return true on success, false otherwise and xbps_errno set appropiately.
*/
bool xbps_add_obj_to_array(prop_array_t array, prop_object_t obj);
/**
* Executes a function callback specified in \a fn with \a arg paassed
* as its argument into they array \a array.
*
* @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 an errno value is set appropiately.
*/
int xbps_callback_array_iter(prop_array_t array,
int (*fn)(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] 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 an
* errno value is set appropiately.
*/
int xbps_callback_array_iter_in_dict(prop_dictionary_t dict,
const char *key,
int (*fn)(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] 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 an
* errno value is set appropiately.
*/
int xbps_callback_array_iter_reverse_in_dict(prop_dictionary_t dict,
const char *key,
int (*fn)(prop_object_t, void *, bool *),
void *arg);
/**
* Finds the proplib's dictionary associated with a package, by looking
* it via its name in a proplib dictionary.
*
* @param[in] dict Proplib dictionary to look for the package dictionary.
* @param[in] key Key associated with the array that stores package's dictionary.
* @param[in] pkgname Package name to look for.
*
* @return The package's proplib dictionary on success, NULL otherwise and
* errno is set appropiately.
*/
prop_dictionary_t xbps_find_pkg_in_dict_by_name(prop_dictionary_t dict,
const char *key,
const char *pkgname);
/**
* Finds the proplib's dictionary associated with a package, by looking
* at it via a package pattern in a proplib dictionary.
*
* @param[in] dict Proplib dictionary to look for the package dictionary.
* @param[in] key Key associated with the array storing the package's dictionary.
* @param[in] pattern Package pattern to match.
*
* @return The package's proplib dictionary on success, NULL otherwise
* and errno is set appropiately.
*/
prop_dictionary_t xbps_find_pkg_in_dict_by_pattern(prop_dictionary_t dict,
const char *key,
const char *pattern);
/**
* Finds the package's proplib dictionary in a plist file by specifying
* a package name.
*
* @param[in] plist Path to a plist file.
* @param[in] key Proplib array's key name.
* @param[in] pkgname Package name to match in array.
*
* @return The package's proplib dictionary on success, NULL otherwise and
* errno is set appropiately. Returned dictionary is copied via
* prop_dictionary_copy(), which means that caller is responsible to
* release the object with prop_object_release() when done.
*/
prop_dictionary_t xbps_find_pkg_dict_from_plist_by_name(const char *plist,
const char *key,
const char *pkgname);
/**
* Finds the package's proplib dictionary in a plist file by specifying
* a package pattern.
*
* @param[in] plist Path to a plist file.
* @param[in] key Proplib array's key name.
* @param[in] pattern Package pattern to match in array.
*
* @return The package's proplib dictionary on success, NULL otherwise and
* errno is set appropiately. Returned dictionary should be released with
* prop_object_release() when it's not any longer needed.
*/
prop_dictionary_t xbps_find_pkg_dict_from_plist_by_pattern(const char *plist,
const char *key,
const char *pattern);
/**
* Finds a package's dictionary searching in the registered packages
* database by using a package name or a package pattern.
*
* @param[in] str Package name or package pattern.
* @param[in] bypattern Set it to true to find the package dictionary
* by using a package pattern. If false, \a str is assumed to be a package name.
*
* @return The package's dictionary on success, NULL otherwise and
* errno is set appropiately. Returned dictionary is copied via
* prop_dictionary_copy(), which means that caller is responsible to
* release the object with prop_object_release() when done.
*/
prop_dictionary_t xbps_find_pkg_dict_installed(const char *str,
bool bypattern);
/**
* Finds a virtual package's dictionary searching in the registered packages
* database by using a package name or a package pattern.
*
* @param[in] str Virtual package name or package pattern to match.
* @param[in] bypattern Set it to true to find the package dictionary
* by using a package pattern. If false, \a str is assumed to be a package name.
*
* @return The virtual package's dictionary on success, NULL otherwise and
* errno is set appropiately. Returned dictionary is copied via
* prop_dictionary_copy(), which means that caller is responsible to
* release the object with prop_object_release() when done.
*/
prop_dictionary_t xbps_find_virtualpkg_dict_installed(const char *str,
bool bypattern);
/**
* 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.
*
* @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);
/**
* Finds a package dictionary in a proplib array by matching a package name.
*
* @param[in] array The proplib array where to look for.
* @param[in] name The package name to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
prop_dictionary_t xbps_find_pkg_in_array_by_name(prop_array_t array,
const char *name);
/**
* Finds a package dictionary in a proplib array by matching a package pattern.
*
* @param[in] array The proplib array where to look for.
* @param[in] pattern The package pattern to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
prop_dictionary_t xbps_find_pkg_in_array_by_pattern(prop_array_t array,
const char *pattern);
/**
* Finds a virtual package dictionary in a proplib array by matching a
* package name.
*
* @param[in] array The proplib array where to look for.
* @param[in] name The virtual package name to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
prop_dictionary_t xbps_find_virtualpkg_in_array_by_name(prop_array_t array,
const char *name);
/**
* Finds a virtual package dictionary in a proplib array by matching a
* package pattern.
*
* @param[in] array The proplib array where to look for.
* @param[in] pattern The virtual package pattern to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
prop_dictionary_t xbps_find_virtualpkg_in_array_by_pattern(prop_array_t array,
const char *pattern);
/**
* Match a package name in the specified array of strings.
*
* @param[in] array The proplib array where to look for.
* @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 where to look for.
* @param[in] pattern The package pattern to match.
*
* @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 string (exact match) in the specified array of strings.
*
* @param[in] array The proplib array where to look for.
* @param[in] val The value of string to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_match_string_in_array(prop_array_t array, const char *val);
/**
* Gets a proplib object iterator associated with an array, contained
* in a proplib dictionary matching a 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);
/**
* Get a proplib object dictionary associated with the installed package
* \a pkgname, by internalizing its plist file defined by \a plist.
*
* @param[in] pkgname Package name of installed package.
* @param[in] plist Package metadata property list file.
*
* @return The proplib object dictionary on success, NULL otherwise and
* errno is set appropiately.
*/
prop_dictionary_t xbps_dictionary_from_metadata_plist(const char *pkgname,
const char *plist);
/**
* Removes the package's proplib dictionary matching \a pkgname
* in a plist file.
*
* @param[in] name Package name to match in plist's dictionary.
* @param[in] plist Path to a plist file.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_remove_pkg_dict_from_plist_by_name(const char *name,
const char *plist);
/**
* Removes the package's proplib dictionary matching \a pkgname
* in a proplib array.
*
* @param[in] array Proplib array where to look for.
* @param[in] name Package name to match in the array.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_remove_pkg_from_array_by_name(prop_array_t array, const char *name);
/**
* Removes the package's proplib dictionary matching \a pkgname,
* in an array with key \a key stored in a proplib dictionary.
*
* @param[in] dict Proplib dictionary storing the proplib array.
* @param[in] key Key associated with the proplib array.
* @param[in] name Package name to look for.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_remove_pkg_from_dict_by_name(prop_dictionary_t dict,
const char *key,
const char *name);
/**
* Removes a string from a proplib's array.
*
* @param[in] array Proplib array where to look for.
* @param[in] str String to match in the array.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_remove_string_from_array(prop_array_t array, const char *str);
/**
* Removes a string from a proplib's array matched by a package name.
*
* @param[in] array Proplib array where to look for.
* @param[in] name Package name to match.
*
* @return true on success, false otherwise and errno is set appropiately.
*/
bool xbps_remove_pkgname_from_array(prop_array_t array, const char *name);
/**
* Replaces a dictionary with another dictionary in \a dict, in the
* array \array by matching its "pkgname" object with \a pkgname.
*
* @param[in] array Proplib array where to look for.
* @param[in] dict Proplib dictionary to be added in \a array.
* @param[in] pkgname Package name to be matched.
*
* @return 0 on success, EINVAL if dictionary couldn't be set in
* array or ENOENT if no match.
*/
int xbps_array_replace_dict_by_name(prop_array_t array,
prop_dictionary_t dict,
const char *pkgname);
/*@}*/
/** @addtogroup purge */
/*@{*/
/**
* Purge an installed package.
*
* @param[in] pkgname Package name to match.
* @param[in] check_state Set it to true to check that package
* is in XBPS_PKG_STATE_CONFIG_FILES state.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_purge_pkg(const char *pkgname, bool check_state);
/**
* Purge all installed packages. Packages that aren't in
* XBPS_PKG_STATE_CONFIG_FILES state will be ignored.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_purge_packages(void);
/*@}*/
/** @addtogroup pkg_register */
/*@{*/
/**
* Register a package into the installed packages database.
*
* @param[in] pkg_dict A dictionary with the following objects:
* \a pkgname, \a version, \a pkgver, \a short_desc (string),
* \a automatic-install (bool) and optionally \a provides (array of strings).
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_register_pkg(prop_dictionary_t pkg_dict);
/**
* Unregister a package from the package database.
*
* @param[in] pkgname Package name.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_unregister_pkg(const char *pkgname);
/*@}*/
/** @addtogroup pkg_remove */
/*@{*/
/**
* Remove an installed package.
*
* @param[in] pkgname Package name to match.
* @param[in] version Package version associated.
* @param[in] update If true, some steps will be skipped. See in the
* detailed description above for more information.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_remove_pkg(const char *pkgname, const char *version, bool update);
/**
* Remove files defined in a proplib array as specified by \a key
* of an installed package.
*
* @param[in] dict Proplib dictionary internalized from package's
* <b>XBPS_PKGFILES</b> definition in package's metadata directory.
* The image in Detailed description shows off its structure.
* @param[in] key Key of the array object to match, valid values are:
* <b>files</b>, <b>dirs</b>, <b>links</b> and <b>conf_files</b>.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_remove_pkg_files(prop_dictionary_t dict, const char *key);
/*@}*/
/** @addtogroup repo_pkgs */
/*@{*/
/**
* Finds a package by a pattern and enqueues it into
* the transaction dictionary for future use. The first repository in
* the pool that matched the pattern wins.
*
* @note The function name might be misleading, but is correct because
* if package is found, it will be marked as "going to be installed".
*
* @param pkgpattern Package name or pattern to find.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_repository_install_pkg(const char *pkgpattern);
/**
* Marks a package as "going to be updated" in the transaction dictionary.
* All repositories in the pool will be used, and if a newer version
* is available the package dictionary will be enqueued.
*
* @param pkgname The package name to update.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_repository_update_pkg(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.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_repository_update_packages(void);
/*@}*/
/** @addtogroup transdict */
/*@{*/
/**
* 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.
*
* @return The proplib transaction dictionary on success, otherwise NULL
* and errno is set appropiately. ENXIO if the transaction
* dictionary and the missing deps array were not created. ENODEV if
* there are missing dependencies or any other if there was an error
* while sorting packages or computing the transaction size.
*
* @note
* - This function will set errno to ENXIO if xbps_repository_install_pkg()
* xbps_repository_update_pkg() functions were not called previously.
*/
prop_dictionary_t xbps_transaction_prepare(void);
/**
* Commit a transaction. The transaction dictionary contains all steps
* to be executed in the transaction, as returned by xbps_transaction_prepare().
*
* @param[in] transd The transaction dictionary.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_transaction_commit(prop_dictionary_t transd);
/**
* Returns the missing deps array if xbps_repository_install_pkg()
* or xbps_repository_update_pkg() failed to find required packages
* in registered repositories.
*
* @return The proplib array, NULL if it couldn't be created.
*/
prop_array_t xbps_transaction_missingdeps_get(void);
/*@}*/
/** @addtogroup plist_fetch */
/*@{*/
/**
* Internalizes a plist file in a binary package file stored locally or
* remotely as specified in the URL.
*
* @param[in] url URL to binary package file (full 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_dictionary_metadata_plist_by_url(const char *url,
const char *plistf);
/*@}*/
/** @addtogroup repopool */
/*@{*/
/**
* @struct repository_pool_index xbps_api.h "xbps_api.h"
* @brief Repository pool dictionary 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 repository_pool_index {
/**
* @var rpi_repod
*
* Internalized Proplib dictionary of the index plist file
* associated with repository.
*/
prop_dictionary_t rpi_repod;
/**
* @var rpi_uri
*
* URI string associated with repository.
*/
char *rpi_uri;
};
/**
* Synchronizes the package index file for all remote repositories
* as specified in the configuration file, repositories.plist.
*
* @return 0 on success, ENOTSUP if no repositories were found in
* the configuration file.
*/
int xbps_repository_pool_sync(void);
/**
* 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] 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_repository_pool_foreach(
int (*fn)(struct repository_pool_index *, 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 set in configuration file.
*
* @param[in] pkg Package pattern or name.
* @param[in] bypattern True if \a pkg is a pattern, false if it is a pkgname.
* @param[in] best True to find the best version available in repo, false to
* fetch the first package found matching its pkgname.
*
* @return The package dictionary if found, NULL otherwise.
*/
prop_dictionary_t
xbps_repository_pool_find_pkg(const char *pkg, bool bypattern, bool best);
/**
* Finds a package dictionary in repository pool by specifying a
* package pattern or a package name. Only virtual packages set in
* configuration file will be matched.
*
* @param[in] pkg Virtual package pattern or name.
* @param[in] bypattern True if \a pkg is a pattern, false if it is a pkgname.
* @param[in] best True to find the best version available in repo, false to
* fetch the first package found matching its pkgname.
*
* @return The package dictionary if found, NULL otherwise.
*/
prop_dictionary_t
xbps_repository_pool_find_virtualpkg(const char *pkg,
bool bypattern, bool best);
/**
* Iterate over the the repository pool and search for a metadata plist
* file in a binary package named 'pkgname'. If a package is matched by
* \a pkgname, the plist file \a plistf will be internalized into a
* proplib dictionary.
*
* The first repository that has it wins and the loop is stopped.
* This will work locally and remotely, thanks to libarchive and
* libfetch!
*
* @param[in] pkgname Package name to match.
* @param[in] plistf Plist file name to match.
*
* @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_repository_pool_dictionary_metadata_plist(const char *pkgname,
const char *plistf);
/*@}*/
/** @addtogroup reposync */
/*@{*/
/**
* Syncs the package index file for a remote repository as specified
* by the \a uri argument (if necessary).
*
* @param[in] uri URI to a remote repository.
*
* @return -1 on error (errno is set appropiately), 0 if transfer was
* not necessary (local/remote size/mtime matched) or 1 if
* downloaded successfully.
*/
int xbps_repository_sync_pkg_index(const char *uri);
/*@}*/
/** @addtogroup pkgstates */
/*@{*/
/**
* @enum pkg_state_t
*
* Integer representing a state on which a package may be. Possible
* values for this are:
*
* <b>XBPS_PKG_STATE_HALF_UNPACKED</b>: Package was being unpacked
* but didn't finish properly.
*
* <b>XBPS_PKG_STATE_UNPACKED</b>: Package has been unpacked correctly
* but has not been configured due to unknown reasons.
*
* <b>XBPS_PKG_STATE_INSTALLED</b>: Package has been installed successfully.
*
* <b>XBPS_PKG_STATE_BROKEN</b>: not yet used.
*
* <b>XBPS_PKG_STATE_CONFIG_FILES</b>: Package has been removed but not
* yet purged.
*
* <b>XBPS_PKG_STATE_NOT_INSTALLED</b>: 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_CONFIG_FILES,
XBPS_PKG_STATE_NOT_INSTALLED,
XBPS_PKG_STATE_HALF_UNPACKED
} pkg_state_t;
/**
* Gets package state from package \a pkgname, and sets its state
* into \a state.
*
* @param[in] pkgname Package name.
* @param[out] state Package state returned.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_pkg_state_installed(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] pkgname Package name.
* @param[in] version Package version (optional).
* @param[in] pkgver Package name/version touple (optional).
* @param[in] state Package state to be set.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_set_pkg_state_installed(const char *pkgname,
const char *version,
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 unpack */
/*@{*/
/**
* Unpacks a binary package into specified root directory.
*
* @param[in] trans_pkg_dict Package proplib dictionary as stored in the
* \a packages array returned by the transaction dictionary.
*
* @return 0 on success, otherwise an errno value.
*/
int xbps_unpack_binary_pkg(prop_dictionary_t trans_pkg_dict);
/*@}*/
/** @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);
/**
* Returns a string with the sha256 hash for the file specified
* by \a file in an array with key \a key in the proplib dictionary
* \a d.
*
* @param[in] d Proplib dictionary to look in.
* @param[in] key Array key to match in dictionary.
* @param[in] file Pathname to a file.
*
* @return The sha256 hash string if found, NULL otherwise
* and errno is set appropiately.
*/
const char *xbps_file_hash_dictionary(prop_dictionary_t d,
const char *key,
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 file matches the sha256 hash specified in the array
* with key \a key in the proplib dictionary \a d.
*
* @param[in] d Proplib dictionary to look in.
* @param[in] key Proplib array key to match for file.
* @param[in] file Pathname to a file.
*
* @return 0 if hash is matched, -1 on error and 1 if no match.
*/
int xbps_file_hash_check_dictionary(prop_dictionary_t d,
const char *key,
const char *file);
/**
* Checks if a package is currently installed by matching a package
* pattern string.
*
* @param[in] pkg Package pattern used to find the package.
*
* @return -1 on error (errno set appropiately), 0 if package pattern
* didn't match installed package, 1 if \a pkg pattern fully
* matched installed package.
*/
int xbps_check_is_installed_pkg_by_pattern(const char *pkg);
/**
* Checks if package \a pkgname is currently installed.
*
* @param[in] pkgname Package name.
*
* @return True if \a pkgname is installed, false otherwise.
*/
bool xbps_check_is_installed_pkg_by_name(const char *pkgname);
/**
* 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_check_is_repository_uri_remote(const char *uri);
/**
* Gets the full URI to a binary package file as returned by a
* package dictionary from a repository in \a pkgd, by looking at the
* repository location object "repository" in its dictionary.
*
* @param[in] pkgd Package dictionary stored in a transaction dictionary.
* @param[in] repoloc Repository URL location string.
*
* @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_path_from_repository_uri(prop_dictionary_t pkgd, const char *repoloc);
/**
* Gets the full path to a repository package index plist file, as
* specified by \a uri.
*
* @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(const char *uri);
/**
* Gets the name of a package string. Package strings are composed
* by a @<pkgname@>/@<version@> pair and separated by the <em>minus</em>
* sign, i.e <b>foo-2.0</b>.
*
* @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 <b>'><='</b> to split components, i.e <b>foo>=2.0</b>,
* <b>blah<1.0</b>, <b>blob==2.0</b>, 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 <b>foo-2.0</b>.
*
* @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);
/**
* Gets the package version revision in a package string.
*
* @param[in] pkg Package string, i.e <b>foo-2.0_1</b>.
*
* @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);
/**
* 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);
/*@}*/
__END_DECLS
#endif /* !_XBPS_API_H_ */
Reference in New Issue View Git Blame Copy Permalink