libalpm_databases(3)

📦
version 7.1.0.r9.g54d9411 · 3 versions
, in arch rolling, epel 10, fedora 43, fedora 44

💖 libalpm_databases 💖

okay so bestie, welcome to the libalpm_databases(3) page — this is the Library Functions Manual entry for the Database part of libalpm, and it's literally just ✨ functions to query and manipulate the database of libalpm ✨. Buckle up, it's giving reference material but make it cute.

✨ NAME ✨

libalpm_databases — Database

  • Functions to query and manipulate the database of libalpm. 🫶

🌸 SYNOPSIS 🌸

🎀 Typedefs 🎀

  • typedef struct _alpm_db_t alpm_db_t — a database. yes queen, that's the whole vibe.

🌈 Enumerations 🌈

  • enum alpm_db_usage_t { ALPM_DB_USAGE_SYNC = 1, ALPM_DB_USAGE_SEARCH = (1 << 1), ALPM_DB_USAGE_INSTALL = (1 << 2), ALPM_DB_USAGE_UPGRADE = (1 << 3), ALPM_DB_USAGE_ALL = (1 << 4) - 1 } — the usage level of a database. noted, bestie.

💜 Functions 💜

  • alpm_db_t * alpm_get_localdb (alpm_handle_t *handle) — get the database of locally installed packages. your own little stash 💅
  • alpm_list_t * alpm_get_syncdbs (alpm_handle_t *handle) — get the list of sync databases. the remote girlies ✨
  • alpm_db_t * alpm_register_syncdb (alpm_handle_t *handle, const char *treename, int level) — register a sync database of packages. sign her up 🎀
  • int alpm_unregister_all_syncdbs (alpm_handle_t *handle) — unregister all package databases. bye bye to all of them at once 😭
  • int alpm_db_unregister (alpm_db_t *db) — unregister a package database. just the one, bestie.
  • alpm_handle_t * alpm_db_get_handle (alpm_db_t *db) — get the handle of a package database. who's her handler 👀
  • const char * alpm_db_get_name (const alpm_db_t *db) — get the name of a package database. what's her name 🦋
  • int alpm_db_get_siglevel (alpm_db_t *db) — get the signature verification level for a database. trust issues, but make it cryptographic 🔥
  • int alpm_db_get_valid (alpm_db_t *db) — check the validity of a database. vibe check fr fr
  • int alpm_db_update (alpm_handle_t *handle, alpm_list_t *dbs, int force) — update package databases. refresh queen 💅
  • alpm_pkg_t * alpm_db_get_pkg (alpm_db_t *db, const char *name) — get a package entry from a package database. pulling one girl out of the crowd ✨
  • alpm_list_t * alpm_db_get_pkgcache (alpm_db_t *db) — get the package cache of a package database. the whole friend group 🌸
  • alpm_group_t * alpm_db_get_group (alpm_db_t *db, const char *name) — get a group entry from a package database. squad goals 🫶
  • alpm_list_t * alpm_db_get_groupcache (alpm_db_t *db) — get the group cache of a package database. all the squads 💖
  • int alpm_db_search (alpm_db_t *db, const alpm_list_t *needles, alpm_list_t **ret) — searches a database with regular expressions. detective mode 🔍

👑 Server accessors 👑

  • alpm_list_t * alpm_db_get_servers (const alpm_db_t *db) — get the list of servers assigned to this db. her contacts 📱
  • int alpm_db_set_servers (alpm_db_t *db, alpm_list_t *servers) — sets the list of servers for the database to use. assigning her whole roster 💅
  • int alpm_db_add_server (alpm_db_t *db, const char *url) — add a download server to a database. plus one to the group chat ➕
  • int alpm_db_remove_server (alpm_db_t *db, const char *url) — remove a download server from a database. and she's out 🙈
  • alpm_list_t * alpm_db_get_cache_servers (const alpm_db_t *db) — get the list of cache servers assigned to this db. the backup besties 🌈
  • int alpm_db_set_cache_servers (alpm_db_t *db, alpm_list_t *servers) — sets the list of cache servers for the database to use. setting the whole backup roster ✨
  • int alpm_db_add_cache_server (alpm_db_t *db, const char *url) — add a download cache server to a database. plus one, but for cache 🎀
  • int alpm_db_remove_cache_server (alpm_db_t *db, const char *url) — remove a download cache server from a database. removing from the cache roster 💀

