path: root/upstream/archlinux/man3/libalpm_databases.3

.TH "libalpm_databases" 3 "libalpm" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libalpm_databases \- Database
.SH SYNOPSIS
.br
.PP
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct _alpm_db_t \fBalpm_db_t\fP"
.br
.RI "A database\&. "
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBalpm_db_usage_t\fP { \fBALPM_DB_USAGE_SYNC\fP = 1, \fBALPM_DB_USAGE_SEARCH\fP = (1 << 1), \fBALPM_DB_USAGE_INSTALL\fP = (1 << 2), \fBALPM_DB_USAGE_UPGRADE\fP = (1 << 3), \fBALPM_DB_USAGE_ALL\fP = (1 << 4) - 1 }"
.br
.RI "The usage level of a database\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBalpm_db_t\fP * \fBalpm_get_localdb\fP (\fBalpm_handle_t\fP *handle)"
.br
.RI "Get the database of locally installed packages\&. "
.ti -1c
.RI "\fBalpm_list_t\fP * \fBalpm_get_syncdbs\fP (\fBalpm_handle_t\fP *handle)"
.br
.RI "Get the list of sync databases\&. "
.ti -1c
.RI "\fBalpm_db_t\fP * \fBalpm_register_syncdb\fP (\fBalpm_handle_t\fP *handle, const char *treename, int level)"
.br
.RI "Register a sync database of packages\&. "
.ti -1c
.RI "int \fBalpm_unregister_all_syncdbs\fP (\fBalpm_handle_t\fP *handle)"
.br
.RI "Unregister all package databases\&. "
.ti -1c
.RI "int \fBalpm_db_unregister\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Unregister a package database\&. "
.ti -1c
.RI "\fBalpm_handle_t\fP * \fBalpm_db_get_handle\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Get the handle of a package database\&. "
.ti -1c
.RI "const char * \fBalpm_db_get_name\fP (const \fBalpm_db_t\fP *db)"
.br
.RI "Get the name of a package database\&. "
.ti -1c
.RI "int \fBalpm_db_get_siglevel\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Get the signature verification level for a database\&. "
.ti -1c
.RI "int \fBalpm_db_get_valid\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Check the validity of a database\&. "
.ti -1c
.RI "int \fBalpm_db_update\fP (\fBalpm_handle_t\fP *handle, \fBalpm_list_t\fP *dbs, int force)"
.br
.RI "Update package databases\&. "
.ti -1c
.RI "\fBalpm_pkg_t\fP * \fBalpm_db_get_pkg\fP (\fBalpm_db_t\fP *db, const char *name)"
.br
.RI "Get a package entry from a package database\&. "
.ti -1c
.RI "\fBalpm_list_t\fP * \fBalpm_db_get_pkgcache\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Get the package cache of a package database\&. "
.ti -1c
.RI "\fBalpm_group_t\fP * \fBalpm_db_get_group\fP (\fBalpm_db_t\fP *db, const char *name)"
.br
.RI "Get a group entry from a package database\&. "
.ti -1c
.RI "\fBalpm_list_t\fP * \fBalpm_db_get_groupcache\fP (\fBalpm_db_t\fP *db)"
.br
.RI "Get the group cache of a package database\&. "
.ti -1c
.RI "int \fBalpm_db_search\fP (\fBalpm_db_t\fP *db, const \fBalpm_list_t\fP *needles, \fBalpm_list_t\fP **ret)"
.br
.RI "Searches a database with regular expressions\&. "
.in -1c
.SS "Server accessors"

.in +1c
.ti -1c
.RI "\fBalpm_list_t\fP * \fBalpm_db_get_servers\fP (const \fBalpm_db_t\fP *db)"
.br
.RI "Get the list of servers assigned to this db\&. "
.ti -1c
.RI "int \fBalpm_db_set_servers\fP (\fBalpm_db_t\fP *db, \fBalpm_list_t\fP *servers)"
.br
.RI "Sets the list of servers for the database to use\&. "
.ti -1c
.RI "int \fBalpm_db_add_server\fP (\fBalpm_db_t\fP *db, const char *url)"
.br
.RI "Add a download server to a database\&. "
.ti -1c
.RI "int \fBalpm_db_remove_server\fP (\fBalpm_db_t\fP *db, const char *url)"
.br
.RI "Remove a download server from a database\&. "
.ti -1c
.RI "\fBalpm_list_t\fP * \fBalpm_db_get_cache_servers\fP (const \fBalpm_db_t\fP *db)"
.br
.RI "Get the list of cache servers assigned to this db\&. "
.ti -1c
.RI "int \fBalpm_db_set_cache_servers\fP (\fBalpm_db_t\fP *db, \fBalpm_list_t\fP *servers)"
.br
.RI "Sets the list of cache servers for the database to use\&. "
.ti -1c
.RI "int \fBalpm_db_add_cache_server\fP (\fBalpm_db_t\fP *db, const char *url)"
.br
.RI "Add a download cache server to a database\&. "
.ti -1c
.RI "int \fBalpm_db_remove_cache_server\fP (\fBalpm_db_t\fP *db, const char *url)"
.br
.RI "Remove a download cache server from a database\&. "
.in -1c
.SS "Usage accessors"

