alpm_api_packages(3)

NAME
alpm_api_packages - Package Functions

 - Functions to manipulate libalpm packages.

SYNOPSIS

  Modules
Transaction Functions
Functions to manipulate libalpm transactions.
Dependency Functions
Functions dealing with libalpm representation of dependency information.

  Functions
int alpm_pkg_load (alpm_handle_t *handle, const char *filename, int full, int level, alpm_pkg_t **pkg)
Create a package from a file.
alpm_pkg_t * alpm_pkg_find (alpm_list_t *haystack, const char *needle)
Find a package in a list by name.
int alpm_pkg_free (alpm_pkg_t *pkg)
Free a package.
int alpm_pkg_checkmd5sum (alpm_pkg_t *pkg)
Check the integrity (with md5) of a package from the sync cache.
int alpm_pkg_vercmp (const char *a, const char *b)
Compare two version strings and determine which one is 'newer'.
alpm_list_t * alpm_pkg_compute_requiredby (alpm_pkg_t *pkg)
Computes the list of packages requiring a given package.
alpm_list_t * alpm_pkg_compute_optionalfor (alpm_pkg_t *pkg)
Computes the list of packages optionally requiring a given package.
int alpm_pkg_should_ignore (alpm_handle_t *handle, alpm_pkg_t *pkg)
Test if a package should be ignored.
alpm_file_t * alpm_filelist_contains (alpm_filelist_t *filelist, const char *path)
Determines whether a package filelist contains a given path.
int alpm_pkg_check_pgp_signature (alpm_pkg_t *pkg, alpm_siglist_t *siglist)
Check the PGP signature for the given package file.
int alpm_db_check_pgp_signature (alpm_db_t *db, alpm_siglist_t *siglist)
Check the PGP signature for the given database.
int alpm_siglist_cleanup (alpm_siglist_t *siglist)
Clean up and free a signature result list.
int alpm_decode_signature (const char *base64_data, unsigned char **data, size_t *data_len)
Decode a loaded signature in base64 form.
int alpm_extract_keyid (alpm_handle_t *handle, const char *identifier, const unsigned char *sig, const size_t len, alpm_list_t **keys)
Extract the Issuer Key ID from a signature.
alpm_list_t * alpm_find_group_pkgs (alpm_list_t *dbs, const char *name)
Find group members across a list of databases.
alpm_pkg_t * alpm_sync_get_new_version (alpm_pkg_t *pkg, alpm_list_t *dbs_sync)
Check for new version of pkg in sync repos (only the first occurrence is considered in sync)

  Package Property Accessors
Any pointer returned by these functions points to internal structures allocated by libalpm.

