aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJason Woodward2005-09-23 18:42:25 +0000
committerJason Woodward2005-09-23 18:42:25 +0000
commit2dc5fb4739b0923dcb86b3e79aacb1dcb155d983 (patch)
treea9ccd6d813e1202b2f8bf60f34d59167c0b976ae /doc
parent81d57cc4c57e2afc35dfa6ecccd9fd2b0170c337 (diff)
downloadslapt-get-2dc5fb4739b0923dcb86b3e79aacb1dcb155d983.tar.gz
added libslapt.3 manpage
Diffstat (limited to 'doc')
-rw-r--r--doc/libslapt.3450
1 files changed, 450 insertions, 0 deletions
diff --git a/doc/libslapt.3 b/doc/libslapt.3
new file mode 100644
index 0000000..2ec9c86
--- /dev/null
+++ b/doc/libslapt.3
@@ -0,0 +1,450 @@
+.TH libslapt 3
+.SH NAME
+libslapt \- slapt-get library
+.SH SYNOPSIS
+.nf
+#define _GNU_SOURCE
+#include <slapt.h>
+
+/* parse config file for sources, excludes, and working_dir*/
+slapt_rc_config *config = slapt_read_rc_config("/etc/slapt-get/slapt-getrc");
+/* get a list of installed packages */
+struct slapt_pkg_list *installed = slapt_get_installed_pkgs();
+/* parse the package data, normally using config->working_dir */
+FILE *data_f = fopen("/var/slapt-get/package_data","r");
+struct slapt_pkg_list *available = slapt_parse_packages_txt(data_f);
+
+/* search for a package in a list via regex */
+struct slapt_pkg_list *results = slapt_search_pkg_list(installed,"[0-9]frg");
+slapt_free_pkg_list(results);
+
+/* look for a specific package */
+slapt_pkg_info_t *pkg = slapt_get_exact_pkg(available,
+ "slapt-get",
+ "0.9.10c-i386-1");
+if (!slapt_is_excluded(config,pkg)) {
+ slapt_download_pkg(config,pkg);
+
+ if (install_pkg(config,pkg) != 0) {
+ fprintf(stderr,"error installing %s\\n"pkg->name);
+ }
+ if (upgrade_pkg(config,pkg) != 0) {
+ fprintf(stderr,"error upgrading %s\\n"pkg->name);
+ }
+ if (remove_pkg(config,pkg) != 0) {
+ fprintf(stderr,"error removing %s\\n"pkg->name);
+ }
+}
+slapt_free_pkg(pkg);
+
+if (slapt_cmp_pkgs(pkg_a,pkg_b) = 0) {
+ fprintf(stderr,"%s is equal to %s\\n",pkg_a->version,pkg_b->version);
+} elsif (slapt_cmp_pkgs(pkg_a,pkg_b) < 0) {
+ fprintf(stderr,"%s is less than %s\\n",pkg_a->version,pkg_b->version);
+} elsif (slapt_cmp_pkgs(pkg_a,pkg_b) > 0) {
+ fprintf(stderr,"%s is greater than %s\\n",pkg_a->version,pkg_b->version);
+}
+
+slapt_free_pkg_list(available);
+slapt_free_pkg_list(installed);
+slapt_free_rc_config(config);
+.fi
+.SH DESCRIPTION
+This is a short overview on how to use libslapt with your C programs.
+.IP \fBCONFIGURATION\fP
+.TP
+slapt-get stores the configuration information in a \fIslapt_rc_config\fP object. The configuration is parsed from the \fIslapt-getrc\fP which includes \fISOURCE\fP, \fIEXCLUDE\fP, and \fIWORKINGDIR\fP directives. Various runtime configuration options are also stored within the \fIslapt_rc_config\fP object.
+
+.nf
+ typedef struct {
+ struct slapt_source_list *sources;
+ char working_dir[WORKINGDIR_TOKEN_LEN];
+ struct slapt_exclude_list *exclude_list;
+ SLAPT_BOOL_T download_only;
+ SLAPT_BOOL_T dist_upgrade;
+ SLAPT_BOOL_T simulate;
+ SLAPT_BOOL_T no_prompt;
+ SLAPT_BOOL_T re_install;
+ SLAPT_BOOL_T ignore_excludes;
+ SLAPT_BOOL_T no_md5_check;
+ SLAPT_BOOL_T ignore_dep;
+ SLAPT_BOOL_T disable_dep_check;
+ SLAPT_BOOL_T print_uris;
+ SLAPT_BOOL_T dl_stats;
+ SLAPT_BOOL_T remove_obsolete;
+ SLAPT_BOOL_T no_upgrade;
+ unsigned int retry;
+ int (*progress_cb) (void *,double,double,double,double);
+ } slapt_rc_config;
+.fi
+
+.TP
+The \fIslapt_rc_config\fP is created with the \fIslapt_read_rc_config\fP() function by passing in the file location of the configuration to parse.
+.sp
+.B "slapt_rc_config *slapt_read_rc_config(const char *file_name);"
+.sp
+.TP
+and is freed by a call to the \fIslapt_free_rc_config\fP() function.
+.sp
+.B "void slapt_free_rc_config(slapt_rc_config *global_config);"
+.sp
+.TP
+The progress callback is a function that is called while data is being downloaded. It is in the format of \fBint slapt_progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow);\fP
+.sp
+.TP
+The \fIstruct slapt_source_list\fP stores the package sources. Sources can be added and removed with \fIslapt_add_source\fP() and \fIslapt_remove_source\fP(). Typically, \fIslapt_rc_config->sources\fP is passed as the first argument, but it could be any pointer to a \fIstruct slapt_source_list\fP.
+.sp
+.nf
+ struct slapt_source_list {
+ char **url;
+ unsigned int count;
+ };
+.sp
+.B "void slapt_add_source(struct slapt_source_list *list,const char *s);"
+.B "void slapt_remove_source (struct slapt_source_list *list, const char *s);"
+.fi
+.sp
+.TP
+The \fIstruct slapt_exclude_list\fP stores the package excludes. Excludes can be added with \fIslapt_add_exclude\fP(). Typically, \fIslapt_rc_config->excludes\fP is passed as the first argument, but it could be any pointer to a \fIstruct slapt_exclude_list\fP.
+.sp
+.nf
+ struct slapt_exclude_list {
+ char **excludes;
+ unsigned int count;
+ };
+.sp
+.B "void slapt_add_exclude(struct slapt_exclude_list *list,const char *e);"
+.fi
+.sp
+.TP
+In order to initialize the slapt_rc_config->working_dir directory, \fIslapt_working_dir_init\fP() must be called. It is a fatal error to call \fIslapt_working_dir_init\fP() with a directory that the current process does not have privileges to read, write, and execute.
+.sp
+.B "void slapt_working_dir_init(const slapt_rc_config *global_config);"
+.sp
+.IP \fBPACKAGES\fP
+.TP
+slapt-get stores packages within \fIslapt_pkg_info_t\fP objects.
+.sp
+.nf
+ typedef struct {
+ char *name;
+ char *version;
+ char *mirror;
+ char *location;
+ unsigned int size_c;
+ unsigned int size_u;
+ char *description;
+ char *required;
+ char *conflicts;
+ char *suggests;
+ char md5[SLAPT_MD5_STR_LEN];
+ char *file_ext;
+ } slapt_pkg_info_t;
+.fi
+.sp
+.TP
+The \fIslapt_pkg_info_t\fP object is created and freed with \fIslapt_init_pkg\fP() and \fIslapt_free_pkg\fP(). A \fIslapt_pkg_info_t\fP can also be copied with \fIslapt_copy_pkg\fP().
+.sp
+.nf
+.B "__inline slapt_pkg_info_t *slapt_init_pkg(void);"
+.B "void slapt_free_pkg(slapt_pkg_info_t *pkg);"
+.B "slapt_pkg_info_t *slapt_copy_pkg(slapt_pkg_info_t *dst,"
+.B " slapt_pkg_info_t *src);"
+.fi
+.sp
+.TP
+Package lists are useful for grouping packages from the existing installed packages, packages available from external sources, a list of dependencies, and more. Package lists are stored within a \fIstruct slapt_pkg_list\fP.
+.sp
+.nf
+ struct slapt_pkg_list {
+ slapt_pkg_info_t **pkgs;
+ unsigned int pkg_count;
+ SLAPT_BOOL_T free_pkgs;
+ };
+.fi
+.sp
+.TP
+If \fIfree_pkgs\fP is set to TRUE, \fIslapt_free_pkg_list\fP will call \fIslapt_free_pkg\fP() for each \fIslapt_pkg_info_t\fP within the list. Leave this to the default of FALSE if the list is populated with pointers to \fIslapt_pkg_info_t\fP objects that are freed elsewhere.
+.sp
+.TP
+\fIslapt_pkg_info_t\fP objects are created by \fIslapt_init_pkg_list\fP() and freed by \fIslapt_free_pkg_list\fP(). \fIslapt_add_pkg_to_pkg_list\fP() is used to add a package to a list.
+.sp
+.nf
+.B "struct slapt_pkg_list *slapt_init_pkg_list(void);"
+.B "void slapt_free_pkg_list(struct slapt_pkg_list *);"
+.B "void slapt_add_pkg_to_pkg_list(struct slapt_pkg_list *list, slapt_pkg_info_t *pkg);"
+.fi
+.sp
+.TP
+Package lists can be parsed from PACKAGES.TXT or similar formated files (such as the working_dir/package_data file used by slapt-get) with \fIslapt_parse_packages_txt\fP(). A package list of the currently installed packages is returned by \fIslapt_get_installed_pkgs\fP(). \fIslapt_get_available_pkgs\fP() is a frontend to \fIslapt_parse_packages_txt\fP() looking for a package_data file in the current directory. All three of the following set \fIfree_pkgs\fP to TRUE.
+.sp
+.nf
+.B "struct slapt_pkg_list *slapt_parse_packages_txt(FILE *);"
+.B "struct slapt_pkg_list *slapt_get_available_pkgs(void);"
+.B "struct slapt_pkg_list *slapt_get_installed_pkgs(void);"
+.fi
+.sp
+.TP
+Finding a specific package in a package list is done through one of the following functions. All return \fIslapt_pkg_info_t\fP, or NULL on error, except for \fIslapt_search_pkg_list\fP() which returns a list of packages as \fIstruct slapt_pkg_list\fP.
+.sp
+.nf
+.B "slapt_pkg_info_t *slapt_get_newest_pkg(struct slapt_pkg_list *,"
+.B " const char *);"
+.B "slapt_pkg_info_t *slapt_get_exact_pkg(struct slapt_pkg_list *list,"
+.B " const char *name,"
+.B " const char *version);"
+.B "slapt_pkg_info_t *slapt_get_pkg_by_details(struct slapt_pkg_list *list,"
+.B " const char *name,"
+.B " const char *version,"
+.B " const char *location);"
+.B "struct slapt_pkg_list *slapt_search_pkg_list(struct slapt_pkg_list *list,"
+.B " const char *pattern);"
+.fi
+.sp
+.TP
+Passing a package to \fIinstallpkg\fP, \fIupgradepkg\fP, and \fIremovepkg\fP is done through the following functions. All return 0 upon success, or non-zero on error.
+.sp
+.nf
+.B "int slapt_install_pkg(const slapt_rc_config *,slapt_pkg_info_t *);"
+.B "int slapt_upgrade_pkg(const slapt_rc_config *global_config,"
+.B " slapt_pkg_info_t *pkg);"
+.B "int slapt_remove_pkg(const slapt_rc_config *,slapt_pkg_info_t *);"
+.fi
+.sp
+.TP
+Comparing package versions is done with the \fIslapt_cmp_pkgs\fP macro. It calls \fIslapt_cmp_pkg_versions\fP() which returns just like strcmp, greater than 0 if a is greater than b, less than 0 if a is less than b, or 0 if a and b are equal.
+.sp
+.nf
+.B "int slapt_cmp_pkg_versions(const char *a, const char *b);"
+.B "#define slapt_cmp_pkgs(x,y) slapt_cmp_pkg_versions(x->version,y->version)"
+.fi
+.sp
+.TP
+The following functions deal with determining package dependencies and conflicts and returning them within a package list. Some require the use of a \fIstruct slapt_pkg_err_list\fP of \fIslapt_pkg_err_t\fP objects for reporting errors on which packages failed or were missing. \fIslapt_search_pkg_err_list\fP() returns 0 if the package and error string combination does not already exist in the \fIstruct slapt_pkg_err_list\fP, 1 if found.
+.sp
+.nf
+ typedef struct {
+ char *pkg;
+ char *error;
+ } slapt_pkg_err_t;
+.sp
+ struct slapt_pkg_err_list {
+ unsigned int err_count;
+ slapt_pkg_err_t **errs;
+ };
+.sp
+.B "struct slapt_pkg_err_list *slapt_init_pkg_err_list(void);"
+.B "void slapt_add_pkg_err_to_list(struct slapt_pkg_err_list *l,"
+.B " const char *pkg,const char *err);"
+.B "int slapt_search_pkg_err_list(struct slapt_pkg_err_list *l, const char *pkg,"
+.B " const char *err);"
+.B "void slapt_free_pkg_err_list(struct slapt_pkg_err_list *l);"
+.sp
+.fi
+.TP
+\fIslapt_get_pkg_dependencies\fP() fills a \fIstruct slapt_pkg_list\fP of dependencies for the specified package. These dependencies are pulled from the available package list and the installed package lists. Missing and conflict errors are placed in \fIstruct slapt_pkg_err_list\fP. \fIdeps\fP, \fIconflict_err\fP, and \fImissing_err\fP are initialized if null. \fIslapt_get_pkg_dependencies\fP() returns 0 on success, or -1 on error.
+.sp
+.nf
+.B "int slapt_get_pkg_dependencies(const slapt_rc_config *global_config,
+.B " struct slapt_pkg_list *avail_pkgs,
+.B " struct slapt_pkg_list *installed_pkgs,
+.B " slapt_pkg_info_t *pkg,
+.B " struct slapt_pkg_list *deps,
+.B " struct slapt_pkg_err_list *conflict_err,
+.B " struct slapt_pkg_err_list *missing_err);"
+.sp
+.fi
+.TP
+\fIslapt_get_pkg_conflicts\fP() returns a \fIstruct slapt_pkg_list\fP of packages that conflict with the specified package.
+.sp
+.nf
+.B "struct slapt_pkg_list *"
+.B "slapt_get_pkg_conflicts(struct slapt_pkg_list *avail_pkgs,
+.B " struct slapt_pkg_list *installed_pkgs,
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.fi
+.TP
+\fIslapt_is_required_by\fP returns a \fIstruct slapt_pkg_list\fP of packages that require the package specified.
+.sp
+.nf
+.B "struct slapt_pkg_list *"
+.B "slapt_is_required_by(const slapt_rc_config *global_config,
+.B " struct slapt_pkg_list *avail,
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.fi
+.TP
+\fIslapt_is_excluded\fP() returns 1 if package is present in the exclude list, 0 if not.
+.sp
+.nf
+.B "int slapt_is_excluded(const slapt_rc_config *,slapt_pkg_info_t *);"
+.fi
+.sp
+.TP
+The \fIworking_dir\fP, defined within the \fIslapt_rc_config\fP object, caches the downloaded packages. At various times it becomes necessary to purge the package cache. \fIslapt_clean_pkg_dir\fP() unlinks all packages within the specified directory location. \fIslapt_purge_old_cached_pkgs\fP() unlinks only packages that are not present in the current sources and thus are no longer downloadable.
+.sp
+.nf
+.B "void slapt_clean_pkg_dir(const char *dir_name);"
+.B "void slapt_purge_old_cached_pkgs(const slapt_rc_config *global_config,"
+.B " const char *dir_name,"
+.B " struct slapt_pkg_list *avail_pkgs);"
+.fi
+.sp
+.IP \fBDOWNLOADING\fP
+.TP
+Downloading packages and the package data from various sources is handled with the following functions.
+.sp
+.nf
+.B "int slapt_update_pkg_cache(const slapt_rc_config *global_config);"
+.B "int slapt_download_pkg(const slapt_rc_config *global_config,"
+.B " slapt_pkg_info_t *pkg);"
+.B "int slapt_verify_downloaded_pkg(const slapt_rc_config *global_config,"
+.B " slapt_pkg_info_t *pkg);"
+.B "int slapt_download_data(FILE *fh,const char *url,size_t bytes,"
+.B " const slapt_rc_config *global_config);"
+.sp
+.B "int slapt_get_mirror_data_from_source(FILE *fh,"
+.B " const slapt_rc_config *global_config,"
+.B " const char *base_url,"
+.B " const char *filename);"
+.B "char *slapt_head_request(const char *url);"
+.B "char *slapt_head_mirror_data(const char *wurl,const char *file);"
+.B "void slapt_clear_head_cache(const char *cache_filename);"
+.B "void slapt_write_head_cache(const char *cache, const char *cache_filename);"
+.B "char *slapt_read_head_cache(const char *cache_filename);"
+.fi
+.sp
+.TP
+The following three functions download the PACKAGES.TXT, the patches/PACKAGES.TXT, and CHECKSUMS.md5 and return a package list or the file of the CHECKSUMS.md5.
+.sp
+.nf
+.B "struct slapt_pkg_list *"
+.B "slapt_get_pkg_source_packages (const slapt_rc_config *global_config,"
+.B " const char *url);"
+.B "struct slapt_pkg_list *"
+.B "slapt_get_pkg_source_patches (const slapt_rc_config *global_config,"
+.B " const char *url);"
+.B "FILE *slapt_get_pkg_source_checksums (const slapt_rc_config *global_config,"
+.B " const char *url);"
+.fi
+.sp
+.IP \fBTRANSACTIONS\fP
+.TP
+Adding, removing, and upgrading packages can be wrapped in a \fIslapt_transaction_t\fP object. This structure will make sure that all packages are worked on in the specific order, downloaded, and handed off to the appropriate pkgtools command via the \fIslapt_handle_transaction\fP() function.
+.sp
+.nf
+ struct slapt_suggests {
+ char **pkgs;
+ unsigned int count;
+ };
+.sp
+ enum slapt_action {
+ USAGE = 0, UPDATE, INSTALL, REMOVE, SHOW, SEARCH, UPGRADE,
+ LIST, INSTALLED, CLEAN, SHOWVERSION, AUTOCLEAN, AVAILABLE
+ };
+.sp
+ typedef struct {
+ union { slapt_pkg_info_t *i; slapt_pkg_upgrade_t *u; } pkg;
+ unsigned int type; /* this is enum slapt_action */
+ } slapt_queue_i;
+.sp
+ typedef struct {
+ slapt_queue_i **pkgs;
+ unsigned int count;
+ } slapt_queue_t;
+.sp
+ typedef struct {
+ slapt_pkg_info_t *installed;
+ slapt_pkg_info_t *upgrade;
+ } slapt_pkg_upgrade_t;
+.sp
+ struct slapt_pkg_upgrade_list {
+ slapt_pkg_upgrade_t **pkgs;
+ unsigned int pkg_count;
+ };
+.sp
+ typedef struct {
+ struct slapt_pkg_list *install_pkgs;
+ struct slapt_pkg_upgrade_list *upgrade_pkgs;
+ struct slapt_pkg_list *remove_pkgs;
+ struct slapt_pkg_list *exclude_pkgs;
+ struct slapt_suggests *suggests;
+ struct slapt_pkg_err_list *conflict_err;
+ struct slapt_pkg_err_list *missing_err;
+ slapt_queue_t *queue;
+ } slapt_transaction_t;
+.sp
+.B "void slapt_init_transaction(slapt_transaction_t *);"
+.B "void slapt_free_transaction(slapt_transaction_t *);"
+.B "int slapt_handle_transaction(const slapt_rc_config *,slapt_transaction_t *);"
+.sp
+.B "void slapt_add_install_to_transaction(slapt_transaction_t *,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "void slapt_add_remove_to_transaction(slapt_transaction_t *,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "void slapt_add_upgrade_to_transaction(slapt_transaction_t *,"
+.B " slapt_pkg_info_t *installed_pkg,"
+.B " slapt_pkg_info_t *upgrade_pkg);"
+.sp
+.B "void slapt_add_exclude_to_transaction(slapt_transaction_t *,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "slapt_transaction_t *slapt_remove_from_transaction(slapt_transaction_t *tran,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "int slapt_search_transaction(slapt_transaction_t *,char *pkg_name);"
+.B "int slapt_search_transaction_by_pkg(slapt_transaction_t *tran,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "int slapt_search_upgrade_transaction(slapt_transaction_t *tran,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "int slapt_add_deps_to_trans(const slapt_rc_config *global_config,"
+.B " slapt_transaction_t *tran,"
+.B " struct slapt_pkg_list *avail_pkgs,"
+.B " struct slapt_pkg_list *installed_pkgs,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "slapt_pkg_info_t *slapt_is_conflicted(slapt_transaction_t *tran,"
+.B " struct slapt_pkg_list *avail_pkgs,"
+.B " struct slapt_pkg_list *installed_pkgs,"
+.B " slapt_pkg_info_t *pkg);"
+.sp
+.B "void slapt_generate_suggestions(slapt_transaction_t *tran);"
+.fi
+.sp
+.IP \fBMISCELLANEOUS\fP
+.TP
+Miscellaneous functionality within libslapt.
+.sp
+.nf
+ typedef struct {
+ regex_t regex;
+ size_t nmatch;
+ regmatch_t pmatch[SLAPT_MAX_REGEX_PARTS];
+ int reg_return;
+ } slapt_regex;
+.sp
+.B "FILE *slapt_open_file(const char *file_name,const char *mode);"
+.B "int slapt_init_regex(slapt_regex *regex_t, const char *regex_string);"
+.B "void slapt_execute_regex(slapt_regex *regex_t,const char *string);"
+.B "void slapt_free_regex(slapt_regex *regex_t);"
+.B "void slapt_create_dir_structure(const char *dir_name);"
+.B "void slapt_gen_md5_sum_of_file(FILE *f,char *result_sum);"
+.B "int slapt_ask_yes_no(const char *format, ...);"
+.B "char *slapt_str_replace_chr(const char *string,const char find,"
+.B " const char replace);"
+.B "__inline void *slapt_malloc(size_t s);"
+.B "__inline void *slapt_calloc(size_t n,size_t s);"
+.fi
+.sp
+.SH LINKING WITH LIBSLAPT
+You must link with -lslapt and with libcurl through the curl-config script. For example: `curl-config --libs` -lslapt
+.SH SEE ALSO
+.BR libcurl(3)
+.BR zlib(3)
+.SH AUTHOR
+Jason Woodward <woodwardj@jaos.org>