alpm.rs

https://docs.rs/alpm
Admin
alpm.rs provides complete, safe, and ergonomic Rust bindings to the libalpm API, the package...
Tokens:470,798
Snippets:3,207
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Get Install Flag

Source: https://docs.rs/alpm/latest/src/alpm/unions.rs.html

Retrieves the 'install' flag from an InstallIgnorepkgQuestion. Returns true if installation is intended.

```rust
pub fn install(&self) -> bool {
        unsafe { (*self.inner).install != 0 }
    }
```

--------------------------------

### Get Package for Install

Source: https://docs.rs/alpm/latest/src/alpm/unions.rs.html

Retrieves the Package associated with an InstallIgnorepkgQuestion.

```rust
pub fn pkg(&self) -> &Package {
        unsafe { Package::from_ptr((*self.inner).pkg) }
    }
```

--------------------------------

### Get Files

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the list of files installed by the package.

```rust
pub fn files(&self) -> &FileList<'_>
```

--------------------------------

### Handle Package Install Operation

Source: https://docs.rs/alpm/latest/src/alpm/unions.rs.html

Parses a package operation as an installation. It extracts the new package information from the raw event data.

```rust
let op = unsafe { (*self.inner).operation };
match op {
    alpm_package_operation_t::ALPM_PACKAGE_INSTALL => {
        let newpkg = unsafe { Package::from_ptr((*self.inner).newpkg) };
        PackageOperation::Install(newpkg)
    }
```

--------------------------------

### Set Install Flag

Source: https://docs.rs/alpm/latest/src/alpm/unions.rs.html

Sets the 'install' flag for an InstallIgnorepkgQuestion. Use this to control whether a package should be installed.

```rust
pub fn set_install(&mut self, install: bool) {
        unsafe {
            if install {
                (*self.inner).install = 1;
            } else {
                (*self.inner).install = 0;
            }
        }
    }
```

--------------------------------

### Get Assumed Installed Dependencies

Source: https://docs.rs/alpm/latest/alpm/struct.Alpm.html

Returns a list of dependencies that are assumed to be installed.

```rust
pub fn assume_installed(&self) -> AlpmList<'_, &Dep>
```

--------------------------------

### Get Assume Installed Dependencies

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Retrieves a list of dependencies that are assumed to be installed. This is useful for testing or specific installation scenarios.

```rust
pub fn assume_installed(&self) -> AlpmList<'_, &Dep> {
        let list = unsafe { alpm_option_get_assumeinstalled(self.as_ptr()) };
        unsafe { AlpmList::from_ptr(list) }
    }
```

--------------------------------

### Assume Installed API

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Manage the list of packages that should be considered installed, even if they are not.