They should not be freed nor modified in any way.
const char * alpm_pkg_get_filename (alpm_pkg_t *pkg)
Gets the name of the file from which the package was loaded.
const char * alpm_pkg_get_base (alpm_pkg_t *pkg)
Returns the package base name.
const char * alpm_pkg_get_name (alpm_pkg_t *pkg)
Returns the package name.
const char * alpm_pkg_get_version (alpm_pkg_t *pkg)
Returns the package version as a string.
alpm_pkgfrom_t alpm_pkg_get_origin (alpm_pkg_t *pkg)
Returns the origin of the package.
const char * alpm_pkg_get_desc (alpm_pkg_t *pkg)
Returns the package description.
const char * alpm_pkg_get_url (alpm_pkg_t *pkg)
Returns the package URL.
alpm_time_t alpm_pkg_get_builddate (alpm_pkg_t *pkg)
Returns the build timestamp of the package.
alpm_time_t alpm_pkg_get_installdate (alpm_pkg_t *pkg)
Returns the install timestamp of the package.
const char * alpm_pkg_get_packager (alpm_pkg_t *pkg)
Returns the packager's name.
const char * alpm_pkg_get_md5sum (alpm_pkg_t *pkg)
Returns the package's MD5 checksum as a string.
const char * alpm_pkg_get_sha256sum (alpm_pkg_t *pkg)
Returns the package's SHA256 checksum as a string.
const char * alpm_pkg_get_arch (alpm_pkg_t *pkg)
Returns the architecture for which the package was built.
off_t alpm_pkg_get_size (alpm_pkg_t *pkg)
Returns the size of the package.
off_t alpm_pkg_get_isize (alpm_pkg_t *pkg)
Returns the installed size of the package.
alpm_pkgreason_t alpm_pkg_get_reason (alpm_pkg_t *pkg)
Returns the package installation reason.
alpm_list_t * alpm_pkg_get_licenses (alpm_pkg_t *pkg)
Returns the list of package licenses.
alpm_list_t * alpm_pkg_get_groups (alpm_pkg_t *pkg)
Returns the list of package groups.
alpm_list_t * alpm_pkg_get_depends (alpm_pkg_t *pkg)
Returns the list of package dependencies as alpm_depend_t.
alpm_list_t * alpm_pkg_get_optdepends (alpm_pkg_t *pkg)
Returns the list of package optional dependencies.
alpm_list_t * alpm_pkg_get_checkdepends (alpm_pkg_t *pkg)
Returns a list of package check dependencies.
alpm_list_t * alpm_pkg_get_makedepends (alpm_pkg_t *pkg)
Returns a list of package make dependencies.
alpm_list_t * alpm_pkg_get_conflicts (alpm_pkg_t *pkg)
Returns the list of packages conflicting with pkg.
alpm_list_t * alpm_pkg_get_provides (alpm_pkg_t *pkg)
Returns the list of packages provided by pkg.
alpm_list_t * alpm_pkg_get_replaces (alpm_pkg_t *pkg)
Returns the list of packages to be replaced by pkg.
alpm_filelist_t * alpm_pkg_get_files (alpm_pkg_t *pkg)
Returns the list of files installed by pkg.
alpm_list_t * alpm_pkg_get_backup (alpm_pkg_t *pkg)
Returns the list of files backed up when installing pkg.
alpm_db_t * alpm_pkg_get_db (alpm_pkg_t *pkg)
Returns the database containing pkg.
const char * alpm_pkg_get_base64_sig (alpm_pkg_t *pkg)
Returns the base64 encoded package signature.
int alpm_pkg_get_validation (alpm_pkg_t *pkg)
Returns the method used to validate a package during install.
void * alpm_pkg_changelog_open (alpm_pkg_t *pkg)
Open a package changelog for reading.
size_t alpm_pkg_changelog_read (void *ptr, size_t size, const alpm_pkg_t *pkg, void *fp)
Read data from an open changelog 'file stream'.
int alpm_pkg_changelog_close (const alpm_pkg_t *pkg, void *fp)
Close a package changelog for reading.
struct archive * alpm_pkg_mtree_open (alpm_pkg_t *pkg)
Open a package mtree file for reading.
int alpm_pkg_mtree_next (const alpm_pkg_t *pkg, struct archive *archive, struct archive_entry **entry)
Read next entry from a package mtree file.
int alpm_pkg_mtree_close (const alpm_pkg_t *pkg, struct archive *archive)
Close a package mtree file for reading.
int alpm_pkg_has_scriptlet (alpm_pkg_t *pkg)
Returns whether the package has an install scriptlet.
off_t alpm_pkg_download_size (alpm_pkg_t *newpkg)
Returns the size of download.
int alpm_pkg_set_reason (alpm_pkg_t *pkg, alpm_pkgreason_t reason)
Set install reason for a package in the local database.

  Common Transactions
int alpm_sync_sysupgrade (alpm_handle_t *handle, int enable_downgrade)
Search for packages to upgrade and add them to the transaction.
int alpm_add_pkg (alpm_handle_t *handle, alpm_pkg_t *pkg)
Add a package to the transaction.
int alpm_remove_pkg (alpm_handle_t *handle, alpm_pkg_t *pkg)
Add a package removal action to the transaction.

Detailed Description

Functions to manipulate libalpm packages.

Function Documentation

  int alpm_add_pkg (alpm_handle_t * handle, alpm_pkg_t * pkg)

Add a package to the transaction. If the package was loaded by alpm_pkg_load(), it will be freed upon alpm_trans_release() invocation.

Parameters
    handle the context handle
    pkg the package to add

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

  int alpm_db_check_pgp_signature (alpm_db_t * db, alpm_siglist_t * siglist)

Check the PGP signature for the given database.

Parameters
    db the database to check
    siglist a pointer to storage for signature results

Returns
    a int value : 0 (valid), 1 (invalid), -1 (an error occurred)

  int alpm_decode_signature (const char * base64_data, unsigned char ** data, size_t * data_len)

Decode a loaded signature in base64 form.

Parameters
    base64_data the signature to attempt to decode
    data the decoded data; must be freed by the caller
    data_len the length of the returned data

Returns
    0 on success, -1 on failure to properly decode

References base64_decode().

  int alpm_extract_keyid (alpm_handle_t * handle, const char * identifier, const unsigned char * sig, const size_t len, alpm_list_t ** keys)

Extract the Issuer Key ID from a signature.