.in +1c
.ti -1c
.RI "int \fBalpm_db_set_usage\fP (\fBalpm_db_t\fP *db, int usage)"
.br
.RI "Sets the usage of a database\&. "
.ti -1c
.RI "int \fBalpm_db_get_usage\fP (\fBalpm_db_t\fP *db, int *usage)"
.br
.RI "Gets the usage of a database\&. "
.in -1c
.SH "Detailed Description"
.PP 


Functions to query and manipulate the database of libalpm\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct _alpm_db_t \fBalpm_db_t\fP"

.PP
A database\&. A database is a container that stores metadata about packages\&.
.PP
A database can be located on the local filesystem or on a remote server\&.
.PP
To use a database, it must first be registered via \fBalpm_register_syncdb\fP\&. If the database is already present in dbpath then it will be usable\&. Otherwise, the database needs to be downloaded using \fBalpm_db_update\fP\&. Even if the source of the database is the local filesystem\&.
.PP
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\&.
.PP
Databases are automatically unregistered when the \fBalpm_handle_t\fP is released\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBalpm_db_usage_t\fP"

.PP
The usage level of a database\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIALPM_DB_USAGE_SYNC \fP\fP
Enable refreshes for this database\&. 
.TP
\fB\fIALPM_DB_USAGE_SEARCH \fP\fP
Enable search for this database\&. 
.TP
\fB\fIALPM_DB_USAGE_INSTALL \fP\fP
Enable installing packages from this database\&. 
.TP
\fB\fIALPM_DB_USAGE_UPGRADE \fP\fP
Enable sysupgrades with this database\&. 
.TP
\fB\fIALPM_DB_USAGE_ALL \fP\fP
Enable all usage levels\&. 
.SH "Function Documentation"
.PP 
.SS "int alpm_db_add_cache_server (\fBalpm_db_t\fP * db, const char * url)"

.PP
Add a download cache server to a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP database pointer 
.br
\fIurl\fP url of the server 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_add_server (\fBalpm_db_t\fP * db, const char * url)"

.PP
Add a download server to a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP database pointer 
.br
\fIurl\fP url of the server 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "\fBalpm_list_t\fP * alpm_db_get_cache_servers (const \fBalpm_db_t\fP * db)"

.PP
Get the list of cache servers assigned to this db\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the database to get the servers from 
.RE
.PP
\fBReturns\fP
.RS 4
a char* list of servers 
.RE
.PP

.SS "\fBalpm_group_t\fP * alpm_db_get_group (\fBalpm_db_t\fP * db, const char * name)"

.PP
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\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to get the group from 
.br
\fIname\fP of the group 
.RE
.PP
\fBReturns\fP
.RS 4
the groups entry on success, NULL on error 
.RE
.PP

.SS "\fBalpm_list_t\fP * alpm_db_get_groupcache (\fBalpm_db_t\fP * db)"

.PP
Get the group cache of a package database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to get the group from 
.RE
.PP
\fBReturns\fP
.RS 4
the list of groups on success, NULL on error 
.RE
.PP

.SS "\fBalpm_handle_t\fP * alpm_db_get_handle (\fBalpm_db_t\fP * db)"

.PP
Get the handle of a package database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database 
.RE
.PP
\fBReturns\fP
.RS 4
the alpm handle that the package database belongs to 
.RE
.PP

.SS "const char * alpm_db_get_name (const \fBalpm_db_t\fP * db)"

.PP
Get the name of a package database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database 
.RE
.PP
\fBReturns\fP
.RS 4
the name of the package database, NULL on error 
.RE
.PP

.SS "\fBalpm_pkg_t\fP * alpm_db_get_pkg (\fBalpm_db_t\fP * db, const char * name)"

.PP
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\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to get the package from 
.br
\fIname\fP of the package 
.RE
.PP
\fBReturns\fP
.RS 4
the package entry on success, NULL on error 
.RE
.PP

.SS "\fBalpm_list_t\fP * alpm_db_get_pkgcache (\fBalpm_db_t\fP * db)"

.PP
Get the package cache of a package database\&. This is a list of all packages the db contains\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to get the package from 
.RE
.PP
\fBReturns\fP
.RS 4
the list of packages on success, NULL on error 
.RE
.PP

.SS "\fBalpm_list_t\fP * alpm_db_get_servers (const \fBalpm_db_t\fP * db)"

.PP
Get the list of servers assigned to this db\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the database to get the servers from 
.RE
.PP
\fBReturns\fP
.RS 4
a char* list of servers 
.RE
.PP

