=head1 NAME

pacutils - utility library for libalpm front-ends

=head1 SYNOPSIS

pu_config_t config = pu_config_new_from_file("/etc/pacman.conf"); alpm_handle_t handle = pu_initialize_handle_from_config(config); alpm_list_t *syncdbs = pu_register_syncdbs(config->repos);

alpm_option_set_progresscb(handle, pu_cb_progress, NULL); alpm_option_set_dlcb(handle, pu_cb_download, NULL);

/ do something with handle... /

alpm_list_free(sync_dbs); alpm_release(handle); pu_config_free(config);

B encapsulates several of the common tasks that most users of I need to perform, such as parsing F and providing standard output functions for callbacks. The included programs can also be used as guides for how to accomplish particular tasks using I.

=head1 DESCRIPTION

=head2 Configuration Parsing

=over

=item pu_config_t pu_config_new_from_file(const char filename);

Parse a I configuration file into a C structure. B this is the final configuration as parsed by I. C directives will be processed, defaults are set, C<$repo> and C<$arch> will be replaced in C directives and C will be replaced if set to C.

=item void pu_config_free(pu_config_t *config);

=item alpm_handle_t pu_initialize_handle_from_config(pu_config_t config);

=back

=head2 Repositories

=over

=item alpm_db_t pu_register_syncdb(pu_repo_t repo);

=item alpm_list_t pu_register_syncdbs(alpm_list_t repos);

=item void pu_repo_free(pu_repo_t *repo);

=back

=head2 Callbacks

=over

=item const char *pu_msg_progress(alpm_progress_t event);

=item void pu_cb_progress(alpm_progress_t event, const char *pkgname, int percent, size_t total, size_t current);

=item void pu_cb_download(const char *filename, off_t xfered, off_t total);

=back

=head2 MTREE

Package mtree reading functions are provided to fill gaps in libarchive's mtree reader, notably C and C which are currently not read by libarchive. Support is incomplete and libalpm's mtree reader should be used whenever possible.

=over

=item pu_mtree_t

typedef struct pu_mtree_t { char *path; char type[16]; uid_t uid; gid_t gid; mode_t mode; off_t size; char md5digest[33]; char sha256digest[65]; } pu_mtree_t;

=item alpm_list_t pu_mtree_load_pkg_mtree(alpm_handle_t handle, alpm_pkg_t *pkg);

Returns a list of mtree entries for C.

=item void pu_mtree_free(pu_mtree_t *mtree);

=back

=head2 Pkgspec

A C is a string consisting of sufficient information to uniquely identify an individual package. Currently recognized formats are:

=over

=item /

local/pacman core/pacman

=item ://

ftp://ftp.archlinux.org/core/os/x86_64/pacman-4.1.2-5-x86_64.pkg.tar.xz file:///var/cache/pacman/pkg/pacman-4.1.2-5-x86_64.pkg.tar.xz

=back

=head1 PROGRAMS

There are several programs located in F. Refer to each program's documentation for more information.

=over

=item paccapability

Query compile time libalpm features.

paccapability signatures >/dev/null && echo "libalpm built with signature support"

=item pacconf

Query I's configuration file. Useful for shell scripts:

dbpath=$(pacconf dbpath) color=$(pacconf color) [[ -n $color ]] && ... # print something in color

B this is the final configuration as parsed by I. C directives will be processed, defaults are set, C<$repo> and C<$arch> will be replaced in C directives and C will be replaced if set to C.

=item pacini

Query a I-style INI configuration file.

=item pacsync

Updates repository databases. Equivalent to C<pacman -Sy>.

=item pactrans, pacinstall, pacremove

Install/remove packages in a single transaction.

B I support for installation and removal in a single transaction is flaky; some options may be ignored.

=item pacinfo

Display information for packages, similar to C<pacman -Qi> and C<pacman -Si>. Input should be a list of pkgspecs.

=item pacsift

Package search/filter tool. Combine with B to display brief package information similar to C<pacman -Qs> and C<pacman -Ss>:

pacsift --name pacman | pacinfo --short

=item pacfile

Display information about a file. Includes information from C<pacman -Qo>, C<pacman -Qkk>, and C<pacman -Qii>. Expects input to match the path stored in B's database with or without the root prepended. I can be used to call with relative paths or paths containing symbolic links:

pacfile "$(realpath ./foo)"

=item pacrepairfile

Repair file properties based on pacman's database.

find /usr/share | pacrepairfile --uid --gid

=item paclock

Provide script-friendly database locking and unlocking.

paclock --run -- paccache --dryrun --verbose

=item paclog

Filter pacman log entries. If multiple filters are provided, the entries returned are the union of all filters. Output can be piped to a second instance to find the intersection of filters instead:

paclog --caller ALPM | paclog --after "$(date -I --date '3 days ago')"

=item pacrepairdb

Attempt to repair broken entries in libalpm's database by reinstalling affected packages from the cache:

paccheck --files --db-files --list-broken | pacrepairdb

=item pacreport

Generate a report of installed packages including:

=over

=item unneeded packages installed explicitly

=item unneeded packages installed as dependencies

=item installed packages not in a repository

=item packages missing from specified groups

=item missing package files

=item cache directory sizes

=item packages sizes include dependencies not needed by other packages

=back

=item paccheck

Verify installed packages against I's database.

=back

=head1 BUGS

Not implemented yet:

=over

=item error reporting

=item proper handling of transaction flags with combined transactions

=back

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2012-2016 Andrew Gregory

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.