Parameters
    sig PGP signature
    len length of signature
    keys a pointer to storage for key IDs

Returns
    0 on success, -1 on error

  alpm_file_t* alpm_filelist_contains (alpm_filelist_t * filelist, const char * path)

Determines whether a package filelist contains a given path. The provided path should be relative to the install root with no leading slashes, e.g. 'etc/localtime'. When searching for directories, the path must have a trailing slash.

Parameters
    filelist a pointer to a package filelist
    path the path to search for in the package

Returns
    a pointer to the matching file or NULL if not found

  alpm_list_t* alpm_find_group_pkgs (alpm_list_t * dbs, const char * name)

Find group members across a list of databases. If a member exists in several databases, only the first database is used. IgnorePkg is also handled.

Parameters
    dbs the list of alpm_db_t *
    name the name of the group

Returns
    the list of alpm_pkg_t * (caller is responsible for alpm_list_free)

References alpm_db_get_group(), alpm_pkg_find(), ALPM_TRANS_FLAG_NEEDED, __alpm_list_t::data, __alpm_list_t::next, and _alpm_group_t::packages.

  int alpm_pkg_changelog_close (const alpm_pkg_t * pkg, void * fp)

Close a package changelog for reading.

  void* alpm_pkg_changelog_open (alpm_pkg_t * pkg)

Open a package changelog for reading. Similar to fopen in functionality, except that the returned 'file stream' could really be from an archive as well as from the database.

Parameters
    pkg the package to read the changelog of (either file or db)

Returns
    a 'file stream' to the package changelog

  size_t alpm_pkg_changelog_read (void * ptr, size_t size, const alpm_pkg_t * pkg, void * fp)

Read data from an open changelog 'file stream'. Similar to fread in functionality, this function takes a buffer and amount of data to read. If an error occurs pm_errno will be set.

Parameters
    ptr a buffer to fill with raw changelog data
    size the size of the buffer
    pkg the package that the changelog is being read from
    fp a 'file stream' to the package changelog

Returns
    the number of characters read, or 0 if there is no more data or an error occurred.

  int alpm_pkg_check_pgp_signature (alpm_pkg_t * pkg, alpm_siglist_t * siglist)

Check the PGP signature for the given package file.

Parameters
    pkg the package to check
    siglist a pointer to storage for signature results

Returns
    a int value : 0 (valid), 1 (invalid), -1 (an error occurred)

  int alpm_pkg_checkmd5sum (alpm_pkg_t * pkg)

Check the integrity (with md5) of a package from the sync cache.

Parameters
    pkg package pointer

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

  alpm_list_t* alpm_pkg_compute_optionalfor (alpm_pkg_t * pkg)

Computes the list of packages optionally requiring a given package. The return value of this function is a newly allocated list of package names (char*), it should be freed by the caller.

Parameters
    pkg a package

Returns
    the list of packages optionally requiring pkg

Computes the list of packages optionally requiring a given package.

  alpm_list_t* alpm_pkg_compute_requiredby (alpm_pkg_t * pkg)

Computes the list of packages requiring a given package. The return value of this function is a newly allocated list of package names (char*), it should be freed by the caller.

Parameters
    pkg a package

Returns
    the list of packages requiring pkg

Computes the list of packages requiring a given package.

  off_t alpm_pkg_download_size (alpm_pkg_t * newpkg)

Returns the size of download. Returns the size of the files that will be downloaded to install a package.

Parameters
    newpkg the new package to upgrade to

Returns
    the size of the download

Returns the size of download.

Parameters
    newpkg the new package to upgrade to

Returns
    the size of the download

  alpm_pkg_t* alpm_pkg_find (alpm_list_t * haystack, const char * needle)

Find a package in a list by name.

Parameters
    haystack a list of alpm_pkg_t
    needle the package name

Returns
    a pointer to the package if found or NULL

References __alpm_list_t::data, and __alpm_list_t::next.

Referenced by alpm_checkdeps(), and alpm_find_group_pkgs().

  int alpm_pkg_free (alpm_pkg_t * pkg)

Free a package.

Parameters
    pkg package pointer to free

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

  const char* alpm_pkg_get_arch (alpm_pkg_t * pkg)

Returns the architecture for which the package was built.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  alpm_list_t* alpm_pkg_get_backup (alpm_pkg_t * pkg)

Returns the list of files backed up when installing pkg.

Parameters
    pkg a pointer to package

Returns
    a reference to a list of alpm_backup_t objects

  const char* alpm_pkg_get_base (alpm_pkg_t * pkg)