🧚 Usage accessors 🧚

  • int alpm_db_set_usage (alpm_db_t *db, int usage) — sets the usage of a database. what is she for, bestie
  • int alpm_db_get_usage (alpm_db_t *db, int *usage) — gets the usage of a database. okay so what is she for 👑

🦋 Detailed Description 🦋

Functions to query and manipulate the database of libalpm. periodt. 💖

🎀 Typedef Documentation 🎀

typedef struct _alpm_db_t alpm_db_t

A database. and like, a database is a container that stores metadata about packages. that's it, that's the girl. 💅

A database can be located on the local filesystem or on a remote server. both are valid, both are iconic.

To use a database, it must first be registered via alpm_register_syncdb. If the database is already present in dbpath then it will be usable. Otherwise, the database needs to be downloaded using alpm_db_update. And yes bestie — even if the source of the database is the local filesystem. no shortcuts, sorry 😭

After this, the database can be used to query packages and groups. Any packages or groups from the database will continue to be owned by the database and do not need to be freed by the user. They will be freed when the database is unregistered. so like, do NOT go freeing them yourself, that's her business not yours 🙈

Databases are automatically unregistered when the alpm_handle_t is released. no cleanup needed, she handles herself 💅

🌈 Enumeration Type Documentation 🌈

enum alpm_db_usage_t

The usage level of a database. literally the "what is she allowed to do" enum ✨

Enumerator

  • ALPM_DB_USAGE_SYNC — enable refreshes for this database. she can refresh 🌸
  • ALPM_DB_USAGE_SEARCH — enable search for this database. she can be searched 🔍
  • ALPM_DB_USAGE_INSTALL — enable installing packages from this database. she can hand over packages 📦
  • ALPM_DB_USAGE_UPGRADE — enable sysupgrades with this database. she can do the big upgrade glow-up 🔥
  • ALPM_DB_USAGE_ALL — enable all usage levels. she can do everything, main character energy 👑

okay that's the whole setup bestie — part 2 is where we actually get into the function docs, so don't go anywhere 💜

💖 FUNCTION DOCUMENTATION 💖

Bestie, buckle UP, because this is the entire function roster and we are going through every single one. No skimming, no "yeah yeah I get it", we're doing this properly. Grab a boba. 🧋

🌸 alpm_db_add_cache_server 🌸

int alpm_db_add_cache_server (alpm_db_t * db, const char * url)

Slap a download cache server onto a database. That's it, that's the whole job. ✨

Parameters

  • db — database pointer
  • url — url of the server

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

🌸 alpm_db_add_server 🌸

int alpm_db_add_server (alpm_db_t * db, const char * url)

Same energy as above but for a regular download server — add one to a database. 💅

Parameters

  • db — database pointer
  • url — url of the server

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

🦋 alpm_db_get_cache_servers 🦋

alpm_list_t * alpm_db_get_cache_servers (const alpm_db_t * db)

Gimme the list of cache servers that belong to this db. 🎀

Parameters

  • db — pointer to the database to get the servers from

Returns — a char* list of servers

🦋 alpm_db_get_group 🦋

alpm_group_t * alpm_db_get_group (alpm_db_t * db, const char * name)

Pull a group entry out of a package database. Lowkey the best part: looking up a group is O(1) and will be significantly faster than iterating over the groupcahe. So like… use this one, bestie, your CPU will thank you. 🫶

Parameters

  • db — pointer to the package database to get the group from
  • name — of the group

Returns — the groups entry on success, NULL on error

🦋 alpm_db_get_groupcache 🦋

alpm_list_t * alpm_db_get_groupcache (alpm_db_t * db)

Get the group cache of a package database. The whole squad, in list form. 🌈

Parameters

  • db — pointer to the package database to get the group from

Returns — the list of groups on success, NULL on error

👑 alpm_db_get_handle 👑

alpm_handle_t * alpm_db_get_handle (alpm_db_t * db)

Find out which handle a package database belongs to. It's giving "who's your parent" but make it Unix. ✨

