It is commonly accepted that incorrect documentation is worse than none. Unfortunately commits 6ebb6fec8b356c87e6fdea5659bbf34461adee90 96432ab4ef27bc6a570427736d8b7f439535e05f aac9e7c280a9686520e0f8f4bd7ffe4ed901716d separated documentation and source code for public, exported functions. This makes maintenance more difficult since behaviour changes require documentation updates in a separate file. This commit moves them back to source files, but leaves the necessary hints in alpm.h to produce structured output using doxygen. Signed-off-by: Rémy Oudompheng --- lib/libalpm/alpm.h | 317 ---------------------------------------------- lib/libalpm/be_package.c | 10 ++ lib/libalpm/db.c | 65 ++++++++-- lib/libalpm/deps.c | 21 +++- lib/libalpm/dload.c | 5 +- lib/libalpm/handle.c | 42 ++++++ lib/libalpm/package.c | 142 ++++++++++++++++++++- lib/libalpm/trans.c | 34 ++++- 8 files changed, 293 insertions(+), 343 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index cb643d2..61c8cdb 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -98,10 +98,6 @@ typedef void (*alpm_cb_totaldl)(off_t total); typedef int (*alpm_cb_fetch)(const char *url, const char *localpath, int force); -/** Fetch a remote pkg. - * @param url URL of the package to download - * @return the downloaded filepath on success, NULL on error - */ char *alpm_fetch_pkgurl(const char *url); /** @addtogroup alpm_api_options Options @@ -109,56 +105,34 @@ char *alpm_fetch_pkgurl(const char *url); * @{ */ -/** @name The logging callback. */ -/* @{ */ alpm_cb_log alpm_option_get_logcb(void); void alpm_option_set_logcb(alpm_cb_log cb); -/* @} */ -/** Get/set the download progress callback. */ alpm_cb_download alpm_option_get_dlcb(void); void alpm_option_set_dlcb(alpm_cb_download cb); -/** Get/set the downloader callback. */ alpm_cb_fetch alpm_option_get_fetchcb(void); void alpm_option_set_fetchcb(alpm_cb_fetch cb); -/** Get/set the callback used when download size is known. */ alpm_cb_totaldl alpm_option_get_totaldlcb(void); void alpm_option_set_totaldlcb(alpm_cb_totaldl cb); -/** Get/set the root of the destination filesystem. */ const char *alpm_option_get_root(void); int alpm_option_set_root(const char *root); -/** Get/set the path to the database directory. */ const char *alpm_option_get_dbpath(void); int alpm_option_set_dbpath(const char *dbpath); -/** Get/set the list of package cache directories. */ alpm_list_t *alpm_option_get_cachedirs(void); void alpm_option_set_cachedirs(alpm_list_t *cachedirs); - -/** Add a single directory to the package cache paths. */ int alpm_option_add_cachedir(const char *cachedir); - -/** Remove a single directory from the package cache paths. */ int alpm_option_remove_cachedir(const char *cachedir); -/** Get/set the logfile name. */ const char *alpm_option_get_logfile(void); int alpm_option_set_logfile(const char *logfile); -/** Get the name of the database lock file. - * - * This properly is read-only, and determined from - * the database path. - * - * @sa alpm_option_set_dbpath(const char*) - */ const char *alpm_option_get_lockfile(void); -/** Get/set whether to use syslog (0 is FALSE, TRUE otherwise). */ int alpm_option_get_usesyslog(void); void alpm_option_set_usesyslog(int usesyslog); @@ -182,7 +156,6 @@ void alpm_option_add_ignoregrp(const char *grp); void alpm_option_set_ignoregrps(alpm_list_t *ignoregrps); int alpm_option_remove_ignoregrp(const char *grp); -/** Get/set the targeted architecture. */ const char *alpm_option_get_arch(void); void alpm_option_set_arch(const char *arch); @@ -209,98 +182,31 @@ typedef enum _pmpkgreason_t { * @{ */ -/** 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. - * @return a reference to the local database - */ pmdb_t *alpm_option_get_localdb(void); - -/** Get the list of sync databases. - * Returns a list of pmdb_t structures, one for each registered - * sync database. - * @return a reference to an internal list of pmdb_t structures - */ alpm_list_t *alpm_option_get_syncdbs(void); -/** Register a sync database of packages. - * @param treename the name of the sync repository - * @return a pmdb_t* on success (the value), NULL on error - */ pmdb_t *alpm_db_register_sync(const char *treename); - -/** Unregister a package database. - * @param db pointer to the package database to unregister - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_db_unregister(pmdb_t *db); - -/** Unregister all package databases. - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_db_unregister_all(void); -/** Get the name of a package database. - * @param db pointer to the package database - * @return the name of the package database, NULL on error - */ const char *alpm_db_get_name(const pmdb_t *db); -/** Get a download URL for the package database. - * @param db pointer to the package database - * @return a fully-specified download URL, NULL on error - */ const char *alpm_db_get_url(const pmdb_t *db); -/** Set the serverlist of a database. - * @param db database pointer - * @param url url of the server - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_db_setserver(pmdb_t *db, const char *url); int alpm_db_update(int level, pmdb_t *db); -/** Get a package entry from a package database. - * @param db pointer to the package database to get the package from - * @param name of the package - * @return the package entry on success, NULL on error - */ pmpkg_t *alpm_db_get_pkg(pmdb_t *db, const char *name); -/** Get the package cache of a package database. - * @param db pointer to the package database to get the package from - * @return the list of packages on success, NULL on error - */ alpm_list_t *alpm_db_get_pkgcache(pmdb_t *db); -/** Get a group entry from a package database. - * @param db pointer to the package database to get the group from - * @param name of the group - * @return the groups entry on success, NULL on error - */ pmgrp_t *alpm_db_readgrp(pmdb_t *db, const char *name); -/** Get the group cache of a package database. - * @param db pointer to the package database to get the group from - * @return the list of groups on success, NULL on error - */ alpm_list_t *alpm_db_get_grpcache(pmdb_t *db); -/** Searches a database. - * @param db pointer to the package database to search in - * @param needles the list of strings to search for - * @return the list of packages on success, NULL on error - */ alpm_list_t *alpm_db_search(pmdb_t *db, const alpm_list_t* needles); -/** Set install reason for a package in db. - * @param db pointer to the package database - * @param name the name of the package - * @param reason the new install reason - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason); /** @} */ @@ -310,39 +216,15 @@ int alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason); * @{ */ -/** Create a package from a file. - * If full is false, the archive is read only until all necessary - * metadata is found. If it is true, the entire archive is read, which - * serves as a verfication of integrity and the filelist can be created. - * @param filename location of the package tarball - * @param full whether to stop the load after metadata is read or continue - * through the full archive - * @param pkg address of the package pointer - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_pkg_load(const char *filename, int full, pmpkg_t **pkg); -/** Free a package. - * @param pkg package pointer to free - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_pkg_free(pmpkg_t *pkg); -/** Check the integrity (with md5) of a package from the sync cache. - * @param pkg package pointer - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_pkg_checkmd5sum(pmpkg_t *pkg); /** Compare two version strings and determine which one is 'newer'. */ int alpm_pkg_vercmp(const char *a, const char *b); -/** Computes the list of packages requiring a given package. - * The return value of this function is a newly allocated - * list of package names (char*), it should be freed by the caller. - * @param pkg a package - * @return the list of packages requiring pkg - */ alpm_list_t *alpm_pkg_compute_requiredby(pmpkg_t *pkg); /** @name Package Property Accessors @@ -352,181 +234,36 @@ alpm_list_t *alpm_pkg_compute_requiredby(pmpkg_t *pkg); * @{ */ -/** Gets the name of the file from which the package was loaded. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_filename(pmpkg_t *pkg); - -/** Returns the package name. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_name(pmpkg_t *pkg); - -/** Returns the package version as a string. - * This includes all available epoch, version, and pkgrel components. Use - * alpm_pkg_vercmp() to compare version strings if necessary. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_version(pmpkg_t *pkg); - -/** Returns the package description. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_desc(pmpkg_t *pkg); - -/** Returns the package URL. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_url(pmpkg_t *pkg); - -/** Returns the build timestamp of the package. - * @param pkg a pointer to package - * @return the timestamp of the build time - */ time_t alpm_pkg_get_builddate(pmpkg_t *pkg); - -/** Returns the install timestamp of the package. - * @param pkg a pointer to package - * @return the timestamp of the install time - */ time_t alpm_pkg_get_installdate(pmpkg_t *pkg); - -/** Returns the packager's name. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_packager(pmpkg_t *pkg); - -/** Returns the package's MD5 checksum as a string. - * The returned string is a sequence of lowercase hexadecimal digits. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_md5sum(pmpkg_t *pkg); - -/** Returns the architecture for which the package was built. - * @param pkg a pointer to package - * @return a reference to an internal string - */ const char *alpm_pkg_get_arch(pmpkg_t *pkg); - -/** Returns the size of the package. - * @param pkg a pointer to package - * @return the size of the package in bytes. - */ off_t alpm_pkg_get_size(pmpkg_t *pkg); - -/** Returns the installed size of the package. - * @param pkg a pointer to package - * @return the total size of files installed by the package. - */ off_t alpm_pkg_get_isize(pmpkg_t *pkg); - -/** Returns the package installation reason. - * @param pkg a pointer to package - * @return an enum member giving the install reason. - */ pmpkgreason_t alpm_pkg_get_reason(pmpkg_t *pkg); - -/** Returns the list of package licenses. - * @param pkg a pointer to package - * @return a pointer to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_licenses(pmpkg_t *pkg); - -/** Returns the list of package groups. - * @param pkg a pointer to package - * @return a pointer to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_groups(pmpkg_t *pkg); - -/** Returns the list of package dependencies as pmdepend_t. - * @param pkg a pointer to package - * @return a reference to an internal list of pmdepend_t structures. - */ alpm_list_t *alpm_pkg_get_depends(pmpkg_t *pkg); - -/** Returns the list of package optional dependencies. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_optdepends(pmpkg_t *pkg); - -/** Returns the list of package names conflicting with pkg. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_conflicts(pmpkg_t *pkg); - -/** Returns the list of package names provided by pkg. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_provides(pmpkg_t *pkg); - -/** Returns the list of available deltas for pkg. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_deltas(pmpkg_t *pkg); - -/** Returns the list of packages to be replaced by pkg. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_replaces(pmpkg_t *pkg); - -/** Returns the list of files installed by pkg. - * The filenames are relative to the install root, - * and do not include leading slashes. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_files(pmpkg_t *pkg); - -/** Returns the list of files backed up when installing pkg. - * The elements of the returned list have the form - * "<filename>\t<md5sum>", where the given md5sum is that of - * the file as provided by the package. - * @param pkg a pointer to package - * @return a reference to an internal list of strings. - */ alpm_list_t *alpm_pkg_get_backup(pmpkg_t *pkg); - -/** Returns the database containing pkg - * Returns a pointer to the pmdb_t structure the package is - * originating from, or NULL is the package was loaded from a file. - * @param pkg a pointer to package - * @return a pointer to the DB containing pkg, or NULL. - */ pmdb_t *alpm_pkg_get_db(pmpkg_t *pkg); /* End of pmpkg_t accessors */ /* @} */ -/** Open a package changelog for reading. - * Similar to fopen in functionality, except that the returned 'file - * stream' could really be from an archive as well as from the database. - * @param pkg the package to read the changelog of (either file or db) - * @return a 'file stream' to the package changelog - */ void *alpm_pkg_changelog_open(pmpkg_t *pkg); -/** Read data from an open changelog 'file stream'. - * Similar to fread in functionality, this function takes a buffer and - * amount of data to read. If an error occurs pm_errno will be set. - * @param ptr a buffer to fill with raw changelog data - * @param size the size of the buffer - * @param pkg the package that the changelog is being read from - * @param fp a 'file stream' to the package changelog - * @return the number of characters read, or 0 if there is no more data or an - * error occurred. - */ size_t alpm_pkg_changelog_read(void *ptr, size_t size, const pmpkg_t *pkg, const void *fp); @@ -536,12 +273,6 @@ int alpm_pkg_changelog_close(const pmpkg_t *pkg, void *fp); int alpm_pkg_has_scriptlet(pmpkg_t *pkg); -/** Returns the size of download. - * Returns the size of the files that will be downloaded to install a - * package. - * @param newpkg the new package to upgrade to - * @return the size of the download - */ off_t alpm_pkg_download_size(pmpkg_t *newpkg); alpm_list_t *alpm_pkg_unused_deltas(pmpkg_t *pkg); @@ -728,49 +459,20 @@ typedef void (*alpm_trans_cb_progress)(pmtransprog_t, const char *, int, size_t, int alpm_trans_get_flags(void); -/** Returns a list of packages added by the transaction. - * @return a list of pmpkg_t structures - */ alpm_list_t * alpm_trans_get_add(void); -/** Returns the list of packages removed by the transaction. - * @return a list of pmpkg_t structures - */ alpm_list_t * alpm_trans_get_remove(void); -/** Initialize the transaction. - * @param flags flags of the transaction (like nodeps, etc) - * @param event event callback function pointer - * @param conv question callback function pointer - * @param progress progress callback function pointer - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_trans_init(pmtransflag_t flags, alpm_trans_cb_event cb_event, alpm_trans_cb_conv conv, alpm_trans_cb_progress cb_progress); -/** Prepare a transaction. - * @param data the address of an alpm_list where a list - * of pmdepmissing_t objects is dumped (conflicting packages) - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_trans_prepare(alpm_list_t **data); -/** Commit a transaction. - * @param data the address of an alpm_list where detailed description - * of an error can be dumped (ie. list of conflicting files) - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_trans_commit(alpm_list_t **data); -/** Interrupt a transaction. - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_trans_interrupt(void); -/** Release a transaction. - * @return 0 on success, -1 on error (pm_errno is set accordingly) - */ int alpm_trans_release(void); /** @} */ @@ -818,31 +520,12 @@ const char *alpm_conflict_get_package1(pmconflict_t *conflict); const char *alpm_conflict_get_package2(pmconflict_t *conflict); const char *alpm_conflict_get_reason(pmconflict_t *conflict); -/** Returns the type of version constraint. - * @param dep a dependency info structure - * @return the type of version constraint (PM_DEP_MOD_ANY if no version - * is specified). - */ pmdepmod_t alpm_dep_get_mod(const pmdepend_t *dep); -/** Returns the package name of a dependency constraint. - * @param dep a dependency info structure - * @return a pointer to an internal string. - */ const char *alpm_dep_get_name(const pmdepend_t *dep); -/** Returns the version specified by a dependency constraint. - * The version information is returned as a string in the same format - * as given by alpm_pkg_get_version(). - * @param dep a dependency info structure - * @return a pointer to an internal string. - */ const char *alpm_dep_get_version(const pmdepend_t *dep); -/** Returns a newly allocated string representing the dependency information. - * @param dep a dependency info structure - * @return a formatted string, e.g. "glibc>=2.12" - */ char *alpm_dep_compute_string(const pmdepend_t *dep); /** @} */ diff --git a/lib/libalpm/be_package.c b/lib/libalpm/be_package.c index 6dfddd6..f483789 100644 --- a/lib/libalpm/be_package.c +++ b/lib/libalpm/be_package.c @@ -367,6 +367,16 @@ error: return(NULL); } +/** Create a package from a file. + * If full is false, the archive is read only until all necessary + * metadata is found. If it is true, the entire archive is read, which + * serves as a verfication of integrity and the filelist can be created. + * @param filename location of the package tarball + * @param full whether to stop the load after metadata is read or continue + * through the full archive + * @param pkg address of the package pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_pkg_load(const char *filename, int full, pmpkg_t **pkg) { ALPM_LOG_FUNC; diff --git a/lib/libalpm/db.c b/lib/libalpm/db.c index 1a3168b..2f4dc4b 100644 --- a/lib/libalpm/db.c +++ b/lib/libalpm/db.c @@ -47,7 +47,10 @@ * @{ */ -/** Register a sync database of packages. */ +/** Register a sync database of packages. + * @param treename the name of the sync repository + * @return a pmdb_t* on success (the value), NULL on error + */ pmdb_t SYMEXPORT *alpm_db_register_sync(const char *treename) { ALPM_LOG_FUNC; @@ -72,7 +75,9 @@ void _alpm_db_unregister(pmdb_t *db) _alpm_db_free(db); } -/** Unregister all package databases. */ +/** Unregister all package sync databases. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_db_unregister_all(void) { alpm_list_t *i; @@ -95,7 +100,10 @@ int SYMEXPORT alpm_db_unregister_all(void) return(0); } -/** Unregister a package database. */ +/** Unregister a package database. + * @param db pointer to the package database to unregister + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_db_unregister(pmdb_t *db) { int found = 0; @@ -132,7 +140,11 @@ int SYMEXPORT alpm_db_unregister(pmdb_t *db) return(0); } -/** Set the serverlist of a database. */ +/** Set the serverlist of a database. + * @param db database pointer + * @param url url of the server + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_db_setserver(pmdb_t *db, const char *url) { alpm_list_t *i; @@ -175,7 +187,10 @@ int SYMEXPORT alpm_db_setserver(pmdb_t *db, const char *url) return(0); } -/** Get the name of a package database. */ +/** Get the name of a package database. + * @param db pointer to the package database + * @return the name of the package database, NULL on error + */ const char SYMEXPORT *alpm_db_get_name(const pmdb_t *db) { ALPM_LOG_FUNC; @@ -187,7 +202,10 @@ const char SYMEXPORT *alpm_db_get_name(const pmdb_t *db) return db->treename; } -/** Get a download URL for the package database. */ +/** Get a download URL for the package database. + * @param db pointer to the package database + * @return a fully-specified download URL, NULL on error + */ const char SYMEXPORT *alpm_db_get_url(const pmdb_t *db) { char *url; @@ -205,7 +223,11 @@ const char SYMEXPORT *alpm_db_get_url(const pmdb_t *db) } -/** Get a package entry from a package database. */ +/** Get a package entry from a package database. + * @param db pointer to the package database to get the package from + * @param name of the package + * @return the package entry on success, NULL on error + */ pmpkg_t SYMEXPORT *alpm_db_get_pkg(pmdb_t *db, const char *name) { ALPM_LOG_FUNC; @@ -218,7 +240,10 @@ pmpkg_t SYMEXPORT *alpm_db_get_pkg(pmdb_t *db, const char *name) return(_alpm_db_get_pkgfromcache(db, name)); } -/** Get the package cache of a package database. */ +/** Get the package cache of a package database. + * @param db pointer to the package database to get the package from + * @return the list of packages on success, NULL on error + */ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(pmdb_t *db) { ALPM_LOG_FUNC; @@ -230,7 +255,11 @@ alpm_list_t SYMEXPORT *alpm_db_get_pkgcache(pmdb_t *db) return(_alpm_db_get_pkgcache(db)); } -/** Get a group entry from a package database. */ +/** Get a group entry from a package database. + * @param db pointer to the package database to get the group from + * @param name of the group + * @return the groups entry on success, NULL on error + */ pmgrp_t SYMEXPORT *alpm_db_readgrp(pmdb_t *db, const char *name) { ALPM_LOG_FUNC; @@ -243,7 +272,10 @@ pmgrp_t SYMEXPORT *alpm_db_readgrp(pmdb_t *db, const char *name) return(_alpm_db_get_grpfromcache(db, name)); } -/** Get the group cache of a package database. */ +/** Get the group cache of a package database. + * @param db pointer to the package database to get the group from + * @return the list of groups on success, NULL on error + */ alpm_list_t SYMEXPORT *alpm_db_get_grpcache(pmdb_t *db) { ALPM_LOG_FUNC; @@ -255,7 +287,11 @@ alpm_list_t SYMEXPORT *alpm_db_get_grpcache(pmdb_t *db) return(_alpm_db_get_grpcache(db)); } -/** Searches a database. */ +/** Searches a database. + * @param db pointer to the package database to search in + * @param needles the list of strings to search for + * @return the list of packages on success, NULL on error + */ alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db, const alpm_list_t* needles) { ALPM_LOG_FUNC; @@ -267,7 +303,12 @@ alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db, const alpm_list_t* needles) return(_alpm_db_search(db, needles)); } -/** Set install reason for a package in db. */ +/** Set install reason for a package in db. + * @param db pointer to the package database + * @param name the name of the package + * @param reason the new install reason + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_db_set_pkgreason(pmdb_t *db, const char *name, pmpkgreason_t reason) { ALPM_LOG_FUNC; diff --git a/lib/libalpm/deps.c b/lib/libalpm/deps.c index 36d6e1a..0396e1e 100644 --- a/lib/libalpm/deps.c +++ b/lib/libalpm/deps.c @@ -793,6 +793,11 @@ pmdepend_t SYMEXPORT *alpm_miss_get_dep(pmdepmissing_t *miss) return(miss->depend); } +/** Returns the type of version constraint. + * @param dep a dependency info structure + * @return the type of version constraint (PM_DEP_MOD_ANY if no version + * is specified). + */ pmdepmod_t SYMEXPORT alpm_dep_get_mod(const pmdepend_t *dep) { ALPM_LOG_FUNC; @@ -803,6 +808,10 @@ pmdepmod_t SYMEXPORT alpm_dep_get_mod(const pmdepend_t *dep) return(dep->mod); } +/** Returns the package name of a dependency constraint. + * @param dep a dependency info structure + * @return a pointer to an internal string. + */ const char SYMEXPORT *alpm_dep_get_name(const pmdepend_t *dep) { ALPM_LOG_FUNC; @@ -813,6 +822,12 @@ const char SYMEXPORT *alpm_dep_get_name(const pmdepend_t *dep) return(dep->name); } +/** Returns the version specified by a dependency constraint. + * The version information is returned as a string in the same format + * as given by alpm_pkg_get_version(). + * @param dep a dependency info structure + * @return a pointer to an internal string. + */ const char SYMEXPORT *alpm_dep_get_version(const pmdepend_t *dep) { ALPM_LOG_FUNC; @@ -823,10 +838,10 @@ const char SYMEXPORT *alpm_dep_get_version(const pmdepend_t *dep) return(dep->version); } -/** Reverse of splitdep; make a dep string from a pmdepend_t struct. +/** Returns a newly allocated string representing the dependency information. * The string must be freed! - * @param dep the depend to turn into a string - * @return a string-formatted dependency with operator if necessary + * @param dep a dependency info structure + * @return a formatted string with operator if necessary, e.g. "glibc>=2.12" */ char SYMEXPORT *alpm_dep_compute_string(const pmdepend_t *dep) { diff --git a/lib/libalpm/dload.c b/lib/libalpm/dload.c index a98d84a..41ae676 100644 --- a/lib/libalpm/dload.c +++ b/lib/libalpm/dload.c @@ -415,7 +415,10 @@ int _alpm_download_files(alpm_list_t *files, return(ret); } -/** Fetch a remote pkg. */ +/** Fetch a remote pkg. + * @param url URL of the package to download + * @return the downloaded filepath on success, NULL on error + */ char SYMEXPORT *alpm_fetch_pkgurl(const char *url) { char *filename, *filepath; diff --git a/lib/libalpm/handle.c b/lib/libalpm/handle.c index d8ce9fd..917441e 100644 --- a/lib/libalpm/handle.c +++ b/lib/libalpm/handle.c @@ -87,6 +87,7 @@ void _alpm_handle_free(pmhandle_t *handle) FREE(handle); } +/** Returns the callback used for logging. */ alpm_cb_log SYMEXPORT alpm_option_get_logcb() { if (handle == NULL) { @@ -96,6 +97,7 @@ alpm_cb_log SYMEXPORT alpm_option_get_logcb() return handle->logcb; } +/** Returns the callback used for reporting download progress. */ alpm_cb_download SYMEXPORT alpm_option_get_dlcb() { if (handle == NULL) { @@ -105,6 +107,7 @@ alpm_cb_download SYMEXPORT alpm_option_get_dlcb() return handle->dlcb; } +/** Returns the callback used for downloading files. */ alpm_cb_fetch SYMEXPORT alpm_option_get_fetchcb() { if (handle == NULL) { @@ -114,6 +117,7 @@ alpm_cb_fetch SYMEXPORT alpm_option_get_fetchcb() return handle->fetchcb; } +/** Returns the callback used for reporting total download size. */ alpm_cb_totaldl SYMEXPORT alpm_option_get_totaldlcb() { if (handle == NULL) { @@ -123,6 +127,7 @@ alpm_cb_totaldl SYMEXPORT alpm_option_get_totaldlcb() return handle->totaldlcb; } +/** Returns the root of the destination filesystem. */ const char SYMEXPORT *alpm_option_get_root() { if (handle == NULL) { @@ -132,6 +137,7 @@ const char SYMEXPORT *alpm_option_get_root() return handle->root; } +/** Returns the path of the database directoy. */ const char SYMEXPORT *alpm_option_get_dbpath() { if (handle == NULL) { @@ -141,6 +147,7 @@ const char SYMEXPORT *alpm_option_get_dbpath() return handle->dbpath; } +/** Returns the list of package cache directories (strings). */ alpm_list_t SYMEXPORT *alpm_option_get_cachedirs() { if (handle == NULL) { @@ -150,6 +157,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_cachedirs() return handle->cachedirs; } +/** Returns the path of the log file. */ const char SYMEXPORT *alpm_option_get_logfile() { if (handle == NULL) { @@ -159,6 +167,11 @@ const char SYMEXPORT *alpm_option_get_logfile() return handle->logfile; } +/** Returns the name of the database lock file. + * This properly is read-only, and determined from + * the database path. + * @sa alpm_option_set_dbpath(const char*) + */ const char SYMEXPORT *alpm_option_get_lockfile() { if (handle == NULL) { @@ -168,6 +181,7 @@ const char SYMEXPORT *alpm_option_get_lockfile() return handle->lockfile; } +/** Returns whether to use syslog (0 is FALSE, TRUE otherwise). */ int SYMEXPORT alpm_option_get_usesyslog() { if (handle == NULL) { @@ -213,6 +227,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_ignoregrps() return handle->ignoregrp; } +/** Returns the targeted architecture. */ const char SYMEXPORT *alpm_option_get_arch() { if (handle == NULL) { @@ -231,6 +246,7 @@ int SYMEXPORT alpm_option_get_usedelta() return handle->usedelta; } +/** Returns whether to check disk space (0 is FALSE, >0 is TRUE). */ int SYMEXPORT alpm_option_get_checkspace() { if (handle == NULL) { @@ -240,6 +256,12 @@ int SYMEXPORT alpm_option_get_checkspace() return handle->checkspace; } +/** Gets the database of locally installed packages. + * The returned pointer points to an internal structure + * of libalpm which should only be manipulated through + * libalpm functions. + * @return a reference to the local database + */ pmdb_t SYMEXPORT *alpm_option_get_localdb() { if (handle == NULL) { @@ -249,6 +271,11 @@ pmdb_t SYMEXPORT *alpm_option_get_localdb() return handle->db_local; } +/** Gets the list of sync databases. + * Returns a list of pmdb_t structures, one for each registered + * sync database. + * @return a reference to an internal list of pmdb_t structures + */ alpm_list_t SYMEXPORT *alpm_option_get_syncdbs() { if (handle == NULL) { @@ -376,6 +403,7 @@ int SYMEXPORT alpm_option_set_dbpath(const char *dbpath) return(0); } +/** Adds a single directory to the package cache paths. */ int SYMEXPORT alpm_option_add_cachedir(const char *cachedir) { char *newcachedir; @@ -411,6 +439,7 @@ void SYMEXPORT alpm_option_set_cachedirs(alpm_list_t *cachedirs) if(cachedirs) handle->cachedirs = cachedirs; } +/** Removes a single directory from the package cache paths. */ int SYMEXPORT alpm_option_remove_cachedir(const char *cachedir) { char *vdata = NULL; @@ -517,12 +546,14 @@ int SYMEXPORT alpm_option_remove_noextract(const char *pkg) return(0); } +/** Adds a package name to the ignore list. */ void SYMEXPORT alpm_option_add_ignorepkg(const char *pkg) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->ignorepkg = alpm_list_add(handle->ignorepkg, strdup(pkg)); } +/** Sets the list of ignored packages. */ void SYMEXPORT alpm_option_set_ignorepkgs(alpm_list_t *ignorepkgs) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -530,6 +561,9 @@ void SYMEXPORT alpm_option_set_ignorepkgs(alpm_list_t *ignorepkgs) if(ignorepkgs) handle->ignorepkg = ignorepkgs; } +/** Removes a package name from the ignore list. + * @return 1 on success, 0 if the group is not in the list, -1 on error + */ int SYMEXPORT alpm_option_remove_ignorepkg(const char *pkg) { char *vdata = NULL; @@ -542,12 +576,14 @@ int SYMEXPORT alpm_option_remove_ignorepkg(const char *pkg) return(0); } +/** Adds a package group to the ignore list. */ void SYMEXPORT alpm_option_add_ignoregrp(const char *grp) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->ignoregrp = alpm_list_add(handle->ignoregrp, strdup(grp)); } +/** Sets the list of ignored groups. */ void SYMEXPORT alpm_option_set_ignoregrps(alpm_list_t *ignoregrps) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -555,6 +591,9 @@ void SYMEXPORT alpm_option_set_ignoregrps(alpm_list_t *ignoregrps) if(ignoregrps) handle->ignoregrp = ignoregrps; } +/** Removes a package group from the ignore list. + * @return 1 on success, 0 if the group is not in the list, -1 on error + */ int SYMEXPORT alpm_option_remove_ignoregrp(const char *grp) { char *vdata = NULL; @@ -567,6 +606,7 @@ int SYMEXPORT alpm_option_remove_ignoregrp(const char *grp) return(0); } +/** Set the targeted architecture. */ void SYMEXPORT alpm_option_set_arch(const char *arch) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -574,12 +614,14 @@ void SYMEXPORT alpm_option_set_arch(const char *arch) if(arch) handle->arch = strdup(arch); } +/** Set whether to use package deltas (0 for FALSE, TRUE otherwise). */ void SYMEXPORT alpm_option_set_usedelta(int usedelta) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->usedelta = usedelta; } +/** Set whether to check disk space (0 for FALSE, TRUE otherwise). */ void SYMEXPORT alpm_option_set_checkspace(int checkspace) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c index f2f15af..9be2fcb 100644 --- a/lib/libalpm/package.c +++ b/lib/libalpm/package.c @@ -46,7 +46,10 @@ * @{ */ -/** Free a package. */ +/** Free a package. + * @param pkg package pointer to free + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_pkg_free(pmpkg_t *pkg) { ALPM_LOG_FUNC; @@ -61,7 +64,10 @@ int SYMEXPORT alpm_pkg_free(pmpkg_t *pkg) return(0); } -/** Check the integrity (with md5) of a package from the sync cache. */ +/** Check the integrity (with md5) of a package from the sync cache. + * @param pkg package pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_pkg_checkmd5sum(pmpkg_t *pkg) { char *fpath; @@ -159,121 +165,228 @@ struct pkg_operations default_pkg_ops = { /* Public functions for getting package information. These functions * delegate the hard work to the function callbacks attached to each * package, which depend on where the package was loaded from. */ + +/** Gets the name of the file from which the package was loaded. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_filename(pmpkg_t *pkg) { return pkg->ops->get_filename(pkg); } +/** Returns the package name. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_name(pmpkg_t *pkg) { return pkg->ops->get_name(pkg); } +/** Returns the package version as a string. + * This includes all available epoch, version, and pkgrel components. Use + * alpm_pkg_vercmp() to compare version strings if necessary. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_version(pmpkg_t *pkg) { return pkg->ops->get_version(pkg); } +/** Returns the package description. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_desc(pmpkg_t *pkg) { return pkg->ops->get_desc(pkg); } +/** Returns the package URL. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_url(pmpkg_t *pkg) { return pkg->ops->get_url(pkg); } +/** Returns the build timestamp of the package. + * @param pkg a pointer to package + * @return the timestamp of the build time + */ time_t SYMEXPORT alpm_pkg_get_builddate(pmpkg_t *pkg) { return pkg->ops->get_builddate(pkg); } +/** Returns the install timestamp of the package. + * @param pkg a pointer to package + * @return the timestamp of the install time + */ time_t SYMEXPORT alpm_pkg_get_installdate(pmpkg_t *pkg) { return pkg->ops->get_installdate(pkg); } +/** Returns the packager's name. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_packager(pmpkg_t *pkg) { return pkg->ops->get_packager(pkg); } +/** Returns the package's MD5 checksum as a string. + * The returned string is a sequence of lowercase hexadecimal digits. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_md5sum(pmpkg_t *pkg) { return pkg->ops->get_md5sum(pkg); } +/** Returns the architecture for which the package was built. + * @param pkg a pointer to package + * @return a reference to an internal string + */ const char SYMEXPORT *alpm_pkg_get_arch(pmpkg_t *pkg) { return pkg->ops->get_arch(pkg); } +/** Returns the size of the package. + * @param pkg a pointer to package + * @return the size of the package in bytes. + */ off_t SYMEXPORT alpm_pkg_get_size(pmpkg_t *pkg) { return pkg->ops->get_size(pkg); } +/** Returns the installed size of the package. + * @param pkg a pointer to package + * @return the total size of files installed by the package. + */ off_t SYMEXPORT alpm_pkg_get_isize(pmpkg_t *pkg) { return pkg->ops->get_isize(pkg); } +/** Returns the package installation reason. + * @param pkg a pointer to package + * @return an enum member giving the install reason. + */ pmpkgreason_t SYMEXPORT alpm_pkg_get_reason(pmpkg_t *pkg) { return pkg->ops->get_reason(pkg); } +/** Returns the list of package licenses. + * @param pkg a pointer to package + * @return a pointer to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_licenses(pmpkg_t *pkg) { return pkg->ops->get_licenses(pkg); } +/** Returns the list of package groups. + * @param pkg a pointer to package + * @return a pointer to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_groups(pmpkg_t *pkg) { return pkg->ops->get_groups(pkg); } +/** Returns the list of package dependencies as pmdepend_t. + * @param pkg a pointer to package + * @return a reference to an internal list of pmdepend_t structures. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_depends(pmpkg_t *pkg) { return pkg->ops->get_depends(pkg); } +/** Returns the list of package optional dependencies. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_optdepends(pmpkg_t *pkg) { return pkg->ops->get_optdepends(pkg); } +/** Returns the list of package names conflicting with pkg. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_conflicts(pmpkg_t *pkg) { return pkg->ops->get_conflicts(pkg); } +/** Returns the list of package names provided by pkg. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_provides(pmpkg_t *pkg) { return pkg->ops->get_provides(pkg); } +/** Returns the list of available deltas for pkg. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_replaces(pmpkg_t *pkg) { return pkg->ops->get_replaces(pkg); } +/** Returns the list of packages to be replaced by pkg. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_deltas(pmpkg_t *pkg) { return pkg->ops->get_deltas(pkg); } +/** Returns the list of files installed by pkg. + * The filenames are relative to the install root, + * and do not include leading slashes. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_files(pmpkg_t *pkg) { return pkg->ops->get_files(pkg); } +/** Returns the list of files backed up when installing pkg. + * The elements of the returned list have the form + * "<filename>\t<md5sum>", where the given md5sum is that of + * the file as provided by the package. + * @param pkg a pointer to package + * @return a reference to an internal list of strings. + */ alpm_list_t SYMEXPORT *alpm_pkg_get_backup(pmpkg_t *pkg) { return pkg->ops->get_backup(pkg); } +/** Returns the database containing pkg. + * Returns a pointer to the pmdb_t structure the package is + * originating from, or NULL is the package was loaded from a file. + * @param pkg a pointer to package + * @return a pointer to the DB containing pkg, or NULL. + */ pmdb_t SYMEXPORT *alpm_pkg_get_db(pmpkg_t *pkg) { /* Sanity checks */ @@ -283,13 +396,27 @@ pmdb_t SYMEXPORT *alpm_pkg_get_db(pmpkg_t *pkg) return(pkg->origin_data.db); } -/** Open a package changelog for reading. */ +/** Open a package changelog for reading. + * Similar to fopen in functionality, except that the returned 'file + * stream' could really be from an archive as well as from the database. + * @param pkg the package to read the changelog of (either file or db) + * @return a 'file stream' to the package changelog + */ void SYMEXPORT *alpm_pkg_changelog_open(pmpkg_t *pkg) { return pkg->ops->changelog_open(pkg); } -/** Read data from an open changelog 'file stream'. */ +/** Read data from an open changelog 'file stream'. + * Similar to fread in functionality, this function takes a buffer and + * amount of data to read. If an error occurs pm_errno will be set. + * @param ptr a buffer to fill with raw changelog data + * @param size the size of the buffer + * @param pkg the package that the changelog is being read from + * @param fp a 'file stream' to the package changelog + * @return the number of characters read, or 0 if there is no more data or an + * error occurred. + */ size_t SYMEXPORT alpm_pkg_changelog_read(void *ptr, size_t size, const pmpkg_t *pkg, const void *fp) { @@ -331,7 +458,12 @@ static void find_requiredby(pmpkg_t *pkg, pmdb_t *db, alpm_list_t **reqs) } } -/** Compute the packages requiring a given package. */ +/** Computes the list of packages requiring a given package. + * The return value of this function is a newly allocated + * list of package names (char*), it should be freed by the caller. + * @param pkg a package + * @return the list of packages requiring pkg + */ alpm_list_t SYMEXPORT *alpm_pkg_compute_requiredby(pmpkg_t *pkg) { const alpm_list_t *i; diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c index c5af7c6..bcb8d14 100644 --- a/lib/libalpm/trans.c +++ b/lib/libalpm/trans.c @@ -97,7 +97,13 @@ static int remove_lock(pmhandle_t *handle) return(0); } -/** Initialize the transaction. */ +/** Initialize the transaction. + * @param flags flags of the transaction (like nodeps, etc) + * @param event event callback function pointer + * @param conv question callback function pointer + * @param progress progress callback function pointer + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_trans_init(pmtransflag_t flags, alpm_trans_cb_event event, alpm_trans_cb_conv conv, alpm_trans_cb_progress progress) @@ -170,7 +176,11 @@ static alpm_list_t *check_arch(alpm_list_t *pkgs) return(invalid); } -/** Prepare a transaction. */ +/** Prepare a transaction. + * @param data the address of an alpm_list where a list + * of pmdepmissing_t objects is dumped (conflicting packages) + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_trans_prepare(alpm_list_t **data) { pmtrans_t *trans; @@ -216,7 +226,11 @@ int SYMEXPORT alpm_trans_prepare(alpm_list_t **data) return(0); } -/** Commit a transaction. */ +/** Commit a transaction. + * @param data the address of an alpm_list where detailed description + * of an error can be dumped (ie. list of conflicting files) + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_trans_commit(alpm_list_t **data) { pmtrans_t *trans; @@ -257,7 +271,9 @@ int SYMEXPORT alpm_trans_commit(alpm_list_t **data) return(0); } -/** Interrupt a transaction. */ +/** Interrupt a transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_trans_interrupt(void) { pmtrans_t *trans; @@ -277,7 +293,9 @@ int SYMEXPORT alpm_trans_interrupt(void) return(0); } -/** Release a transaction. */ +/** Release a transaction. + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_trans_release(void) { pmtrans_t *trans; @@ -453,6 +471,9 @@ int SYMEXPORT alpm_trans_get_flags() return handle->trans->flags; } +/** Returns a list of packages added by the transaction. + * @return a list of pmpkg_t structures + */ alpm_list_t SYMEXPORT * alpm_trans_get_add() { /* Sanity checks */ @@ -462,6 +483,9 @@ alpm_list_t SYMEXPORT * alpm_trans_get_add() return handle->trans->add; } +/** Returns the list of packages removed by the transaction. + * @return a list of pmpkg_t structures + */ alpm_list_t SYMEXPORT * alpm_trans_get_remove() { /* Sanity checks */ -- 1.7.4.4

Signed-off-by: Rémy Oudompheng --- lib/libalpm/alpm.h | 7 +++++++ lib/libalpm/handle.c | 28 ++++++++++++++++++++++++++++ lib/libalpm/package.c | 1 + lib/libalpm/remove.c | 4 ++++ lib/libalpm/trans.c | 3 +++ 5 files changed, 43 insertions(+), 0 deletions(-) diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h index 61c8cdb..582b2c0 100644 --- a/lib/libalpm/alpm.h +++ b/lib/libalpm/alpm.h @@ -85,9 +85,16 @@ int alpm_logaction(const char *fmt, ...); * Downloading */ +/** Type of download progress callbacks. + * @param filename the name of the file being downloaded + * @param xfered the number of transferred bytes + * @param total the total number of bytes to transfer + */ typedef void (*alpm_cb_download)(const char *filename, off_t xfered, off_t total); + typedef void (*alpm_cb_totaldl)(off_t total); + /** A callback for downloading files * @param url the URL of the file to be downloaded * @param localpath the directory to which the file should be downloaded diff --git a/lib/libalpm/handle.c b/lib/libalpm/handle.c index 917441e..34e0d4f 100644 --- a/lib/libalpm/handle.c +++ b/lib/libalpm/handle.c @@ -191,6 +191,7 @@ int SYMEXPORT alpm_option_get_usesyslog() return handle->usesyslog; } +/** Returns the list of packages names in the NoUpgrades list. */ alpm_list_t SYMEXPORT *alpm_option_get_noupgrades() { if (handle == NULL) { @@ -200,6 +201,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_noupgrades() return handle->noupgrade; } +/** Returns the list of packages names in the NoExtract list. */ alpm_list_t SYMEXPORT *alpm_option_get_noextracts() { if (handle == NULL) { @@ -209,6 +211,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_noextracts() return handle->noextract; } +/** Returns the list of packages in the ignore list. */ alpm_list_t SYMEXPORT *alpm_option_get_ignorepkgs() { if (handle == NULL) { @@ -218,6 +221,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_ignorepkgs() return handle->ignorepkg; } +/** Returns the list of groups in the ignore list. */ alpm_list_t SYMEXPORT *alpm_option_get_ignoregrps() { if (handle == NULL) { @@ -237,6 +241,7 @@ const char SYMEXPORT *alpm_option_get_arch() return handle->arch; } +/** Returns whether libalpm uses deltas (0 is FALSE, TRUE otherwise, -1 on error). */ int SYMEXPORT alpm_option_get_usedelta() { if (handle == NULL) { @@ -285,6 +290,7 @@ alpm_list_t SYMEXPORT *alpm_option_get_syncdbs() return handle->dbs_sync; } +/** Sets the logging callback. */ void SYMEXPORT alpm_option_set_logcb(alpm_cb_log cb) { if (handle == NULL) { @@ -294,6 +300,7 @@ void SYMEXPORT alpm_option_set_logcb(alpm_cb_log cb) handle->logcb = cb; } +/** Sets the callback download progress callback. */ void SYMEXPORT alpm_option_set_dlcb(alpm_cb_download cb) { if (handle == NULL) { @@ -303,6 +310,7 @@ void SYMEXPORT alpm_option_set_dlcb(alpm_cb_download cb) handle->dlcb = cb; } +/** Sets the download callback. */ void SYMEXPORT alpm_option_set_fetchcb(alpm_cb_fetch cb) { if (handle == NULL) { @@ -312,6 +320,7 @@ void SYMEXPORT alpm_option_set_fetchcb(alpm_cb_fetch cb) handle->fetchcb = cb; } +/** Sets the callback used to report total download size. */ void SYMEXPORT alpm_option_set_totaldlcb(alpm_cb_totaldl cb) { if (handle == NULL) { @@ -321,6 +330,7 @@ void SYMEXPORT alpm_option_set_totaldlcb(alpm_cb_totaldl cb) handle->totaldlcb = cb; } +/** Sets the root directory of the destination filesystem. */ int SYMEXPORT alpm_option_set_root(const char *root) { struct stat st; @@ -363,6 +373,7 @@ int SYMEXPORT alpm_option_set_root(const char *root) return(0); } +/** Sets the path of the database. */ int SYMEXPORT alpm_option_set_dbpath(const char *dbpath) { struct stat st; @@ -432,6 +443,7 @@ int SYMEXPORT alpm_option_add_cachedir(const char *cachedir) return(0); } +/** Sets the list of package cache directories. */ void SYMEXPORT alpm_option_set_cachedirs(alpm_list_t *cachedirs) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -463,6 +475,7 @@ int SYMEXPORT alpm_option_remove_cachedir(const char *cachedir) return(0); } +/** Sets the path of the file used for logging. */ int SYMEXPORT alpm_option_set_logfile(const char *logfile) { char *oldlogfile = handle->logfile; @@ -490,18 +503,23 @@ int SYMEXPORT alpm_option_set_logfile(const char *logfile) return(0); } +/** Sets whether to use syslog for logging. */ void SYMEXPORT alpm_option_set_usesyslog(int usesyslog) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->usesyslog = usesyslog; } +/** Adds a single package to the no-upgrade list. */ void SYMEXPORT alpm_option_add_noupgrade(const char *pkg) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->noupgrade = alpm_list_add(handle->noupgrade, strdup(pkg)); } +/** Sets the no-upgrade list. + * @param noupgrade a list of strings + */ void SYMEXPORT alpm_option_set_noupgrades(alpm_list_t *noupgrade) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -509,6 +527,9 @@ void SYMEXPORT alpm_option_set_noupgrades(alpm_list_t *noupgrade) if(noupgrade) handle->noupgrade = noupgrade; } +/** Removes a package name from the no-upgrade list. + * @return 1 on success, 0 if the group is not in the list, -1 on error + */ int SYMEXPORT alpm_option_remove_noupgrade(const char *pkg) { char *vdata = NULL; @@ -521,12 +542,16 @@ int SYMEXPORT alpm_option_remove_noupgrade(const char *pkg) return(0); } +/** Adds a single package to the no-extract list. */ void SYMEXPORT alpm_option_add_noextract(const char *pkg) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); handle->noextract = alpm_list_add(handle->noextract, strdup(pkg)); } +/** Sets the no-extract list. + * @param noupgrade a list of strings + */ void SYMEXPORT alpm_option_set_noextracts(alpm_list_t *noextract) { ASSERT(handle != NULL, RET_ERR_VOID(PM_ERR_HANDLE_NULL)); @@ -534,6 +559,9 @@ void SYMEXPORT alpm_option_set_noextracts(alpm_list_t *noextract) if(noextract) handle->noextract = noextract; } +/** Removes a package name from the no-extract list. + * @return 1 on success, 0 if the group is not in the list, -1 on error + */ int SYMEXPORT alpm_option_remove_noextract(const char *pkg) { char *vdata = NULL; diff --git a/lib/libalpm/package.c b/lib/libalpm/package.c index 9be2fcb..0458993 100644 --- a/lib/libalpm/package.c +++ b/lib/libalpm/package.c @@ -436,6 +436,7 @@ int SYMEXPORT alpm_pkg_changelog_close(const pmpkg_t *pkg, void *fp) return pkg->ops->changelog_close(pkg, fp); } +/** Returns whether the package has an install scriptlet (0 is FALSE, TRUE otherwise). */ int SYMEXPORT alpm_pkg_has_scriptlet(pmpkg_t *pkg) { return pkg->ops->has_scriptlet(pkg); diff --git a/lib/libalpm/remove.c b/lib/libalpm/remove.c index 7c8a99f..eafacdd 100644 --- a/lib/libalpm/remove.c +++ b/lib/libalpm/remove.c @@ -46,6 +46,10 @@ #include "handle.h" #include "alpm.h" +/** Add a package removal action to the transaction. + * @param pkg the package to uninstall + * @return 0 on success, -1 on error (pm_errno is set accordingly) + */ int SYMEXPORT alpm_remove_pkg(pmpkg_t *pkg) { pmtrans_t *trans; diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c index bcb8d14..c711705 100644 --- a/lib/libalpm/trans.c +++ b/lib/libalpm/trans.c @@ -462,6 +462,9 @@ cleanup: return(retval); } +/** Returns the bitfield of flags for the current transaction. + * @sa _pmtransflag_t + */ int SYMEXPORT alpm_trans_get_flags() { /* Sanity checks */ -- 1.7.4.4