Returns the package base name.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  const char* alpm_pkg_get_base64_sig (alpm_pkg_t * pkg)

Returns the base64 encoded package signature.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  alpm_time_t alpm_pkg_get_builddate (alpm_pkg_t * pkg)

Returns the build timestamp of the package.

Parameters
    pkg a pointer to package

Returns
    the timestamp of the build time

  alpm_list_t* alpm_pkg_get_checkdepends (alpm_pkg_t * pkg)

Returns a list of package check dependencies.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  alpm_list_t* alpm_pkg_get_conflicts (alpm_pkg_t * pkg)

Returns the list of packages conflicting with pkg.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  alpm_db_t* alpm_pkg_get_db (alpm_pkg_t * pkg)

Returns the database containing pkg. Returns a pointer to the alpm_db_t structure the package is originating from, or NULL if the package was loaded from a file.

Parameters
    pkg a pointer to package

Returns
    a pointer to the DB containing pkg, or NULL.

  alpm_list_t* alpm_pkg_get_depends (alpm_pkg_t * pkg)

Returns the list of package dependencies as alpm_depend_t.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  const char* alpm_pkg_get_desc (alpm_pkg_t * pkg)

Returns the package description.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  const char* alpm_pkg_get_filename (alpm_pkg_t * pkg)

Gets the name of the file from which the package was loaded.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  alpm_filelist_t* alpm_pkg_get_files (alpm_pkg_t * pkg)

Returns the list of files installed by pkg. The filenames are relative to the install root, and do not include leading slashes.

Parameters
    pkg a pointer to package

Returns
    a pointer to a filelist object containing a count and an array of package file objects

  alpm_list_t* alpm_pkg_get_groups (alpm_pkg_t * pkg)

Returns the list of package groups.

Parameters
    pkg a pointer to package

Returns
    a pointer to an internal list of strings.

Referenced by alpm_pkg_should_ignore().

  alpm_time_t alpm_pkg_get_installdate (alpm_pkg_t * pkg)

Returns the install timestamp of the package.

Parameters
    pkg a pointer to package

Returns
    the timestamp of the install time

  off_t alpm_pkg_get_isize (alpm_pkg_t * pkg)

Returns the installed size of the package.

Parameters
    pkg a pointer to package

Returns
    the total size of files installed by the package.

  alpm_list_t* alpm_pkg_get_licenses (alpm_pkg_t * pkg)

Returns the list of package licenses.

Parameters
    pkg a pointer to package

Returns
    a pointer to an internal list of strings.

  alpm_list_t* alpm_pkg_get_makedepends (alpm_pkg_t * pkg)

Returns a list of package make dependencies.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  const char* alpm_pkg_get_md5sum (alpm_pkg_t * pkg)

Returns the package's MD5 checksum as a string. The returned string is a sequence of 32 lowercase hexadecimal digits.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  const char* alpm_pkg_get_name (alpm_pkg_t * pkg)

Returns the package name.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  alpm_list_t* alpm_pkg_get_optdepends (alpm_pkg_t * pkg)

Returns the list of package optional dependencies.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  alpm_pkgfrom_t alpm_pkg_get_origin (alpm_pkg_t * pkg)

Returns the origin of the package.

Returns
    an alpm_pkgfrom_t constant, -1 on error

  const char* alpm_pkg_get_packager (alpm_pkg_t * pkg)

Returns the packager's name.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  alpm_list_t* alpm_pkg_get_provides (alpm_pkg_t * pkg)

Returns the list of packages provided by pkg.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  alpm_pkgreason_t alpm_pkg_get_reason (alpm_pkg_t * pkg)

Returns the package installation reason.

Parameters
    pkg a pointer to package

Returns
    an enum member giving the install reason.

  alpm_list_t* alpm_pkg_get_replaces (alpm_pkg_t * pkg)

Returns the list of packages to be replaced by pkg.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal list of alpm_depend_t structures.

  const char* alpm_pkg_get_sha256sum (alpm_pkg_t * pkg)

Returns the package's SHA256 checksum as a string. The returned string is a sequence of 64 lowercase hexadecimal digits.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  off_t alpm_pkg_get_size (alpm_pkg_t * pkg)

Returns the size of the package. This is only available for sync database packages and package files, not those loaded from the local database.

Parameters
    pkg a pointer to package

Returns
    the size of the package in bytes.

  const char* alpm_pkg_get_url (alpm_pkg_t * pkg)

Returns the package URL.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  int alpm_pkg_get_validation (alpm_pkg_t * pkg)