Parameters

  • db — pointer to the package database

Returns — the alpm handle that the package database belongs to

👑 alpm_db_get_name 👑

const char * alpm_db_get_name (const alpm_db_t * db)

Get the name of a package database. Name reveal moment. 💅

Parameters

  • db — pointer to the package database

Returns — the name of the package database, NULL on error

🔥 alpm_db_get_pkg 🔥

alpm_pkg_t * alpm_db_get_pkg (alpm_db_t * db, const char * name)

Grab a package entry from a package database. And listen — looking up a package is O(1) and will be significantly faster than iterating over the pkgcahe. Do not walk the whole list, I am begging you. 😭

Parameters

  • db — pointer to the package database to get the package from
  • name — of the package

Returns — the package entry on success, NULL on error

🔥 alpm_db_get_pkgcache 🔥

alpm_list_t * alpm_db_get_pkgcache (alpm_db_t * db)

Get the package cache of a package database. This is a list of all packages the db contains. The full roster. Periodt. 🌟

Parameters

  • db — pointer to the package database to get the package from

Returns — the list of packages on success, NULL on error

💜 alpm_db_get_servers 💜

alpm_list_t * alpm_db_get_servers (const alpm_db_t * db)

The list of servers assigned to this db. Show me the servers, bestie. 🎀

Parameters

  • db — pointer to the database to get the servers from

Returns — a char* list of servers

💜 alpm_db_get_siglevel 💜

int alpm_db_get_siglevel (alpm_db_t * db)

Get the signature verification level for a database. And here's the cute bit: if this database is set up with ALPM_SIG_USE_DEFAULT, it'll return the default verification level instead. iykyk. ✨

Parameters

  • db — pointer to the package database

Returns — the signature verification level

🍓 alpm_db_get_usage 🍓

int alpm_db_get_usage (alpm_db_t * db, int * usage)

Gets the usage of a database. Vibe check, but for dbs. 👀

Parameters

  • db — pointer to the package database to get the status of
  • usage — pointer to an alpm_db_usage_t to store db's status

Returns — 0 on success, or -1 on error

🍓 alpm_db_get_valid 🍓

int alpm_db_get_valid (alpm_db_t * db)

Check the validity of a database. This is most useful for sync databases and verifying signature status. If it turns out invalid, the handle error code will be set accordingly. 🚨

Parameters

  • db — pointer to the package database

Returns — 0 if valid, -1 if invalid (pm_errno is set accordingly)

💀 alpm_db_remove_cache_server 💀

int alpm_db_remove_cache_server (alpm_db_t * db, const char * url)

Yeet a download cache server off a database. 🫥

Parameters

  • db — database pointer
  • url — url of the server

Returns — 0 on success, 1 on server not present, -1 on error (pm_errno is set accordingly)

Note that cute little 1 — that's not an error, bestie, that just means the server wasn't even there. Don't panic.

💀 alpm_db_remove_server 💀

int alpm_db_remove_server (alpm_db_t * db, const char * url)

Same deal, but for a regular download server: remove it from a database. 💅

Parameters

  • db — database pointer
  • url — url of the server

Returns — 0 on success, 1 on server not present, -1 on error (pm_errno is set accordingly)

int alpm_db_search (alpm_db_t * db, const alpm_list_t * needles, alpm_list_t ** ret)

Searches a database with regular expressions. Yes, regex. Yes, it goes hard. ✨

Parameters

  • db — pointer to the package database to search in
  • needles — a list of regular expressions to search for
  • ret — pointer to list for storing packages matching all regular expressions — must point to an empty (NULL) alpm_list_t *.
Bestie, read that again: ret must point to an empty (NULL) alpm_list_t *. Not "a list you already filled", not "whatever you had lying around". Empty. NULL. Periodt. 😤

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

🌈 alpm_db_set_cache_servers 🌈

int alpm_db_set_cache_servers (alpm_db_t * db, alpm_list_t * servers)

Sets the list of cache servers for the database to use. 🔥

Parameters

  • db — the database to set the servers. The list will be duped and the original will still need to be freed by the caller.
  • servers — a char* list of servers.
The dupe thing matters, okay? libalpm makes its own copy, but you still own the original and you still have to free it. No leaks in this household. 🫶