.SS "int alpm_db_get_siglevel (\fBalpm_db_t\fP * db)"

.PP
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\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database 
.RE
.PP
\fBReturns\fP
.RS 4
the signature verification level 
.RE
.PP

.SS "int alpm_db_get_usage (\fBalpm_db_t\fP * db, int * usage)"

.PP
Gets the usage of a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to get the status of 
.br
\fIusage\fP pointer to an alpm_db_usage_t to store db's status 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, or -1 on error 
.RE
.PP

.SS "int alpm_db_get_valid (\fBalpm_db_t\fP * db)"

.PP
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\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database 
.RE
.PP
\fBReturns\fP
.RS 4
0 if valid, -1 if invalid (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_remove_cache_server (\fBalpm_db_t\fP * db, const char * url)"

.PP
Remove a download cache server from a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP database pointer 
.br
\fIurl\fP url of the server 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, 1 on server not present, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_remove_server (\fBalpm_db_t\fP * db, const char * url)"

.PP
Remove a download server from a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP database pointer 
.br
\fIurl\fP url of the server 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, 1 on server not present, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_search (\fBalpm_db_t\fP * db, const \fBalpm_list_t\fP * needles, \fBalpm_list_t\fP ** ret)"

.PP
Searches a database with regular expressions\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to search in 
.br
\fIneedles\fP a list of regular expressions to search for 
.br
\fIret\fP pointer to list for storing packages matching all regular expressions - must point to an empty (NULL) \fBalpm_list_t\fP *\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_set_cache_servers (\fBalpm_db_t\fP * db, \fBalpm_list_t\fP * servers)"

.PP
Sets the list of cache servers for the database to use\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP the database to set the servers\&. The list will be duped and the original will still need to be freed by the caller\&. 
.br
\fIservers\fP a char* list of servers\&. 
.RE
.PP

.SS "int alpm_db_set_servers (\fBalpm_db_t\fP * db, \fBalpm_list_t\fP * servers)"

.PP
Sets the list of servers for the database to use\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP the database to set the servers\&. The list will be duped and the original will still need to be freed by the caller\&. 
.br
\fIservers\fP a char* list of servers\&. 
.RE
.PP

.SS "int alpm_db_set_usage (\fBalpm_db_t\fP * db, int usage)"

.PP
Sets the usage of a database\&. 
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to set the status for 
.br
\fIusage\fP a bitmask of alpm_db_usage_t values 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, or -1 on error 
.RE
.PP

.SS "int alpm_db_unregister (\fBalpm_db_t\fP * db)"

.PP
Unregister a package database\&. Databases can not be unregistered when there is an active transaction\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP pointer to the package database to unregister 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SS "int alpm_db_update (\fBalpm_handle_t\fP * handle, \fBalpm_list_t\fP * dbs, int force)"

.PP
Update package databases\&. An update of the package databases in the list \fIdbs\fP will be attempted\&. Unless \fIforce\fP is true, the update will only be performed if the remote databases were modified since the last update\&.
.PP
This operation requires a database lock, and will return an applicable error if the lock could not be obtained\&.
.PP
Example: 
.PP
.nf
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)));
}

.fi
.PP
.PP
\fBNote\fP
.RS 4
After a successful update, the \fBpackage cache \fP will be invalidated 
.RE
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the context handle 
.br
\fIdbs\fP list of package databases to update 
.br
\fIforce\fP if true, then forces the update, otherwise update only in case the databases aren't up to date 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly), 1 if all databases are up to to date 
.RE
.PP

.SS "\fBalpm_db_t\fP * alpm_get_localdb (\fBalpm_handle_t\fP * handle)"

.PP
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\&. 
.PP
\fBReturns\fP
.RS 4
a reference to the local database 
.RE
.PP

.SS "\fBalpm_list_t\fP * alpm_get_syncdbs (\fBalpm_handle_t\fP * handle)"

.PP
Get the list of sync databases\&. Returns a list of alpm_db_t structures, one for each registered sync database\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the context handle 
.RE
.PP
\fBReturns\fP
.RS 4
a reference to an internal list of alpm_db_t structures 
.RE
.PP

.SS "\fBalpm_db_t\fP * alpm_register_syncdb (\fBalpm_handle_t\fP * handle, const char * treename, int level)"

.PP
Register a sync database of packages\&. Databases can not be registered when there is an active transaction\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the context handle 
.br
\fItreename\fP the name of the sync repository 
.br
\fIlevel\fP what level of signature checking to perform on the database; note that this must be a '\&.sig' file type verification 
.RE
.PP
\fBReturns\fP
.RS 4
an alpm_db_t* on success (the value), NULL on error 
.RE
.PP

.SS "int alpm_unregister_all_syncdbs (\fBalpm_handle_t\fP * handle)"

.PP
Unregister all package databases\&. Databases can not be unregistered while there is an active transaction\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the context handle 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (pm_errno is set accordingly) 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libalpm from the source code\&.