Returns the method used to validate a package during install.

Parameters
    pkg a pointer to package

Returns
    an enum member giving the validation method

  const char* alpm_pkg_get_version (alpm_pkg_t * pkg)

Returns the package version as a string. This includes all available epoch, version, and pkgrel components. Use alpm_pkg_vercmp() to compare version strings if necessary.

Parameters
    pkg a pointer to package

Returns
    a reference to an internal string

  int alpm_pkg_has_scriptlet (alpm_pkg_t * pkg)

Returns whether the package has an install scriptlet.

Returns
    0 if FALSE, TRUE otherwise

  int alpm_pkg_load (alpm_handle_t * handle, const char * filename, int full, int level, alpm_pkg_t ** pkg)

Create a package from a file. If full is false, the archive is read only until all necessary metadata is found. If it is true, the entire archive is read, which serves as a verification of integrity and the filelist can be created. The allocated structure should be freed using alpm_pkg_free().

Parameters
    handle the context handle
    filename location of the package tarball
    full whether to stop the load after metadata is read or continue through the full archive
    level what level of package signature checking to perform on the package; note that this must be a '.sig' file type verification
    pkg address of the package pointer

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

  int alpm_pkg_mtree_close (const alpm_pkg_t * pkg, struct archive * archive)

Close a package mtree file for reading.

  int alpm_pkg_mtree_next (const alpm_pkg_t * pkg, struct archive * archive, struct archive_entry ** entry)

Read next entry from a package mtree file.

Parameters
    pkg the package that the mtree file is being read from
    archive the archive structure reading from the mtree file
    entry an archive_entry to store the entry header information

Returns
    0 if end of archive is reached, non-zero otherwise.

Read next entry from a package mtree file.

  struct archive* alpm_pkg_mtree_open (alpm_pkg_t * pkg)

Open a package mtree file for reading.

Parameters
    pkg the local package to read the changelog of

Returns
    a archive structure for the package mtree file

  int alpm_pkg_set_reason (alpm_pkg_t * pkg, alpm_pkgreason_t reason)

Set install reason for a package in the local database. The provided package object must be from the local database or this method will fail. The write to the local database is performed immediately.

Parameters
    pkg the package to update
    reason the new install reason

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

  int alpm_pkg_should_ignore (alpm_handle_t * handle, alpm_pkg_t * pkg)

Test if a package should be ignored. Checks if the package is ignored via IgnorePkg, or if the package is in a group ignored via IgnoreGroup.

Parameters
    handle the context handle
    pkg the package to test

Returns
    1 if the package should be ignored, 0 otherwise

References alpm_list_find(), alpm_pkg_get_groups(), __alpm_list_t::data, and __alpm_list_t::next.

  int alpm_pkg_vercmp (const char * a, const char * b)

Compare two version strings and determine which one is 'newer'. Returns a value comparable to the way strcmp works. Returns 1 if a is newer than b, 0 if a and b are the same version, or -1 if b is newer than a.

Different epoch values for version strings will override any further comparison. If no epoch is provided, 0 is assumed.

Keep in mind that the pkgrel is only compared if it is available on both versions handed to this function. For example, comparing 1.5-1 and 1.5 will yield 0; comparing 1.5-1 and 1.5-2 will yield -1 as expected. This is mainly for supporting versioned dependencies that do not include the pkgrel.

  int alpm_remove_pkg (alpm_handle_t * handle, alpm_pkg_t * pkg)

Add a package removal action to the transaction.

Parameters
    handle the context handle
    pkg the package to uninstall

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

Parameters
    handle the context handle
    pkg the package to uninstall

Returns
    0 on success, -1 on error

  int alpm_siglist_cleanup (alpm_siglist_t * siglist)

Clean up and free a signature result list. Note that this does not free the siglist object itself in case that was allocated on the stack; this is the responsibility of the caller.

Parameters
    siglist a pointer to storage for signature results

Returns
    0 on success, -1 on error

  alpm_pkg_t* alpm_sync_get_new_version (alpm_pkg_t * pkg, alpm_list_t * dbs_sync)

Check for new version of pkg in sync repos (only the first occurrence is considered in sync)

  int alpm_sync_sysupgrade (alpm_handle_t * handle, int enable_downgrade)

Search for packages to upgrade and add them to the transaction.

Parameters
    handle the context handle
    enable_downgrade allow downgrading of packages if the remote version is lower

Returns
    0 on success, -1 on error (pm_errno is set accordingly)

Author

Generated automatically by Doxygen for libalpm from the source code.