🌈 alpm_db_set_servers 🌈

int alpm_db_set_servers (alpm_db_t * db, alpm_list_t * servers)

Sets the list of servers for the database to use. Same rules, same dupe situation. 💅

Parameters

  • db — the database to set the servers. The list will be duped and the original will still need to be freed by the caller.
  • servers — a char* list of servers.

⭐ alpm_db_set_usage ⭐

int alpm_db_set_usage (alpm_db_t * db, int usage)

Sets the usage of a database. Main character energy: you decide what this db is for. 👑

Parameters

  • db — pointer to the package database to set the status for
  • usage — a bitmask of alpm_db_usage_t values

Returns — 0 on success, or -1 on error

🚨 alpm_db_unregister 🚨

int alpm_db_unregister (alpm_db_t * db)

Unregister a package database. But hear me out — Databases can not be unregistered when there is an active transaction. That's a hard no, not a "try it and see". ⚠️

Parameters

  • db — pointer to the package database to unregister

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

🎀 alpm_db_update 🎀

int alpm_db_update (alpm_handle_t * handle, alpm_list_t * dbs, int force)

Update package databases. An update of the package databases in the list dbs will be attempted. Unless force is true, the update will only be performed if the remote databases were modified since the last update. So force is the "I said what I said" switch. 💅

This operation requires a database lock, and will return an applicable error if the lock could not be obtained. (Translation: someone else is holding it, go wait your turn.) 🔒

Example:

alpm_list_t *dbs = alpm_get_syncdbs(config->handle);
ret = alpm_db_update(config->handle, dbs, force);
if(ret < 0) {
    pm_printf(ALPM_LOG_ERROR, _("failed to synchronize all databases (%s)\n"),
        alpm_strerror(alpm_errno(config->handle)));
}
Note — After a successful update, the package cache will be invalidated. So don't be out here holding onto stale pointers like they're still valid, bestie. 😭

Parameters

  • handle — the context handle
  • dbs — list of package databases to update
  • force — if true, then forces the update, otherwise update only in case the databases aren't up to date

Returns — 0 on success, -1 on error (pm_errno is set accordingly), 1 if all databases are up to to date

🏠 alpm_get_localdb 🏠

alpm_db_t * alpm_get_localdb (alpm_handle_t * handle)

Get the database of locally installed packages — your actual machine, your actual stuff. 🫶

The returned pointer points to an internal structure of libalpm which should only be manipulated through libalpm functions. Do not free it. Do not poke it. Do not "just take a peek". Use the API. 🙈

Returns — a reference to the local database

🌈 alpm_get_syncdbs 🌈

alpm_list_t * alpm_get_syncdbs (alpm_handle_t * handle)

Get the list of sync databases. Returns a list of alpm_db_t structures, one for each registered sync database. All the repos, lined up. ⭐

Parameters

  • handle — the context handle

Returns — a reference to an internal list of alpm_db_t structures

✨ alpm_register_syncdb ✨

alpm_db_t * alpm_register_syncdb (alpm_handle_t * handle, const char * treename, int level)

Register a sync database of packages. But heads up — Databases can not be registered when there is an active transaction. Same rule as unregistering, no exceptions. 🚨

Parameters

  • handle — the context handle
  • treename — the name of the sync repository
  • level — what level of signature checking to perform on the database; note that this must be a '.sig' file type verification

Returns — an alpm_db_t* on success (the value), NULL on error

💥 alpm_unregister_all_syncdbs 💥

int alpm_unregister_all_syncdbs (alpm_handle_t * handle)

Unregister all package databases. Every last one. And once again for the people in the back: Databases can not be unregistered while there is an active transaction. 😤

Parameters

  • handle — the context handle

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

✍️ AUTHOR ✍️

Generated automatically by Doxygen for libalpm from the source code. (Not a human author, just a robot doing its little documentation dance. 🤖✨)

And that's the whole page, bestie — this was libalpm_databases(3), brought to you by libalpm, dated by Doxygen and stamped with the manual page name libalpm_databases(3) down at the bottom like a little signature. You made it to the end, I'm so proud of you. Go touch some grass, then come back and read it again. 💖🎀🦋

📦 where this page comes from