```APIDOC
## POST /alpm/options/assume_installed

### Description
Adds a dependency to the assume installed list. This is useful for packages that are provided by other means or are not in the repositories.

### Method
POST

### Endpoint
/alpm/options/assume_installed

### Parameters
#### Request Body
- **dependency** (object) - Required - The dependency object representing the package to assume installed.
  - **name** (string) - Required - The name of the package.
  - **version** (string) - Optional - The version of the package.

### Request Example
```json
{
  "dependency": {
    "name": "custom-package",
    "version": "1.0-1"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful addition.

#### Response Example
```json
{
  "message": "Dependency 'custom-package=1.0-1' added to assume installed list."
}
```

## PUT /alpm/options/assume_installed

### Description
Sets the entire list of packages to assume installed. This will replace any existing assume installed list.

### Method
PUT

### Endpoint
/alpm/options/assume_installed

### Parameters
#### Request Body
- **dependencies** (array of objects) - Required - A list of dependency objects to assume installed.
  - **name** (string) - Required - The name of the package.
  - **version** (string) - Optional - The version of the package.

### Request Example
```json
{
  "dependencies": [
    {"name": "pkgA", "version": "1.0"},
    {"name": "pkgB"}
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful update.

#### Response Example
```json
{
  "message": "Assume installed list updated."
}
```

## DELETE /alpm/options/assume_installed

### Description
Removes a dependency from the assume installed list.

### Method
DELETE

### Endpoint
/alpm/options/assume_installed

### Parameters
#### Query Parameters
- **dependency** (object) - Required - The dependency object representing the package to remove.
  - **name** (string) - Required - The name of the package.
  - **version** (string) - Optional - The version of the package.

### Response
#### Success Response (200)
- **message** (string) - Indicates successful removal or that the dependency was not found.

#### Response Example
```json
{
  "message": "Dependency 'custom-package=1.0-1' removed from assume installed list."
}
```
```

--------------------------------

### String Length Example

Source: https://docs.rs/alpm/latest/alpm/struct.Ver.html

Demonstrates how to get the length of a string in bytes. Note that this may not correspond to the number of characters, especially with multi-byte UTF-8 characters.

```rust
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```

--------------------------------

### Split and Get Substring Ranges

Source: https://docs.rs/alpm/latest/alpm/struct.Ver.html

This example demonstrates splitting a string and obtaining the byte range of substrings. It requires the `substr_range` feature and is experimental.

```rust
#![feature(substr_range)]

let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());

assert_eq!(iter.next(), Some(0..1));
assert_eq!(iter.next(), Some(3..4));
assert_eq!(iter.next(), Some(6..7));
assert_eq!(iter.next(), Some(9..10));

```

--------------------------------

### Assume Installed Management

Source: https://docs.rs/alpm/latest/alpm/struct.Alpm.html

APIs for managing packages that are assumed to be installed.

```APIDOC
## Assume Installed Management

### Description
APIs for managing packages that are assumed to be installed.

### Methods

- `add_assume_installed(s: &Dep)`: Adds a dependency to the assume installed list.
- `set_assume_installed<'a, T: AsAlpmList<&'a Dep>>(list: T)`: Sets the entire assume installed list.
- `remove_assume_installed(s: &Dep)`: Removes a dependency from the assume installed list.
```

--------------------------------

### Get Provides

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves a list of capabilities that this package provides.

```rust
pub fn provides(&self) -> AlpmList<'_, &Dep>
```

--------------------------------

### alpm_pkg_get_reason

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_reason.html

Retrieves the installation reason for a given package.

```APIDOC
## alpm_pkg_get_reason

### Description
Returns the package installation reason.

### Method
This is a function call within the alpm-sys library, not a direct HTTP method.

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Assuming 'pkg' is a valid pointer to an alpm_pkg_t object
alpm_pkgreason_t reason = alpm_pkg_get_reason(pkg);
```

### Response
#### Success Response
- **alpm_pkgreason_t** (enum) - An enum member giving the install reason.

#### Response Example
```json
{
  "reason": "explicitly_installed" 
}
```

**Note**: The actual return value is an enum of type `alpm_pkgreason_t`. The JSON example is illustrative.
```

--------------------------------

### Retrieve package file list with alpm_pkg_get_files

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_files.html

Returns a pointer to a filelist object containing installed files for the specified package. The returned filenames are relative to the install root without leading slashes.

```rust
pub unsafe extern "C" fn alpm_pkg_get_files(
    pkg: *mut alpm_pkg_t,
) -> *mut alpm_filelist_t
```

--------------------------------

### Retrieve package installation reason

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_reason.html

Use this function to obtain the installation reason of a package. It requires a pointer to an alpm_pkg_t structure and returns an alpm_pkgreason_t enum.

```rust
pub unsafe extern "C" fn alpm_pkg_get_reason(
    pkg: *mut alpm_pkg_t,
) -> alpm_pkgreason_t
```

--------------------------------

### Get Package Reason

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the reason for the package.

```rust
pub fn reason(&self) -> PackageReason
```

--------------------------------

### Set Assume Installed Dependencies

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_option_set_assumeinstalled.html

Use this function to specify dependencies that should be considered already installed. The list will be duplicated, so the original list still needs to be freed by the caller. Returns 0 on success, -1 on error.

```rust
pub unsafe extern "C" fn alpm_option_set_assumeinstalled(
    handle: *mut alpm_handle_t,
    deps: *mut alpm_list_t,
) -> c_int
```

--------------------------------

### Set Assume Installed

Source: https://docs.rs/alpm-sys/5.0.1/index.html

Sets the list of dependencies that are assumed to be met.

```APIDOC
## Set Assume Installed

### Description
Sets the list of dependencies that are assumed to be met.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **handle** (context handle) - The context handle.
* **deps** (list of *alpm_depend_t) - A list of dependencies. The list will be duplicated, and the original will still need to be freed by the caller.

### Return Value
* **0** on success
* **-1** on error (pm_errno is set accordingly)
```

--------------------------------

### Get Configured Cache Directories - Rust

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_option_get_cachedirs.html

Use this function to get a list of currently configured cache directories. It requires a valid ALPM context handle. The returned list is a C-style list of strings.

```rust
pub unsafe extern "C" fn alpm_option_get_cachedirs(
    handle: *mut alpm_handle_t,
) -> *mut alpm_list_t
```

--------------------------------

### InstallIgnorepkgQuestion Methods

Source: https://docs.rs/alpm/latest/alpm/struct.InstallIgnorepkgQuestion.html

Methods for interacting with the InstallIgnorepkgQuestion struct to manage package installation status and retrieve package information.

```APIDOC
## InstallIgnorepkgQuestion Methods

### Description
Provides methods to set or check the installation status of a package and retrieve the associated package object.

### Methods
- **set_install(&mut self, install: bool)**: Sets whether the package should be installed.
- **install(&self) -> bool**: Returns the current installation status of the package.
- **pkg(&self) -> &Package**: Returns a reference to the associated Package.
```

--------------------------------

### ALPM Test Transaction Setup

Source: https://docs.rs/alpm/latest/src/alpm/trans.rs.html

Sets up an ALPM transaction for testing, including registering a sync database, adding a server, and retrieving a package. It also sets log and event callbacks.

```rust
let mut handle = Alpm::new("/", "tests/db").unwrap();
let flags = TransFlag::DB_ONLY;

handle.set_log_cb((), logcb);
handle.set_event_cb((), eventcb);

let db = handle.register_syncdb_mut("core", SigLevel::NONE).unwrap();
db.add_server("https://ftp.rnl.tecnico.ulisboa.pt/pub/archlinux/core/os/x86_64")
    .unwrap();
let db = handle
    .syncdbs()
    .iter()
    .find(|db| db.name() == "core")
    .unwrap();
let pkg = db.pkg("filesystem").unwrap();

handle.trans_init(flags).unwrap();
handle.trans_add_pkg(pkg).unwrap();
handle.trans_prepare().unwrap();
// Due to age the mirror now returns 404 for the package.
// But we're only testing that the function is called correctly anyway.
assert!(handle.trans_commit().unwrap_err().error() == Error::Retrieve);
```

--------------------------------

### Get Installed Size

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the installed size of the package in bytes.

```rust
pub fn isize(&self) -> i64
```

--------------------------------

### Package Reason API

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/index.html

Retrieves the installation reason for a package.

```APIDOC
## alpm_pkg_get_reason

### Description
Returns the package installation reason.

### Method
N/A (Function call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **pkg** (pointer to package) - A pointer to the package object.
- **return value** (enum member) - An enum member giving the install reason.

#### Response Example
N/A
```

--------------------------------

### Get Package Installed Size

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_isize.html

Retrieves the installed size of a package.

```APIDOC
## alpm_pkg_get_isize

### Description
Returns the installed size of the package.

### Method
Not applicable (C function binding)

### Endpoint
Not applicable (C function binding)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Example usage within C code
alpm_pkg_t* pkg = ...; // Obtain a pointer to an alpm_pkg_t
long installed_size = alpm_pkg_get_isize(pkg);
```

### Response
#### Success Response
- **installed_size** (off_t) - The total size of files installed by the package.

#### Response Example
```json
{
  "installed_size": 1234567 // Example size in bytes
}
```
```

--------------------------------

### alpm_initialize

Source: https://docs.rs/alpm-sys/%5E5.0.0

Initializes the libalpm library, creates a handle, connects to the database, and creates a lockfile.

```APIDOC
## alpm_initialize

### Description
Initializes the library. Creates handle, connects to database and creates lockfile. This must be called before any other functions are called.

### Parameters
- **root** (string) - Required - The root path for all filesystem operations
- **dbpath** (string) - Required - The absolute path to the libalpm database
- **err** (variable) - Optional - An optional variable to hold any error return codes

### Response
- **handle** (context handle) - Returns a context handle on success, NULL on error.
```

--------------------------------

### Get Database

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the database the package belongs to, if available.

```rust
pub fn db(&self) -> Option<&Db>
```

--------------------------------

### Register ALPM Databases

Source: https://docs.rs/alpm/latest/src/alpm/list_mut.rs.html

Demonstrates registering multiple ALPM databases ('community', 'extra') with a given handle. This is a setup step for package operations.

```rust
let handle = Alpm::new("/", "tests/db").unwrap();
handle.register_syncdb("community", SigLevel::NONE).unwrap();
handle.register_syncdb("extra", SigLevel::NONE).unwrap();
```

--------------------------------

### Get Replaces

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves a list of packages that this package replaces.

```rust
pub fn replaces(&self) -> AlpmList<'_, &Dep>
```

--------------------------------

### Initialization and Logging

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys

Functions for initializing the ALPM library and for logging actions.

```APIDOC
## alpm_initialize

### Description
Initializes the library. Creates a handle, connects to the database, and creates a lockfile. This must be called before any other functions are called.

### Parameters
#### Path Parameters
- **root** (string) - Required - The root path for all filesystem operations.
- **dbpath** (string) - Required - The absolute path to the libalpm database.
- **err** (pointer) - Optional - A variable to hold any error return codes.

### Return Value
A context handle on success, NULL on error. `err` will be set if provided.

## alpm_logaction

### Description
A printf-like function for logging.

### Parameters
#### Path Parameters
- **handle** (pointer) - Required - The context handle.
- **prefix** (string) - Required - Caller-specific prefix for the log.
- **fmt** (string) - Required - Output format.

### Return Value
0 on success, -1 on error (pm_errno is set accordingly).
```

--------------------------------

### Get Install Date

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the install date of the package as a Unix timestamp, if available.

```rust
pub fn install_date(&self) -> Option<i64>
```

--------------------------------

### Setup Child Process for Sandbox

Source: https://docs.rs/alpm/latest/src/alpm/sandbox.rs.html

Use this function to set up a child process for sandboxing. It requires the user, path, and a flag to restrict syscalls. Ensure CString conversions are handled correctly.

```rust
use alpm_sys::*
use std::ffi::CString;

use crate::{Alpm, Result};

impl Alpm {
    pub fn sandbox_setup_child<S: Into<Vec<u8>>>(
        &mut self,
        user: S,
        path: S,
        restrict_syscalls: bool,
    ) -> Result<()> {
        let user = CString::new(user).unwrap();
        let path = CString::new(path).unwrap();
        let ret = unsafe {
            alpm_sandbox_setup_child(
                self.as_ptr(),
                user.as_ptr(),
                path.as_ptr(),
                restrict_syscalls,
            )
        };
        self.check_ret(ret)
    }
}
```

--------------------------------

### Get Package Install Date

Source: https://docs.rs/alpm-sys/5.0.1/src/alpm_sys/ffi.rs.html

Retrieves the timestamp of when the package was installed. Returns an `alpm_time_t` value.

```rust
pub fn alpm_pkg_get_installdate(pkg: *mut alpm_pkg_t) -> alpm_time_t;
```

--------------------------------

### sandbox_setup_child

Source: https://docs.rs/alpm/latest/src/alpm/sandbox.rs.html

Configures a child process within the ALPM sandbox environment.

```APIDOC
## sandbox_setup_child

### Description
Sets up a child process for the ALPM sandbox with a specified user, path, and syscall restriction policy.

### Parameters
- **user** (S: Into<Vec<u8>>) - Required - The user to run the child process as.
- **path** (S: Into<Vec<u8>>) - Required - The filesystem path for the sandbox.
- **restrict_syscalls** (bool) - Required - Whether to apply syscall restrictions.

### Response
- **Result<()>** - Returns Ok(()) on success, or an error if the underlying ALPM call fails.
```

--------------------------------

### Get Package Install Date - Rust

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_installdate.html

Use this function to retrieve the install timestamp of a package. It requires a pointer to an alpm_pkg_t structure.

```rust
pub unsafe extern "C" fn alpm_pkg_get_installdate(
    pkg: *mut alpm_pkg_t,
) -> alpm_time_t
```

--------------------------------

### Configure ALPM Callbacks and Logging

Source: https://docs.rs/alpm/latest/src/alpm/cb.rs.html

Demonstrates setting up various callbacks for events, fetching, and logging within an ALPM handle.

```rust
#[test]
    fn test_cb() {
        let mut handle = Alpm::new("/", "tests/db").unwrap();

        handle.set_use_syslog(true);
        handle.set_logfile("tests/log").unwrap();
        handle.set_log_cb(0, |_, msg, data| {
            print!("log {} {}", data, msg);
            *data += 1;
        });
        handle.set_event_cb((), eventcb);
        handle.set_fetch_cb((), fetchcb);
        handle.set_question_cb((), questioncb);
        handle.set_dl_cb((), downloadcb);
        handle.set_progress_cb((), progresscb);

        log_action!(handle, "me", "look i am logging an action {}", ":D").unwrap();
        handle
            .log_action("me", "look i am logging an action 2")
            .unwrap();
        handle
            .log_action("me", "look i am logging an action 2")
            .unwrap();
        handle
            .log_action("me", "look i am logging an action 2")
            .unwrap();
        handle
            .log_action("me", "look i am logging an action 2")
            .unwrap();
        handle
            .log_action("me", "look i am logging an action 2")
            .unwrap();

        let db = handle.register_syncdb_mut("core", SigLevel::NONE).unwrap();
        db.add_server("https://ftp.rnl.tecnico.ulisboa.pt/pub/archlinux/core/os/x86_64")
            .unwrap();
        db.pkg("filesystem").unwrap();
    }
```

--------------------------------

### Get New Database

Source: https://docs.rs/alpm/latest/src/alpm/unions.rs.html

Retrieves the new database associated with a ReplaceQuestion.

```rust
pub fn newdb(&self) -> &Db {
        unsafe { Db::from_ptr((*self.inner).newdb) }
    }
```

--------------------------------

### Get Package Size

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the installed size of the package in bytes.

```rust
pub fn size(&self) -> i64
```

--------------------------------

### match_indices: Iterate over matches and their starting indices

Source: https://docs.rs/alpm/latest/alpm/struct.Version.html

Use `match_indices` to get an iterator over the starting indices and the matched substrings for all non-overlapping occurrences of a pattern. Overlapping matches are not included.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
```

```rust
let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);
```

```rust
let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### Get Licenses

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves a list of licenses associated with the package.

```rust
pub fn licenses(&self) -> AlpmList<'_, &str>
```

--------------------------------

### Sandbox Setup

Source: https://docs.rs/alpm-sys/5.0.1/src/alpm_sys/ffi.rs.html

Function to drop privileges and restrict filesystem access for child processes.

```rust
unsafe extern "C" {
    #[doc = " Drop privileges by switching to a different user.\n @param handle the context handle\n @param sandboxuser the user to switch to\n @param sandbox_path if non-NULL, restrict writes to this filesystem path\n @param restrict_syscalls whether to deny access to a list of dangerous syscalls\n @return 0 on success, -1 on failure"]
    pub fn alpm_sandbox_setup_child(
        handle: *mut alpm_handle_t,
        sandboxuser: *const ::std::os::raw::c_char,
        sandbox_path: *const ::std::os::raw::c_char,
        restrict_syscalls: bool,
    ) -> ::std::os::raw::c_int;
}
```

--------------------------------

### Get No Extract List

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Retrieves a list of packages whose files should not be extracted during installation. This is rarely used.

```rust
pub fn noextracts(&self) -> AlpmList<'_, &str> {
        let list = unsafe { alpm_option_get_noextracts(self.as_ptr()) };
        unsafe { AlpmList::from_ptr(list) }
    }
```

--------------------------------

### Initialize ALPM Handle and Capabilities

Source: https://docs.rs/alpm/latest/src/alpm/cb.rs.html

Basic tests for verifying ALPM capabilities, handle initialization, and version retrieval.

```rust
#[test]
    fn test_capabilities() {
        let _caps = Capabilities::new();
    }

    #[test]
    fn test_init() {
        let _handle = Alpm::new("/", "tests/db").unwrap();
    }

    #[test]
    fn test_version() {
        assert!(!version().is_empty());
    }
```

--------------------------------

### Get alpm Version

Source: https://docs.rs/alpm/latest/alpm/fn.version.html

Returns the version of the alpm library as a static string slice. No setup or imports are required.

```rust
pub fn version() -> &'static str
```

--------------------------------

### Debug Alpm Package Dependencies

Source: https://docs.rs/alpm/latest/src/alpm/list_mut.rs.html

Shows how to initialize ALPM, register a database, and then print the dependencies of a specific package using debug formatting. This is useful for inspecting package information.

```rust
let handle = Alpm::new("/", "tests/db").unwrap();
let db = handle.register_syncdb("core", SigLevel::NONE).unwrap();
let pkg = db.pkg("linux").unwrap();

println!("{:#?}", db.pkgs());
println!("{:#?}", pkg.depends());
```

--------------------------------

### Get Ignore Packages List

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Retrieves a list of packages that should be ignored during operations like upgrades. This prevents them from being installed or updated.

```rust
pub fn ignorepkgs(&self) -> AlpmList<'_, &str> {
        let list = unsafe { alpm_option_get_ignorepkgs(self.as_ptr()) };
        unsafe { AlpmList::from_ptr(list) }
    }
```

--------------------------------

### Get Package Validation Method

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_validation.html

Use this function to determine how a package was validated during installation. It requires a pointer to the package structure.

```rust
pub unsafe extern "C" fn alpm_pkg_get_validation(
    pkg: *mut alpm_pkg_t,
) -> c_int
```

--------------------------------

### Get Ignore Groups List

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Retrieves a list of package groups that should be ignored during operations. This prevents all packages within a group from being installed or updated.

```rust
pub fn ignoregroups(&self) -> AlpmList<'_, &str> {
        let list = unsafe { alpm_option_get_ignoregroups(self.as_ptr()) };
        unsafe { AlpmList::from_ptr(list) }
    }
```

--------------------------------

### Initialize alpm Library

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_initialize.html

Initializes the library, connects to the database, and creates a lockfile. This function must be called before any other alpm functions. It requires the root path, database path, and an optional error variable.

```rust
pub unsafe extern "C" fn alpm_initialize(
    root: *const c_char,
    dbpath: *const c_char,
    err: *mut alpm_errno_t,
) -> *mut alpm_handle_t
```

--------------------------------

### Setup Child Sandbox with alpm_sandbox_setup_child

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_sandbox_setup_child.html

Use this function to drop privileges by switching to a specified user. Optionally, restrict writes to a given filesystem path and deny access to dangerous syscalls. Returns 0 on success, -1 on failure.

```rust
pub unsafe extern "C" fn alpm_sandbox_setup_child(
    handle: *mut alpm_handle_t,
    sandboxuser: *const c_char,
    sandbox_path: *const c_char,
    restrict_syscalls: bool,
) -> c_int
```

--------------------------------

### Initialize Alpm Instance

Source: https://docs.rs/alpm/latest/alpm/struct.Alpm.html

Creates a new Alpm instance. Requires the root directory and database path. Use this to start interacting with the package manager.

```rust
pub fn new<S: Into<Vec<u8>>>(root: S, db_path: S) -> Result<Alpm>
```

--------------------------------

### String get Method Example

Source: https://docs.rs/alpm/latest/alpm/struct.Ver.html

Safely returns a subslice of the string. Returns `None` if the indices are out of bounds or do not lie on UTF-8 sequence boundaries.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

--------------------------------

### String is_char_boundary Method Example

Source: https://docs.rs/alpm/latest/alpm/struct.Ver.html

Verifies if a given byte index falls on a UTF-8 character boundary. The start and end of the string are considered boundaries.

```rust
let s = "Löwe 老虎 Léopard";
assert!(s.is_char_boundary(0));
// start of `老`
assert!(s.is_char_boundary(6));
assert!(s.is_char_boundary(s.len()));

// second byte of `ö`
assert!(!s.is_char_boundary(2));

// third byte of `老`
assert!(!s.is_char_boundary(8));
```

--------------------------------

### Set Configuration Options

Source: https://docs.rs/alpm/latest/src/alpm/handle.rs.html

Methods to configure global ALPM options like disk space checking and database extensions.

```rust
pub fn set_check_space(&self, b: bool) {
        let b = if b { 1 } else { 0 };
        unsafe { alpm_option_set_checkspace(self.as_ptr(), b) };
    }

    pub fn set_dbext<S: Into<Vec<u8>>>(&mut self, s: S) {
        let s = CString::new(s).unwrap();
```

--------------------------------

### alpm_pkg_load

Source: https://docs.rs/alpm-sys/%5E5.0.0

Creates a package structure from a file on disk.

```APIDOC
## alpm_pkg_load
### Description
Create a package from a file. The allocated structure should be freed using alpm_pkg_free().
### Parameters
- **handle** (context) - Required - The context handle.
- **filename** (string) - Required - Location of the package tarball.
- **full** (boolean) - Required - Whether to stop the load after metadata is read or continue through the full archive.
- **level** (int) - Required - What level of package signature checking to perform.
- **pkg** (pointer) - Required - Address of the package pointer.
### Response
- **return** (int) - 0 on success, -1 on error.
```

--------------------------------

### Get alpm Library Capabilities

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_capabilities.html

Call this function to retrieve a bitmask indicating the capabilities supported by the alpm library. No specific setup is required beyond linking the library.

```rust
pub unsafe extern "C" fn alpm_capabilities() -> c_int
```

--------------------------------

### Implement fetch_pkgurl for Alpm

Source: https://docs.rs/alpm/latest/src/alpm/dload.rs.html

This method fetches package URLs using the `alpm_fetch_pkgurl` function. It requires a list of URLs and returns a mutable list of fetched package URLs. Ensure the `Alpm` instance is valid and the provided URLs are correctly formatted.

```rust
use crate::{Alpm, AlpmListMut, AsAlpmList, Result};

use alpm_sys::*;

use std::ptr;

impl Alpm {
    pub fn fetch_pkgurl<'a, L: AsAlpmList<&'a str>>(&self, urls: L) -> Result<AlpmListMut<String>> {
        urls.with(|url| {
            let mut out = ptr::null_mut();
            let ret = unsafe { alpm_fetch_pkgurl(self.as_ptr(), url.as_ptr(), &mut out) };
            self.check_ret(ret)?;
            let fetched = unsafe { AlpmListMut::from_ptr(out) };
            Ok(fetched)
        })
    }
}
```

--------------------------------

### Initialize ALPM Handle

Source: https://docs.rs/alpm/latest/src/alpm/alpm.rs.html

Creates a new ALPM handle by specifying the root directory and the database path.

```APIDOC
## Alpm::new

### Description
Initializes a new ALPM handle with the specified root and database path.

### Parameters
#### Arguments
- **root** (S: Into<Vec<u8>>) - Required - The root directory path.
- **db_path** (S: Into<Vec<u8>>) - Required - The path to the ALPM database.

### Response
- **Result<Alpm>** - Returns an Alpm handle on success, or an Error if initialization fails.
```

--------------------------------

### PackageReason Enum

Source: https://docs.rs/alpm/latest/src/alpm/types.rs.html

Specifies the reason a package is installed or being considered. Differentiates between explicitly installed packages and those installed as dependencies.

```rust
#[repr(u32)]
#[derive(Debug, Eq, PartialEq, Copy, Clone, Ord, PartialOrd, Hash)]
pub enum PackageReason {
    Explicit = ALPM_PKG_REASON_EXPLICIT as u32,
    Depend = ALPM_PKG_REASON_DEPEND as u32,
}
```

--------------------------------

### Package Install Reasons Enum

Source: https://docs.rs/alpm-sys/5.0.1/src/alpm_sys/ffi.rs.html

Defines the reasons why a package might be installed. This enum is used to categorize package installations, such as explicit user requests or dependency fulfillment.

```rust
#[repr(u32)]
#[doc = " Package install reasons."]
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub enum _alpm_pkgreason_t {
    #[doc = " Explicitly requested by the user."]
    ALPM_PKG_REASON_EXPLICIT = 0,
    #[doc = " Installed as a dependency for another package."]
    ALPM_PKG_REASON_DEPEND = 1,
    #[doc = " Failed parsing of local database"]
    ALPM_PKG_REASON_UNKNOWN = 2,
}
#[doc = " Package install reasons."]
pub use self::_alpm_pkgreason_t as alpm_pkgreason_t;
```

--------------------------------

### Get Database Servers List

Source: https://docs.rs/alpm/latest/alpm/struct.DbMut.html

Returns a list of servers configured for this database. The list is an AlpmList containing string slices.

```rust
pub fn servers(&self) -> AlpmList<'_, &str>
```

--------------------------------

### Retrieve Package Files and Database Info

Source: https://docs.rs/alpm/latest/src/alpm/package.rs.html

Methods for accessing file lists, backup files, and the associated database.

```rust
pub fn files(&self) -> &FileList {
        let files = unsafe { alpm_pkg_get_files(self.as_ptr()) };
        unsafe { FileList::new(files) }
    }

    pub fn backup(&self) -> AlpmList<&Backup> {
        let list = unsafe { alpm_pkg_get_backup(self.as_ptr()) };
        unsafe { AlpmList::from_ptr(list) }
    }

    pub fn db(&self) -> Option<&Db> {
        let db = unsafe { alpm_pkg_get_db(self.as_ptr()) };
        self.check_null(db).ok()?;
        unsafe { Some(Db::from_ptr(db)) }
    }
```

--------------------------------

### Check Dependencies with Specific Packages

Source: https://docs.rs/alpm/latest/src/alpm/deps.rs.html

Initializes ALPM, registers databases, and checks dependencies for a local package set against a specific removed package. Asserts the number of missing dependencies.

```rust
let handle = Alpm::new("/", "tests/db").unwrap();
handle.register_syncdb("extra", SigLevel::NONE).unwrap();
handle.register_syncdb("community", SigLevel::NONE).unwrap();

let pkgs1 = handle.localdb().pkgs();
let pkgs = pkgs1.iter().collect::<Vec<_>>();
let rem = handle.localdb().pkg("ncurses").unwrap();
let missing = handle.check_deps(
    pkgs.iter(),
    vec![rem].iter(),
    AlpmListMut::<&Pkg>::new(),
    true,
);
assert_eq!(missing.len(), 9);
```

--------------------------------

### Define alpm_pkgreason_t Enum

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/enum.alpm_pkgreason_t.html

Defines the possible reasons for a package installation. Use this enum to categorize package install reasons.

```rust
#[repr(u32)]
pub enum alpm_pkgreason_t {
    ALPM_PKG_REASON_EXPLICIT = 0,
    ALPM_PKG_REASON_DEPEND = 1,
    ALPM_PKG_REASON_UNKNOWN = 2,
}
```

--------------------------------

### ALPM_TRANS_FLAG_NEEDED Constant Definition

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/_alpm_transflag_t/constant.ALPM_TRANS_FLAG_NEEDED.html

Defines the ALPM_TRANS_FLAG_NEEDED constant. Use this flag to prevent installing a package if it is already installed and up to date.

```rust
pub const ALPM_TRANS_FLAG_NEEDED: Type = 8192;
```

--------------------------------

### Library Initialization and Cleanup

Source: https://docs.rs/alpm-sys/5.0.1/src/alpm_sys/ffi.rs.html

Functions for initializing and releasing the libalpm library, including setting up the context handle.

```APIDOC
## Initialize libalpm

### `alpm_initialize`

Initializes the library. Creates a handle, connects to the database, and creates a lockfile. This must be called before any other functions.

### Method

```APIDOC
unsafe extern "C" {
    pub fn alpm_initialize(
        root: *const ::std::os::raw::c_char,
        dbpath: *const ::std::os::raw::c_char,
        err: *mut alpm_errno_t,
    ) -> *mut alpm_handle_t;
}
```

### Parameters

#### Path Parameters

- **root** (*const ::std::os::raw::c_char*) - The root path for all filesystem operations.
- **dbpath** (*const ::std::os::raw::c_char*) - The absolute path to the libalpm database.
- **err** (*mut alpm_errno_t*) - An optional variable to hold any error return codes.

### Response

#### Success Response

- ** *mut alpm_handle_t***: A context handle on success.

#### Error Response

- **NULL**: On error. The `err` parameter will be set if provided.

## Release libalpm

### `alpm_release`

Releases the library. Disconnects from the database, removes the handle and lockfile. This should be the last alpm call. After this returns, the handle should be considered invalid and cannot be reused.

### Method

```APIDOC
unsafe extern "C" {
    pub fn alpm_release(handle: *mut alpm_handle_t) -> ::std::os::raw::c_int;
}
```

### Parameters

#### Path Parameters

- **handle** (*mut alpm_handle_t*) - The context handle.

### Response

#### Success Response

- **0**: On success.

#### Error Response

- **-1**: On error.

```

--------------------------------

### Option<V> FromIterator<Option<A>> Example (Short-circuiting)

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/type.alpm_cb_fetch.html

Demonstrates that collection stops immediately upon encountering a None value, affecting side effects.

```rust
let items = vec![3_u16, 2, 1, 10];

let mut shared = 0;

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| { shared += x; x.checked_sub(2) })
    .collect();

assert_eq!(res, None);
assert_eq!(shared, 6);
```

--------------------------------

### Retrieve package installed size with alpm_pkg_get_isize

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_isize.html

Returns the total size of files installed by the package. Requires a pointer to an alpm_pkg_t structure.

```rust
pub unsafe extern "C" fn alpm_pkg_get_isize(
    pkg: *mut alpm_pkg_t,
) -> off_t
```

--------------------------------

### Alpm Initialization and Release

Source: https://docs.rs/alpm/latest/alpm/struct.Alpm.html

Methods for creating and releasing Alpm instances.

```APIDOC
## Alpm Initialization and Release

### `new`

Creates a new Alpm instance.

- **Method**: `pub fn new<S: Into<Vec<u8>>>(root: S, db_path: S) -> Result<Alpm>`
- **Parameters**:
  - `root` (S): The root directory path.
  - `db_path` (S): The database path.

### `release`

Releases the Alpm instance.

- **Method**: `pub fn release(self) -> Result<(), ReleaseError>`
- **Parameters**: None
```

--------------------------------

### Define alpm_question_install_ignorepkg_t struct

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/type.alpm_question_install_ignorepkg_t.html

The C-compatible structure definition for handling ignored package installation questions.

```rust
#[repr(C)]
pub struct alpm_question_install_ignorepkg_t {
    pub type_: u32,
    pub install: i32,
    pub pkg: *mut u8,
}
```

--------------------------------

### Remove Assume Installed Entry

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_option_remove_assumeinstalled.html

Use this function to remove a dependency from the assume installed list. Returns 0 on success, -1 on error.

```rust
pub unsafe extern "C" fn alpm_option_remove_assumeinstalled(
    handle: *mut alpm_handle_t,
    dep: *const alpm_depend_t,
) -> c_int
```

--------------------------------

### Define alpm_download_event_init_t struct

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/type.alpm_download_event_init_t.html

The C-compatible structure containing the optional flag for download events.

```rust
#[repr(C)]
pub struct alpm_download_event_init_t {
    pub optional: i32,
}
```

--------------------------------

### Get Package Dependencies in alpm-sys

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_depends.html

Use this function to get a list of package dependencies. It returns a reference to an internal list of alpm_depend_t structures.

```rust
pub unsafe extern "C" fn alpm_pkg_get_depends(
    pkg: *mut alpm_pkg_t,
) -> *mut alpm_list_t
```

--------------------------------

### Set package installation reason in Rust

Source: https://docs.rs/alpm/latest/src/alpm/be_local.rs.html

Updates the installation reason for a package. Requires the alpm-sys crate and appropriate safety handling for FFI calls.

```rust
1use crate::{Package, PackageReason, Result};
2
3use alpm_sys::*;
4
5use std::mem::transmute;
6
7impl Package {
8    pub fn set_reason(&self, reason: PackageReason) -> Result<()> {
9        let reason = unsafe { transmute::<PackageReason, _alpm_pkgreason_t>(reason) };
10        let ret = unsafe { alpm_pkg_set_reason(self.as_ptr(), reason) };
11        self.check_ret(ret)
12    }
13}
```

--------------------------------

### Get Last Chunk of Slice

Source: https://docs.rs/alpm/latest/alpm/struct.Signature.html

Use `last_chunk` to get a reference to the last `N` items in a slice. Returns `None` if the slice is shorter than `N`.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

--------------------------------

### Get Element or Subslice by Index

Source: https://docs.rs/alpm/latest/alpm/struct.Signature.html

The `get` method safely retrieves an element or subslice using various index types. It returns `None` if the index is out of bounds.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Define InstallIgnorepkgQuestion struct

Source: https://docs.rs/alpm/latest/alpm/struct.InstallIgnorepkgQuestion.html

The definition of the InstallIgnorepkgQuestion struct with private fields.

```rust
pub struct InstallIgnorepkgQuestion<'a> { /* private fields */ }
```

--------------------------------

### Option<V> FromIterator<Option<A>> Example (Success)

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/type.alpm_cb_fetch.html

Collects an iterator of Option<A> into an Option<V>, succeeding when all elements are Some.

```rust
let items = vec![0_u16, 1, 2];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_add(1))
    .collect();

assert_eq!(res, Some(vec![1, 2, 3]));
```

--------------------------------

### Get Conflicting Packages - Rust

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_conflicts.html

Use this function to get a list of packages that conflict with the specified package. It returns a reference to an internal list of alpm_depend_t structures.

```rust
pub unsafe extern "C" fn alpm_pkg_get_conflicts(
    pkg: *mut alpm_pkg_t,
) -> *mut alpm_list_t
```

--------------------------------

### Get Database for Package - alpm-sys

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_db.html

Use this function to get the database containing a package. Returns NULL if the package was loaded from a file. Requires a pointer to an alpm_pkg_t structure.

```rust
pub unsafe extern "C" fn alpm_pkg_get_db(
    pkg: *mut alpm_pkg_t,
) -> *mut alpm_db_t
```

--------------------------------

### Get All Packages

Source: https://docs.rs/alpm/latest/alpm/struct.DbMut.html

Returns a list of all packages available in the database. The list is an AlpmList containing references to Package objects.

```rust
pub fn pkgs(&self) -> AlpmList<'_, &Package>
```

--------------------------------

### Retain Packages by Name Prefix

Source: https://docs.rs/alpm/latest/src/alpm/list_mut.rs.html

Filters a mutable list of packages to keep only those whose names start with 'a'. Asserts that the resulting list is not empty and all remaining package names start with 'a'.

```rust
let mut pkgs = db.pkgs().to_list_mut();
pkgs.retain(|p| p.name().starts_with('a'));

assert!(!pkgs.is_empty());
pkgs.iter().for_each(|p| assert!(p.name().starts_with('a')));
```

--------------------------------

### Retrieve package version string

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_version.html

Returns the full version string of a package. Use alpm_pkg_vercmp for version comparisons.

```rust
pub unsafe extern "C" fn alpm_pkg_get_version(
    pkg: *mut alpm_pkg_t,
) -> *const c_char
```

--------------------------------

### Package Set Reason API

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/index.html

Sets the install reason for a package in the local database. The write to the local database is performed immediately.

```APIDOC
## alpm_pkg_set_reason

### Description
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.

### Method
N/A (Function call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **pkg** (pointer to package) - The package to update.
- **reason** (enum member) - The new install reason.
- **return value** (integer) - 0 on success, -1 on error (pm_errno is set accordingly).

#### Response Example
N/A
```

--------------------------------

### Get Provides List for a Package

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_pkg_get_provides.html

Use this function to get the list of packages that a specific package provides. It requires a pointer to an alpm_pkg_t structure and returns a pointer to an internal list of alpm_depend_t structures.

```rust
pub unsafe extern "C" fn alpm_pkg_get_provides(
    pkg: *mut alpm_pkg_t,
) -> *mut alpm_list_t
```

--------------------------------

### alpm_trans_init

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/fn.alpm_trans_init.html

Initializes a transaction using the provided handle and flags.

```APIDOC
## C alpm_trans_init

### Description
Initialize the transaction for the alpm system.

### Method
Function Call

### Parameters
#### Arguments
- **handle** (*mut alpm_handle_t) - Required - The context handle.
- **flags** (c_int) - Required - Flags of the transaction (e.g., nodeps; see alpm_transflag_t).

### Response
- **Return Value** (c_int) - 0 on success, -1 on error (pm_errno is set accordingly).
```

--------------------------------

### Struct _alpm_download_event_init_t

Source: https://docs.rs/alpm-sys/5.0.1/alpm_sys/struct._alpm_download_event_init_t.html

Definition and field details for the _alpm_download_event_init_t structure used during download initialization.

```APIDOC
## Struct _alpm_download_event_init_t

### Description
Context struct for when a download starts.

### Fields
- **optional** (c_int) - Whether this file is optional and thus the errors could be ignored.
```

--------------------------------

### Get Signature

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the signature of the package.

```rust
pub fn sig(&self) -> Result<Signature>
```

--------------------------------

### Get Changelog

Source: https://docs.rs/alpm/latest/alpm/struct.Package.html

Retrieves the changelog for the package.

```rust
pub fn changelog(&self) -> Result<ChangeLog<'_>>
```

--------------------------------

### Split string by simple patterns

Source: https://docs.rs/alpm/latest/alpm/struct.Version.html

Demonstrates splitting a string using characters, strings, and closures as delimiters.

```rust
let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);

let v: Vec<&str> = "".split('X').collect();
assert_eq!(v, [""]);

let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
assert_eq!(v, ["lion", "", "tiger", "leopard"]);

let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);

let v: Vec<&str> = "AABBCC".split("DD").collect();
assert_eq!(v, ["AABBCC"]);

let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
assert_eq!(v, ["abc", "def", "ghi"]);

let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);
```
Tokens:
Raw