Send patches - preferably formatted by git format-patch - to patches at archlinux32 dot org.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorandrew.gregory.8@gmail.com <andrew.gregory.8@gmail.com>2011-11-22 00:35:46 -0500
committerDan McGee <dan@archlinux.org>2011-11-22 00:31:10 -0600
commit77af613efc8b4c99115fdf81f8284955b1e95da6 (patch)
treeee524d8440ea43b407c20696be6ee03597ed94bb
parent96b3ba3470f11842312e4fdb34b74b391842fc33 (diff)
added doxygen documentation
Made existing documentation more consistent and added documentation where there was none. One function still needs documentation and is marked with 'TODO'. Signed-off-by: Andrew Gregory <andrew.gregory.8@gmail.com> Signed-off-by: Dan McGee <dan@archlinux.org>
-rw-r--r--lib/libalpm/util.c152
-rw-r--r--lib/libalpm/util.h2
2 files changed, 124 insertions, 30 deletions
diff --git a/lib/libalpm/util.c b/lib/libalpm/util.c
index f5b79688..74c9740c 100644
--- a/lib/libalpm/util.c
+++ b/lib/libalpm/util.c
@@ -57,8 +57,16 @@
#include "trans.h"
#ifndef HAVE_STRSEP
-/* This is a replacement for strsep which is not portable (missing on Solaris).
- * Copyright (c) 2001 by François Gouget <fgouget_at_codeweavers.com> */
+/** Extracts tokens from a string.
+ * Replaces strset which is not portable (missing on Solaris).
+ * Copyright (c) 2001 by François Gouget <fgouget_at_codeweavers.com>
+ * Modifies str to point to the first character after the token if one is
+ * found, or NULL if one is not.
+ * @param str string containing delimited tokens to parse
+ * @param delim character delimiting tokens in str
+ * @return pointer to the first token in str if str is not NULL, NULL if
+ * str is NULL
+ */
char* strsep(char** str, const char* delims)
{
char* token;
@@ -88,7 +96,11 @@ int _alpm_makepath(const char *path)
return _alpm_makepath_mode(path, 0755);
}
-/* does the same thing as 'mkdir -p' */
+/** Creates a directory, including parents if needed, similar to 'mkdir -p'.
+ * @param path directory path to create
+ * @param mode permission mode for created directories
+ * @return 0 on success, 1 on error
+ */
int _alpm_makepath_mode(const char *path, mode_t mode)
{
/* A bit of pointer hell here. Descriptions:
@@ -124,6 +136,11 @@ int _alpm_makepath_mode(const char *path, mode_t mode)
return ret;
}
+/** Copies a file.
+ * @param src file path to copy from
+ * @param dest file path to copy to
+ * @return 0 on success, 1 on error
+ */
int _alpm_copyfile(const char *src, const char *dest)
{
char *buf;
@@ -173,8 +190,11 @@ cleanup:
return ret;
}
-/* Trim whitespace and newlines from a string
-*/
+/** Trim leading and trailing whitespace, including newlines, from a string.
+ * Modifies str in place.
+ * @param str a string to trim
+ * @return str
+ */
char *_alpm_strtrim(char *str)
{
char *pch = str;
@@ -190,6 +210,7 @@ char *_alpm_strtrim(char *str)
if(pch != str) {
size_t len = strlen(pch);
if(len) {
+ /* move the remaining string to the beginning of str */
memmove(str, pch, len + 1);
} else {
*str = '\0';
@@ -210,8 +231,7 @@ char *_alpm_strtrim(char *str)
return str;
}
-/**
- * Trim trailing newline from a string (if one exists).
+/** Trim trailing newlines from a string (if any exist).
* @param str a single line of text
* @return the length of the trimmed string
*/
@@ -232,8 +252,7 @@ size_t _alpm_strip_newline(char *str)
/* Compression functions */
-/**
- * Open an archive for reading and perform the necessary boilerplate.
+/** Open an archive for reading and perform the necessary boilerplate.
* This takes care of creating the libarchive 'archive' struct, setting up
* compression and format options, opening a file descriptor, setting up the
* buffer size, and performing a stat on the path once opened.
@@ -290,9 +309,7 @@ int _alpm_open_archive(alpm_handle_t *handle, const char *path,
return fd;
}
-/**
- * @brief Unpack a specific file in an archive.
- *
+/** Unpack a specific file in an archive.
* @param handle the context handle
* @param archive the archive to unpack
* @param prefix where to extract the files
@@ -313,15 +330,12 @@ int _alpm_unpack_single(alpm_handle_t *handle, const char *archive,
return ret;
}
-/**
- * @brief Unpack a list of files in an archive.
- *
+/** Unpack a list of files in an archive.
* @param handle the context handle
* @param path the archive to unpack
* @param prefix where to extract the files
* @param list a list of files within the archive to unpack or NULL for all
* @param breakfirst break after the first entry found
- *
* @return 0 on success, 1 on failure
*/
int _alpm_unpack(alpm_handle_t *handle, const char *path, const char *prefix,
@@ -421,7 +435,10 @@ cleanup:
return ret;
}
-/* does the same thing as 'rm -rf' */
+/** Recursively removes a path similar to 'rm -rf'.
+ * @param path path to remove
+ * @return 0 on success, number of paths that could not be removed on error
+ */
int _alpm_rmrf(const char *path)
{
int errflag = 0;
@@ -464,8 +481,7 @@ int _alpm_rmrf(const char *path)
return 0;
}
-/**
- * Determine if there are files in a directory
+/** Determine if there are files in a directory.
* @param handle the context handle
* @param path the full absolute directory path
* @param full_count whether to return an exact count of files
@@ -506,6 +522,13 @@ ssize_t _alpm_files_in_directory(alpm_handle_t *handle, const char *path,
return files;
}
+/** Write formatted message to log.
+ * @param handle the context handle
+ * @param format formatted string to write out
+ * @param args formatting arguments
+ * @return 0 or number of characters written on success, vfprintf return value
+ * on error
+ */
int _alpm_logaction(alpm_handle_t *handle, const char *fmt, va_list args)
{
int ret = 0;
@@ -537,7 +560,13 @@ int _alpm_logaction(alpm_handle_t *handle, const char *fmt, va_list args)
return ret;
}
-int _alpm_run_chroot(alpm_handle_t *handle, const char *path, char *const argv[])
+/** Execute a command with arguments in a chroot.
+ * @param handle the context handle
+ * @param cmd command to execute
+ * @param argv arguments to pass to cmd
+ * @return 0 on success, 1 on error
+ */
+int _alpm_run_chroot(alpm_handle_t *handle, const char *cmd, char *const argv[])
{
pid_t pid;
int pipefd[2], cwdfd;
@@ -557,7 +586,7 @@ int _alpm_run_chroot(alpm_handle_t *handle, const char *path, char *const argv[]
}
_alpm_log(handle, ALPM_LOG_DEBUG, "executing \"%s\" under chroot \"%s\"\n",
- path, handle->root);
+ cmd, handle->root);
/* Flush open fds before fork() to avoid cloning buffers */
fflush(NULL);
@@ -596,7 +625,7 @@ int _alpm_run_chroot(alpm_handle_t *handle, const char *path, char *const argv[]
exit(1);
}
umask(0022);
- execv(path, argv);
+ execv(cmd, argv);
/* execv only returns if there was an error */
fprintf(stderr, _("call to execv failed (%s)\n"), strerror(errno));
exit(1);
@@ -656,6 +685,10 @@ cleanup:
return retval;
}
+/** Run ldconfig in a chroot.
+ * @param handle the context handle
+ * @return 0 on success, 1 on error
+ */
int _alpm_ldconfig(alpm_handle_t *handle)
{
char line[PATH_MAX];
@@ -674,8 +707,13 @@ int _alpm_ldconfig(alpm_handle_t *handle)
return 0;
}
-/* Helper function for comparing strings using the
- * alpm "compare func" signature */
+/** Helper function for comparing strings using the alpm "compare func"
+ * signature.
+ * @param s1 first string to be compared
+ * @param s2 second string to be compared
+ * @return 0 if strings are equal, positive int if first unequal character
+ * has a greater value in s1, negative if it has a greater value in s2
+ */
int _alpm_str_cmp(const void *s1, const void *s2)
{
return strcmp(s1, s2);
@@ -784,6 +822,11 @@ int _alpm_lstat(const char *path, struct stat *buf)
}
#ifdef HAVE_LIBSSL
+/** Compute the MD5 message digest of a file.
+ * @param path file path of file to compute MD5 digest of
+ * @param output string to hold computed MD5 digest
+ * @return 0 on success, 1 on file open error, 2 on file read error
+ */
static int md5_file(const char *path, unsigned char output[16])
{
MD5_CTX ctx;
@@ -820,6 +863,12 @@ static int md5_file(const char *path, unsigned char output[16])
}
/* third param is so we match the PolarSSL definition */
+/** Compute the SHA-224 or SHA-256 message digest of a file.
+ * @param path file path of file to compute SHA2 digest of
+ * @param output string to hold computed SHA2 digest
+ * @param is224 use SHA-224 instead of SHA-256
+ * @return 0 on success, 1 on file open error, 2 on file read error
+ */
static int sha2_file(const char *path, unsigned char output[32], int is224)
{
SHA256_CTX ctx;
@@ -936,6 +985,13 @@ char SYMEXPORT *alpm_compute_sha256sum(const char *filename)
return sha256sum;
}
+/** Calculates a file's MD5 or SHA2 digest and compares it to an expected value.
+ * @param filepath path of the file to check
+ * @param expected hash value to compare against
+ * @param type digest type to use
+ * @return 0 if file matches the expected hash, 1 if they do not match, -1 on
+ * error
+ */
int _alpm_test_checksum(const char *filepath, const char *expected,
enum _alpm_csum type)
{
@@ -963,6 +1019,12 @@ int _alpm_test_checksum(const char *filepath, const char *expected,
}
/* Note: does NOT handle sparse files on purpose for speed. */
+/** TODO.
+ * Does not handle sparse files on purpose for speed.
+ * @param a
+ * @param b
+ * @return
+ */
int _alpm_archive_fgets(struct archive *a, struct archive_read_buffer *b)
{
/* ensure we start populating our line buffer at the beginning */
@@ -1058,6 +1120,14 @@ cleanup:
}
}
+/** Parse a full package specifier.
+ * @param target package specifier to parse, such as: "pacman-4.0.1-2",
+ * "pacman-4.01-2/", or "pacman-4.0.1-2/desc"
+ * @param name to hold package name
+ * @param version to hold package version
+ * @param name_hash to hold package name hash
+ * @return 0 on success, -1 on error
+ */
int _alpm_splitname(const char *target, char **name, char **version,
unsigned long *name_hash)
{
@@ -1110,8 +1180,7 @@ int _alpm_splitname(const char *target, char **name, char **version,
return 0;
}
-/**
- * Hash the given string to an unsigned long value.
+/** Hash the given string to an unsigned long value.
* This is the standard sdbm hashing algorithm.
* @param str string to hash
* @return the hash value of the given string
@@ -1131,6 +1200,11 @@ unsigned long _alpm_hash_sdbm(const char *str)
return hash;
}
+/** Convert a string to a file offset.
+ * This parses bare positive integers only.
+ * @param line string to convert
+ * @return off_t on success, -1 on error
+ */
off_t _alpm_strtoofft(const char *line)
{
char *end;
@@ -1156,6 +1230,10 @@ off_t _alpm_strtoofft(const char *line)
return (off_t)result;
}
+/** Parses a date into an alpm_time_t struct.
+ * @param line date to parse
+ * @return time struct on success, 0 on error
+ */
alpm_time_t _alpm_parsedate(const char *line)
{
char *end;
@@ -1189,8 +1267,7 @@ alpm_time_t _alpm_parsedate(const char *line)
return (alpm_time_t)result;
}
-/**
- * Wrapper around access() which takes a dir and file argument
+/** Wrapper around access() which takes a dir and file argument
* separately and generates an appropriate error message.
* If dir is NULL file will be treated as the whole path.
* @param handle an alpm handle
@@ -1199,7 +1276,6 @@ alpm_time_t _alpm_parsedate(const char *line)
* @param amode access mode as described in access()
* @return int value returned by access()
*/
-
int _alpm_access(alpm_handle_t *handle, const char *dir, const char *file, int amode)
{
size_t len = 0;
@@ -1240,6 +1316,13 @@ int _alpm_access(alpm_handle_t *handle, const char *dir, const char *file, int a
return ret;
}
+/** Checks whether a string matches a shell wildcard pattern.
+ * Wrapper around fnmatch.
+ * @param pattern pattern to match aganist
+ * @param string string to check against pattern
+ * @return 0 if string matches pattern, non-zero if they don't match and on
+ * error
+ */
int _alpm_fnmatch(const void *pattern, const void *string)
{
return fnmatch(pattern, string, 0);
@@ -1247,6 +1330,11 @@ int _alpm_fnmatch(const void *pattern, const void *string)
#ifndef HAVE_STRNDUP
/* A quick and dirty implementation derived from glibc */
+/** Determines the length of a fixed-size string.
+ * @param s string to be measured
+ * @param max maximum number of characters to search for the string end
+ * @return length of s or max, whichever is smaller
+ */
static size_t strnlen(const char *s, size_t max)
{
register const char *p;
@@ -1254,6 +1342,12 @@ static size_t strnlen(const char *s, size_t max)
return (p - s);
}
+/** Copies a string.
+ * Returned string needs to be freed
+ * @param s string to be copied
+ * @param n maximum number of characters to copy
+ * @return pointer to the new string on success, NULL on error
+ */
char *strndup(const char *s, size_t n)
{
size_t len = strnlen(s, n);
diff --git a/lib/libalpm/util.h b/lib/libalpm/util.h
index fa86679f..1e192747 100644
--- a/lib/libalpm/util.h
+++ b/lib/libalpm/util.h
@@ -127,7 +127,7 @@ int _alpm_unpack(alpm_handle_t *handle, const char *archive, const char *prefix,
int _alpm_rmrf(const char *path);
ssize_t _alpm_files_in_directory(alpm_handle_t *handle, const char *path, int full_count);
int _alpm_logaction(alpm_handle_t *handle, const char *fmt, va_list args);
-int _alpm_run_chroot(alpm_handle_t *handle, const char *path, char *const argv[]);
+int _alpm_run_chroot(alpm_handle_t *handle, const char *cmd, char *const argv[]);
int _alpm_ldconfig(alpm_handle_t *handle);
int _alpm_str_cmp(const void *s1, const void *s2);
char *_alpm_filecache_find(alpm_handle_t *handle, const char *filename);