<commit_before>/*-
 * Copyright (c) 2008-2012 <NAME>.
 * 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>
#include <confuse.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.4"

#define XBPS_API_VERSION	"20120122-1"
#define XBPS_VERSION		"0.12"

/**
 * @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_PKGDB
 * Filename for the master package database.
 */
#define XBPS_PKGDB		"pkgdb.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		"rindex.plist"

/**
 * @def XBPS_PKGINDEX_FILES
 * Filename for the repository package index files property list.
 */
#define XBPS_PKGINDEX_FILES	"rindex-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_INSTALL_MANUAL
 * Enabled manual install mode for a package and all dependencies
 * installed direct and indirectly.
 */
#define XBPS_FLAG_INSTALL_MANUAL	0x00000020

/**
 * @def XBPS_FLAG_DEBUG
 * Enable debug mode to output debugging printfs to stdout/stderr.
 */
#define XBPS_FLAG_DEBUG 		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

/**
 * @def XBPS_TRANS_FLUSH
 * Default number of packages to be processed in a transaction to
 * trigger a flush to the master package database XBPS_REGPKGDB.
 */
#define XBPS_TRANS_FLUSH		5

__BEGIN_DECLS

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 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_CONFIG_FILE: a package configuration file is being processed.
 * - XBPS_STATE_REGISTER: a package is being registered.
 * - XBPS_STATE_UNREGISTER: a package is being unregistered.
 * - 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_REGISTER_FAIL: package register has failed.
 * - XBPS_STATE_UNREGISTER_FAIL: package unregister 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_REGISTER,
	XBPS_STATE_UNREGISTER,
	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_REGISTER_FAIL,
	XBPS_STATE_UNREGISTER_FAIL,
	XBPS_STATE_REPOSYNC_FAIL
} 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.
 */
struct xbps_state_cb_data {
	/**
	 * @var state
	 *
	 * Returned xbps state (set internally, read-only).
	 */
	xbps_state_t state;
	/**
	 * @var desc
	 *
	 * XBPS state string description (set internally, read-only).
	 */
	const char *desc;
	/**
	 * @var pkgname
	 *
	 * Package name string (set internally, read-only).
	 */
	const char *pkgname;
	/**
	 * @var version
	 *
	 * Package version string (set internally, read-only).
	 */
	const char *version;
	/**
	 * @var err
	 *
	 * XBPS 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 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 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.
	 */
	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_metadata
	 *
	 * If true "entry" is a metadata file.
	 */
	bool entry_is_metadata;
	/**
	 * @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 array with the master package database
	 * stored in XBPS_META_PATH/XBPS_PKGDB.
	 */
	prop_array_t pkgdb;
	/**
	 * @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)(const 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)(const 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)(const 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;
	/**
	 * @private
	 */
	char *cachedir_priv;
	/**
	 * @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 transaction_frequency_flush
	 *
	 * Number of packages to be processed in a transaction to
	 * trigger a flush to the master databases.
	 */
	uint16_t transaction_frequency_flush;
	/**
	 * @var flags
	 *
	 * Flags to be set globally, possible values:
	 *
	 * - XBPS_FLAG_VERBOSE
	 * - XBPS_FLAG_FORCE
	 */
	int flags;
};

/**
 * 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 strcucture.
 * @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.
 */
void xbps_end(void);

/**
 * Returns a pointer to the xbps_handle structure passed to xbps_init().
 *
 * @return A pointer the struct xbps_handle passed to xbps_init().
 */
struct xbps_handle *xbps_handle_get(void);
<commit_msg>xbps_api.h: fix xbps_handle::flags possible values.<commit_after>/*-
 * Copyright (c) 2008-2012 <NAME>.
 * 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>
#include <confuse.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.4"

#define XBPS_API_VERSION	"20120122-1"
#define XBPS_VERSION		"0.12"

/**
 * @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_PKGDB
 * Filename for the master package database.
 */
#define XBPS_PKGDB		"pkgdb.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		"rindex.plist"

/**
 * @def XBPS_PKGINDEX_FILES
 * Filename for the repository package index files property list.
 */
#define XBPS_PKGINDEX_FILES	"rindex-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_INSTALL_MANUAL
 * Enabled manual install mode for a package and all dependencies
 * installed direct and indirectly.
 */
#define XBPS_FLAG_INSTALL_MANUAL	0x00000020

/**
 * @def XBPS_FLAG_DEBUG
 * Enable debug mode to output debugging printfs to stdout/stderr.
 */
#define XBPS_FLAG_DEBUG 		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

/**
 * @def XBPS_TRANS_FLUSH
 * Default number of packages to be processed in a transaction to
 * trigger a flush to the master package database XBPS_REGPKGDB.
 */
#define XBPS_TRANS_FLUSH		5

__BEGIN_DECLS

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 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_CONFIG_FILE: a package configuration file is being processed.
 * - XBPS_STATE_REGISTER: a package is being registered.
 * - XBPS_STATE_UNREGISTER: a package is being unregistered.
 * - 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_REGISTER_FAIL: package register has failed.
 * - XBPS_STATE_UNREGISTER_FAIL: package unregister 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_REGISTER,
	XBPS_STATE_UNREGISTER,
	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_REGISTER_FAIL,
	XBPS_STATE_UNREGISTER_FAIL,
	XBPS_STATE_REPOSYNC_FAIL
} 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.
 */
struct xbps_state_cb_data {
	/**
	 * @var state
	 *
	 * Returned xbps state (set internally, read-only).
	 */
	xbps_state_t state;
	/**
	 * @var desc
	 *
	 * XBPS state string description (set internally, read-only).
	 */
	const char *desc;
	/**
	 * @var pkgname
	 *
	 * Package name string (set internally, read-only).
	 */
	const char *pkgname;
	/**
	 * @var version
	 *
	 * Package version string (set internally, read-only).
	 */
	const char *version;
	/**
	 * @var err
	 *
	 * XBPS 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 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 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.
	 */
	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_metadata
	 *
	 * If true "entry" is a metadata file.
	 */
	bool entry_is_metadata;
	/**
	 * @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 array with the master package database
	 * stored in XBPS_META_PATH/XBPS_PKGDB.
	 */
	prop_array_t pkgdb;
	/**
	 * @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)(const 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)(const 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)(const 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;
	/**
	 * @private
	 */
	char *cachedir_priv;
	/**
	 * @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 transaction_frequency_flush
	 *
	 * Number of packages to be processed in a transaction to
	 * trigger a flush to the master databases.
	 */
	uint16_t transaction_frequency_flush;
	/**
	 * @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
	 *  - XBPS_FLAG_INSTALL_MANUAL
	 */
	int flags;
};

/**
 * 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 strcucture.
 * @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.
 */
void xbps_end(void);

/**
 * Returns a pointer to the xbps_handle structure passed to xbps_init().
 *
 * @return A pointer the struct xbps_handle passed to xbps_init().
 */
struct xbps_handle *xbps_handle_get(void);

{'fraction_non_alphanumeric': 0.08481168769566455, 'fraction_numerical': 0.006640736173038611, 'mean_word_length': 3.844362745098039, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 8, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6156158', 'n_tokens_mistral': 11302, 'n_tokens_neox': 10562, 'n_words': 3336}