Database

Functions to query and manipulate the database of libalpm. More...

Collaboration diagram for Database:

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. More...

Functions
alpm_db_t *	alpm_get_localdb (alpm_handle_t *handle)
	Get the database of locally installed packages.
alpm_list_t *	alpm_get_syncdbs (alpm_handle_t *handle)
	Get the list of sync databases.
alpm_db_t *	alpm_register_syncdb (alpm_handle_t *handle, const char *treename, int level)
	Register a sync database of packages.
int	alpm_unregister_all_syncdbs (alpm_handle_t *handle)
	Unregister all package databases.
int	alpm_db_unregister (alpm_db_t *db)
	Unregister a package database.
alpm_handle_t *	alpm_db_get_handle (alpm_db_t *db)
	Get the handle of a package database.
const char *	alpm_db_get_name (const alpm_db_t *db)
	Get the name of a package database.
int	alpm_db_get_siglevel (alpm_db_t *db)
	Get the signature verification level for a database.
int	alpm_db_get_valid (alpm_db_t *db)
	Check the validity of a database.
int	alpm_db_update (alpm_handle_t *handle, alpm_list_t *dbs, int force)
	Update package databases.
alpm_pkg_t *	alpm_db_get_pkg (alpm_db_t *db, const char *name)
	Get a package entry from a package database.
alpm_list_t *	alpm_db_get_pkgcache (alpm_db_t *db)
	Get the package cache of a package database.
alpm_group_t *	alpm_db_get_group (alpm_db_t *db, const char *name)
	Get a group entry from a package database.
alpm_list_t *	alpm_db_get_groupcache (alpm_db_t *db)
	Get the group cache of a package database.
int	alpm_db_search (alpm_db_t *db, const alpm_list_t *needles, alpm_list_t **ret)
	Searches a database with regular expressions.

Server accessors
alpm_list_t *	alpm_db_get_servers (const alpm_db_t *db)
	Get the list of servers assigned to this db.
int	alpm_db_set_servers (alpm_db_t *db, alpm_list_t *servers)
	Sets the list of servers for the database to use.
int	alpm_db_add_server (alpm_db_t *db, const char *url)
	Add a download server to a database.
int	alpm_db_remove_server (alpm_db_t *db, const char *url)
	Remove a download server from a database.
alpm_list_t *	alpm_db_get_cache_servers (const alpm_db_t *db)
	Get the list of cache servers assigned to this db.
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.
int	alpm_db_add_cache_server (alpm_db_t *db, const char *url)
	Add a download cache server to a database.
int	alpm_db_remove_cache_server (alpm_db_t *db, const char *url)
	Remove a download cache server from a database.

Usage accessors
int	alpm_db_set_usage (alpm_db_t *db, int usage)
	Sets the usage of a database.
int	alpm_db_get_usage (alpm_db_t *db, int *usage)
	Gets the usage of a database.

Detailed Description

Functions to query and manipulate the database of libalpm.

Enumeration Type Documentation

alpm_db_usage_t

enum alpm_db_usage_t

The usage level of a database.

Enumerator
ALPM_DB_USAGE_SYNC	Enable refreshes for this database.
ALPM_DB_USAGE_SEARCH	Enable search for this database.
ALPM_DB_USAGE_INSTALL	Enable installing packages from this database.
ALPM_DB_USAGE_UPGRADE	Enable sysupgrades with this database.
ALPM_DB_USAGE_ALL	Enable all usage levels.

Function Documentation

alpm_db_add_cache_server()

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

Add a download cache server to a database.

Parameters

db	database pointer
url	url of the server

Returns

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

References ALPM_ERR_MEMORY, ALPM_ERR_OK, ALPM_ERR_WRONG_ARGS, alpm_list_add(), ALPM_LOG_DEBUG, ASSERT, RET_ERR, and sanitize_url().

Referenced by alpm_db_set_cache_servers().

alpm_db_add_server()

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

Add a download server to a database.

Parameters

db	database pointer
url	url of the server

Returns

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

References ALPM_ERR_MEMORY, ALPM_ERR_OK, ALPM_ERR_WRONG_ARGS, alpm_list_add(), ALPM_LOG_DEBUG, ASSERT, RET_ERR, and sanitize_url().

Referenced by alpm_db_set_servers().

alpm_db_get_cache_servers()

alpm_list_t * alpm_db_get_cache_servers

(

const alpm_db_t *

db

)

Get the list of cache servers assigned to this db.

Parameters

db	pointer to the database to get the servers from

Returns

a char* list of servers

References ASSERT.

alpm_db_get_group()

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

Get a group entry from a package database.

Looking up a group is O(1) and will be significantly faster than iterating over the groupcahe.

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

References ALPM_ERR_WRONG_ARGS, ASSERT, and RET_ERR.

Referenced by alpm_find_group_pkgs().

alpm_db_get_groupcache()

alpm_list_t * alpm_db_get_groupcache

(

alpm_db_t *

db

)

Get the group cache of a package database.

Parameters

db	pointer to the package database to get the group from

Returns

the list of groups on success, NULL on error

References ALPM_ERR_OK, and ASSERT.

alpm_db_get_handle()

alpm_handle_t * alpm_db_get_handle

(

alpm_db_t *

db

)

Get the handle of a package database.

Parameters

db	pointer to the package database

Returns

the alpm handle that the package database belongs to

References ASSERT.

alpm_db_get_name()

const char * alpm_db_get_name

(

const alpm_db_t *

db

)

Get the name of a package database.

Parameters

db	pointer to the package database

Returns

the name of the package database, NULL on error

References ASSERT.

alpm_db_get_pkg()

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

Get a package entry from a package database.

Looking up a package is O(1) and will be significantly faster than iterating over the pkgcahe.

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

References ALPM_ERR_OK, ALPM_ERR_PKG_NOT_FOUND, ALPM_ERR_WRONG_ARGS, ASSERT, and RET_ERR.

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.

Parameters

db	pointer to the package database to get the package from

Returns

the list of packages on success, NULL on error

References ALPM_ERR_OK, and ASSERT.

Referenced by alpm_db_find_file_owners(), and dep_graph_init().

alpm_db_get_servers()

alpm_list_t * alpm_db_get_servers

(

const alpm_db_t *

db

)

Get the list of servers assigned to this db.

Parameters

db	pointer to the database to get the servers from

Returns

a char* list of servers

References ASSERT.

alpm_db_get_siglevel()

int alpm_db_get_siglevel

(

alpm_db_t *

db

)

Get the signature verification level for a database.

Will return the default verification level if this database is set up with ALPM_SIG_USE_DEFAULT.

Parameters

db	pointer to the package database

Returns

the signature verification level

References ALPM_SIG_USE_DEFAULT, and ASSERT.

Referenced by alpm_db_update(), check_keyring(), check_validity(), download_files(), find_dl_candidates(), and sync_db_validate().

alpm_db_get_usage()

int alpm_db_get_usage	(	alpm_db_t *	db,
		int *	usage )

Gets the usage of a database.

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

References ASSERT.

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 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)

References ALPM_ERR_OK, and ASSERT.

alpm_db_remove_cache_server()

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

Remove a download cache server 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)

References ALPM_ERR_MEMORY, ALPM_ERR_OK, ALPM_ERR_WRONG_ARGS, alpm_list_remove_str(), ALPM_LOG_DEBUG, ASSERT, RET_ERR, and sanitize_url().

alpm_db_remove_server()

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

Remove a download server 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)

References ALPM_ERR_MEMORY, ALPM_ERR_OK, ALPM_ERR_WRONG_ARGS, alpm_list_remove_str(), ALPM_LOG_DEBUG, ASSERT, RET_ERR, and sanitize_url().

alpm_db_search()

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

Searches a database with regular expressions.

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 *.

Returns

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

References ALPM_ERR_OK, ALPM_ERR_WRONG_ARGS, ASSERT, and RET_ERR.

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.

References alpm_db_add_cache_server(), ASSERT, alpm_list_t::data, FREELIST, and alpm_list_t::next.

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.

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.

References alpm_db_add_server(), ASSERT, alpm_list_t::data, FREELIST, and alpm_list_t::next.

alpm_db_set_usage()

int alpm_db_set_usage	(	alpm_db_t *	db,
		int	usage )

Sets the usage of a database.

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

References ASSERT.

alpm_db_unregister()

int alpm_db_unregister

(

alpm_db_t *

db

)

Unregister a package database.

Databases can not be unregistered when there is an active transaction.

Parameters

db	pointer to the package database to unregister

Returns

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

References ALPM_ERR_DB_NOT_FOUND, ALPM_ERR_OK, ALPM_ERR_TRANS_NOT_NULL, alpm_list_remove(), ASSERT, and RET_ERR.

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.

This operation requires a database lock, and will return an applicable error if the lock could not be obtained.

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

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

References alpm_db_get_siglevel(), ALPM_DB_USAGE_SYNC, ALPM_ERR_HANDLE_LOCK, ALPM_ERR_MEMORY, ALPM_ERR_OK, ALPM_ERR_SERVER_NONE, ALPM_ERR_WRONG_ARGS, ALPM_EVENT_DB_RETRIEVE_DONE, ALPM_EVENT_DB_RETRIEVE_FAILED, ALPM_EVENT_DB_RETRIEVE_START, alpm_list_add(), alpm_list_free_inner(), ALPM_LOG_DEBUG, ALPM_SIG_DATABASE, ALPM_SIG_DATABASE_OPTIONAL, alpm_strerror(), ASSERT, CALLOC, CHECK_HANDLE, alpm_list_t::data, DB_STATUS_INVALID, dload_payload::destfile_name, dload_payload::download_signature, EVENT, dload_payload::filepath, dload_payload::force, FREE, FREELIST, get_sync_dir(), GOTO_ERR, dload_payload::handle, MALLOC, dload_payload::max_size, alpm_list_t::next, dload_payload::remote_name, dload_payload::servers, dload_payload::signature_optional, STRDUP, sync_db_validate(), dload_payload::tempfile_name, and dload_payload::unlink_on_fail.

alpm_get_localdb()

alpm_db_t * alpm_get_localdb

(

alpm_handle_t *

handle

)

Get the database of locally installed packages.

The returned pointer points to an internal structure of libalpm which should only be manipulated through libalpm functions.

Returns

a reference to the local database

References CHECK_HANDLE.

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.

Parameters

handle

the context handle

Returns

a reference to an internal list of alpm_db_t structures

References CHECK_HANDLE.

alpm_register_syncdb()

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

Register a sync database of packages.

Databases can not be registered when there is an active transaction.

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

References ALPM_ERR_DB_NOT_NULL, ALPM_ERR_TRANS_NOT_NULL, ALPM_ERR_WRONG_ARGS, ASSERT, CHECK_HANDLE, alpm_list_t::data, alpm_list_t::next, and RET_ERR.

alpm_unregister_all_syncdbs()

int alpm_unregister_all_syncdbs

(

alpm_handle_t *

handle

)

Unregister all package databases.

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)

References ALPM_ERR_TRANS_NOT_NULL, ASSERT, CHECK_HANDLE, alpm_list_t::data, FREELIST, alpm_list_t::next, and RET_ERR.